Returning a Workspace to the Workspace Factory

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

To return a workspace object to the Java Workspace Factory, call the close() method on the WorkspaceConnector object that was returned when you called the getWorkspaceConnector() method.

Workspace objects themselves (the objects that implement IWorkspace) also have a Close() method. You do not need to call this method when you are closing a workspace object, because the close() method on the WorkspaceConnector 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 WorkspaceConnector object, 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 WorkspaceConnector objects if at all possible rather than depending on garbage collection.

Shutting Down the Java Workspace Factory

When you are done with the instance of the Java Workspace Factory itself and you no longer need to request workspace objects 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 Workspace 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 method waits and cancels these connections after the users return the workspace objects to the factory. In addition, the Java Workspace Factory will no longer honor new requests for workspace objects.

  Once 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 Workspace Factory will no longer honor new requests for workspace objects.

  Once 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 Workspace Factory by calling shutdown() and being sure to call close() on all the WorkspaceConnector objects. However, in some cases it may be desirable to call destroy() instead of (or after) calling shutdown() to ensure that an instance of the Java Workspace Factory has been properly cleaned up.

Example

The following example shows how to return a workspace object to the Java Workspace Factory and how to shut a Java Workspace Factory down.

import com.sas.iom.WorkspaceConnector;
import com.sas.iom.WorkspaceFactory;
import com.sas.iom.SAS.IWorkspace;
import java.util.Properties;

Properties iomServerProperties = new Properties();
iomServerProperties.put("host",host);
iomServerProperties.put("port",port);
iomServerProperties.put("userName",user name);
iomServerProperties.put("password",password);
Properties[] serverList = {iomServerProperties};

WorkspaceFactory wFactory = new WorkspaceFactory(serverList,null,null);
WorkspaceConnector connector = wFactory.getWorkspaceConnector(0L);
IWorkspace workspace = connector.getWorkspace();

< insert workspace usage code here >

wFactory.shutdown();
connector.close();

In the preceding example, exception handling statements have been removed for the sake of clarity.

In the code example above (and in other code examples in our documentation), the final call to the close() method on the WorkspaceConnector object occurs after the call to shutdown() the Java Workspace Factory. This pattern displays a useful optimization that you should take advantage of whenever possible. If the WorkspaceConnector object is closed after the Java Workspace Factory is shutdown, the Java Workspace Factory does not have to decide what to do with the returned connection. It can always be canceled immediately.