Returning Connections to the Java Connection Factory

When you are finished using a connection that you have obtained from the Java Connection Factory, you must return the connection to the factory so that it can be either reused or canceled.

Returning a Connection to the Java Connection Factory

To return a connection to the Java Connection Factory, call the close() method on the connection that was returned when you called the getConnection method.

The objects that implement the IWorkspace interface also have a Close() method. You do not need to call this method when you are closing an object because the close() method on the connection object will call it for you. However, no harm will occur if you call the close() method on both objects.

If you do not explicitly close a connection, it will close itself when it is no longer referenced and is garbage collected. However, you generally cannot determine when or if garbage collection will occur. Therefore, it is recommended that you explicitly close your connection if at all possible rather than depending on garbage collection.

Shutting Down the Java Connection Factory

When you are finished with the instance of the Java Connection Factory itself and you no longer need to request connections from it, you must shut it down so that any remaining connections can be canceled and other resources can be released.

To shut down the Java Connection Factory, call one of the following methods:

• The shutdown() method. This method immediately cancels all idle connections in the pool. If connections are currently allocated to users, the connection factory waits and cancels these connections after the users return the connections to the factory. In addition, the Java Connection Factory will no longer honor new requests for connections.

  After shutdown() has been called, later calls to shutdown() have no effect.
  
  

• The destroy() method. This method immediately cancels connections in the pool, including connections that have been allocated to users. Any attempt to use a connection from the factory will result in an exception. In addition, the Java Connection Factory will no longer honor new requests for connections.

  For user-managed connections, the destroy() method never destroys the connection.

  After destroy() has been called, later calls to shutdown() or destroy() have no effect.

It is often possible to cancel all connections and release all resources in an instance of the Java Connection Factory by calling shutdown() and being sure to call close() on all the connections. However, in some cases you might want to call destroy() instead of (or after) calling shutdown() to ensure that an instance of the Java Connection Factory has been properly cleaned up.

Note: If you are using the PlatformConnectionFactory and the Session Service, you can shut down servers automatically by destroying a session. When you destroy a session, any repository connections associated with the session are destroyed. Additionally, all connection factories that were configured with the repository connections are shut down as with the shutdown() method.