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:

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.