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 DataAccessor

All Known Subinterfaces:
  ProcessInstance, ProcessInstantiator, WorkItem

public interface DataAccessor

`DataAccessor` is the superinterface for `ProcessInstance`, `ProcessInstantiator` and `WorkItem`.

In `ProcessInstance` and `WorkItem`, the `DataAccessor` interface provides operations for accessing User Defined Attributes (UDA) of a process instance. `ProcessInstantiator` uses these methods to interact with a server object, rather than a model object.

`String` parameters of all methods in this class have a length limit. This limit is documented in the Javadoc comment 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 throwing any exception, 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 comment.

Exceptions. Three kinds of exceptions are commonly thrown within this class: `WFServerException`, `WFInternalException`, and `ModelInternalException`, all of which 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, `ModelInternalException` denotes other problems that are internal to the Model API.

Method Summary
`void` | `cancelEdit()` Unlocks this `DataAccessor` from edit-mode without committing any done changes.
`void` | `commitEdit()` Stores all done changes of this `DataAccessor` since calling method `startEdit` and unlocks it.
`DataItem` | `getDataItem(java.lang.String dataItemName)` Returns the User Defined Attribute (UDA) of this `DataAcessor` regarding to the name.
`DataItem[]` | `getDataItems()` Returns an array of all User Defined Attributes (UDA) regarding to this data accessor.
`java.lang.String` | `getDataItemType(java.lang.String dataItemName)` Deprecated. This method is replaced by getDataItem(String).getType.
`java.lang.String` | `getDataItemValue(java.lang.String dataItemName)` Deprecated. This method is replaced by getDataItem(String).getValue.
`boolean` | `hasDataItem(java.lang.String dataItemName)` Indicates whether this `DataAccessor` object has a User Defined Attribute (UDA) with the specific name.
`boolean` | `isLockedForEdit()` Determines whether this `DataAccessor` object is locked for edit.
`void` | `setDataItemValues(java.util.Properties nvlist)` Sets the values of a group of User Defined Attributes (UDA).
`void` | `startEdit()` Sets the current `DataAccessor` object to edit mode and locks it for modifications by someone else.

Method Detail

### getDataItemValue

    public java.lang.String getDataItemValue(java.lang.String dataItemName)
                                      throws ModelInternalException

  Deprecated. This method is replaced by getDataItem(String).getValue.

  Returns a String representation of the value of a User Defined Attribute (UDA). In the case of a boolean data type, the returned values would be "True" or "False". All other data types return the actual value of the UDA as a String.

  Parameters:
    `dataItemName` - The name of the UDA. This is the name that was used when the UDA for the process definition was created.
  Returns:
    A String representation of the value stored in the UDA.
  Throws:
    `ModelInternalException` - This exception returns the `GET_DATA_FAILED` error-code constant.

### hasDataItem

    public boolean hasDataItem(java.lang.String dataItemName)

  Indicates whether this `DataAccessor` object has a User Defined Attribute (UDA) with the specific name.

  The argument of this method is the name of UDA which is implemented by a `DataItem` where the length of name is limited to `DataItemRef.MAX_DATA_REF_NAME_LENGTH`. If the length of `dataItemName` exceeds the maximum length, the value is truncated. If the supplied value is `null`, `false` will be returned.

  Parameters:
    `dataItemName` - The UDA's name.
  Returns:
    `true` when the regarding process instance has a UDA with the given name; `false` otherwise.

### isLockedForEdit

    public boolean isLockedForEdit()
                            throws WFInternalException,
                                   WFServerException

  Determines whether this `DataAccessor` object is locked for edit. The `DataAccessor` object is locked for edit by calling method `startEdit` and is unlocked by calling method `commitEdit` or `cancelEdit`. The edit-mode is necessary when the User Defined Attributes (UDA) of the `DataAccessor` object shall be modified. Only if `DataAccessor` object is in edit-mode the UDAs can be changed.

  All the thrown exceptions should be caught as `ModelException` for future compatibility.

  Returns:
    `true` when this `DataAccessor` object is locked for edit; `false` otherwise.
  Throws:
    `WFServerException` - The most probable server error messages wrapped in this exception are: `Process locked by someone else`, `Failed to get Read Transaction`.
    `WFInternalException`
  See Also:
    `startEdit()`, `commitEdit()`, `cancelEdit()`

### getDataItem

    public DataItem getDataItem(java.lang.String dataItemName)

  Returns the User Defined Attribute (UDA) of this `DataAcessor` regarding to the name.

  The argument of this method is the name of UDA which is implemented by a `DataItem` where the length of name is limited to `DataItemRef.MAX_DATA_REF_NAME_LENGTH`. If the length of `dataItemName` exceeds the maximum length, the value is truncated. Returns null if the supplied data item name is `null` or the associated UDA does not exist.

  Parameters:
    `dataItemName` - The UDA's name.
  Returns:
    The `DataItem` object which represents the UDA.

### getDataItems

    public DataItem[] getDataItems()

  Returns an array of all User Defined Attributes (UDA) regarding to this data accessor. Returns an empty array if no UDAs are defined.

  Returns:
    A list of `DataItem` objects which represent the current UDAs of this data accessor.

### setDataItemValues

    public void setDataItemValues(java.util.Properties nvlist)
                           throws WFInternalException,
                                  WFServerException,
                                  ModelInternalException

  Sets the values of a group of User Defined Attributes (UDA). The values of existing UDAs are set by using 'UDA name' (key) and 'UDA value' (value) as pairs in a `java.util.Properties` array.

  The length of properties key (UDA name) is limited to the length specified by `DataItemRef.MAX_DATA_REF_NAME_LENGTH`.

  The data accessor has to be in edit-mode before calling `setDataItemValues`. Edit-mode is entered by calling `DataAccessor.startEdit`.

  All the thrown exceptions should be caught as `ModelException` for future compatibility.

  Parameters:
    `nvlist` - list of UDA name and UDA value groups.
  Throws:
    `WFServerException`
    `ModelInternalException`
    `WFInternalException` - Thrown when the data accessor is not in edit-mode when this method is called.
  See Also:
    `startEdit()`

### getDataItemType

    public java.lang.String getDataItemType(java.lang.String dataItemName)
                                     throws ModelInternalException

  Deprecated. This method is replaced by getDataItem(String).getType.

  Returns the data type of a User Defined Attribute (UDA). UDAs are defined during the creation of a process definition. This method returns the data type for the specified UDA. See list of types in the `DataItemRef` class description.

  Parameters:
    `dataItemName` - The name of the UDA definition. This is the name that was used when the UDA for the process definition was created.
  Returns:
    A String representation of the UDA type. See list of types in the `DataItemRef` class description.
  Throws:
    `ModelInternalException` - This exception returns the `GET_DATA_TYPE_FAILED` error-code constant.

### startEdit

    public void startEdit()
                   throws WFServerException,
                          WFInternalException,
                          ModelInternalException

  Sets the current `DataAccessor` object to edit mode and locks it for modifications by someone else. This method can be used to modify the values of User Defined Attributes (UDA) by first locking this `DataAccessor` object, updating values, and then unlocking the `DataAccessor` object with calling the method `commitEdit`.

  It is recommended that the period of time between locking and unlocking it be very brief.

  No UDA in any `ProcessInstance`, `WorkItem` or `ProcessInstantiator` can be changed without first calling this method.

  All the thrown exceptions should be caught as `ModelException` for future compatibility.

  Throws:
    `WFServerException` - The most probable server error messages wrapped in this exception are: `Illegal access into server`, `Process instance locked by someone else`, `Failed to lock process instance`, `The suspended process instance cannot be edited`, `Process definition is already locked for edit`, `Failed to get Read Transaction`, `Failed to lock process definition`, `Attempt to edit a published process definition`, `Process definition is private`, `Failed to register process instance with LCC`.
    `ModelInternalException` - Thrown when the `DataAccessor` is already in edit mode. If this method is used by a process instance or by one of its components (`WorkItem`) this exception is also thrown if process instance is already in structural edit-mode.
    `WFInternalException`
  See Also:
    `commitEdit()`, `cancelEdit()`

### commitEdit

    public void commitEdit()
                    throws WFServerException,
                           WFInternalException

  Stores all done changes of this `DataAccessor` since calling method `startEdit` and unlocks it.

  The `DataAccessor` has to be in edit-mode before calling `commitEdit`. Edit-mode is entered by calling `DataAccessor.startEdit`.

  All the thrown exceptions should be caught as `ModelException` for future compatibility.

  Throws:
    `WFServerException` - The most probable server error messages wrapped in this exception are: `Failed to unlock process instance`, `Failed to get Read Transaction`, `Could not find writeTxn of process instance`, `Failed to commit edit`, `DBAccess Error`, `Create process definition failed`, `Failed to get Read Transaction`, `Failed to get Write Transaction`, `Failed to commit edit`.
    `WFInternalException` - Thrown when the data accessor is not in edit mode when this method is called.
  See Also:
    `startEdit()`

### cancelEdit

    public void cancelEdit()
                    throws WFServerException,
                           WFInternalException

  Unlocks this `DataAccessor` from edit-mode without committing any done changes. All changes made to this `DataAccessor` since calling method `startEdit` are discarded.

  The data accessor has to be in edit-mode before calling `commitEdit`. Edit-mode is entered by calling `DataAccessor.startEdit`.

  All the thrown exceptions should be caught as `ModelException` for future compatibility.

  Throws:
    `WFServerException` - The most probable server error messages wrapped in this exception are: `Failed to unlock process instance`, `Could not find writTxn of process instance`, `DBAccess Error`, `Failed to convert notification Data to byte Array`, `Failed to cancel process definition edit`, `Failed to get Write Transaction`.
    `WFInternalException` - Thrown when the data accessor is not in edit mode when this method is called.
  See Also:
    `startEdit()`

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