com.groiss.wfxml
Class CreatePIMessage

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

public class CreatePIMessage
extends WfXMLMessage

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

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	CreatePIMessage(org.jdom.Document doc) This method is used internally for creating a create process instance message out of a xml document.
protected	CreatePIMessage(org.jdom.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

void	addParameter(java.lang.String parameterName, org.jdom.Element content) Like addParameter(String, String) but you can add whatever you want (complex structures...) with a JDOM Element here.
void	addParameter(java.lang.String parameterName, java.lang.String parameterValue) Use this method to add a parameter to the ContextData part of the request.
void	addParameter(java.lang.String parameterName, WfXMLForm form) Use this method to add a WfXMLForm as parameter to this message.
void	addProcessForm(java.lang.String formName, DMSForm form) Use this method to add process forms to a CreateProcessInstance request message.
void	addProcessForm(java.lang.String formName, WfXMLForm form) Like addProcessForm(String,DMSForm), but you can add a form here, without having a DMSForm available.
void	addToDMSFolder(java.util.Collection objects) Use this method to add multiple DMSObjects at once by providing a Collection containing DMSObject objects.
void	addToDMSFolder(java.util.Collection objects, java.util.Collection documentTypes) This method adds a Collection of DMSObject objects to the DMS folder of this message.
void	addToDMSFolder(DMSObject obj) This method adds a DMSObject to the message.
void	addToDMSFolder(WfXMLObject obj) Use this method to add any WfXMLObject to the process instance's DMSFolder without having a DMSObject.
void	attachNote(DMSNote note) Use this method if you want that a note will be attached to the process instance that will be created.
void	attachNote(java.lang.String subject, java.lang.String content, java.lang.String userId, boolean isPrivate) Use this method to quickly attach notes without creating WfXMLNote or DMSNote objects.
void	attachNote(WfXMLNote note) This method attaches a WfXMLNote to this message.
java.util.Collection	createAttachedNotes() Use this method to get all attached notes out of this message (these are notes which should be attached directly to the new process instance).
java.util.Collection	getAttachedNotes() Use this method to get all attached notes as WfXMLNote objects.
java.lang.String	getDescription() Returns the description of request messages.
java.lang.String	getKeyApplID() Returns the application ID part of the key.
java.lang.String	getKeyProcDefID() Returns the process definition ID part of the key.
int	getKeyVersion() Returns the version part of the key.
java.lang.String	getName() Use this method to get the name of the process instance.
java.lang.String	getObserverClass() This method returns the observer class (as String object) which can be set in CreateProcessInstance request messages.
java.lang.String	getObserverKey() This method returns the whole observer key that is set in the message.
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	getParameterForm(java.lang.String parameterName) Use this method to retrieve a WfXMLForm object representing a form that has been set for or added to the parameter parameterName.
WfXMLForm	getProcessForm(java.lang.String formName) Use this method to retrieve the data of a process form, if you know the exact form name with which the form is defined in the process definition.
java.lang.String	getProcessInstanceKey() Use this method to get the process instance key out of repsonse messages.
Agent	getStartParameterAgent() Returns an Agent instance representing the user or role who is specified in the message's start parameters.
java.lang.String	getStartParameterAgentID() Returns the agent id defined in the start parameters of this CreateProcessInstance request message.
java.util.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.
java.lang.String	getStartParameterOrgUnitID() Returns the organization unit's id defined in the start parameters of this CreateProcessInstance request message.
java.lang.String	getSubject() This method returns the subject for the process instance.
java.util.List	listDMSFolderContent() This method gives you a List holding all the content of this message's DMS folder (thus, all documents that have to be added to the new process instance).
java.util.Collection	listParameterForms(java.lang.String parameterName) This method returns a Collection containing WfXMLForm objects which were set for the given parameter parameterName.
java.util.Collection	listParameterValueElements(java.lang.String parameterName) This method returns a Collection with all values (as JDOM Element objects) for the given parameter.
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.
java.util.List	listProcessForms() Returns a list with WfXMLForm objects representing the data of all process forms included in this message.
void	prepare(Partner partner) This method is called by the Sender before the message is sent.
protected void	prepare(java.lang.String targetURL) This method is used by the WfXML test client only!
void	setDescription(java.lang.String desc) A longer description of the purpose for the process instance that will be created with this message.
void	setKey(java.lang.String applID, java.lang.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(java.lang.String name) Sets the name for the process instance.
void	setObserver(java.lang.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(java.lang.String uri) Setting a dummy observer.
void	setParameter(java.lang.String parameterName, org.jdom.Element content) Similar to setParameter(String, String) but you can set your own JDOM Element as content here.
void	setParameter(java.lang.String parameterName, java.lang.String parameterValue) Use this method for setting a parameter in the ContextData part of request messages.
void	setParameter(java.lang.String parameterName, WfXMLForm form) Use this method to set a WfXMLForm as a parameter for this message.
void	setProcessInstanceKey(java.lang.String procInstOID) Sets the process instance key of the newly created process instance.
void	setStartParameter(Agent agent, OrgUnit orgUnit, java.util.Date dueDate) Use this method to set the start parameters for CreateProcessInstance request methods.
void	setStartParameter(java.lang.String agentID, java.lang.String agentClassName, java.lang.String orgUnitID, java.util.Date dueDate) This method sets start parameters with which the process instance will be started.
void	setSubject(java.lang.String subject) A subject for the process instance.

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

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(org.jdom.Document doc)
                   throws java.lang.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:

java.lang.Exception

CreatePIMessage

protected CreatePIMessage(org.jdom.Document doc,
                          boolean justIDs)
                   throws java.lang.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:

java.lang.Exception

Method Detail

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)

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 java.lang.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(java.lang.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 java.lang.String getProcessInstanceKey()

Use this method to get the process instance key out of repsonse 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(java.lang.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(java.lang.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 java.lang.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 java.lang.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(java.lang.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 java.lang.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(java.lang.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 java.lang.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(java.lang.String applID,
                   java.lang.String procdefID,
                   int version)
            throws java.lang.IllegalArgumentException

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:

java.lang.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(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.

getKeyApplID

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

attachNote

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

Use this method if you want that a note will be attached to the process instance that will be created. You can attach as many notes as you want.
If you want to put a note in the document folder of the process instance, use the addToDMSFolder(DMSObject) method instead.

Parameters:

note - The DMSNote object you want to attach.

Throws:

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

attachNote

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

Use this method to quickly attach notes without creating WfXMLNote or DMSNote objects.
You can simply provide three strings, a subject, a content, and the ID of a user who will be the creator of the note on the remote server. The boolean value indicates whether the note will be 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. In that case either the default document creator (see WfXMLMessage.setDocumentCreator) or the starter of the process instance will be set as user.

isPrivate - set this parameter to true if this note should be private (only the specified user will be able to read it), or to false, if all users should be able to read the note.

attachNote

public void attachNote(WfXMLNote note)

This method attaches a WfXMLNote to this message. The note will be attached to the new process instance, after it has been started.

Parameters:

note - A WfXMLNote object.

createAttachedNotes

public java.util.Collection createAttachedNotes()

Use this method to get all attached notes out of this message (these are notes which should be attached directly to the new process instance). The message must be a request message. DMSNote objects are created for the notes and returned in a collection.
This method uses the getAttachedNotes() method to get all attached notes, and then calls WfXMLNote.createDMSObject(com.groiss.org.User) on all of the notes.
The document creator of this message is used as default creator for the notes.

Returns:

A collection of DMSNote objects containing notes for the new process instance. If there are no notes, the Collection will be empty (this also happens if you call this method for response messages).

getAttachedNotes

public java.util.Collection getAttachedNotes()

Use this method to get all attached notes as WfXMLNote objects. This method does not create any DMSObject objects.

Returns:

A Collection filled with WfXMLNote objects representing all attached notes. If there are no notes, or if this is a response message (which cannot contain notes), you will receive an empty Collection.

addProcessForm

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

Use this method to add process forms to a CreateProcessInstance request message. Process forms belong to the process instance and are defined in the process definition with a name. You must provide this name as parameter formName here, so that the values of the added form will be used for the correct process form once the process instance has been created on the communication partner server.

Parameters:

formName - The name of the form as it is defined in the process definition of the process that will be instantiated.

form - A DMSForm object containing the process form data.

Throws:

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

addProcessForm

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

Like addProcessForm(String,DMSForm), but you can add a form here, without having a DMSForm available. See the other addProcessForm method for more details.
Mind: adding a WfXMLForm with this method copies the form's values to the message. You can modify the WfXMLForm object afterwards without affecting the data which is stored in this message. Because of this behavior it is not necessary to clone the WfXMLForm object!

Parameters:

formName - The name of the form, as it is defined in the process definition, that you want to instantiate.

form - A WfXMLForm will all form data.

getProcessForm

public WfXMLForm getProcessForm(java.lang.String formName)

Use this method to retrieve the data of a process form, if you know the exact form name with which the form is defined in the process definition. This method does not create any DMSForm object, it only builds a WfXMLForm object with all the data. So you can control and also change the data before you create a DMSForm with it.

Parameters:

formName - Name of the form (as defined in the process definition).

Returns:

A WfXMLForm object containing all the form's data, or null if no form with the given name was found (this also happens if the message is a response message).

listProcessForms

public java.util.List listProcessForms()

Returns a list with WfXMLForm objects representing the data of all process forms included in this message. If you only want one specific process form, use the getProcessForm(String) method instead.

Returns:

A List with all process forms (represented as WfXMLForm objects. If there are no process forms in the message, the List will be empty. The returned WfXMLForm objects have the right form names set.

addToDMSFolder

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

This method adds a DMSObject to the message. DMSObjects can only be added for request messages. After the new process has been started on the remote server, these objects will be added to its document folder.
If you want to add a process form, use one of the addProcessForm methods instead.
If you want that notes will be attached to the new process instance, use a attachNote method.

obj may be one of the following:

• DMSNote - the DMSNote is added (it will be placed in the document folder, and not attached to the new process instance!).
• 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.

WfXMLMessageException - if adding failed because of an error. This can happen if, e.g., there is not enough memory for adding the object.

addToDMSFolder

public void addToDMSFolder(java.util.Collection objects)
                    throws java.lang.Exception,
                           java.lang.IllegalArgumentException

Use this method to add multiple DMSObjects at once by providing a Collection containing DMSObject objects. The objects of the collection will be added using the addToDMSFolder(DMSObject) method.
If you want to add a process form, use the addProcessForm methods instead.
If you want that notes will be attached to the new process instance, use one of the attachNote methods.

Parameters:

objects - Any Collection containing DMSObject objects. If there are other objects in the collection, an IllegalArgumentException will be thrown.

Throws:

java.lang.IllegalArgumentException - if there are other objects than DMSObject objects in the collection.

java.lang.Exception - if any other error occurs. The message can be in an undefined state after such an exception. Some objects may have been added and some others not.

addToDMSFolder

public void addToDMSFolder(java.util.Collection objects,
                           java.util.Collection documentTypes)
                    throws java.lang.Exception,
                           java.lang.IllegalArgumentException

This method adds a Collection of DMSObject objects to the DMS folder of this message. The second parameter specifies a set of document types, that will be added. This has the following effect: all objects will be added to the DMS folder, but DMSDocForm objects will be added only if their form type appears in the documentTypes collection. So you can restrict the types of documents you want to add to this message. If the objects collection contains folders, the document types restriction will also be applied to these folders and any subfolders and so on.

Parameters:

objects - A Collection containing DMSObject objects.

documentTypes - A Collection with FormType objects. DMSDocForm with other form types will not be added.

Throws:

java.lang.IllegalArgumentException - If the objects collection contains an object which is no DMSObject

java.lang.Exception - If other errors occur and the operation fails. The message can be in an undefined state after such an exception. Some objects may have been added and some others not.

addToDMSFolder

public void addToDMSFolder(WfXMLObject obj)
                    throws WfXMLMessageException

Use this method to add any WfXMLObject to the process instance's DMSFolder without having a DMSObject. You can simply create a WfXMLObject instead and add it with this method. On response messages this method will not have any effect.

Parameters:

obj - The WfXMLObject you want to add.

Throws:

WfXMLMessageException - if the object could not be added because of a runtime problem (e.g., not enough memory for adding the object).

listDMSFolderContent

public java.util.List listDMSFolderContent()

This method gives you a List holding all the content of this message's DMS folder (thus, all documents that have to be added to the new process instance). The list contains the content as WfXMLObject objects. There are no DMSObject objects created, when you call this method.
You can create DMSObjects yourself using the createDMSObject method of the WfXMLObject objects.

Returns:

A List holding the content of the DMS folder in form of WfXMLObject objects. If there is no content, the List will be empty.

setStartParameter

public void setStartParameter(Agent agent,
                              OrgUnit orgUnit,
                              java.util.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(java.lang.String agentID,
                              java.lang.String agentClassName,
                              java.lang.String orgUnitID,
                              java.util.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 java.util.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()
                                 throws java.lang.Exception

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.

Throws:

java.lang.Exception

getStartParameterOrgUnitID

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

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.

Throws:

java.lang.Exception

getStartParameterAgentID

public java.lang.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(java.lang.String parameterName,
                         java.lang.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(java.lang.String parameterName,
                         org.jdom.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(java.lang.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 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.

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.

listParameterForms

public java.util.Collection listParameterForms(java.lang.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(java.lang.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 java.util.Collection listParameterValueElements(java.lang.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 paramter is not found, the collection is empty.

addParameter

public void addParameter(java.lang.String parameterName,
                         java.lang.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(java.lang.String parameterName,
                         org.jdom.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(java.lang.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.