About this task
To write a service, do the following:
- Create a new class extending the Service type.
- Create variables to hold the attributes of the service.
- Create getters and setters for the new attributes.
- Override the initializeFrom(Tag) method.
- Override the toString() method.
- Add the tagName - className relationship in the toolkit configuration
(dse.ini) file.
For example, suppose you already have a class called MyClass. This
class adds two integers and throws a Java event if the result is greater than
some predefined value. The signature of the method that performs the addition
is int addition(int,int). The predefined value is set through the method setMyMaximum(int),
and the Java event MaximumValueExceeded is thrown when the result
of the addition is greater than the value set in setMyMaximum(int). Any class
willing to receive this event implements the interface MaximumValueExceededListener,
which defines the method handleMaximumValueExceededEvent(MaximumValueExceeded
event).
The following example describes how to access the MyClass method(s)
from an application using a service:
- Create a subclass of DSEEventObject, and call it ValueExceeded. This is
the event that the service fires when it receives the MaximumValueExceeded Java event.
There is no need to add any code to this subclass.
- Create a service subclass of Service, and call it MyService. This service
must implement the MaximumValueExceededListener interface, so that it will
receive the Java events generated in MyClass. At this time, do not
code the body of the interface method.
- Create the initializeFrom(Tag) method in MyService. This is the method
that instantiates the service when the toolkit instantiates the context containing
the service. To do this, instantiate MyClass and register the service as a
listener of the MaximumValueExceeded event. The service has the parameter
maxValue, so you can externalize the addition maximum value before the ValueExceeded
event is fired (see the service definition in step 8).
In this example,
assume that there is an instance variable myInst of type MyClass:
public Object initializeFrom(com.ibm.dse.base.Tag aTag)
{
myInst = new MyClass();
myInst.addMaximumValueExceededListener(this);
for (int i=0;i<aTag.getAttrList().size();i++) {
TagAttribute attribute = (TagAttribute) aTag.getAttrList().elementAt(i);
if (attribute.getName().equals("maxValue")) {
myInst.setMyMaximum(Integer.parseInt((String) (attribute.getValue())));
}
}
return this;
}
- Create the toString() method in MyService. This method returns a visual
representation of MyService.
public String toString() {
String s="<"+getTagName()+" ";
s=JavaExtensions.addAttribute(s,"maxValue",
String.valueOf(getMaxValue()));
s=s+">";
return s;
}
- Implement the Java event MaximumValueExceeded interface method in
MyService. This method receives the Java event when the result of the addition(int,int)
method of MyClass is greater than the value specified in setMyMaximum(int),
and throws the ValueExceeded event.
public void handleMaximumValueExceededEvent(MaximumValueExceeded event) {
try {
signalEvent(new ValueExceeded((String)event.getSource(), this));
}catch(DSEInvalidArgumentException e){}
}
- Implement the public methods for the service MyService. In this example,
there is only one method, called add(int,int).
public int add(int a, int b) {
return myInst.addition(a,b);
}
Now, you have a service that deals with MyClass. Note that
MyClass is unchanged. Before using it from an application, you must update
the configuration file and the XML services and contexts files.
- Add MyService in the services section of the dse.ini configuration file.
The id tag specifies the tag name that you will use in the services file to
refer to this service and the value tag specifies the package and class name
where this service is located.
<field id=myService value=com.ibm.dse.service.sample.MyService>
If
the service definition needed subtags (additional tags inside the service
tag), the line above would also contain the attribute description=compound.
In this example, however, there are no subtags.
- Add the service definition in the XML services file. The tag name corresponds
to the value of the id tag in the configuration file. As a service
parameter, include the maxValue value so that the value can be changed
with no code changes.
<myService id=newService maxValue=10>
- Add the service in the context. For the service to be used, it must be
defined in one of the context nodes visible from the operation. The value
of the refId tag corresponds to the value of the id tag in the
XML services file. The value of the alias tag is used by the operation
to locate the service by name. The value of the type tag is used by
the operation to locate the service by type.
<refService refId=newService alias=serv type=srv>
Now,
you can use the service from an operation as in the following example (not
from the sample application):
public void execute() throws Exception {
try {
handleEvent("allEvents","serv",getContext());
((MyService)getService("serv")).add(int1,int2);
stopHandlingEvent("allEvents","serv",getContext());
} catch (Exception e) {
stopHandlingEvent("allEvents","serv",getContext());
throw e;
}
}
You will get the ValueExceeded event through the Handler
dispatchEvent(DSEEventObject anEvent) method of your operation.