4.1.2. Lifecycle and Caching

After being created using the Cap.connect(...) methods, a connection is open immediately, that is, its methods can be invoked and all read and write accesses to the associate repositories are possible, too. A connection that was created through Cap.prepare(...) starts off closed. It has to be opened by a call to open().

An open connection will stay open until closed explicitly. In particular, an open connection does not become eligible for garbage collection simply by discarding references to it. There are a number of active threads inside a Unified API connection that will keep the connection alive until explicitly closed.

After you have closed the connection, all stateful objects that were retrieved from the connection become nonfunctional, in particular the repositories, services and CapObjects. Immutable objects like strings or markup objects generally remain intact, but blobs become unusable.

Operations on Closed Connections

The only operations that are possible on a closed or not yet opened connection are calls to setters and getters for the connection parameters like user name or password.

Reopening a Connection

You can reopen a closed connection using the method's connection.open(). This should only be done in special cases. Normally, a connection is expected to stay open until the application terminates.

Care must be taken when reopening connections under an Oracle JDK, whose ORB implementation does not properly release its memory and TCP sockets when being closed. Since the Unified API connection must instantiate an ORB for managing the CORBA connection to the servers, this ORB bug can lead to resource problems after repeated sequences of open and close operations. In order to avoid this, you can inject a singleton ORB into the connection, which will then be used continually without being shut down at the close of the connection. 

org.omg.CORBA.ORB orb =
  org.omg.CORBA.ORB.init(new String[0],
    System.getProperties());
Map<String,?> params = new HashMap<String,?>();
params.put(Cap.ORB, orb);
params.put(Cap.USER, "admin");
params.put(Cap.PASSWORD, "admin");
CapConnection connection = Cap.connect(params);

Management of Open Connections

While a connection is open, you can also access the connection's management bean as provided by the getMBean() method. These are the configurable parameters:

Property Value Default Description

heapCacheSize

 long 20000000 the number of bytes to use by the main memory cache

blobCacheSize

 long 10737418240 the number of bytes to use by the disk cache

blobCachePath

 string N/A the location of the disk cache in the file system; this property maps directly to the system property java.io.tmpdir

maxCachedBlobSize

 int Integer.MAX_VALUE the maximum size of a blob that can be cached. Note that the maximum size of a cached blob is implicitly limited by blobCacheSize

blobStreamingSizeThreshold

 int 131072 the threshold for blob sizes above which blobs are streamed instead of being completely downloaded first

blobStreamingThreads

 int 2 the maximum number of threads that is used for streaming large blobs

eventChunkSize

 int 1000 the maximum number of events that is fetched at once from the Content Server when attaching a listener with a historic time stamp

Table 4.2. Parameters of connection's management bean


Reopening Connections

The Unified API also supports the reopening of closed connections. After a connection has been reopened, the listeners have all been removed from the listener sets and blobs may have been rendered unusable, but the repositories, services and CapObjects have returned to their previous state, allowing reads and writes.

The cache object that is associated with the connection does not remain stable. Instead, a new cache object is created whenever the connection is opened.

This makes it possible to create a perpetually running client that releases its licenses when it is idle for an extended period. Of course, the reacquisition of contested licenses may fail, so that this pattern is not suitable for system components with strict availability requirements.

Automatic Reconnect after Server or Network Problems

The Unified API supports reconnects to servers after network problems and even after the servers are restarted. The connection remains open while a reconnect is attempted, but read and write accesses may fail with an exception.

In the case of the content and user repository, the event streams are reestablished and no events are lost. In the case of the workflow repository, events may be lost, but all caches are properly invalidated after the reconnect.

If the document types are changed in any way while the Content Server is down, a reconnect may fail in unexpected ways. Always shut down all clients before modifying the document type declarations.

Prev Up Next
 Home