Handling Control Events

Controls allow the specification of event methods. Event methods provide a way for a control to asynchronously notify its client that something has occurred. Event methods are especially useful when you don't want client resources to be bound up with a network request or a long running operation. Instead of forcing the client to waste resources waiting for the control to return a value, the client can disengage from the control and engage in other processes while it listens for an event from the control.

A control event causes something to happen in the client code. When an control event method is triggered it sends an event to the client, causing an event handler (implemented in the client) to execute. The event handler is a method like any other, except that the client code does not determine when it is called; instead the control event method determines when the event handler is executed.

Events and Callbacks

Events and callbacks both have same underlying intent: to provide a way to asynchronously notify client code that something has occurred. The difference between the two technologies is, for the most part, terminological and a question of scope: web services send "callback" messages, controls send "event" messages.

A Control Event Scenario

The diagram below shows a simple control event scenario. The scenario contains two main components: a web service (the client) and a control (used by the client web service). (Notice that only the control interface class is depicted below; the implementation class is not depicted.)

Rightward pointing arrows depict ordinary method calls; leftward pointing arrows depict events and event handlers.

The following sequence explains how the client web service invokes the control and receives an event from the control.

1. The client web service method start is executed, which invokes the control method requestMessage.

ClientWebService.java

    @Control
    private MyControl myControl;
  
    public void start() {
        myControl.requestMessage();
    }

2. The control method requestMessage is executed

Notice that the requestMessage method signature is defined in the control interface class while the method body is defined in the control implementation class. The message body invokes the event method. (See stage 3 below for details on event method syntax.)

MyControl.java (Control Interface)

    public void requestMessage();

MyControlImpl.java (Control Implementation)

    public void requestMessage() {
        
		// Invoke the event method to send the event to the client. 
		eventSet.onMessage("This is a message from the custom control.");
    }

3. The the event method onMessage is invoked an sends an event to the client.

The control interface class exposes the event set interface. Notice that the event set interface must be decorated by the @EventSet annotation. The @EventSet annotation exposes all methods in the interface as event methods: methods capable of triggering the corresponding event handlers in the client.

MyControl.java (Control Interface)

    @EventSet
    public interface MyEventSet {
        void onMessage(String aMessage);
    }

Notice that is there is no implementation of the onMessage event method in either the control interface or implementation classes. Only the event method signature (void onMessage(String aMessage)) exists in the control interface class. This is because the only purpose of an event method is to invoke the event handler in the client and pass data to that handler.

In this scenario, the event method onMessage has one parameter String aMessage, which is transmitted to the client's method handler.

The @Client annotation causes the ControlBean to initialize an implementation of the event interface. This implementation is used to fire events back to the client.

MyControlImpl.java (Control Implementation)

    @Client 
    MyEventSet eventSet;
 
    public void requestMessage() {
        eventSet.onMessage("This is a message from the custom control.");
    }

4. The event handler executes.

ClientWebService.java

    @EventHandler(field = "myControl", eventSet = MyControl.MyEventSet.class, eventName = "onMessage")
    protected void myControl_MyEventSet_onMessage(String aMessage) {
        System.out.println("Got message from myControl: " + aMessage);
    }

The @EventHandler annotation provides the pathway that allows the control event method onMessage to invoke the client's event handler method. Notice that the @EventHandler contains all of the information necessary to indicate which event method the handler is sensitive to: the target control, the event set, and the particular event in that event set.

The event handler name can be anything (because the @EventHandler annotation does all of the work of sensitizing the handler to the appropriate event method). By convention we have named the event handler according to the following rule:

<control-reference-field-name>_<event-set-name>_<event-name>

Workshop for WebLogic uses this naming rule by default when a event handler is added to a client class using Right-click > Insert > Control Event Handler.

Note that the parameter set of the event method must match the parameter set of the event handler for the event handler to be successfully invoked. In the above example, both the event method and its handler have matching parameter sets, namely, one String parameter:

    @EventSet
    public interface MyEventSet {
        void onMessage(String aMessage);
    }

    @EventHandler(field = "myControl", eventSet = MyControl.MyEventSet.class, eventName = "onMessage")
    protected void myControl_MyEventSet_onMessage(String aMessage) {
        ...
    }

Control Event Set Definition

An event set definition in a control consists of two elements:

(1) An @EventSet declaration on the event set interface:

MyControl.java

    @ControlInterface
    public interface MyControl {
    
        public void requestMessage();
	    
        @EventSet
        public interface MyEventSet {
            void onMessage(String aMessage);
       }
   
    }

Multiple event methods may be defined in the @EventSet declaration:

MyControl.java

    @ControlInterface
    public interface MyControl {
    
        public void requestMessage();
	    
        @EventSet
        public interface MyEventSet {
            void onMessage(String aMessage);
            void onReady(boolean boolReady);
       }
   
    }

(2) A @Client declaration in the control implementation:

MyControlImpl.java

    @Client MyEventSet eventSet;

For events to be sent, you must invoke the event method somewhere within the control implementation.

    public void requestMessage() {
        eventSet.onMessage("This is a message from the custom control.");
    }

Note that the event method definition has no body -- only the method signature, including the return type and any parameters.

It is common for event methods to have names that begin with on because the event handler in the client will be called on occurrence of the event.

Event Handler Definition

The client application is responsible for implementing the handler for a control's event method.

The following shows an example of a event handler as it might appear in a client application:

    @EventHandler(field = "myControl", eventSet = MyControl.MyEventSet.class, eventName = "onMessage")
    protected void eventHandler(String aMessage) {
	  
        // do something with the message here ...
		  
    }

For the event handler to successfully listen for an associated event, the following two conditions must be fulfilled:

(1) The @EventHandler annotation must point at the appropriate control, event set, and event.

This means that the field attribute must refer to the control field as it is declared in the client. Suppose the control field is declared as so:

    @Control
    private MyControl myControl;

Then the @EventHandler must refer to this field:

   @EventHandler(field = "myControl",

The @EventHandler must also refer to the EventSet and the particular event method as they are defined on the control. Suppose the control defines the following EventSet and event method:

    @EventSet
    public interface MyEventSet {
        void onMessage(String aMessage);
    }

Then the @EventHandler must refer to the EventSet and event method as so:

    @EventHandler(field = "myControl", eventSet = MyControl.MyEventSet.class, eventName = "onMessage")

(2) The event method and its handler must have matching parameter sets. That is, the number of parameters, their order, and their types must match. For example, the following event method and handler have matching parameter sets.

    @EventSet
    public interface MyEventSet {
        void onMessage(String aMessage, boolean status);
    }

    @EventHandler(...)
    protected void eventHandler(String aMessage, boolean status) {

Limitations for External Events

External events are supported only for web service clients. Other clients cannot cannot handle event notification over a network protocol.

Adding Event Sets and Event Handlers with Workshop for WebLogic

The following commands are available for adding event sets and event handlers.

To Add an Event Set

To add an event set to a control, right-click anywhere within the control interface source view and select Insert > Event Set. By default an event set interface named NewEventSet with one event method, named onEvent1(), is added to the control interface:

SomeControl.java

    @EventSet
    public interface NewEventSet {
        void onEvent1();
    }

And the corresponding @Client declaration is added to the control implementation file:

SomeControlImpl.java

	   @Client 
    NewEventSet eventSetClient;

You must manually rename default the event set and event method names. Add additional event methods as necessary.

To Add an Event Handler

To add an event handler to a control client, right-click anywhere in source view and select Insert > Control Event Handler. A dialog will appear presenting you with the controls declared on the client and the events exposed by those controls. Select the control, event set, and particular event method to construct an event handler for that event method.

An event handler will be added to your client's source:

    @EventHandler(field = "myControl", eventSet = MyControl.MyEventSet.class, eventName = "onMessage")
    protected void myControl_MyEventSet_onMessage(String aMessage) {
	  
    }