com.groiss.wfxml

Class NotifyMessage

java.lang.Object

com.groiss.wfxml.WfXMLMessage

com.groiss.wfxml.NotifyMessage

public class NotifyMessage
extends WfXMLMessage

Notify messages are used to inform process instance observers about arbitrary events or other things. Observers must implement the ProcessInstanceObserver interface and be added to CreatePIMessage messages when remote process instances are created.
When you create notify message, you must set the process instance oid of the process instance from which you send the notify message with the setProcessInstanceKey(java.lang.String) method. Then you send the message with the Sender's Sender.send(WfXMLMessage,Class,boolean) method. This method searches for an observer and sends the message to the right observer, so you don't need to care about finding observers at all.
This message type has various getParameter and setParameter methods for using parameters. Parameters can be defined individually according to your needs.

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	MSG_BODY_REQ
protected static String	MSG_BODY_RESP

Fields inherited from class com.groiss.wfxml.WfXMLMessage

body, CONTEXTDATA_DOCUMENTCREATOR, documentCreator, documentCreatorId, header, message, MSG_BODY, MSG_BODY_CTXDATA, MSG_BODY_CTXDATA_DMSFOLDER, MSG_BODY_CTXDATA_NOTES, MSG_BODY_CTXDATA_PROCESSFORMS, MSG_BODY_CTXDATA_PROCESSFORMS_NAME, MSG_BODY_EXC, MSG_BODY_EXC_DESC, MSG_BODY_EXC_MAINCODE, MSG_BODY_EXC_SUBCODE, MSG_BODY_EXC_SUBJECT, MSG_BODY_EXC_TYPE, MSG_BODY_RSLTDATA, MSG_BODY_RSLTDATASET, MSG_BODY_SET_NAME, MSG_BODY_SET_PARAM, MSG_BODY_SET_VALUE, MSG_HEAD, MSG_HEAD_KEY, MSG_HEAD_REQ, MSG_HEAD_RESP, MSG_HEAD_RESPREQUIRED, MSG_HEAD_RESPREQUIRED_NO, MSG_HEAD_RESPREQUIRED_ONERROR, MSG_HEAD_RESPREQUIRED_YES, MSG_ROOT, MSG_TRANSPORT, MSG_TRANSPORT_CORDATA, MSG_TRANSPORT_CORDATA_OID, MSG_TRANSPORT_CORDATA_ORIGIN, MSG_TRANSPORT_CORDATA_TIMESTAMP, MSG_VERSION, namespace, PI_STATE_CLOSED_ABNORMAL_COMPLETED, PI_STATE_CLOSED_ABNORMAL_COMPLETED_STR, PI_STATE_CLOSED_COMPLETED, PI_STATE_CLOSED_COMPLETED_STR, PI_STATE_NONE, PI_STATE_OPEN_NOTRUNNING, PI_STATE_OPEN_NOTRUNNING_STR, PI_STATE_OPEN_RUNNING, PI_STATE_OPEN_RUNNING_STR, REQUEST, RESPONSE, RESPONSE_NOT_REQUIRED, RESPONSE_REQUIRED, RESPONSE_REQUIRED_ONERROR, root, transport, usingPlainKey

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	NotifyMessage(Document doc) This method is used internally for creating a NotifyMessage out of a xml document.
	NotifyMessage(short messageType) Creates a new and empty NotifyMessage object.

Method Summary

Modifier and Type	Method and Description
void	addParameter(String parameterName, Element content) Like addParameter(String, String) but you can add whatever you want (complex structures...) with a JDOM Element here.
void	addParameter(String parameterName, String parameterValue) Use this method to add a parameter to the ContextData part of the request.
void	addParameter(String parameterName, WfXMLForm form) Use this method to add a WfXMLForm as parameter to this message.
String	getKey() This method returns the key of this notify message.
String	getNotificationName() Use this method for getting the notification name set in this notify request message.
String	getParameter(String parameterName) Use this method to retrieve a simple text parameter, which has been set with setParameter(String, String) before.
WfXMLForm	getParameterForm(String parameterName) Use this method to retrieve a WfXMLForm object representing a form that has been set for or added to the parameter parameterName.
String	getProcessInstanceKey() This method returns the process instance key that is defined in notify request messages.
String	getProcessInstanceKeyOid() Use this method to get the oid of the process instance which sent the notify request message.
Collection<WfXMLForm>	listParameterForms(String parameterName) This method returns a Collection containing WfXMLForm objects which were set for the given parameter parameterName.
Collection<Element>	listParameterValueElements(String parameterName) This method returns a Collection with all values (as JDOM Element objects) for the given parameter.
Collection<String>	listParameterValueStrings(String parameterName) Use this method to get a Collection filled with the strings of all values of a parameter.
void	prepare(Partner partner) The prepare method prepares a message for being sent to the given partner.
void	setKey(String procInstObserverID) Sets the key for the Notify message.
void	setMessageType(short type) Set the message type of this WfXML message (in the message header).
void	setNotificationName(String name) Set a notification name for a notify request message.
void	setParameter(String parameterName, Element content) Similar to setParameter(String, String) but you can set your own JDOM Element as content here.
void	setParameter(String parameterName, String parameterValue) Use this method for setting a parameter in the ContextData part of request messages.
void	setParameter(String parameterName, WfXMLForm form) Use this method to set a WfXMLForm as a parameter for this message.
void	setProcessInstanceKey(String processInstanceOID) Use this method to set the process instance key of the process instance, which sends the notify request.

Methods inherited from class com.groiss.wfxml.WfXMLMessage

addParameterValueElem, assureBodyExists, assureHeaderExists, assureTransportExists, createMessage, createMessage, getDocumentCreator, getException, getMessageIdentifier, getMessageOrigin, getMessageType, getParameterValueElem, getParameterValueElems, getPlainKey, getResponseRequired, getStateString, getTimestamp, getTransportElementValue, setDocumentCreator, setException, setMessageIdentifier, setMessageOrigin, setPlainKey, setResponseRequired, setTimestamp, setTransportElement, toPrettyString, toString, write

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

MSG_BODY_REQ

protected static final String MSG_BODY_REQ

See Also:

Constant Field Values

MSG_BODY_RESP

protected static final String MSG_BODY_RESP

See Also:

Constant Field Values

Constructor Detail

NotifyMessage

public NotifyMessage(short messageType)

Creates a new and empty NotifyMessage object. Use the various setter methods to fill the message with content.

NotifyMessage

protected NotifyMessage(Document doc)

This method is used internally for creating a NotifyMessage out of a xml document. After the message has been created, the getter methods can be used to retrieve the content of the message.

Parameters:

doc - JDOM Document containing the content for the message.

Method Detail

setKey

public void setKey(String procInstObserverID)

Sets the key for the Notify message. The key identifies a process instance observer on a remote partner server.
Mind: Usually it will be not necessary to set this key manually, because the WfXML-layer does that for you when the message will be sent. When you create a notify message, the important thing is that you set the oid of the process instance from which you send the notify message (see setProcessInstanceKey(java.lang.String) method). Then you can send the message with the sender's Sender.send(WfXMLMessage,Class,boolean) method, which is especially designed to send NotifyMessage and PIStateChangedMessage messages. It searches for an observer of the local process instance and sends the message to the right partner server and observer, so it is not necessary to search for observers or remember observers manually.

Parameters:

procInstObserverID - The ID of the process instance observer on the remote partner server (just the ID, not a complete WfXML key).

Throws:

IllegalArgumentException - if procInstObserverID == null.

getKey

public String getKey()
              throws WfXMLMessageException

This method returns the key of this notify message. In case of @enterprise this key is the observer class (the class name as String object).

Returns:

A String containing the name of the observer class.

Throws:

WfXMLMessageException - if the key doesn't exist or if it is not compatible to @enterprise requirements.

setMessageType

public void setMessageType(short type)

Description copied from class: WfXMLMessage

Set the message type of this WfXML message (in the message header). Derived message classes can overwrite this method in order to set additional message type dependent content in the message body. Possible message types are request or response.
Take care: setting the message type removes proviously set content from the message.

Overrides:

setMessageType in class WfXMLMessage

Parameters:

type - Use the constants WfXMLMessage.REQUEST or WfXMLMessage.RESPONSE as value for this parameter, depending on if you want to create a request or a response message.

setProcessInstanceKey

public void setProcessInstanceKey(String processInstanceOID)

Use this method to set the process instance key of the process instance, which sends the notify request. This is the process instance that the observer observes. So the observer can use the getProcessInstanceKey() method to get the key out of this notify message in order to find out from which process instance the message has been sent.
On response messages this method doesn't have any effect.

Parameters:

processInstanceOID - The oid of the process instance that sends the notify request.

getProcessInstanceKey

public String getProcessInstanceKey()

This method returns the process instance key that is defined in notify request messages. The key identifies the process instance which sent the notify request.

Returns:

A String containing the complete process instance key, or null if the message doesn't contain a process instance key.

getProcessInstanceKeyOid

public String getProcessInstanceKeyOid()
                                throws WfXMLMessageException

Use this method to get the oid of the process instance which sent the notify request message. This method returns a substring of what the getProcessInstanceKey() method returns.

Returns:

The oid of the process instance specified in the process instance key of the message, or null if the message doesn't contain a key.

Throws:

WfXMLMessageException - if the key doesn't contain readable data (maybe not @enterprise format?).

setNotificationName

public void setNotificationName(String name)

Set a notification name for a notify request message. The notification name defines what kind of notification this is. The observer on the target partner must know how to handle this kind of notification.
You can invent arbitrary notification names. The only important thing is that the partner knows about these notification names.

Parameters:

name - A name for this notification.

getNotificationName

public String getNotificationName()

Use this method for getting the notification name set in this notify request message. Observers should read the notification name to find out which kind of notification this is and decide how to handle them.

Returns:

The notification name, or null if no notification name is defined in the message.

prepare

public void prepare(Partner partner)

The prepare method prepares a message for being sent to the given partner. You don't need to call this message, because it will be automatically called when you use the Sender.send(WfXMLMessage,Class,boolean) method of the Sender.

Specified by:

prepare in class WfXMLMessage

Parameters:

partner - The partner to which the message will be sent.

setParameter

public void setParameter(String parameterName,
                         String parameterValue)

Use this method for setting a parameter in the ContextData part of request messages. If the parameter already exists, the old value will be overwritten. If you want to add more values to one parameter, use the addParameter method instead.

Parameters:

parameterName - Name of the parameter that you want to set.

parameterValue - The value for the parameter.

setParameter

public void setParameter(String parameterName,
                         Element content)

Similar to setParameter(String, String) but you can set your own JDOM Element as content here. Use this method to add complex, self-defined data...

Parameters:

parameterName - Name of the parameter that you want to set.

content - A JDOM Element object containing everything you want to set as parameter.

setParameter

public void setParameter(String parameterName,
                         WfXMLForm form)

Use this method to set a WfXMLForm as a parameter for this message. If the parameter already existed before, the old value(s) will be lost.

Parameters:

parameterName - The name of the parameter you want to set.

form - The WfXMLForm you want to add.

addParameter

public void addParameter(String parameterName,
                         String parameterValue)

Use this method to add a parameter to the ContextData part of the request. If the parameter already exists, the new value will be added to the existing parameter (so the parameter will have multiple values then). If the parameter does not exist, it will be created.

Parameters:

parameterName - Name of the parameter for which you want to add a value.

parameterValue - The value for the parameter.

addParameter

public void addParameter(String parameterName,
                         Element content)

Like addParameter(String, String) but you can add whatever you want (complex structures...) with a JDOM Element here.

Parameters:

parameterName - Name of the parameter for which you want to add a value.

content - A JDOM Element object containing content (attributes, subelements, etc.). All this content will be added as a value to the parameter.

addParameter

public void addParameter(String parameterName,
                         WfXMLForm form)

Use this method to add a WfXMLForm as parameter to this message. Using a WfXMLForm is an easy way to create forms when you don't have an existing DMSObject available.
You can add multiple forms for one parameter name with this method. To retrieve all the forms later, use the listParameterForms method.

Parameters:

parameterName - The name of the parameter under which you want to add this form.

form - A reference to the WfXMLForm object you want to add to this parameter.

getParameter

public String getParameter(String parameterName)

Use this method to retrieve a simple text parameter, which has been set with setParameter(String, String) before. Take care: if you use this method to access a parameter which contains multiple values, you will only retrieve one of these values with this method! If you want to get all the values of such a multiple-value parameter, use the listParameterValueStrings method instead.

Parameters:

parameterName - The name of the parameter you are searching for.

Returns:

A String containing the value of the parameter, or null if the parameter was not found in the message.

getParameterForm

public WfXMLForm getParameterForm(String parameterName)

Use this method to retrieve a WfXMLForm object representing a form that has been set for or added to the parameter parameterName. If the parameter contains more than one form, you will retrieve one of these forms (it cannot be guaranteed which one!). So if you know that there is maybe more than one form for this parameter, use the method listParameterForms, which returns a collection of all forms, instead.

Parameters:

parameterName - The name of the parameter you want to get a form of.

Returns:

A WfXMLForm object containing the data of the form, or null if the parameter doesn't exist or if it doesn't contain a form.

listParameterForms

public Collection<WfXMLForm> listParameterForms(String parameterName)

This method returns a Collection containing WfXMLForm objects which were set for the given parameter parameterName. If you are sure that there is only one WfXMLForm set for this parameter, you could also use the getParameterForm method, which doesn't return a collection, but only one single WfXMLForm.

Parameters:

parameterName - The name of the parameter for which you want to retrieve values.

Returns:

A Collection containing WfXMLForm objects. If the parameter was not found or if the parameter didn't contain any forms, the returned collection will be empty.

listParameterValueElements

public Collection<Element> listParameterValueElements(String parameterName)

This method returns a Collection with all values (as JDOM Element objects) for the given parameter. So this method is good for retrieving values which have been set with the addParameter(String, Element) or setParameter(String, Element) methods.

Parameters:

parameterName - The name of the parameter for which you want to retrieve the value elements.

Returns:

A Collection containing Element objects representing the values of the parameter. If the parameter is not found, the collection is empty.

listParameterValueStrings

public Collection<String> listParameterValueStrings(String parameterName)

Use this method to get a Collection filled with the strings of all values of a parameter. You only retrieve the texts of the parameter's values, so this method makes most sence for "simple" parameters that have been set with the setParameter(String, String) or addParameter(String, String) methods.

Parameters:

parameterName - The name of the parameter for which you want to retrieve the value strings.

Returns:

A Collection containing String objects representing the texts of all values of the parameter. The Collection is empty if the parameter does not contain values or if the parameter was not found in the message.