# 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.

- onCreate() — Received after a new instance of the control's top-level container has been created and system initialization (of context object and contained controls) has completed.

  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.

- onAcquire() — Received after the top-level container's operation has been called but before the call to the control. For example, if your control is in a conversational web service, this callback will be received when one of the conversation operations is about to execute.

  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.

- onRelease() — Received as a conversation operation of the control's container is finishing execution.

  You should handle this callback to release resources you acquired in the `onAcquire()` callback handler.

- onReset() — Received after the control's container has finished executing, but only if the container is stateless -- meaning non-conversational.

  Handle this callback to reset internal fields to a default state.

- onFinish() — Received just after a top-level container's conversation has finished. For example, if your control is in a conversational web service, this callback will be received just after that service's conversation ends.

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