com.groiss.wfxml

Class PIStateChangedMessage

java.lang.Object

com.groiss.wfxml.WfXMLMessage

com.groiss.wfxml.WfXMLDocFormMessage

com.groiss.wfxml.PIStateChangedMessage

public class PIStateChangedMessage
extends WfXMLDocFormMessage

A PIStateChangedMessage is similar to NotifyMessage messages. It informs a registered observer about a state change of an observed process instance. The WfXML-layer automatically sends a PIStateChangedMessage to an observer if a process instance (that has been created with WfXML and for which an observer has been defined) is terminated or finishes.
You can send PIStateChangedMessage messages on any other state changes manually. Important is, that you set the oid of the process instance that changes its state with the setProcessInstanceKey(java.lang.String) method. Then you can send the message with the sender's Sender.send(WfXMLMessage,Class,boolean) method. The sender will search for the observer automatically and send the message to the right observer on the right partner server.

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	PIStateChangedMessage(Document doc) This method is used internally for creating a PIStateChangedMessage out of a xml document.
	PIStateChangedMessage(short messageType) Use this method to create a new ChangePIStateMessage message.

Method Summary

Modifier and Type	Method and Description
void	addParameter(String parameterName, String parameterValue) Use this method to add a parameter to the ResultData part of the request.
protected Element	getDMSParentElem() Get the correct element of the message that wiil contain DMS artefacts;
String	getKey() This method returns the key of this message.
Date	getLastModified() Returns the date at which the process instance has been last modified.
String	getParameter(String parameterName) Use this method to retrieve a simple text parameter, which has been set with setParameter(String, String) before.
String	getProcessInstanceKey() Use this method to get the process instance key of the process instance that changed its state.
String	getProcessInstanceKeyOid() Use this method to get the oid of the process instance which has changed its state.
short	getState() Returns the new state of the process instance that changed its state.
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) This method prepares the message to be sent to a specific partner.
void	setKey(String procInstObserverID) Sets the key for the ProcessInstanceStateChanged message.
void	setLastModified(Date lastModified) This method sets the date at which the process instance has been modified the last time.
void	setMessageType(short type) Set the message type of this WfXML message (in the message header).
void	setParameter(String parameterName, String parameterValue) Use this method for setting a parameter in the ResultData part of request messages.
void	setProcessInstanceKey(String processInstanceOid) This method sets the process instance key (oid) of the process instance that changed its state.
void	setState(short state) This method sets the new state of the process instance that changed its state.

Methods inherited from class com.groiss.wfxml.WfXMLDocFormMessage

addProcessForm, addProcessForm, addToDMSFolder, addToDMSFolder, addToDMSFolder, attachNote, attachNote, attachNote, createAttachedNotes, getAttachedNotes, getDMSFolder, getProcessForm, listDMSFolderContent, listProcessForms

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

PIStateChangedMessage

public PIStateChangedMessage(short messageType)

Use this method to create a new ChangePIStateMessage message. You must specify the type of message (request or response).

Parameters:

messageType - The type of new message you want to create: this can be either WfXMLMessage.REQUEST or WfXMLMessage.RESPONSE.

PIStateChangedMessage

protected PIStateChangedMessage(Document doc)

This method is used internally for creating a PIStateChangedMessage 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 ProcessInstanceStateChanged message. The key defines 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 process instance state changed message, the important thing is that you set the oid of the process instance from which you send the 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.

Throws:

IllegalArgumentException - if procInstObserverID == null.

getKey

public String getKey()
              throws WfXMLMessageException

This method returns the key of this message. The key is the observer class of the observer who should receive this message.

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.

prepare

public void prepare(Partner partner)

This method prepares the message to be sent to a specific partner. It is called by the Sender before the message is sent, so it should be never necessary to call this method yourself.

Specified by:

prepare in class WfXMLMessage

Parameters:

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

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)

This method sets the process instance key (oid) of the process instance that changed its state. It's important that you set this key, because without it the Sender will not be able to find an observer and it will not be possible to send the message.

Parameters:

processInstanceOid - oid of the process instance that changed its state.

getProcessInstanceKey

public String getProcessInstanceKey()

Use this method to get the process instance key of the process instance that changed its state. This key identifies the process instance so that the observer who receives this message knows which process instance changed its state.
Mind: this method returns the whole process instance key, not just the oid of the process instance.

Returns:

A String containing the process instance key.

getProcessInstanceKeyOid

public String getProcessInstanceKeyOid()
                                throws WfXMLMessageException

Use this method to get the oid of the process instance which has changed its state. 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 process instance key.

Throws:

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

setState

public void setState(short state)

This method sets the new state of the process instance that changed its state.

Parameters:

state - The new state of the process instance. The value must be one of the values defined in the WfXMLMessage class. If you set state to WfXMLMessage.PI_STATE_NONE the state element will be removed from the message.

getState

public short getState()

Returns the new state of the process instance that changed its state. The returned value is one of the values defined in WfXMLMessage. If the message doesn't contain a state element, the returned value will be WfXMLMessage.PI_STATE_NONE.

Returns:

the new state of the process instance.

setLastModified

public void setLastModified(Date lastModified)

This method sets the date at which the process instance has been modified the last time.
It's a good idea to use the last modified parameter with the same semantics as it is used in the GetPIDataMessage message. Thus, the date should be the date at which the last task has been started (for running process instances), or the date at which the process instance has been finished (for finished process instances).

Parameters:

lastModified - A Date object representing the last modified date.

getLastModified

public Date getLastModified()
                     throws WfXMLMessageException

Returns the date at which the process instance has been last modified. If this message doesn't contain this information, null will be returned.

Returns:

A Date object representing the last modified date.

Throws:

WfXMLMessageException - if the message contains a last modified date that doesn't meet the WfXML date requirements.

getDMSParentElem

protected Element getDMSParentElem()

Description copied from class: WfXMLDocFormMessage

Get the correct element of the message that wiil contain DMS artefacts;

Specified by:

getDMSParentElem in class WfXMLDocFormMessage

Returns:

The container element. May be null, if it is the wrong context (Request/Response)...

setParameter

public void setParameter(String parameterName,
                         String parameterValue)

Use this method for setting a parameter in the ResultData 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.
On response messages this method doesn't have any effect.

Parameters:

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

parameterValue - The value for the parameter.

addParameter

public void addParameter(String parameterName,
                         String parameterValue)

Use this method to add a parameter to the ResultData 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.

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.

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.