Handling Control Life Cycle Events

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.

Life Cycle Patterns

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.

Note that controls have different life cycles depending on the client that calls that control.

Controls Called from Stateful (Conversational) Processes

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()

Controls Called from Stateless (Non-conversational) Processes

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()

Syntax for Handling Life Cycle Callbacks

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); } }

Related Topics

Control Lifetime Considerations when Invoking Controls from Page Flows