The Java control API provides life cycle callback events that you can handle in your control code. Using these callbacks (exposed by the ControlContext.Callback interface), you can anticipate the start and end of your control's use in a container and write code that executes in response. This is useful when your control's logic includes access to a resource. You can use two of the life cycle callback events (onAcquire() and onRelease()) to acquire the resource when you anticipate needing it, and release the resource when the container using your control is nearly finished. Another callback event (onReset()) is useful for resetting state when your control is not in a conversational container.
The basic life cycle for a control goes as follows. First the control container
and control are created. Immediately after this occurs the onCreate()
callback is sent. Second the the onAcquire()
callback is sent
just before any methods are called on the resource. Third, just after the
method or methods are called, the onRelease()
callback is sent.
Finally, after the control and its container has been destroyed, the onFinish()
callback is sent. All of these callbacks are sent from the control container
to the control.
The following list describes the life cycle events that are fired by a control container when called by a stateful client.
Handle this callback to execute code that you might otherwise place in a constructor. Note that you should never use a constructor in a JCS file.
Note that this callback is received when a method of a top-level container is about to execute; in other words, if your control is nested in another control that is itself nested in a conversational web service, then it is the call to the web service's method that will provoke this callback.
You should handle this callback to acquire resources or state that your
control will need for any of its methods. You should release the resource
in the onRelease()
callback handler.
You should handle this callback to release resources you acquired in
the onAcquire()
callback handler.
Handle this callback to reset internal fields to a default state.
Note that controls have different life cycles depending on the client that calls that control.
When a control is called by a stateful process, such as a conversational web service (JWS), the entire conversation is wrapped by a single set of life cycle callbacks.
controlContainer.onCreate()
controlContainer.onAcquire()
myControl.method1()
myControl.method2()
myControl.method3()
controlContainer.onRelease()
controlContainer.onFinish()
When a control is called by a stateless process, such as a Page Flow, each method call is wrapped a single set of life cycle callbacks.
controlContainer.onCreate()
controlContainer.onAcquire()
myControl.method1()
controlContainer.onRelease()
controlContainer.onReset()
controlContainer.onFinish()
controlContainer.onCreate()
controlContainer.onAcquire()
myControl.method2()
controlContainer.onRelease()
controlContainer.onReset()
controlContainer.onFinish()
Code for handling these callbacks goes into your control's JCS file. The following example shows a callback handler for the callback onAcquire(). Notice that the name of the handler is formed form the name of the control context ("context") + an underscore character + the name of the callback you want to handle ("onAcquire").
MyControl.jcs
/**
* @common:context
*/
public ControlContext context; /* * onAcquire is received when a container's operation is about to start. */ public void context_onAcquire() { // Use data retrieved from property attribute values to acquire a WebLogic MBean instance. try { m_localMBean = MBeanUtil.getMBean(m_userName, m_password, m_serverURL, m_serverName); } catch (IllegalArgumentException iae) { context.getLogger("ServerCheck"); throw new ControlException("ServerCheck: Error getting the domain name.", iae); } }