com.groiss.wfxml

Class CreatePIMessage

java.lang.Object

com.groiss.wfxml.WfXMLMessage

com.groiss.wfxml.WfXMLDocFormMessage

com.groiss.wfxml.CreatePIMessage

public class CreatePIMessage
extends WfXMLDocFormMessage

This message is used for creating a new process instance on a partner server. It provides a lot of various methods for adding all kind of content (process forms, notes, DMS folder content, self-defined parameters...). See the documentation of the methods for further details.

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	CreatePIMessage(Document doc) This method is used internally for creating a create process instance message out of a xml document.
protected	CreatePIMessage(Document doc, boolean justIDs) That's a special constructor which doesn't try to create user objects out of the users that are specified in the message.
	CreatePIMessage(short messageType) Use this method to create a new and empty CreatePIMessage 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	getDescription() Returns the description of request messages.
protected Element	getDMSParentElem() Get the correct element of the message that wiil contain DMS artefacts;
String	getKeyApplID() Returns the application ID part of the key.
String	getKeyProcDefID() Returns the process definition ID part of the key.
int	getKeyVersion() Returns the version part of the key.
String	getName() Use this method to get the name of the process instance.
String	getObserverClass() This method returns the observer class (as String object) which can be set in CreateProcessInstance request messages.
String	getObserverKey() This method returns the whole observer key that is set in the 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() Use this method to get the process instance key out of response messages.
Agent	getStartParameterAgent() Returns an Agent instance representing the user or role who is specified in the message's start parameters.
String	getStartParameterAgentID() Returns the agent id defined in the start parameters of this CreateProcessInstance request message.
Date	getStartParameterDueDate() Use this method to get the due-date which is set in the start parameters of a CreateProcessInstance request message.
OrgUnit	getStartParameterOrgUnit() Returns a OrgUnit instance representing the organizational unit which is specified in the message's start parameters.
String	getStartParameterOrgUnitID() Returns the organization unit's id defined in the start parameters of this CreateProcessInstance request message.
String	getSubject() This method returns the subject for the process instance.
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) This method is called by the Sender before the message is sent.
protected void	prepare(String targetURL) This method is used by the WfXML test client only!
void	setDescription(String desc) A longer description of the purpose for the process instance that will be created with this message.
void	setKey(String applID, String procdefID, int version) Use this method to set the key for this CreateProcessInstance message.
void	setMessageType(short type) Set the message type of this WfXML message (in the message header).
void	setName(String name) Sets the name for the process instance.
void	setObserver(Class<?> observer) Use this method to set an observer for the process instance that will be created on the remote server by this CreateProcessInstance request.
protected void	setObserver(String uri) Setting a dummy observer.
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 procInstOID) Sets the process instance key of the newly created process instance.
void	setStartParameter(Agent agent, OrgUnit orgUnit, Date dueDate) Use this method to set the start parameters for CreateProcessInstance request methods.
void	setStartParameter(String agentID, String agentClassName, String orgUnitID, Date dueDate) This method sets start parameters with which the process instance will be started.
void	setSubject(String subject) A subject for the process instance.

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

CreatePIMessage

public CreatePIMessage(short messageType)

Use this method to create a new and empty CreatePIMessage object. 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.

CreatePIMessage

protected CreatePIMessage(Document doc)
                   throws Exception

This method is used internally for creating a create process instance message 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.

Throws:

Exception

CreatePIMessage

protected CreatePIMessage(Document doc,
                          boolean justIDs)
                   throws Exception

That's a special constructor which doesn't try to create user objects out of the users that are specified in the message. It is used by the wfxml test client, which doesn't have access to such information.

Parameters:

doc - JDOM document with the message content.

justIDs - true means that just IDs will be used and no user objects will be created. false creates user objects.

Throws:

Exception

Method Detail

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.

setName

public void setName(String name)

Sets the name for the process instance. If you build a request message, this name will be used as suggestion. It is not guaranteed, that the process instance will be assigned this name.
For response messages this is the name of the process instance that has been created.
Mind: if the remote server is an @enterprise server, setting a name when creating a new process instance will have no effect, because @enterprise process instances don't have names.

Parameters:

name - String containing the name.

getName

public String getName()

Use this method to get the name of the process instance. Depending on whether this message is a request or a response message the name has different meanings. If it is a request message, this is the requested name for the process instance that will be created (as a suggestion). If the message is a response message, the name is the name of the newly created process instance.
Mind: if the remote server is an @enterprise server, the response message will contain the @enterprise id of the new process instance as name. You can use this id, e.g., for displaying, so that users can find out which remote process instance has been started from the local process instance and so on.

Returns:

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

setProcessInstanceKey

public void setProcessInstanceKey(String procInstOID)

Sets the process instance key of the newly created process instance. This element only occurs in response messages. If you try to set it for a request message, nothing will be done.
Mind: the standard WfXML receiver creates process instances and also sets the process instance key in response messages, so in general it will seldom be necessary to use this method.

Parameters:

procInstOID - Unique oid of the process instance.

getProcessInstanceKey

public String getProcessInstanceKey()

Use this method to get the process instance key out of response messages. It returns the process instance key of the newly created process instance.
Mind: this method returns the whole process instance key, not only the process instance oid.

Returns:

A String representing the process instance key or null if there is no process instance key in the message (this also happens if you call this method on a request message).

setObserver

public void setObserver(Class<?> observer)

Use this method to set an observer for the process instance that will be created on the remote server by this CreateProcessInstance request. Later, when messages from this process instance arrive, they will be forwarded to the observer. Possible messages are Notify (NotifyMessage) and ProcessInstanceStateChanged (PIStateChangedMessage) requests.
The observer can only be set for request messages. If you try to set it for a response message, nothing will be done.

Parameters:

observer - A class implementing the ProcessInstanceObserver interface. If you want to remove a previously set observer, provide null as parameter.

setObserver

protected void setObserver(String uri)

Setting a dummy observer. This method is used by the WfXML test client. It creates a pi observer entry without real observer class. The classname will be set to dummyclass.

Parameters:

uri - Specifies the uri that should be set in the observer.

getObserverKey

public String getObserverKey()

This method returns the whole observer key that is set in the message. An observer key is a URI consisting of an observer class and communication partner details. The observer key is returned in any case, even if it is not compatible to @enterprise requirements.

Returns:

A String containing the complete observer key or null if the message doesn't contain an observer key (this also happens if you call this method for a response message).

getObserverClass

public String getObserverClass()
                        throws WfXMLMessageException

This method returns the observer class (as String object) which can be set in CreateProcessInstance request messages. The observer class is a part of the observer key, so this method returns a substring of what the getObserverKey method would return.

Returns:

A String containing the name of the observer class, or null if no observer was defined.

Throws:

WfXMLMessageException - if the observer key is not compatible to @enterprise requirements.

setSubject

public void setSubject(String subject)

A subject for the process instance. This can only be set for request messages. If you call the method for a response message, nothing will happen.

Parameters:

subject - The subject that you wish to be assigned to the process instance.

getSubject

public String getSubject()

This method returns the subject for the process instance. The subject can only occur in request messages.

Returns:

A String containing the subject or null if the message doesn't contain a subject.

setDescription

public void setDescription(String desc)

A longer description of the purpose for the process instance that will be created with this message.
This can only be set for request messages and is optional. On response messages this method will not have any effect.

Parameters:

desc - String containing the description that you want to add.

getDescription

public String getDescription()

Returns the description of request messages. The description explains the purpose of the process instance that will be created.

Returns:

A String containing the description or null if there is no description. If you call this method for response messages, you will always receive null, because this element only occurs in request messages.

setKey

public void setKey(String applID,
                   String procdefID,
                   int version)

Use this method to set the key for this CreateProcessInstance message. A key has to be defined before the message is sent.
The key references a process definition on the partner server.
Use this method if the partner server is an @enterprise server, because with this method an @enterprise specific key will be generated.

Parameters:

applID - Application ID: this parameter is optional and defines the application in which the process definition is located. If you don't set this parameter (null), the default application will be used.

procdefID - Process Definition ID: this is the process ID of the process that you want to start. You must provide this id.

version - Defines the version of the process. You can provide a positive integer value for a specific version, or -1 if you want that the process definition with the highest version number will be instantiated.

Throws:

IllegalArgumentException - if no process definition ID is defined or version < 0

prepare

public void prepare(Partner partner)

This method is called by the Sender before the message is sent. It completes the key of the message with the data of the given Partner in case that the key is a @enterprise specific key. If it is a user-defined key for other communication partners (no @enterprise server), the key will not be modified here.
This method is called automatically by the Sender, before the message is sent. You don't need to call it manually.

Specified by:

prepare in class WfXMLMessage

Parameters:

partner - Reference to the Partner object, which holds the information about the partner, to which the message will be sent.

prepare

protected void prepare(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.

getKeyApplID

public String getKeyApplID()
                    throws WfXMLMessageException

Returns the application ID part of the key. See setKey(String,String,int) for more details on key parts.

Returns:

String representing the application ID.

Throws:

WfXMLMessageException - if any error occurs while reading the key.

getKeyProcDefID

public String getKeyProcDefID()
                       throws WfXMLMessageException

Returns the process definition ID part of the key. See setKey(String,String,int) for more details on key parts.

Returns:

String containing the process definition ID.

Throws:

WfXMLMessageException - if any error occurs while reading the key.

getKeyVersion

public int getKeyVersion()
                  throws WfXMLMessageException

Returns the version part of the key. See setKey(String,String,int) for more details on key parts.

Returns:

int value containing the version part of the key, or -1 if no version has been specified. In this case the newest version should be used.

Throws:

WfXMLMessageException - if any error occurs while reading the key.

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)...

setStartParameter

public void setStartParameter(Agent agent,
                              OrgUnit orgUnit,
                              Date dueDate)

Use this method to set the start parameters for CreateProcessInstance request methods. The start parameters specify a user (and an organizational unit) and a due-date for starting the process instance. All of these parameters are optional (the organizational unit only if an interface for starting the process has been defined, see below for more details).

Parameters:

agent - An Agent object (user or role) representing the agent who starts the process. If you start the process with a role, the new process instance will appear in the role worklist of this role. You can set the agent also to null if you don't want to specify an agent for starting the process instance.

orgUnit - A OrgUnit object representing the organization unit (department) for which the process will be started. This value can also be set to null, but only if the remote @enterprise server has an interface defined for starting this process. Interfaces define a relation between form, process definition, and organizational unit. If you set this parameter to null the organizational unit defined in the interface will be used. And if there is no interface for starting this process, you will get back an exception message from the remote server.

dueDate - A Date object containing a date and time which will be set as due-date for the process instance. If you don't provide a value for this parameter (null), no due-date will be set.

setStartParameter

public void setStartParameter(String agentID,
                              String agentClassName,
                              String orgUnitID,
                              Date dueDate)

This method sets start parameters with which the process instance will be started. This method does the same as the other setStartParameter, with the only difference that you don't need to provide User and OrgUnit objects here. Instead you simply define the IDs of these parameters.

Parameters:

agentID - String specifying an agent ID. The ID can be the ID of a user or the ID of a role. Use the agentClassName parameter for specifying whether it is a user or a role. Set the agentID to null if you don't want to specify an agent for starting the process.

agentClassName - Set this value to com.dec.avw.core.User or com.dec.avw.core.Role, depending on whether the agentID parameter is the ID of a role or of a user. If agentID is null, you can also set this parameter to null.

orgUnitID - String specifying a org.unit ID. This value can also be set to null, but only if the remote @enterprise server has an interface defined for starting this process. Interfaces define a relation between form, process definition, and organizational unit. If you set this parameter to null the organizational unit defined in the interface will be used. And if there is no interface for starting this process, you will get back an exception message from the remote server.

dueDate - A Date object containing the due-date with which the process will be started. This parameter can also be set to null.

getStartParameterDueDate

public Date getStartParameterDueDate()
                              throws WfXMLMessageException

Use this method to get the due-date which is set in the start parameters of a CreateProcessInstance request message.

Returns:

A Date object representing the date and time set in the message's start parameters, or null if no due-date has been set in this message. The returned Date object contains the time in the local timezone.

Throws:

WfXMLMessageException - if the date and time defined in this message don't meet the format requirements defined in the WfXML specification.

getStartParameterOrgUnit

public OrgUnit getStartParameterOrgUnit()

Returns a OrgUnit instance representing the organizational unit which is specified in the message's start parameters.

Returns:

A OrgUnit instance of the organizational unit which is specified in the message's start parameters, or null if no org.unit has been defined or if the defined org.unit does not exist on the local server.

getStartParameterOrgUnitID

public String getStartParameterOrgUnitID()

Returns the organization unit's id defined in the start parameters of this CreateProcessInstance request message.

Returns:

A String object containing the org.unit's id, or null if no org.unit has been defined.

getStartParameterAgent

public Agent getStartParameterAgent()

Returns an Agent instance representing the user or role who is specified in the message's start parameters.

Returns:

An Agent instance of the user or role who is specified in the message's start parameters, or null if no agent has been defined or if the defined agent does not exist on the local server.

getStartParameterAgentID

public String getStartParameterAgentID()

Returns the agent id defined in the start parameters of this CreateProcessInstance request message.

Returns:

A String object containing the agent id, or null if no agent has been defined.

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.
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.

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...
On response messages this method doesn't have any effect.

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.
On response messages this method doesn't have any effect.

Parameters:

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

form - The WfXMLForm you want to add.

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.

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.

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.

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.

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.

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.