Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.fujitsu.iflow.model.workflow
Interface ProcessInstantiator

All Superinterfaces:
  DataAccessor

public interface ProcessInstantiator
extends DataAccessor

This `ProcessInstantiator` interface provides the necessary operations for creating and initiating a process instance. An instance of `ProcessInstantiator` can be acquired from `WFObjectFactory` using the method `getProcessInstantiator`. The `ProcessInstantiator` extends `DataAccessor`, which allows it to manipulate User Defined Attributes (UDA), as well as starting and committing edits.

String parameters: `String` parameters of all methods in this class have a length limit. This limit is documented in the Javadoc description for every parameter. If the length of a value supplied for such a parameter exceeds this limit, or the value is `null`, an exception is thrown. This exception is a subclass of `ModelException`. For future compatibility, only `ModelException` should be caught explicitly.

If the signature of a method does not allow the throwing of exceptions, any value supplied to this method that exceeds the length limit is truncated to the maximum length supported. `null` values are ignored in this case. Any method’s behaviour that differs from the behaviour described above is explained in this method’s Javadoc description.

Exceptions. Three kinds of exceptions are commonly thrown within this class: `WFServerException`, `WFInternalException`, and `ModelInternalException`. All of these exceptions are instances of `ModelException`. In the methods that directly throw a `ModelException`, this exception usually wraps one of the former three exceptions. `WFServerException` indicates that the server failed to operate normally. `WFInternalException` indicates a problem in the communication between client and server. As its name suggests, `util.ModelInternalException` denotes other problems that are internal to the Model API.

See Also:
  `WFObjectFactory`, `ProcessInstance`

Method Summary
`void` | `addAttachment(java.lang.String attachmentName, java.lang.String attachmentPath)` Adds an `AttachmentRef` to this process instantiator which will be added to the new process instance when calling method `startNewProcess`.
`void` | `commit()` Deprecated. Use method `startNewProcess()` instead.
`AttachmentRef` | `getAttachment(java.lang.String attachmentName)` Returns the `AttachmentRef` of the specified attachment which will be associated with the new process instance after calling method `startNewProcess`.
`AttachmentRef[]` | `getAttachments()` Returns the references to all the attachments which will be associated with the process instance after calling method `startNewProcess` of this process instantiator.
`java.lang.String` | `getDescription()` Returns the description of the process instance created with this process instantiator.
`java.lang.String` | `getName()` Returns the name of the process instance that will be created with this process instantiator.
`java.lang.String` | `getParentProcessURI()` Returns the `parentProcessURI` of the process instance.
`Plan` | `getPlan()` Returns the `Plan` object associated with the `ProcessInstantiator`.
`long` | `getPriority()` Returns the current priority of the process instance as defined in the `ProcessInstance` interface by constants such as `PRIORITY_HIGH`.
`long` | `getProcessInstanceId()` Deprecated. Use method `ProcessInstance.getId()` from process instance that is returned by the method `startNewProcess`.
`int` | `getState()` Deprecated. Use method `ProcessInstance.getState()` from process instance that is returned by the method `startNewProcess`.
`java.lang.String` | `getTitle()` Returns the title of the process instance.
`void` | `removeAttachment(java.lang.String attachmentName)` Removes a designated attachment from the list of attachments that will be add to the new process instance when calling method `startNewProcess`.
`void` | `setDescription(java.lang.String description)` Sets the description of the process instance.
`void` | `setName(java.lang.String name)` Sets the name of the process instance, which should be short and descriptive.
`void` | `setParentProcessURI(java.lang.String parentProcessURI)` Sets the `parentProcessURI` of the process instance.
`void` | `setPriority(long priority)` Sets the priority of the process instance.
`void` | `setTitle(java.lang.String title)` Sets the title of the process instance created by this process instantiator.
`ProcessInstance` | `startNewProcess()` Creates a process instance using the data associated with this `ProcessInstantiator` object, and starts the process instance.

Methods inherited from interface com.fujitsu.iflow.model.workflow.DataAccessor
`cancelEdit, commitEdit, getDataItem, getDataItems, getDataItemType, getDataItemValue, hasDataItem, isLockedForEdit, setDataItemValues, startEdit`

Method Detail

### commit

    public void commit()
                throws WFServerException,
                       WFInternalException,
                       ModelInternalException

  Deprecated. Use method `startNewProcess()` instead.

  Commits cached `ProcessInstance` properties and creates a process instance with them.

  Throws:
    `WFServerException`
    `WFInternalException`
    `ModelInternalException`

### getPlan

    public Plan getPlan()
                 throws ModelInternalException,
                        WFInternalException,
                        WFServerException

  Returns the `Plan` object associated with the `ProcessInstantiator`.

  Returns:
    The process definition the process instance belongs to.
  Throws:
    `WFServerException`
    `WFInternalException`
    `ModelInternalException`

### addAttachment

    public void addAttachment(java.lang.String attachmentName,
                              java.lang.String attachmentPath)
                       throws WFServerException,
                              WFInternalException,
                              ModelInternalException

  Adds an `AttachmentRef` to this process instantiator which will be added to the new process instance when calling method `startNewProcess`. This method is only supported if the new process instance is not created yet. After creating the new process instance by calling method `startNewProcess`, attachments can be add to the process instance using the operations of the returned `ProcessInstance` object.

  A process instance does not have any limits to the number of attachments that can be associated with it beside the maximum size of a process instance. Attachments are global to the process instance; any activity in a process instance can access the attachment.

  The name of attachment is limited to the number of characters specified by `AttachmentRef.MAX_ATTACHMENT_NAME_LENGTH`. The attachment's path must not be longer than specified by `AttachmentRef.MAX_ATTACHMENT_PATH_LENGTH`.

  Parameters:
    `attachmentName` - The attachment's name.
    `attachmentPath` - The fully qualified path and filename of the attachment.
  Throws:
    `WFServerException`
    `WFInternalException`
    `ModelInternalException` - Thrown when the supplied name or path is invalid or `null`. Should be caught as `ModelException` for future compatibility.

### removeAttachment

    public void removeAttachment(java.lang.String attachmentName)
                          throws WFServerException,
                                 WFInternalException,
                                 ModelInternalException

  Removes a designated attachment from the list of attachments that will be add to the new process instance when calling method `startNewProcess`. This method is only supported if the new process instance is not created yet. After creating the new process instance by calling method `startNewProcess`, attachments can be removed using the operations of the returned `ProcessInstance` object.

  The name of attachment is limited to the number of characters specified by `AttachmentRef.MAX_ATTACHMENT_NAME_LENGTH`.

  Parameters:
    `attachmentName` - The attachment's name.
  Throws:
    `WFServerException`
    `WFInternalException`
    `ModelInternalException`

### getAttachment

    public AttachmentRef getAttachment(java.lang.String attachmentName)
                                throws ModelInternalException

  Returns the `AttachmentRef` of the specified attachment which will be associated with the new process instance after calling method `startNewProcess`.

  The name of attachment is limited to the number of characters specified by `AttachmentRef.MAX_ATTACHMENT_NAME_LENGTH`.

  Parameters:
    `attachmentName` - The attachment's name.
  Returns:
    An attachment object that has been added to this process instance.
  Throws:
    `ModelInternalException` - Thrown if no attachment is found for the supplied attachment name.

### getAttachments

    public AttachmentRef[] getAttachments()

  Returns the references to all the attachments which will be associated with the process instance after calling method `startNewProcess` of this process instantiator. Returns an empty array if no attachments are defined.

  Returns:
    The attachment referecens associated with this process instance or an empty array when there are no attachments added.

### getProcessInstanceId

    public long getProcessInstanceId()

  Deprecated. Use method `ProcessInstance.getId()` from process instance that is returned by the method `startNewProcess`.

  Returns the unique identifier of process instance that this instantiator is attempting to create. Each process instance contains an unique ID number it can be identified by. Returns `-1` if the process instance has not been created.

### getState

    public int getState()

  Deprecated. Use method `ProcessInstance.getState()` from process instance that is returned by the method `startNewProcess`.

  Returns the current state of the process instance as defined in the `ProcessInstance` interface by constants such as `STATE_RUNNING`.

### startNewProcess

    public ProcessInstance startNewProcess()
                                    throws WFServerException,
                                           WFInternalException,
                                           ModelInternalException

  Creates a process instance using the data associated with this `ProcessInstantiator` object, and starts the process instance.

  Throws:
    `WFServerException`
    `ModelInternalException`
    `WFInternalException`

### getName

    public java.lang.String getName()

  Returns the name of the process instance that will be created with this process instantiator. The name of the process instance defaults to the process definition name when the process is first created from a process instance.

  Returns:
    The process instance's name.
  See Also:
    `setName(String)`

### getTitle

    public java.lang.String getTitle()

  Returns the title of the process instance. The initial process instance title is inherited from the process definition from which the process instance was created.

  Returns:
    The process instance's title.
  See Also:
    `setTitle(String)`

### getDescription

    public java.lang.String getDescription()

  Returns the description of the process instance created with this process instantiator. This description is copied from the process definition description when the process instance is created.

  Returns:
    The process instance's description.
  See Also:
    `setDescription(String)`

### getPriority

    public long getPriority()

  Returns the current priority of the process instance as defined in the `ProcessInstance` interface by constants such as `PRIORITY_HIGH`.

  When the process instance is first created, it inherits the priority of the process definition it is based on. During the execution of the process, the priority of the process instance can be changed. Changing the running process instance priority will have no effect on the base process definition.

  Returns:
    The integer constant specifying the current priority of this process instance.

### getParentProcessURI

    public java.lang.String getParentProcessURI()
                                         throws ModelException

  Returns the `parentProcessURI` of the process instance. If this process instance is started as a subprocess of a remote process, then the id of the remote process is set as the `parentProcessURI` of this process instance.

  Throws:
    `ModelException`

### setName

    public void setName(java.lang.String name)

  Sets the name of the process instance, which should be short and descriptive. The process instance inherits the name of the process definition when it is first created. This method allows you to modify the process name.

  This method is only supported if the new process instance is not created yet. After creating the new process instance by calling method `startNewProcess`, the name can be changed by using the operations of the returned `ProcessInstance` object.

  The name is limited to the number of characters specified by the constant `ProcessInstance.MAX_PROCESS_NAME_LENGTH` and must not contain any of the following characters: `\ | / : * ? " < >`. If the length exceeds the maximum length, the name is truncated to the specified number of characters. If the supplied value is null, the identifier will not be changed.

  Parameters:
    `name` - The new name of the process instance.

### setTitle

    public void setTitle(java.lang.String title)

  Sets the title of the process instance created by this process instantiator. By default, the title of the process instance is inherited from the process definition from which the process instance was copied. This method allows you to modify instance the process title.

  This method is only supported if the new process instance is not created yet. After creating the new process instance by calling method `startNewProcess`, the title can be changed by using the operations of the returned `ProcessInstance` object.

  The title is limited to the number of characters specified by the constant `ProcessInstance.MAX_PROCESS_TITLE_LENGTH`. If the length exceeds that length, the title is truncated to the maximum number if characters. If the supplied value is null, the title will not be changed.

  Parameters:
    `title` - The new title of this process instance.

### setDescription

    public void setDescription(java.lang.String description)

  Sets the description of the process instance. By default, the process instance inherits the description of the process definition when the process instance is first created. This method allows you to modify this description.

  This method is only supported if the new process instance is not created yet. After creating the new process instance by calling method `startNewProcess`, the description can be changed by using the operations of the returned `ProcessInstance` object.

  The description is limited to the number of characters specified by the constant `ProcessInstance.MAX_PROCESS_DESCRIPTION_LENGTH`. If the length exceeds that length,, the description is truncated to the maximum number of characters. If the supplied value is null, the description will not be changed.

  Parameters:
    `description` - The new description of this process instance.

### setPriority

    public void setPriority(long priority)

  Sets the priority of the process instance. The process instance priority can be any value between plus or minus 32,767.

  However, process instance priorities is separated in three categories: high (High), medium (Med), and low (Low).
  This categorization of priorities is made according to the following rules:

  - HIGHT: Any number greater than or equal to 16.
  - MEDIUM: Any number between eight and 16 (including eight)
  - LOW: Any number less than eight.

  This method is only supported if the new process instance is not created yet. After creating the new process instance by calling method `startNewProcess`, the priority can be changed by using the operations of the returned `ProcessInstance` object.

  Parameters:
    `priority` - The new priority of the process instance.

### setParentProcessURI

    public void setParentProcessURI(java.lang.String parentProcessURI)
                             throws ModelException

  Sets the `parentProcessURI` of the process instance. If this process instance is started as a subprocess of a remote process, then the id of the remote process should be set as the `parentProcessURI` of this process instaance.

  Throws:
    `ModelException`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD