com.groiss.wfxml
Class GetPIDataMessage

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

public class GetPIDataMessage
extends WfXMLMessage

With this message you can request data of a process instance on a partner server. You can specify which items the answer should contain (as defined in the WfXML specification).
See the documentation of the methods for details on what you can do with this message.

Field Summary

static java.lang.String	DESC
static java.lang.String	LASTMODIFIED
protected static java.lang.String	MSG_BODY_REQ
protected static java.lang.String	MSG_BODY_RESP
static java.lang.String	NAME
static java.lang.String	OBSERVERKEY
static java.lang.String	PRIORITY
static java.lang.String	PROCDEFKEY
static java.lang.String	STATE
static java.lang.String	SUBJECT
static java.lang.String	VALIDSTATES

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	GetPIDataMessage(org.jdom.Document doc) This method is used internally for creating a GetPIDataMessage out of a xml document.
	GetPIDataMessage(short messageType) Creates a new empty message and sets a type for that message (request or response).

Method Summary

void	addNote(DMSNote note) Use this method to add a note to a response message.
void	addNote(java.lang.String subject, java.lang.String content, java.lang.String userId, boolean isPrivate) Use this method to quickly add notes without creating WfXMLNote or DMSNote objects.
void	addNote(WfXMLNote note) This method adds a WfXMLNote to a response message (that's a note attached to the process instance).
void	addProcessForm(java.lang.String formName, DMSForm form) Use this method to add a process form to a response message.
void	addProcessForm(java.lang.String formName, WfXMLForm form) Add a process form to a response message.
void	addToDMSFolder(DMSObject obj) This method adds a DMSObject to a response message.
void	addToDMSFolder(WfXMLObject obj) Use this method to add a WfXMLObject to the DMSFolder in a response message.
boolean	areNotesRequested() Use this method to find out if notes are requested in a request message.
java.lang.String	getDescription() Use this method to get the Description attribute.
java.lang.String	getKey() Use this method to get the oid of the target process instance.
java.util.Date	getLastModified() Use this method to get the value of the LastModified attribute.
java.lang.String	getName() This method gets the Name attribute.
java.lang.String	getObserverKey() Use this method to get the ObserverKey attribute.
int	getPriority() Use this method to get the Priority attribute.
java.lang.String	getProcessDefinitionKey() Use this method to get the ProcessDefinitionKey attribute.
WfXMLForm	getProcessForm(java.lang.String formName) Use this method to get a specific process form out of a response message.
short	getState() This method returns the value set in the State attribute.
java.lang.String	getSubject() Use this method to get the Subject attribute.
short[]	getValidStates() Use this method to get all states set in the ValidStates attribute.
boolean	isDMSFolderRequested() Use this method to find out if the content of the process instance's DMSFolder is requested in a request message.
WfXMLObject[]	listDMSFolderContent() Use this method to get the content of a response message's DMSFolder.
WfXMLNote[]	listNotes() Use this method to get all notes as WfXMLNote objects out of a response message.
java.lang.String[]	listProcessFormNames() Use this method to get all form names of the process forms that are included in this message.
WfXMLForm[]	listProcessForms() Use this method to get an array of process forms included in a response message.
java.lang.String[]	listRequestedAttributeNames() Use this method to get a list containing the names of all requested attributes.
void	prepare(Partner partner) This method prepares the message to be sent to a specific partner.
protected void	prepare(java.lang.String targetURL) This method is used by the WfXML test client only!
void	requestDMSFolder() Adds a request for the content of the process instance's DMSFolder to a request message.
void	requestNotes() Adds a request for all notes to a request message.
void	requestProcessForm(java.lang.String formName) Adds a request for a specific process form to a request message.
void	requestProcessForms() Call this method on request messages in order to add a request for process forms.
void	setDescription(java.lang.String description) This method sets the Description attribute.
void	setKey(java.lang.String procInstID) Sets the key for the GetProcessInstanceData message.
void	setLastModified(java.util.Date date) This method sets the LastModified attribute.
void	setMessageType(short type) Set the message type of this WfXML message (in the message header).
void	setName(java.lang.String name) This method sets the Name attribute.
void	setObserverKey(java.lang.String observerKey) This method sets the ObserverKey attribute.
void	setPriority(int value) Use this method to set the Priority attribute.
void	setProcessDefinitionKey(java.lang.String procDefKey) This method sets the ProcessDefinitionKey attribute.
void	setState(short state) Use this method to set the State attribute.
void	setSubject(java.lang.String subject) This method sets the Subject attribute.
void	setValidStates(short[] states) Use this method to set the ValidStates attribute.

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

NAME

public static final java.lang.String NAME

See Also:

Constant Field Values

SUBJECT

public static final java.lang.String SUBJECT

See Also:

Constant Field Values

DESC

public static final java.lang.String DESC

See Also:

Constant Field Values

STATE

public static final java.lang.String STATE

See Also:

Constant Field Values

VALIDSTATES

public static final java.lang.String VALIDSTATES

See Also:

Constant Field Values

OBSERVERKEY

public static final java.lang.String OBSERVERKEY

See Also:

Constant Field Values

PROCDEFKEY

public static final java.lang.String PROCDEFKEY

See Also:

Constant Field Values

PRIORITY

public static final java.lang.String PRIORITY

See Also:

Constant Field Values

LASTMODIFIED

public static final java.lang.String LASTMODIFIED

See Also:

Constant Field Values

Constructor Detail

GetPIDataMessage

public GetPIDataMessage(short messageType)

Creates a new empty message and sets a type for that message (request or response).

Parameters:

messageType - The type of the new message. Use WfXMLMessage.REQUEST or WfXMLMessage.RESPONSE as type.

GetPIDataMessage

protected GetPIDataMessage(org.jdom.Document doc)

This method is used internally for creating a GetPIDataMessage 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 procInstID)
            throws java.lang.IllegalArgumentException

Sets the key for the GetProcessInstanceData message. The key defines a process instance on the remote partner server.
If you don't have a process instance oid available, use the WfXMLMessage.setPlainKey(java.lang.String) method instead. With that method you can set a complete key, like you receive it after you created a new process instance with a CreatePIMessage.

Parameters:

procInstID - The unique process instance OID of the process instance on the remote partner server. This parameter must be provided.

Throws:

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

getKey

public java.lang.String getKey()
                        throws WfXMLMessageException

Use this method to get the oid of the target process instance. The method does not return the whole key but only the relevant oid part.
If you want to retrieve the whole key, use the WfXMLMessage.getPlainKey() method.

Returns:

The oid of the process instance that is defined in the key of the message. That's the target process instance of this data request.

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.

prepare

protected void prepare(java.lang.String targetURL)

This method is used by the WfXML test client only! it sets an arbitrary target URL for this message and does not need to have a partner provided.

Parameters:

targetURL - target URL 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.

setName

public void setName(java.lang.String name)

This method sets the Name attribute. If this is a request message, it means that you want to request the name (in that case you can set the name parameter to null). In @enterprise the name is a process instance's id.
If this is a response message you can set the value for the name in the response with this method.

Parameters:

name - The name - according to the WfXML specification this is a human readable identifier of the resource. In case this is a request message, you can pass null as parameter.

getName

public java.lang.String getName()

This method gets the Name attribute. There are three possible types of return values:

• A String containing the name, if this is a response message and the name has been set. @enterprise uses the process instance id as name.
• An empty String, if the name attribute is available, but no content is defined for it (=> a request message that is requesting the name...)
• null, if the message doesn't contain a name.

Returns:

The value of the name attribute, or an empty String, or null. See the text above for further details.

setSubject

public void setSubject(java.lang.String subject)

This method sets the Subject attribute. It works like the setName(java.lang.String) method, with the only difference that it sets the subject attribute instead of the name attribute.

Parameters:

subject - The value of the subject attribute. According to the WfXML specification this is a short description of the process instance. If this is a request message, you can set the parameter to null.

getSubject

public java.lang.String getSubject()

Use this method to get the Subject attribute. Refer to the getName() method for more details (this method works identically).

Returns:

The value of the subject, or an empty String, or null. See the similar getName() method for more details.

setDescription

public void setDescription(java.lang.String description)

This method sets the Description attribute. It works like the setName(java.lang.String) method, with the only difference that it sets the description attribute instead of the name attribute. @enterprise doesn't return descriptions, because descriptions with this semantics don't exist.

Parameters:

description - The value of the description attribute. According to the WfXML specification this is a longer description of this process instance resource. If this is a request message, you can set the parameter to null.

getDescription

public java.lang.String getDescription()

Use this method to get the Description attribute. Refer to the getName() method for more details (this method works identically).

Returns:

The value of the description, or an empty String, or null. See the similar getName() method for more details.

setObserverKey

public void setObserverKey(java.lang.String observerKey)

This method sets the ObserverKey attribute. It works like the setName(java.lang.String) method, with the only difference that it sets the observerkey attribute instead of the name attribute.

Parameters:

observerKey - The value of the observerkey attribute. This is the id of the observer which is registered for the process instance that you are requesting data from. If this is a request message, you can set the parameter to null.

getObserverKey

public java.lang.String getObserverKey()

Use this method to get the ObserverKey attribute. Refer to the getName() method for more details (this method works identically).

Returns:

The value of the observerkey, or an empty String, or null. See the similar getName() method for more details.

setProcessDefinitionKey

public void setProcessDefinitionKey(java.lang.String procDefKey)

This method sets the ProcessDefinitionKey attribute. This also works like the setName(java.lang.String) method.

Parameters:

procDefKey - The value of the process definition key. This is the URI of the process definition resource from which this instance was created.

getProcessDefinitionKey

public java.lang.String getProcessDefinitionKey()

Use this method to get the ProcessDefinitionKey attribute. Refer to the getName() method for more details (this method works identically).

Returns:

The value of the process definition key (full WfXML key), or an empty String, or null. See the similar getName() method for more details.

setPriority

public void setPriority(int value)

Use this method to set the Priority attribute. It works similar to the setName(java.lang.String) method. If you want to set "no value" for the priority (e.g., in request messages), use 0 as parameter.
Mind: if you request a process instance priority from an @enterprise server, you will always receive "3" (the default value) as result, because @enterprise doesn't have process instance priorities. If you want to change that behaviour for one of your @enterprise applications (e.g., if you use self-made priorities), write a MessageListener that sets the right value.

Parameters:

value - The priority that you want to set. The priority indicates the relative importance of this process instance. Regular values are integers from 1 (highest priority) to 5 (lowest priority). Use 0 if you don't want to set a value (e.g., in a request message). If you attempt to set an invalid value, no value will be set.

getPriority

public int getPriority()

Use this method to get the Priority attribute. If a value has been set, you will retrieve that value (1-5). If no value has been set, or the attribute does not exist at all, 0 will be returned.

Returns:

The value of the priority attribute, or 0 if no value is defined or the attribute does not exist.

setLastModified

public void setLastModified(java.util.Date date)

This method sets the LastModified attribute. This also works like the setName(java.lang.String) method.

Mind: dates in WfXML are timezone independent. If you communicate with a server which is located in a different timezone, the date will be transformed so that you and the other server are talking about the same point in time, thus, for you it is always your local time and you don't need to care about any conversion.

Parameters:

date - The date that you want to set for this attribute. This is the date of the last modification of the process instance.

getLastModified

public java.util.Date getLastModified()

Use this method to get the value of the LastModified attribute. You will receive a Date object containing the date when the last change occured, or null if the attribute doesn't contain a value, the value is not readable (according to the format defined by the WfXML specification), or the attribute does not exist in the message.
If you requested the last modified date from an @enterprise server, the returned date will 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).

Mind: dates in WfXML are timezone independent. If you communicate with a server which is located in a different timezone, the date will be transformed so that you and the other server are talking about the same point in time (for you it is always your local time).

Returns:

A Date object or null. See the text above for more details.

setState

public void setState(short state)

Use this method to set the State attribute. In a request message you should use the value WfXMLMessage.PI_STATE_NONE or 0 (both indicating that there is no state defined). In the response you will find one of the states defined as constants in WfXMLMessage.

Parameters:

state - WfXMLMessage.PI_STATE_NONE or 0 for indicating that no state is set, or one of the valid states WfXMLMessage.PI_STATE_OPEN_RUNNING, WfXMLMessage.PI_STATE_OPEN_NOTRUNNING, WfXMLMessage.PI_STATE_CLOSED_COMPLETED, or WfXMLMessage.PI_STATE_CLOSED_ABNORMAL_COMPLETED.
If you pass an invalid value, no state will be set.

getState

public short getState()

This method returns the value set in the State attribute. The value is one of the state constants defined in WfXMLMessage. If there is no value defined for that attribute, or if the attribute is not part of the message at all, WfXMLMessage.PI_STATE_NONE (0) will be returned. State is the current state of the process instance.

Returns:

The value of the state attribute.

setValidStates

public void setValidStates(short[] states)

Use this method to set the ValidStates attribute. In a request method you can pass null as parameter. If you want to set states in a response message, create an array containg state constants defined in WfXMLMessage (short values).

Parameters:

states - An array containing the states that you want to set for this parameter, or null if you don't want to set any states at all.
Invalid states will not be added.

getValidStates

public short[] getValidStates()

Use this method to get all states set in the ValidStates attribute. If the attribute does not exist, null will be returned. If the attribute exists but doesn't have values set, the array will be empty. Otherwise you retrieve an array filled with all states that have been set for this attribute (states are constants defined in WfXMLMessage).

Returns:

A short array containing the states (see above for more details), or null if the attribute does not exist.

listRequestedAttributeNames

public java.lang.String[] listRequestedAttributeNames()

Use this method to get a list containing the names of all requested attributes. The names are constants defined in this message (like NAME, SUBJECT, ...).

Returns:

An array with the names of all requested attributes. If there are no requested attributes, the array will be empty.

requestProcessForms

public void requestProcessForms()

Call this method on request messages in order to add a request for process forms. The response will then include all process forms of the target process instance.

requestProcessForm

public void requestProcessForm(java.lang.String formName)

Adds a request for a specific process form to a request message. You can call this method multiple times if you want to request more than one specific process form. The formName should be the name of the process form as it is defined in the remote process instance's process definition. The response message will contain only the requested process forms.

Parameters:

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

listProcessFormNames

public java.lang.String[] listProcessFormNames()

Use this method to get all form names of the process forms that are included in this message. This method works with both request and response messages, but mind: it doesn't return the content of the forms, it returns just the form names.

Returns:

An array with the form names of all process forms that are included in this message. If there are no forms in the message, the array will be empty (in a request message this means: no process forms are requested). If the message is a request message and it requests all process forms, you will receive an array with one element, and this element will be null (because no specific forms are requested).

requestNotes

public void requestNotes()

Adds a request for all notes to a request message. The response will then include all process instance notes (mind: notes located in the DMSFolder and notes attached to documents are not included here).

areNotesRequested

public boolean areNotesRequested()

Use this method to find out if notes are requested in a request message.

Returns:

true if notes are requested, or false if notes are not requested.

requestDMSFolder

public void requestDMSFolder()

Adds a request for the content of the process instance's DMSFolder to a request message. The response will contain all documents that reside in the DMSFolder of the target process instance.

isDMSFolderRequested

public boolean isDMSFolderRequested()

Use this method to find out if the content of the process instance's DMSFolder is requested in a request message.

Returns:

true if the content of the DMSFolder is requested, or false if it is not requested.

addProcessForm

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

Use this method to add a process form to a response message. It will add the form including attached notes, subforms, and referenced forms. If you don't have a DMSForm available, use a WfXMLForm instead (method addProcessForm(String,WfXMLForm)).

Parameters:

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

form - The DMSForm that you want to add.

Throws:

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

addProcessForm

public void addProcessForm(java.lang.String formName,
                           WfXMLForm form)

Add a process form to a response message. The form will be added including all attached notes, subforms, and referenced forms.

Parameters:

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

form - The WfXMLForm that you want to add.

listProcessForms

public WfXMLForm[] listProcessForms()

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

Returns:

An array containing all requested process forms. If no requested process forms were found, the array will be empty.

getProcessForm

public WfXMLForm getProcessForm(java.lang.String formName)

Use this method to get a specific process form out of a response 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 out of the response message.

Returns:

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

addNote

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

Use this method to add a note to a response message. This should be a note which is attached to the target process instance.

Parameters:

note - The DMSNote object you want to add.

Throws:

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

addNote

public void addNote(java.lang.String subject,
                    java.lang.String content,
                    java.lang.String userId,
                    boolean isPrivate)

Use this method to quickly add notes without creating WfXMLNote or DMSNote objects.
You can simply provide three strings, a subject, a content, and the ID of a user who is the creator of the note. The boolean value indicates whether the note is private or public.

Parameters:

subject - A Subject for the note.

content - The content of the note.

userId - ID String of the user. You can set this to null if you don't want to specify a particular user for this note.

isPrivate - set this parameter to true if this note is private, or to false if it is public.

addNote

public void addNote(WfXMLNote note)

This method adds a WfXMLNote to a response message (that's a note attached to the process instance).

Parameters:

note - The WfXMLNote object that you want to add.

listNotes

public WfXMLNote[] listNotes()

Use this method to get all notes as WfXMLNote objects out of a response message. This method does not create any DMSObject objects.

Returns:

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

addToDMSFolder

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

This method adds a DMSObject to a response message.
If you want to add a process form, use one of the addProcessForm methods 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 DMSWebLink 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.

addToDMSFolder

public void addToDMSFolder(WfXMLObject obj)

Use this method to add a WfXMLObject to the DMSFolder in a response message.

Parameters:

obj - The WfXMLObject you want to add.

listDMSFolderContent

public WfXMLObject[] listDMSFolderContent()

Use this method to get the content of a response message's DMSFolder. 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.