com.groiss.wfxml
Interface MessageListener

All Known Implementing Classes:

MessageListenerAdapter

public interface MessageListener

Implement this interface in order to be notified when request messages arrive. Usually the receiver calls before methods before an incoming message will be processed. In the before method you can decide if you want that the message will be processed or not, by returning a boolean value. If there is only one listener for an incoming message, the message will be processed if this listener wants it to be processed or not. If there are more than one listeners, all listeners must agree to process the request. If one of the listeners vetos, the request will not be processed and a response message containing a WfXMLException will be generated (main code: WfXMLException.WF_OTHER, and sub code WfXMLException.WF_OTHER_LISTENER_VETOED).

After all before methods have been called and the message may have been processed (depends on the results of the before methods), a after method is called for some message types. Read the comments for each method to get more details. Again, the after methods of all registered listeners will be called. So, e.g., the response can be modified multiple times, if more than one listener exists.

If you don't want to implement all methods, you should extend the MessageListenerAdapter and overwrite the methods that you are interested in.
Use the WfXML class to register and unregister message listeners.

Method Summary

void	after(ChangePIStateMessage request, ProcessInstance pi, WfXMLMessage response) This message will be called after a ChangeProcessInstance request has been processed.
void	after(CreatePIMessage request, ProcessInstance pi, WfXMLMessage response) This message will be called after a CreateProcessInstance request has been processed (i.e., the process instance and all content have been created).
void	after(GetPIDataMessage request, ProcessInstance pi, WfXMLMessage response) This message will be called after a GetProcessInstanceData request has been processed.
boolean	before(ChangePIStateMessage request) A ChangeProcessInstanceState request has arrived.
boolean	before(CreatePIMessage request) You get a CreateProcessInstance request before it will be processed by the WfXML layer.
boolean	before(GetPIDataMessage request) A GetProcessInstanceData request has arrived.
boolean	before(NotifyMessage request) A Notify message has arrived.
boolean	before(PIStateChangedMessage request) A ProcessInstanceStateChangedMessage has arrived.
WfXMLMessage	handle(GenericMessage request) The WfXML layer uses some generic messages for the communication between active and passive servers.

Method Detail

handle

WfXMLMessage handle(GenericMessage request)

The WfXML layer uses some generic messages for the communication between active and passive servers. If you want, you can use your own generic messages, too. These messages will not be processed by the WfXML layer in any way, but this handle method of registered listeners will be called. In this method you can handle the request and generate an answer message. Return the answer (which can be any WfXMLMessage), or null if you don't want to return an answer.

As there can be more than one listeners, the WfXML layer will give the request to the listeners until one of them creates an answer (because it is impossible to return multiple responses to one request). So you should ensure that on each server there is only one listener that creates responses for a special kind of generic message request. Otherwise it will be not sure which listener will create the response.

Please mind that these generic messages are not part of the WfXML specification.

Parameters:

request - The incoming request message.

Returns:

You should generate a return message (in most cases this will also be a GenericMessage). If you don't want to send a response, simply return null.

before

boolean before(CreatePIMessage request)

You get a CreateProcessInstance request before it will be processed by the WfXML layer. The WfXML layer will create a new process instance and attach/add all DMSObjects that are defined in the request message. If you want, you can modify the content of the request message here, before it will be processed. If you want to prevent the request to be processed, return false.

Parameters:

request - The incoming CreateProcessInstance request.

Returns:

true if you want that the WfXML layer processes the message or false if the message should not be processed.

before

boolean before(GetPIDataMessage request)

A GetProcessInstanceData request has arrived. Again, you can modify the request before it will be processed and you can decide if the request will be modified at all.

Parameters:

request - The incoming GetProcessInstanceData request.

Returns:

true if you want that the WfXML layer processes the message or false if the message should not be processed.

before

boolean before(ChangePIStateMessage request)

A ChangeProcessInstanceState request has arrived. You can modify the request before it will be processed and you can decide if it will be processed at all.

Parameters:

request - The incoming ChangeProcessInstanceState request.

Returns:

true if you want that the WfXML layer processes the message or false if the message should not be processed.

before

boolean before(PIStateChangedMessage request)

A ProcessInstanceStateChangedMessage has arrived. This message is only sent to registered process instance observers of the remote process instance (ProcessInstanceObserver). You can read the request here and decide if observers on the local server will be notified about this request or not. In general you should always let observers be notified.

Parameters:

request - The incoming ProcessInstanceStateChanged request.

Returns:

true if you want that the WfXML layer passes the message on to registered ProcessInstanceObservers or false if the message should not be given to observers.

before

boolean before(NotifyMessage request)

A Notify message has arrived. Like the ProcessInstanceStateChanged message, Notify messages are also only sent to registered process instance observers. You can read (and also change) the Notify request before it will be passed on to registered observers and you can decide if it will be passed on to observers at all.

Parameters:

request - The incoming Notify request.

Returns:

true if you want that the WfXML layer passes the message on to registered ProcessInstanceObservers or false if the message should not be given to observers.

after

void after(CreatePIMessage request,
           ProcessInstance pi,
           WfXMLMessage response)

This message will be called after a CreateProcessInstance request has been processed (i.e., the process instance and all content have been created). You get the request, the newly created process instance and the generated response message here. You can do modifications to the process instance and you can modify the response message (it will be sent afterwards...). Mind, that the response message may be null if the requester didn't require a response.

Parameters:

request - The request that has been processed.

pi - The new process instance.

response - The response message that will be sent back to the requester, or null if no response will be sent. The response will be most likely of type CreatePIMessage.

after

void after(GetPIDataMessage request,
           ProcessInstance pi,
           WfXMLMessage response)

This message will be called after a GetProcessInstanceData request has been processed. As parameters, you get the request, the process instance of which data has been requested, and the response message. You can modify the response message, which will be sent afterwards.

Parameters:

request - The request message that has been processed.

pi - The process instance of which data has been requested.

response - The response message that will be sent back to the requester. Here the response message should always be available, because a GetProcessInstanceData request requests data and so the response returns the requested data. The response will be of type GetPIDataMessage in most cases.

after

void after(ChangePIStateMessage request,
           ProcessInstance pi,
           WfXMLMessage response)

This message will be called after a ChangeProcessInstance request has been processed. You get the request message, the process instance that has been affected, and the response message that will be returned.

Parameters:

request - The request message that has been processed.

pi - The affected process instance.

response - The response message that will be sent back to the requester. For this message type the response contains the new process instance state, so a response should always exist. The response message will be most likely of type ChangePIStateMessage.