The Web Service Life Cycle
Stefan Burwitz, Senior Engineer @ Cape Clear
The purpose of this article is twofold:
- To increase the understanding of the Web service life cycle and state management mechanisms used by Cape Clear Server.
- To provide insights into how you can use this knowledge to your advantage when developing and deploying Web service applications.
Activation is the process of creating or making a Web service instance active to serve a Web service request. The way in which the activation process is controlled is called the activation policy. The process of activation enables a Web service instance hosted by Cape Clear Server to hold session state.
Following are the supported activation policies and the main attributes of each policy:
- Application - One instance of the service is created to handle all requests. If the timeout is set to zero, the same instance will always be in memory. If the timeout period is set to some non-zero value, the instance will be removed from memory if it has not been used for a period of time equal to the timeout period. When a request is received and the instance has expired, a new instance is created. The service implementation must be thread-safe. This model should be used where only application state or no state is required and performance is important.
- User - An instance of the service is created to handle all requests for a particular user. The client must first be authenticated with the server to use this policy type. The instance is removed from memory when no requests have been received from the user for a period of time equal to the timeout. A user may be logged into the server more than once simultaneously, but effectively the user has only one active session. Each request for that user will always use the same instance. The user activation policy uses the user name Principal as a basis for allocating Web service instances. Use this model when only one instance is to process requests for a particular authenticated user.
- Session - An instance of the service is created to handle all requests for a particular user session. This does not require a client to authenticate with the server first. A user can have many sessions active simultaneously. If a request has no session ID, a new session ID is created and used to associate the instance with the session. On response, for the HTTP transport, the session ID is stored as a cookie on the client. All future requests from the client will send the session ID cookie, ensuring that the correct instance is invoked on the server. Use this model if general session behavior is required and the service must maintain state, or to increase performance by allocating a single instance to a particular session.
- Request - An instance is created to handle each request. After handling the request, the instance is discarded. Use this model if no state is required, the implementation is not thread-safe, and performance is not critical. This policy is the most expensive, because it causes more Java objects to be created (and ultimately garbage-collected), and each instance must be initialized on every request. This is the default policy assigned to Web Services.
Note that a timeout value less than or equal to zero means that an instance never expires. The activation policy and timeout value are configured in the Web service deployment descriptor (ws-application.xml).
To ensure that Web services hosted by Cape Clear Server are properly initialized before they are invoked (that is, before they service a request) and destroyed in a controlled fashion, a Web service implementation class should implement the JAX-RPC javax.xml.rpc.service.ServiceLifecycle interface. This interface provides initialize, create, and destroy methods, which are called at the appropriate points in the Web service life cycle.
During initialization, an application context object is passed to the service. The application context provides information such as the server home directory, the application base directory, and the temporary/working directory, as well as access to the server module registry and the Web service initialization parameters from the deployment descriptor (ws-application.xml).
The JAX-RPC javax.xml.rpc.service.ServiceLifecycle interface is defined as:
interface ServiceLifecycle {
void init(Object context);
void destroy();
}
Following is an example Web service:
import com.capeclear.capeconnect.application.ServerApplicationContext;
import javax.xml.rpc.service.ServiceLifecycle;
public class MyWebService implements ServiceLifecycle {
private boolean debug;
private String name;
/**
* NOT exposed as a Web service operation
*/
public void init(Object context) {
ServerApplicationContext appctx = (ServerApplicationContext) object;
Map params = appctx.getInitParams();
debug = Boolean.valueOf((String) params.get("debug")) .booleanValue ();
name = (String) params.get("name");
...
}
/**
* NOT exposed as a Web service operation
*/
public void destroy() {
//free any resources
}
/**
* Method exposed as a Web service.
*/
public String getName() {
if (debug) {
System.out.println("MyWebService.name="+name);
}
return name;
}
...
}
The activation policy of a Web service can be changed after deployment using Cape Clear Manager. In some cases, this is not a problem, however, be aware of the effect this may have on the Web service behavior. Java Web service implementations will normally be designed and developed with a specific type of threading behavior.