com.groiss.wfxml
Class PIStateChangedMessage

java.lang.Object
  com.groiss.wfxml.WfXMLMessage
      com.groiss.wfxml.PIStateChangedMessage

public class PIStateChangedMessage
extends WfXMLMessage

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

protected static java.lang.String	MSG_BODY_REQ
protected static java.lang.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

protected	PIStateChangedMessage(org.jdom.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

void	addNote(DMSNote note) Use this method to add a note to this message.
void	addParameter(java.lang.String parameterName, java.lang.String parameterValue) Use this method to add a parameter to the ResultData part of the request.
void	addProcessForm(java.lang.String formName, DMSForm form) Use this method to add a process form to this message.
void	addToDMSFolder(DMSObject obj) This method adds a DMSObject to this message.
WfXMLFolder	getDMSFolder() This method returns a WfXMLFolder object containing the content of the DMS folder part of this message.
java.lang.String	getKey() This method returns the key of this message.
java.util.Date	getLastModified() Returns the date at which the process instance has been last modified.
java.lang.String	getParameter(java.lang.String parameterName) Use this method to retrieve a simple text parameter, which has been set with setParameter(String, String) before.
WfXMLForm	getProcessForm(java.lang.String formName) Use this method to get a specific process form out of this message.
java.lang.String	getProcessInstanceKey() Use this method to get the process instance key of the process instance that changed its state.
java.lang.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.
WfXMLObject[]	listDMSFolderContent() Use this method to get the content of this message's DMSFolder (that's the DMSFolder content of the process instance that changed its state).
WfXMLNote[]	listNotes() Use this method to get all notes as WfXMLNote objects out of this message.
java.util.Collection	listParameterValueStrings(java.lang.String parameterName) Use this method to get a Collection filled with the strings of all values of a parameter.
WfXMLForm[]	listProcessForms() Use this method to get an array of process forms included in this message.
void	prepare(Partner partner) This method prepares the message to be sent to a specific partner.
void	setKey(java.lang.String procInstObserverID) Sets the key for the ProcessInstanceStateChanged message.
void	setLastModified(java.util.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(java.lang.String parameterName, java.lang.String parameterValue) Use this method for setting a parameter in the ResultData part of request messages.
void	setProcessInstanceKey(java.lang.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.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 java.lang.String MSG_BODY_REQ

See Also:

Constant Field Values

MSG_BODY_RESP

protected static final java.lang.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(org.jdom.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(java.lang.String procInstObserverID)
            throws java.lang.IllegalArgumentException

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:

java.lang.IllegalArgumentException - if procInstObserverID == null.

getKey

public java.lang.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)
                    throws java.lang.IllegalArgumentException

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.

Throws:

java.lang.IllegalArgumentException - If type is illegal.

setProcessInstanceKey

public void setProcessInstanceKey(java.lang.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 java.lang.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 java.lang.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(java.util.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 java.util.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.

addNote

public void addNote(DMSNote note)
             throws java.lang.Exception

Use this method to add a note to this message. This should be a process instance note.

Parameters:

note - The DMSNote object you want to add.

Throws:

java.lang.Exception - if any error occurs while the note is added.

listNotes

public WfXMLNote[] listNotes()

Use this method to get all notes as WfXMLNote objects out of this message.

Returns:

An array of WfXMLNote objects, or an empty array if there are no notes in the message.

addProcessForm

public void addProcessForm(java.lang.String formName,
                           DMSForm form)
                    throws java.lang.Exception

Use this method to add a process form to this message. It will add the form including attached notes, subforms, and referenced forms.

Parameters:

formName - The form name of that process form as defined in the process definition.

form - The DMSForm that you want to add.

Throws:

ApplicationException - if any other error occurs while the process form is added (database problems, etc.).

java.lang.Exception

listProcessForms

public WfXMLForm[] listProcessForms()

Use this method to get an array of process forms included in this message.

Returns:

An array containing process forms. If there are no process forms in this message, you will receive an empty array.

getProcessForm

public WfXMLForm getProcessForm(java.lang.String formName)

Use this method to get a specific process form out of this message. You will receive the form as WfXMLForm, so you can access all of its content easily.

Parameters:

formName - The form name of the process form that you want to get.

Returns:

A WfXMLForm with the content of the form, or null if no process form with the given name exists.

addToDMSFolder

public void addToDMSFolder(DMSObject obj)
                    throws java.lang.Exception

This method adds a DMSObject to this message.
If you want to add a process form, use the addProcessForm method instead.

obj may be one of the following:

• DMSNote - the DMSNote is added (this is a note in the document folder and not a note which is attached to the process instance).
• DMSWebLink - the content of the web link will be added.
• DMSDocForm - the document (base64 encoded) and any notes that may be attached to the document are added.
• DMSFolder - a whole DMSFolder including all content (also subfolders!) is added.
• DMSForm - the form plus any referenced forms and subforms and attached notes are added.
• DMSLink - the linked object (=> one of the 4 types mentioned before) is added.

Parameters:

obj - The DMSObject that you want to add to the message.

Throws:

java.lang.Exception - if any error occurs while the object is added.

listDMSFolderContent

public WfXMLObject[] listDMSFolderContent()

Use this method to get the content of this message's DMSFolder (that's the DMSFolder content of the process instance that changed its state). The content is returned as array of WfXMLObject objects. If you need DMSObject objects, you can create DMSObjects easily by calling the WfXMLObjects' WfXMLObject.createDMSObject(com.groiss.org.User) method.

Returns:

An array holding the content of the DMSFolder in form of WfXMLObject objects. If the folder is empty, the returned array will be empty, too.

getDMSFolder

public WfXMLFolder getDMSFolder()

This method returns a WfXMLFolder object containing the content of the DMS folder part of this message. Warning: don't create a DMSFolder out of this folder, because it is not supposed to be created "in real". You can use this folder to update an existing folder (especially the DMS folder of a process) by using the folder's fill method.

Returns:

A DMSFolder holding the content of this message's DMS folder.

setParameter

public void setParameter(java.lang.String parameterName,
                         java.lang.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(java.lang.String parameterName,
                         java.lang.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 java.lang.String getParameter(java.lang.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 java.util.Collection listParameterValueStrings(java.lang.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.