11.2. Remote Managers

11.2.1. Standalone Persistence Server
11.2.2. HTTP Persistence Server
11.2.3. Client Managers
11.2.4. Data Compression and Filtering
11.2.5. Remote Persistence Deployment
11.2.6. Remote Transfer Listeners

In Kodo, each factory maintains a set of resources shared by all the EntityManagers or 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 PersistenceManagers or 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 each client.

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.

The EntityManagers and PersistenceManagers in these applications will then connect back to the server that they were downloaded from in order to access the database.

11.2.1. Standalone Persistence Server

To configure a factory act as a standalone server to remote clients, the factory's kodo.PersistenceServer configuration property to a plugin string (see Section 2.4, “Plugin Configuration”) describing the com.solarmetric.remote.Transport implementation to use for remote communication. You can implement your own Transport, or use one of the bulit-in options:

  • false: The default value. No server is started.

  • tcp: An alias for com.solarmetric.remote.TCPTransport , 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 localhost. 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 timeout.

    • Decorators: See 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:

kodo.PersistenceServer: tcp(Port=5555)

The kodo.remote.Remote class 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...
    // 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...
    // 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, kodo.jdbc.kernel.StartPersistenceServer, or through the provided startserver command-line script. The script accepts the standard Kodo command-line arguments outlined in Section 2.3, “Command Line Configuration”.

Example 11.4. Starting a Standalone Persistence Server

startserver -p server.properties

11.2.2. HTTP Persistence Server

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 kodo.remote.PersistenceServerServlet . You can deploy this servlet into any standards-compliant servlet container.

The PersistenceServerServlet services remote requests using an internal factory. The servlet provides several mechanisms for configuring this factory:

  1. First, the servlet checks the value of the kodo.jndi servlet initialization parameter (servlet initialization parameters are specified in the standard web.xml deployment file; see your servlet container documentation for details). If the value of this parameter is non-null, Kodo attempts to look up the kodo.kernel.BrokerFactory at the indicated JNDI location. (A BrokerFactory is the native Kodo component that underlies every PersistenceManagerFactory or EntityManagerFactory.)

  2. If the kodo.jndi initialization parameter is not set, Kodo checks the kodo.properties initialization parameter. The value of this parameter is a resource path to an JPA XML or a JDO properties file containing Kodo configuration properties.

  3. 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 ejb or 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.

11.2.3. Client Managers

Client EntityManagers and 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 manager's cache.

You obtain client EntityManagers and PersistenceManagers in the same way you obtain local managers: from an EntityManagerFactory or PersistenceManagerFactory that you have constructed through JCA or the Persistence helper / JDOHelper 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 remote.

  • The kodo.PersistenceServer setting is used to find the remote server. If you are using a standalone server, the value of this property is typically the same as its value on the server. If you are using the HTTP servlet , the value of this property on the client is:


    http in the setting above is an alias for the com.solarmetric.remote.HTTPTransport , whose 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”.

  • The kodo.ConnectionRetainMode property 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 database connections:

    • always: Each client manager obtains a single connection to its server-side counterpart and uses this connection until it is closed.

    • 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.

  • kodo.ConnectionFactoryProperties controls 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 to validate the connection (subject to the TestOnReturn, TestOnBorrow, and other test settings). Set to none to ignore the fact that the connection has thrown an exception, and assume it is still usable. Defaults to destroy.

    • 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 to 8.

    • MaxWait: The maximum number of milliseconds to wait for a free connection to become available before giving up. Defaults to 3000.

    • MinEvictableIdleTimeMillis: The 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 true.

    • TestOnReturn: Set to true to validate connections when they are returned to the pool.

    • TestWhileIdle: Set to true to periodically validate idle connections.

    • TimeBetweenEvictionRunsMillis: The number of milliseconds between runs of the eviction thread. Defaults to -1, meaning the eviction thread will never run.

    • ValidationTimeout: The minimum number of milliseconds that must elapse before a connection will ever be re-validated. This property is usually used with TestOnBorrow or TestOnReturn to 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 exception to immediately throw an exception. Set to block to block until a connection is available or the maximum wait time is exceeded. Set to grow to automatically grow the pool. Defaults to block.

    Remember that persistent connections to the server consume server-side resources, and therefore should be minimized if possible. To disable pooling altogether, set MaxActive to 0.

  • 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 local kodo.ConnectionUserName and kodo.ConnectionPassword 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

11.2.4. Data Compression and Filtering

Kodo's built in transport implementations - tcp, http - allow you to wrap their data streams in decorators to add additional functionality such as data compression and filtering. Each accepts a Decorators configuration property specifying a semicolon-separated list of com.solarmetric.remote.StreamDecorators 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 aliases:

  • gzip: Use gzip compression when transferring data.

Example 11.7. Enabling Compression with the TCP Transport

On the server, set the kodo.PersistenceServer property to:

tcp(Port=5555, Decorators=gzip)

And on the client:

tcp(Host=jdohost.mydomain.com, Port=5555, Decorators=gzip)

Example 11.8. Enabling Compression with the HTTP Transport

In the server properties file / servlet configuration, set the kodo.PersistenceServer property to:


And on the client:

http(URL=http://jdohost.mydomain.com/tomcat/pmserver, Decorators=gzip)

11.2.5. Remote Persistence Deployment

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:

  1. JDBC libraries are not required on the client.

  2. 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.

11.2.6. Remote Transfer Listeners

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 kodo.remote.RemoteTransferListener.


Skip navigation bar   Back to Top