In Kodo, each factory maintains a set of resources shared by all the
PersistenceManagers produced by that factory.
Sharing common structures like connection pools and data caches
drastically reduces the resource consumption of each manager,
increasing your application's scalability. Kodo takes this concept
one step further by also giving its factories the ability to
act as servers for
EntityManagers on remote machines. You can
thus leverage the full JDO or Java Persistence API in your client
tier without duplicating limited resources like database connections on
In addition to ensuring that your application scales as more clients are added, this model may allow you to use Kodo in situations where the client machine cannot directly access the necessary server-side resources itself - for example, when the database is only available to the local network.
This remote capability means that you can design your application as a simple two-tiered servlet-database application, and then migrate to a more scalable servlet-Kodo middle tier-database architecture as the load on your system increases. This end picture looks much like a standard J2EE application server architecture, except that the code that uses the persistence APIs in the servlet does not need to change at all to toggle between the more performant two-tier architecture and the more scalable three-tier architecture.
Additionally, Kodo's remote capability is useful for applet and Java Web Start application development. In conjunction with the compressed HTTP transport, you can deploy code that uses standard persistence APIs in an applet or a Web Start application.
PersistenceManagers in these applications
will then connect back to the server that they were downloaded from in
order to access the database.
To configure a factory act as a standalone server to remote clients,
property to a plugin string (see
Section 2.4, “Plugin Configuration”) describing the
implementation to use for remote communication. You can implement
Transport, or use one of the
false: The default value. No server is
tcp: An alias for
, a TCP transport layer. This transport layer has
the following settings:
Port: The port the server will
listen on. Defaults to 5637.
Host: The host name of the
server. Defaults to
This setting is not used by the server, but by
clients. We discuss client configuration below.
SoTimeout: The socket read
timeout in milliseconds. Defaults to 0 for no
Section 11.2.4, “Data Compression and Filtering”
Example 11.2. Configuring a Standalone Persistence Server
JPA XML format:
<property name="kodo.PersistenceServer" value="tcp(Port=5555)"/>
JDO properties format:
Javadoc details the methods Kodo exposes for manually managing
a persistence server thread.
Example 11.3. Starting a Persistence Server
After obtaining the server factory for the first time, you must start the server thread. Attempting to start the server thread when it is already running or when there is no persistence server configured will have no effect.
import kodo.remote.*; import org.apache.openjpa.persistence.*; ... EntityManagerFactory emf = Persistence.createEntityManagerFactory ("kodo"); if (Remote.getInstance (OpenJPAPersistence.toBrokerFactory (emf)).startPersistenceServer ()) // server started... else // server not started; may have already been running or not configured
import kodo.jdo.*; ... PersistenceManagerFactory pmf = JDOHelper.getPersistenceManagerFactory (kodo.properties"); if (((KodoPersistenceManagerFactory) pmf).startPersistenceServer ()) // server started... else // server not started; may have already been running or not configured
Your Kodo distribution also includes a program to start a standalone
persistence server. You can run the program through its Java class,
through the provided
script. The script accepts the standard Kodo command-line arguments
outlined in Section 2.3, “Command Line Configuration”.
Kodo's remote managers can communicate with the server
over HTTP, allowing you to use them through firewalls that shut off
other ports and protocols. In order to receive HTTP requests from
remote clients, Kodo includes the
. You can deploy this servlet into any standards-compliant
remote requests using an internal factory. The
servlet provides several mechanisms for configuring this factory:
First, the servlet checks the value of the
kodo.jndi servlet initialization parameter
(servlet initialization parameters are specified in the
web.xml deployment file; see
your servlet container documentation for details). If the
value of this parameter is non-null, Kodo attempts to look
the indicated JNDI location. (A
is the native Kodo component that underlies
kodo.jndi initialization parameter
is not set, Kodo checks the
initialization parameter. The value of this
parameter is a resource path to
an JPA XML
a JDO properties
file containing Kodo configuration properties.
Finally, Kodo checks the remainder of the servlet initialization parameters for Kodo configuration properties. These parameter values override the value supplied in the configuration file (if any).
If you use servlet parameters alone to configure the
persistence server, Kodo will not know whether to apply JPA
or JDO defaults. Set the
kodo.Specification servlet parameter to
jdo to tell
Kodo which specification defaults to apply.
You can make sure that the servlet's factory is configured as expected by navigating to the servlet in your web browser. The servlet will display a simple web page detailing the configuration of its internal factory.
PersistenceManagers are remote
proxies to server-side managers created by the server-side
factory you are communicating with. From an API standpoint, a
client manager is exactly like a local one, complete
with all Kodo API extensions. Behind the scenes, however, the
actions you take on a client manager are sent to the
corresponding server-side manager for processing. For
performance reasons and because your persistent objects are not
proxies themselves, each client manager has a local
cache of managed objects, synchronized with the server-side
You obtain client
the same way you obtain local managers: from an
PersistenceManagerFactory that you have constructed
through JCA or the
Persistence helper /
Client configuration properties are the same as those used for
local Kodo operation, with the following exceptions:
You must set the
kodo.BrokerFactory property to
kodo.PersistenceServer setting is
used to find the remote server. If you are using a
server, the value of this property is typically the
same as its value on the server. If you are using the
, the value of this property on the client is:
http in the setting above is an alias
URL property indicates
the URL to connect to. You can also specify a
Decorators property, as discussed in
Section 11.2.4, “Data Compression and Filtering”.
controls how the client handles connections to the server,
not how the server handles connections to the database.
The available values are the same as the options for
always: Each client manager
obtains a single connection to its server-side
counterpart and uses this connection until it is
transaction: A connection is
obtained when each transaction begins, and
relinquished when the transaction completes.
Nontransactional connections are obtained as needed
and released immediately.
on-demand: A connection to the
server is obtained when needed, and immediately
closed when the request has been fulfilled. This
is the default.
pooling not for database connections, but for connections
from the client machine to the remote server. The following
pooling options are available:
ExceptionAction: The action
to take when when a connection that has thrown
an exception is returned to the pool. Set to
destroy to destroy the
connection. Set to
validate the connection (subject to the
TestOnBorrow, and other test settings).
none to ignore the fact
that the connection has thrown an exception, and
assume it is still usable. Defaults to
MaxActive: The maximum number of
connections in use at one time. Defaults to 8.
MaxIdle: The maximum number of
idle connections to keep in the pool. Defaults
MaxWait: The maximum number of
milliseconds to wait for a free connection to
become available before giving up. Defaults to
minimum number of milliseconds that a
connection can sit idle before it becomes a
candidate for eviction from the pool. Defaults to
30 minutes. Set to 0 to never evict a connection
based on idle time alone.
TestOnBorrow: Whether to to
validate connections before obtaining them from the
pool. Defaults to
TestOnReturn: Set to
true to validate connections
when they are returned to the pool.
TestWhileIdle: Set to
true to periodically validate
The number of milliseconds between runs of the
eviction thread. Defaults to -1, meaning the
eviction thread will never run.
The minimum number of milliseconds that must elapse
before a connection will ever be re-validated. This
property is usually used with
reduce the number of validations performed, because
the same connection is often borrowed and returned
many times in short periods of time. Defaults to
300000 (5 minutes).
WhenExhaustedAction: The action
to take when there are no available connections
in the pool. Set to
immediately throw an exception. Set to
block to block until a connection
is available or the maximum wait time is exceeded.
grow to automatically
grow the pool. Defaults to
Remember that persistent connections to the server consume
server-side resources, and therefore should be minimized
if possible. To disable pooling altogether, set
Database connectivity and JDBC-related properties are
ignored by the client factory. All
database communication takes place on the server, so these
properties are only valid on the server-side factory.
There are, however, two exceptions to
this rule. If specified, the client will transfer your
settings to the server. This allows different
remote clients to connect as different database users.
Other than the bullet points above, you configure client factories in the same way as local factories. Keep in mind, though, that the configuration you specify on the client only applies to the client factory, not the server. For example, if you configure a data cache and query cache on the client, these caches will only "see" changes made by the client; they will not automatically synchronize with changes made by any other client or changes made on the server. Thus, you will typically want to configure components like the data cache, query cache, lock manager, etc. on the server only (where clients can still benefit from them by proxy), and turn them off on the client.
Example 11.5. Client Configuration
JPA XML format:
<property name="kodo.BrokerFactory" value="remote"/> <property name="kodo.PersistenceServer" value="tcp(Host=kodohost.mydomain.com, Port=5555)"/> <property name="kodo.ConnectionRetainMode" value="transaction"/> <property name="kodo.ConnectionFactoryProperties" value="MaxIdle=3, ValidationTimeout=60000"/>
JDO properties format:
kodo.BrokerFactory: remote kodo.PersistenceServer: tcp(Host=kodohost.mydomain.com, Port=5555) kodo.ConnectionRetainMode: transaction kodo.ConnectionFactoryProperties: MaxIdle=3, ValidationTimeout=60000
Example 11.6. HTTP Client Configuration
JPA XML format:
<property name="kodo.BrokerFactory" value="remote"/> <property name="kodo.PersistenceServer" value="http(URL=http://jdohost.mydomain.com/tomcat/pmserver)"/> <property name="kodo.ConnectionRetainMode" value="transaction"/> <property name="kodo.ConnectionFactoryProperties" value="MaxIdle=3, ValidationTimeout=60000"/>
JDO properties format:
kodo.BrokerFactory: remote kodo.PersistenceServer: http(URL=http://jdohost.mydomain.com/tomcat/pmserver) kodo.ConnectionRetainMode: transaction kodo.ConnectionFactoryProperties: MaxIdle=3, ValidationTimeout=60000
Kodo's built in transport implementations -
http - allow you to wrap their data streams in decorators
to add additional functionality such as data compression and
filtering. Each accepts a
configuration property specifying a semicolon-separated list of
to decorate the input and output streams between the
client and server. Each item in the list can be the full class
name of a custom decorator, or one of the following built-in
gzip: Use gzip compression when
Example 11.7. Enabling Compression with the TCP Transport
On the server, set the
And on the client:
tcp(Host=jdohost.mydomain.com, Port=5555, Decorators=gzip)
Using Kodo's remote features involves deploying Kodo to the server machine as well as one or more client machines. Deploying Kodo on the server is exactly the same as deploying Kodo for local use. You must include all Kodo libraries, your configuration properties file (if you use one), your logging configuration file (again, if you use one), your JDBC drivers, your enhanced persistent classes, your metadata, and your O/R mapping information. All of these topics are covered in other sections of this manual.
Deploying Kodo on the client is also the same as deploying Kodo for local use, with two small exceptions:
JDBC libraries are not required on the client.
O/R mapping information is not required on the client.
Note that you may include the above information in your deployment; it is simply not required.
The Kodo remote package provides a mechanism for your application to
register an object that can listen for transfer events.
Transfer events take place during flush operations as objects
are sent to the server, and when objects are loaded from the server
by extents, queries, or obtaining objects by id.
For more details, please see the javadoc for