This page describes how to write a custom task. To better illustrate the topic, we provide instructions based on the example.
The created task will read a text file at a specified location and places orders for stocks that are given in the text file is created. The text file has entries such as this one:
Each line in the text file contains details for a stock order:
The "PlaceStockOrderTask" will read the text file, a line at a time, and create orders using the given values to be sent to a sample Axis2 server. The text file will then be tagged as processed to include a system time stamp. The task will be scheduled to run every 15 seconds.
The main steps while writing a task are as follows:
- Write the Task class
- Customize the task
- Compile and bundle the task
- Add the task to the WSO2 ESB class path
- Configure and schedule the task in ESB Console
Step 1. Write the Task Class
PlaceStockOrderTask class implements
org.apache.synapse.startup.Task. Each task should therefore implement the
Task interface. This interface has a single
execute() method. This method contains the code that is to be run at the specified intervals.
execute() method contains the following actions:
- Check whether the file exists at the desired location.
- If it does, then read the file line by line composing place order messages for each line in the text file.
- Individual messages are then injected to the synapse environment with the given
- Set each message as
OUT_ONLYsince it is not expected any response for messages.
In addition to the
execute() method, it is also possible to make the class implement a
JavaBean interface. The WSO2 ESB console can then be used to configure the properties of this
The complete code listing of the Task class is provided below:
When creating the customized schedule tasks, if the injecting sequence of the message flow contains Publish Event mediators, set the following property in the Synapse message context:
Also, add the following dependency to the
POM file of the custom task project:
WSO2 Carbon - Utilities bundle (symbolic name:
This is a bean implementing two properties -
StockFile. These are used to configure the task.
ManagedLifecycle for Initialization and Cleanup
Since a task implements
ManagedLifecyle interface, ESB will call the
init() method at the initialization of a
Task object and
destroy() method when a
Task object is destroyed:
PlaceStockOrderTask it is stored the Synapse environment object reference in an instance variable for later use with the
init() method. The
SynapseEnvironment is needed to inject messages into the ESB.
Step 2. Customize the Task
It is possible to pass values to a task at run time using property elements. In this example, the location of the stock order file and its address was given using two properties within the
The properties can be:
- String type
- OMElement type
For OMElement type, it is possible to pass XML elements as values in the configuration file.
When creating a
Task object, WSO2 ESB will initialize the properties with the given values in the configuration file.
For example, the following properties in the
are initialized with the given values within the property element of the task in the configuration.
For those properties given as XML elements, properties need to be defined within the
Task class using the following format:
It can be initialized with an XML elmenent as follows:
Step 3. Compile and Bundle the Task
Assemble the compiled class Task as a JAR file.
Step 4. Add to the WSO2 ESB Class Path
After compiling and bundling the
Task class, you need to add it to the WSO2 ESB class path. Place the JAR file to the
repository/components/lib directory of the ESB.
Task class will be available for use from the next time you start WSO2 ESB.
It is required to restart the ESB for the JAR containing the task implementation to be picked up by the server runtime. An OSGi bundle containing the task implementation will be created automatically and it will be deployed in the server.
Step 5. Configure and Schedule in ESB Console
After adding the
Task class to class path and restarting the WSO2 ESB, you can add configuration settings using the ESB console. Follow the steps given below (for the detailed information on how to schedule tasks see Adding and Scheduling Tasks):
1. Log in to the ESB console.
2. Click the "Main" button to access the "Manage" menu.
3. Click "Scheduled Tasks" in the "Manage" group.
4. Click "Add Task."
5. The "New Scheduled Task" page will open. Enter "placeOrder" as "Task Name."
6. Enter "org.wso2.esb.tutorial.tasks.PlaceStockOrderTask" as "Task Implementation."
7. Click "Load Task Properties."
8. ESB console will load the custom
Task class and show you the properties it finds.
9. Enterfor "To" property. Keep property type as "Literal."
10. Copy the
stockfile.txt to a new directory. The
stockfile.txt will contain the following entries:
stock.txt file location for the
stockFile property. Keep property type as "Literal."
11. Select the "Trigger Type" as "Simple."
12. Enter 15000 to "Interval."
13. Click "Schedule."