20 Event Orchestration in the Service Foundation Toolkit

Service Foundation Toolkit (SFT) defines the CommunicationBean as the programming unit through which to implement communication logic. There may be many CommunicationBeans in a single SFT application. A primary function of SFT is routing events among CommunicationBeans, using an event routing module called the orchestration module.

About Event Orchestration

By default, CommunicationBeans receive SFT events. If multiple CommunicationBeans are interested in the same event, SFT sequentially forwards the event to the individual CommunicationBeans. This default behavior does not allow you to customize the invocation sequence.

The orchestration module lets you use one of two ways of defining the orchestration order: an XML-based, or an annotation-based. Both of the orchestration mechanisms allow you to customize the Communication bean's invocation sequence.

When SFT is instantiated, the it performs the following checks to determine which way the invocation order is defined:

SFT searches the WEB-INF directory for the application's deployment descriptor file (sft.xml).

The sft.xml deployment descriptor is a standard XML file and contains markup describing the attributes of all SFT-based applications. Converged Application Server reads the sft.xml file during initialization of the application.
If Converged Application Server discovers the sft.xml deployment descriptor, this one is used.
If there is no sft.xml file, the annotations are used.

Using Annotations to Define the Invocation Order

Use the @EventOrchestration annotation. This annotation must be used in conjunction with the @CommunicationEvent and @ParticipantEvent annotations to identify which events to prioritize.

To assign an event orchestration priority, specify a value using the priority attribute. The orchestrator routes the SFT event according to the priority you specify.

Table 20-1 Attributes of the @EventOrchestration Annotation

Name	Description	Data Type	Required?
priority	Assigns an event orchestration priority. The default value is 100, and the lower the numerical value the higher the event orchestration priority. You can not assign a negative value.	Integer	Yes

Example 20-1 The @EventOrchestration Annotation

@CommunicationBean()
public class MyExampleApplication {
  @Context
  CommunicationContext<?, UserParticipant,?> ctx;
 
  @EventOrchestration( priority=50 )
  @ParticipantEvent(type= ParticipantEvent.Type.JOINING, communicationType = Conversation.class)
  public void hanldeStatedEvent() {
  }  
}

Using XML to Define the Invocation Order

To specify event orchestration using XML, you must deploy a SFT application with the sft.xml deployment descriptor within the application's WAR or SAR file.

Example 20-2 illustrates two instances of the communication-bean element with orchestration priority set to “2” and “1” respectively. Both instances of the CommunicationBean are defined with the ParticipantEvent.Type.JOINING event type. Since the orchestration priority for Bean1 is set to 1, all ParticipantEvent.Type.JOINING events will be directed to Bean1 first, and then to Bean2, whose orchestration priority is set to 2.

Note:

The event type you want the Communication bean to listen for must be specified in both the bean's Java source file using the appropriate annotation, and the sft.xml deployment descriptor. In this example, the ParticipantEvent.Type.JOINING event type must be specified in sft.xml as shown in Example 20-2, and in the bean's Java code using the @ParticipantEvent annotation as shown in Example 20-3.

Example 20-2 Specifying Orchestration Priority in the SFT.XML Deployment Descriptor

<?xml version="1.0" encoding="UTF-8"?>
<sft-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.oracle.com/sdp/sft sft.xsd"
    xmlns="http://www.oracle.com/sdp/sft">
  
  <communication-bean>
         <class-name>com.oracle.sft.test.Bean1</class-name>
         <event communication-type="Conversation" event-type="ParticipantEvent.Type.JOINING">
             <orchestration priority="2" />        
         </event>    
  </communication-bean>
  
  <communication-bean>
         <class-name>com.oracle.sft.test.Bean2</class-name>
         <event communication-type="Conversation" 
          event-type="ParticipantEvent.Type.JOINING">
         <orchestration priority="1" />        
         </event>    
  </communication-bean>  
</sft-app>

Example 20-3 shows the @CommunicationBean annotation with the @ParticipantEvent event type JOINING specified. This must match the configuration specified in the sft.xml deployment descriptor as illustrated in Example 20-2.

Example 20-3 @ParticipantEvent Whose Orchestration Priority

@CommunicationBean()
public class Bean1 {
  @Context
  CommunicationContext<?, UserParticipant,?> ctx;
 
  @ParticipantEvent(type= ParticipantEvent.Type.JOINING, communicationType = 
  Conversation.class, priority = 1)
  public void hanldeStatedEvent() {
  }  
}

Filtering and Overriding Communication Beans

CommunicationBeans are defined using the @CommunicationBean annotation, however, SFT provides a mechanism to override or filter the annotation specified in the bean's Java code.

Filtering Communication Beans

SFT provides Communication beans suitable for most types of applications, however, certain deployments may require a greater amount of flexibility in creating and assigning beans for different event types. To accommodate this, you can filter beans such that only beans with event types that you specify are given event orchestration priority via the orchestration module, and beans with other event types sequentially receive event notifications using the default event orchestration behavior.

To filter beans use the annotation-scanning element in the sft.xml deployment descriptor's to specify which JAR files and Java packages to load. Beans that are not explicitly specified are discarded, even if they are present and in the class path.

Example 20-4 filters beans whose class files are contained in the sft-sample.jar file, and whose package name is com.oracle.sft.MyCommunicationBean. Using these parameters, the following filtering is performed:

If a bean's Java class file is not contained in the sft-sample.jar file, it will be discarded.
If a bean's Java class file is contained in the sft-sample.jar file, and its package name starts with com.oracle.sft.MyCommunicationBean, it will be retained and initialized.
If a bean's Java class file is located in the /WEB-INF/classes directory of the application folder structure, and its package name begins with com.oracle.sft.MyCommunicationBean, it will be retained and initialized.
If no JAR files or packages are specified using the annotation-scanning element, then all Communication beans contained in /WEB-INF/lib/*.jar or /WEB-INF/classes/ are retained and initialized (e.g. no filtering using annotation scanning is performed).

When a bean passes the filtering check performed by the annotation-scanning element, it is initialized by SFT.

Example 20-4 The annotation-scanning element

<annotation-scanning>
     <jars>
          <jar>sft-sample.jar</jar>
     </jars>
     <packages>
         <package>com.oracle.sft.MyCommunicationBean</package>
     </packages>
</annotation-scanning>

Filtering Specific Communication Bean Annotations

You can further limit annotation scanning to CommunicationBeans specified in the sft.xml deployment descriptor. SFT will only perform annotation scanning on the beans specified in the sft.xml deployment descriptor. To enable annotation scanning, set the beanclasses-from-descriptor attribute of the annotation-scanning element to true, as shown in Example 20-5.

Example 20-5 Specifying annotation scanning for a Communication bean

<?xml version="1.0" encoding="UTF-8"?>
<sft-app xmlns="http://www.oracle.com/sdp/sft">
    <communication-bean>
        <name>MyCommunicationBean</name>
        <class-name>com.oracle.example.web.ExampleBean</class-name>
        <event communication-type="Conversation" event-type="CommunicationEvent.Type.STARTED">
            <orchestration priority="0"/>
        </event>
    </communication-bean>
  <annotation-scanning beanclasses-from-descriptor="true"/>
 
</sft-app>

Overriding CommunicationBean Annotations

SFT uses the communication-bean element of the sft.xml deployment descriptor to filter using the annotation specified for a given CommunicationBean. SFT can also override a bean's annotation as defined by the communication-bean element of the sft.xml deployment descriptor. This allows you to override certain attributes of a bean's annotation using the definition of the communication-bean element.

The annotation override includes four bean-related attributes, which are overridden by corresponding sub-elements (or the attribute of a sub-element) of the communication-bean element.

Table 20-2 Overriding CommunicationBean Annotations

Sequence	Attribute defined by annotation	Attribute defined in sft.xml	Override condition
1	Priority of `@EventOrchstration`	`orchestration priority`	Explicitly defined in sft.xml
2	Name of `@CommunicationBean`	`name`	Explicitly defined in sft.xml
3	Type of `@CommunicationBean`	`communication-type`	Explicitly defined in sft.xml
4	Event type for each bean (e.g. `CommunicationEvent` or `ParticipantEvent`)	`event-type`	Explicitly defined in sft.xml

Using the sequence shown in Table 20-2, if both annotation-scanning and communication-bean are explicitly defined in the sft.xml deployment descriptor, the override sequence is as follows:

Filtering is performed as specified by the annotation-scanning element. If a bean's class name is discovered by the annotation-scanning element it overrides sequence rules 2, 3, and 4.
If a bean's class name is discovered by the communication-bean element, it overrides sequence rule 1.