Writing extensions in flow

The following sections of this article provide information about writing extensions in the flow language.

1. Creating an extension activity
2. Setting activity work in the handler
3. Writing output data
4. Handling exceptions
5. Global context reference for Assemble flow

Creating an extension activity

To create an extension activity using the Assemble flow language, use the following steps:

1. Decide what you want your activity to look like and document it in normal text for users. You do not need to create a schema, just list what attributes it should have, how many input elements and whether or not they must be named.

   You might want to create a new activity called add, for example, that has the mandatory name attribute, the optional outputVariable attribute, and one or more unnamed input sub-elements.

2. Choose a name for the new extension activity. This is also the name of the corresponding IBM® WebSphere® sMash event.
3. Create a handler that has an on[ActivityElementName]Activity method.

   For example, for the add activity you would create an MathActivityHandler class and it would have a method public void onAddActivity(){...}. If you later decide to also do a multiple activity, then you would add a onMultiplyActivity method.

4. Register the event handler in the zero.config file. The add activity would look like the following example:

   /config/handlers += [{
   	"events" : "addActivity",
   	"handler" : "mypackage.MathActivityHandler.class"
   }]
   

5. In your handler, do the work of the activity as described in the following section.

Setting activity work in the handler

To get the data for the activity, use the global context. Using the global context, you You can retrieve the following information:

• Data that was provided as attributes in the process definition with the following statement:

  GlobalContext.zget("/event/attributes#[attributeName]")
  	

  For example, if you wanted to get the url from add, you would use the following statement to do so:

  GlobalContext.zget("/event/attributes#url")
  

• Values of all input elements (regardless of their names) as an ordered list. The order respects the order of the input elements in the process definition. Input values are evaluated before they are placed in the global context. This list is retrieved from .zget("/event/inputs"). The add inputs, in this example, are not named, so this is exactly how you would get them.
• Values of input elements with names as a map. Input values are evaluated before they are placed in the global context. This value could be retrieved by GlobalContext.get("/event/inputMap#[inputName]") as shown in the following example:

  	<input name="x" value="${addRcv.num[0]}"/>
  	<input name="y" value="${addRcv.num[1]}"/>
  	

  You can get the value of input x by GlobalContext.zget("/event/inputMap#x").

A handler example

In the following example, assume that you provide the following add handler:

package myPackage;
import java.util.List;
import zero.core.context.GlobalContext;

public class MathActivityHandler {
    public void onAddActivity()
    {
        double sum = 0d;
        List values = GlobalContext.zget("/event/inputs");
        for (Object value : values)
        {
            sum += Double.valueOf(value + "");
        }
        GlobalContext.zput("/event/result", sum);
    }
        
}

A process, like the one shown in the following example, would then cause the handler to run when the add is encountered:

<process name="addExtProcess" >
   <receiveGET name="addRcv"/>
   <add name="adder">
     <input value="${addRcv.num[0]}"/>
     <input value="${addRcv.num[1]}"/>
   </add>  
   <replyGET name="addReply">        
     <input value="${adder}"/>
   </replyGET>
</process>

Assume that you have placed the process in public/addext and run WebSphere sMash application on port 8080. Then, the http://localhost:8080/samples/addext/?num=123&num=456 URL would display a Web page with 579.0.

Of course, add is not the most compelling of extension activities because you can add it in Groovy or Javascript™ (see the add sample) but it is used here to show you the simple steps in creating an extension activity.

Writing output data

If your extension activity writes output data, it must be written to the proper place in the global context. You can put your extension activity result in the /event/result directory and you can also put its contentType in the "/event/resultContentType" directory for further usage, as shown in the following example:

GlobalContext.zput("/event/result", result);
GlobalContext.zput("/event/resultContentType", "text/xml");

There are several classes in the zero.assemble.flow.activity.handler package that you can use to guide you as you create your own extension activities.

Handling exceptions

Any thrown exception from an extension activity is caught by the flow engine, which can be referenced by an explicit exception variable and error link. You can throw an exception in an activity implementation directly, and then use the error link or reference exception variable explicitly in the flow for error handling. If there is no error link or exception variable referencing for an activity exception, the flow fails.

Global context reference for Assemble flow

More information about the global context for the WebSphere sMash runtime can be found in the reference section of Developer's guide in the global context article.