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 DataItemRef

All Superinterfaces:
  java.lang.Comparable

All Known Subinterfaces:
  DataItem

public interface DataItemRef
extends java.lang.Comparable

The `DataItemRef` interface provides access to all aspects of a User Defined Attributes (UDA). A UDA is a variable of a process instance. The `DataItemRef` represents the meta data of such a variable and is part of a process definition. It can be accessed by all nodes of the appropriate process definition and is used to specify the behaviour of `Node`s. It also stores data for process execution.

A UDA has the following set of attributes: `Name`, `Type`, and `Value`. The `Name` attribute of the UDA is its identifier and must be unique throughout the entire process definition. The `Type` attribute defines the kind of value that is stored within the UDA. The following types are supported:

- BOOLEAN - can be set to the values "true" or "false"
- INTEGER - 32 bit numeric integer value
- STRING - Allows a string of unicode characters.
- FLOAT - Java float value
- LONG - 64 bit numeric integer value
- DATE - Java Date value
- BIGDECIMAL - Java BigDecimal value

The `Value` attribute of a `DataItemRef` is the initial value of the UDA for process execution.

The standard way of constructing a new `DataItemRef` object is to call the method `Plan.addDataItemRef`. This method creates and returns a new `DataItemRef` with the minimum attributes of a UDA and adds it directly to the process definition.

`String` parameters of all methods in this class have a length limit. This limit is documented in the Javadoc description for each 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.

Field Summary
`static int` | `MAX_AGGREGATES_NAME_LENGTH` Specifies the maximum length of the aggregates name 256 characters.
`static int` | `MAX_CUBE_NAME_LENGTH` Specifies the maximum length of the cube name; currently 256 characters.
`static int` | `MAX_DATA_REF_NAME_LENGTH` Specifies the maximum length of the name identifier of the User Defined Attribute; currently 64 characters.
`static java.lang.String` | `TYPE_BIGDECIMAL` Indicates that the type of value is Java `BigDecimal` one.
`static java.lang.String` | `TYPE_BOOLEAN` Indicates that the type of value is a boolean one (value can be `"true"` or `"false"`).
`static java.lang.String` | `TYPE_DATE` Indicates that the type of value is Java `Date` one.
`static java.lang.String` | `TYPE_FLOAT` Indicates that the type of value is a float one.
`static java.lang.String` | `TYPE_INTEGER` Indicates that the type of value is a 32 bit numeric integer value.
`static java.lang.String` | `TYPE_LONG` Indicates that the type of value is a 64 bit numeric integer value.
`static java.lang.String` | `TYPE_STRING` Indicates that the type of value is a `String` of unicode characters.

Method Summary
`java.lang.String` | `getAggregates()` Returns the aggregates of the User Defined Attribute (UDA).
`java.lang.String` | `getCubeNames()` Returns the cube name of the User Defined Attribute (UDA).
`boolean` | `getDimension()` Returns if this User Defined Attribute (UDA) is marked as dimension.
`org.w3c.dom.Document` | `getExtendedAttributes()` Returns the DOM document object that contains all of the User Defined Attributes (UDA) level extended attributes.
`boolean` | `getMeasure()` Returns if this User Defined Attribute (UDA) is a measure.
`java.lang.String` | `getName()` Returns this User Defined Attribute's (UDA) name, which is the unique identifier of this object.
`java.lang.String` | `getType()` Returns the current type of this User Defined Attribute (UDA) as defined in the `DataItemRef` interface by constants such as `TYPE_BOOLEAN`.
`java.lang.String` | `getValue()` Returns the current value of this User Defined Attribute (UDA).
`boolean` | `isReadOnly()` Returns `true` if the User Defined Attribute (UDA) is marked as read-only; `false` otherwise.
`boolean` | `isUdaTracking()` Returns `true` if the User Defined Attribute (UDA) is marked as UDA tracking; `false` otherwise.
`boolean` | `isWorkListUDA()` Returns if this User Defined Attribute (UDA) is marked as worklist UDA.
`void` | `markAsReadOnly(boolean mark)` Marks the User Defined Attributes (UDA) as a read-only or a non read-only.
`void` | `markAsWorkListUDA(boolean mark)` Sets the flag of this User Defined Attribute (UDA); setting `mark` to `true` marks this a worklist UDA.
`void` | `markUdaTracking(boolean mark)` Marks the User Defined Attributes (UDA) to track the UDA or not to track the UDA.
`void` | `setAggregates(java.lang.String value)` Sets the aggregates of the User Defined Attribute (UDA).
`void` | `setCubeNames(java.lang.String name)` Sets the cube name of the User Defined Attribute (UDA).
`void` | `setDimension(boolean value)` Specifies if the this User Defined Attribute (UDA) is a dimension.
`void` | `setExtendedAttributes(org.w3c.dom.Document attrs)` Sets the DOM document that contains all of the User Defined Attribtes (UDA) level extended attributes.
`void` | `setMeasure(boolean value)` Specifies if the this User Defined Attribute (UDA) is a measure.
`void` | `setName(java.lang.String name)` Sets the name of this User Defined Attribute (UDA).
`void` | `setType(java.lang.String type)` Sets the type of this User Defined Attribute (UDA).
`void` | `setValue(java.lang.String value)` Sets the value of this User Defined Attribute (UDA).

Methods inherited from interface java.lang.Comparable
`compareTo`

Field Detail

### TYPE_BOOLEAN

    public static final java.lang.String TYPE_BOOLEAN

  Indicates that the type of value is a boolean one (value can be `"true"` or `"false"`).

  See Also:
    Constant Field Values

### TYPE_INTEGER

    public static final java.lang.String TYPE_INTEGER

  Indicates that the type of value is a 32 bit numeric integer value.

  See Also:
    Constant Field Values

### TYPE_FLOAT

    public static final java.lang.String TYPE_FLOAT

  Indicates that the type of value is a float one.

  See Also:
    Constant Field Values

### TYPE_STRING

    public static final java.lang.String TYPE_STRING

  Indicates that the type of value is a `String` of unicode characters.

  See Also:
    Constant Field Values

### TYPE_LONG

    public static final java.lang.String TYPE_LONG

  Indicates that the type of value is a 64 bit numeric integer value.

  See Also:
    Constant Field Values

### TYPE_BIGDECIMAL

    public static final java.lang.String TYPE_BIGDECIMAL

  Indicates that the type of value is Java `BigDecimal` one.

  See Also:
    Constant Field Values

### TYPE_DATE

    public static final java.lang.String TYPE_DATE

  Indicates that the type of value is Java `Date` one.

  See Also:
    Constant Field Values

### MAX_DATA_REF_NAME_LENGTH

    public static final int MAX_DATA_REF_NAME_LENGTH

  Specifies the maximum length of the name identifier of the User Defined Attribute; currently 64 characters.

  See Also:
    Constant Field Values

### MAX_CUBE_NAME_LENGTH

    public static final int MAX_CUBE_NAME_LENGTH

  Specifies the maximum length of the cube name; currently 256 characters.

  See Also:
    Constant Field Values

### MAX_AGGREGATES_NAME_LENGTH

    public static final int MAX_AGGREGATES_NAME_LENGTH

  Specifies the maximum length of the aggregates name 256 characters.

  See Also:
    Constant Field Values

Method Detail

### getName

    public java.lang.String getName()

  Returns this User Defined Attribute's (UDA) name, which is the unique identifier of this object. The name is used when generating forms.

  The UDA name is set with initialisation of this `DataItemRef` object. It can be changed by calling method `setName`.

  Returns:
    The name of this UDA.
  See Also:
    `setName(String)`

### setName

    public void setName(java.lang.String name)
                 throws ModelInternalException

  Sets the name of this User Defined Attribute (UDA).

  Since forms use the name of the UDA to reference it in the process instance, care should be taken when programmatically changing the name. If the name of a UDA that is identified in a form no longer exists, the form will become invalid. If this is the case, you should also change the name of the UDA on the form or regenerate the form.

  The name must not be longer than specified in `MAX_DATA_REF_NAME_LENGTH`.

  If the `DataItemRef` already belongs to a process definition, that process definition has to be in edit-mode before calling `setName`. Edit-mode is entered by calling `Plan.startEdit`.

  This method is not supported if the data item is fetched from the process instance or work item.

  Parameters:
    `name` - The new name of this UDA.
  Throws:
    `ModelInternalException` - Thrown when the process definition is not in edit-mode when this method is called, or the supplied name is invalid (e.g. length of name is 0) or `null`. Furthermore this exception is thrown if this method is called of a data item that is fetched via process instance or work item. The exception should be caught as `ModelException` for future compatibility.
  See Also:
    `Plan.startEdit()`, `getName()`

### getType

    public java.lang.String getType()

  Returns the current type of this User Defined Attribute (UDA) as defined in the `DataItemRef` interface by constants such as `TYPE_BOOLEAN`.

  The type is set with initialisation of this `DataItemRef` object. It can be changed by calling method `setType`.

  Returns:
    The String constant specifying the current type of this UDA.
  See Also:
    `setType(String)`

### setType

    public void setType(java.lang.String type)

  Sets the type of this User Defined Attribute (UDA). The parameter must be one of the constants defined in the `DataItemRef` interface such as `TYPE_BOOLEAN`.

  If the `DataItemRef` already belongs to a process definition, that process definition has to be in edit-mode before calling `setName`. Edit-mode is entered by calling `Plan.startEdit`. If process definition is not in edit mode, calling this method will have no effect.

  This method is not supported if the data item is fetched from the process instance or work item.

  Parameters:
    `type` - The new type of UDA.
  See Also:
    `getType()`, `Plan.startEdit()`

### getValue

    public java.lang.String getValue()

  Returns the current value of this User Defined Attribute (UDA). The return value is always a `String` and can be parsed to the regarding Java data type depending on the type of this UDA. For example if the type is `TYPE_BOOLEAN` you can parse the value to boolean value by `Boolean.valueOf(String)`. If no value is defined when this method is called, depending on the type of `DataItemRef` following values are returned:

  `TYPE_BIGDECIMAL` | 0.00
  `TYPE_BOOLEAN` | false
  `TYPE_DATA` | current data as long value
  `TYPE_FLOAT` | 0.0
  `TYPE_INTEGER` | 0
  `TYPE_LONG` | 0
  `TYPE_STRING` | empty `String`

  Returns:
    The current value of UDA in String format.
  See Also:
    `setValue(String)`

### setValue

    public void setValue(java.lang.String value)

  Sets the value of this User Defined Attribute (UDA).

  If the `DataItemRef` already belongs to a process definition, that process definition has to be in edit-mode before calling `setName`. Edit-mode is entered by calling `Plan.startEdit`. If process definition is not in edit mode, calling this method will have no effect.

  This method is not supported if the data item is fetched from the process instance or work item.

  Parameters:
    `value` - The new value of this UDA in String format.
  See Also:
    `getValue()`, `Plan.startEdit()`

### getDimension

    public boolean getDimension()
                         throws ModelException

  Returns if this User Defined Attribute (UDA) is marked as dimension.

  Returns:
    `true` if the UDA is marked as dimension; `false` otherwise.
  Throws:
    `ModelException`

### setDimension

    public void setDimension(boolean value)
                      throws ModelException

  Specifies if the this User Defined Attribute (UDA) is a dimension.

  If the `DataItemRef` already belongs to a process definition that process definition has to be in edit-mode before calling `setDimension`. Edit-mode of process definition is entered by calling `Plan.startEdit`.

  This method is not supported if the data item is fetched from the process instance or work item.

  Parameters:
    `value` - `true` to mark this UDA as dimension; `false` otherwise.
  Throws:
    `ModelException` - Thrown when this data item object is fetched from the process instance or work item. Furthermore this exception is thrown when the related process definition is not in edit-mode.
  See Also:
    `Plan.startEdit()`

### getMeasure

    public boolean getMeasure()
                       throws ModelException

  Returns if this User Defined Attribute (UDA) is a measure.

  Returns:
    `true` if this UDA is marked as measure; `false` otherwise.
  Throws:
    `ModelException`

### setMeasure

    public void setMeasure(boolean value)
                    throws ModelException

  Specifies if the this User Defined Attribute (UDA) is a measure.

  If the `DataItemRef` already belongs to a process definition that process definition has to be in edit-mode before calling `setMeasure`. Edit-mode of process definition is entered by calling `Plan.startEdit`.

  This method is not supported if the data item is fetched from the process instance or work item.

  Parameters:
    `value` - `true` to mark this UDA as measure; `false` otherwise.
  Throws:
    `ModelException` - Thrown when this data item object is fetched from the process instance or work item. Furthermore this exception is thrown when the related process definition is not in edit-mode.
  See Also:
    `Plan.startEdit()`

### getCubeNames

    public java.lang.String getCubeNames()
                                  throws ModelException

  Returns the cube name of the User Defined Attribute (UDA).

  Returns:
    A String representation of the cube name of the UDA.
  Throws:
    `ModelException`

### setCubeNames

    public void setCubeNames(java.lang.String name)
                      throws ModelException

  Sets the cube name of the User Defined Attribute (UDA). Before modifying the cube name of a UDA, the process definition or process instance must be placed in edit-mode.

  Parameters:
    `name` - The cube name to set the UDA to as a String.
  Throws:
    `ModelException`

### getAggregates

    public java.lang.String getAggregates()
                                   throws ModelException

  Returns the aggregates of the User Defined Attribute (UDA).

  Returns:
    A String representation of the aggregates of the UDA.
  Throws:
    `ModelException`

### setAggregates

    public void setAggregates(java.lang.String value)
                       throws ModelException

  Sets the aggregates of the User Defined Attribute (UDA). Before modifying the aggregates of a UDA, the process definition or process instance must be placed in edit-mode.

  Parameters:
    `value` - The aggregates to set the UDA to as a String.
  Throws:
    `ModelException`

### markAsWorkListUDA

    public void markAsWorkListUDA(boolean mark)
                           throws ModelException

  Sets the flag of this User Defined Attribute (UDA); setting `mark` to `true` marks this a worklist UDA.

  If this is a worklist UDA:

  1. You can sort a worklist on it.
  2. You can filter a worklist by it.
  3. The value of this UDA is delivered with the worklist for fast retrieval and display in a worklist without having to return the entire set of UDAs defined on the process definition.

  If the `DataItemRef` already belongs to a process definition, that process definition has to be in edit-mode before calling `setName`. Edit-mode is entered by calling `Plan.startEdit`.

  This method is not supported if the data item is fetched from the process instance or work item.

  Parameters:
    `mark` - `true` to mark this UDA as worklist UDA; `false` otherwise.
  Throws:
    `ModelException` - Thrown if the process definition is not in edit mode or if this method is called of a data item that is fetched via process instance or work item.
  See Also:
    `Plan.startEdit()`

### isWorkListUDA

    public boolean isWorkListUDA()
                          throws ModelException

  Returns if this User Defined Attribute (UDA) is marked as worklist UDA.

  Returns:
    `true` if the UDA is marked as worklist UDA; `false` otherwise.
  Throws:
    `ModelException`
  See Also:
    `markAsWorkListUDA(boolean)`

### markAsReadOnly

    public void markAsReadOnly(boolean mark)
                        throws ModelException

  Marks the User Defined Attributes (UDA) as a read-only or a non read-only. Setting `mark` to `true` marks this a read-only UDA. Marking a UDA as a read-only or non read-only is possible only at the design time of the process definition. Once the UDA has been marked as read-only then its value cannot be changed during the Process Enactment.

  Parameters:
    `mark` - `True` to mark this UDA as read-only; `false` otherwise.
  Throws:
    `ModelException`

### isReadOnly

    public boolean isReadOnly()
                       throws ModelException

  Returns `true` if the User Defined Attribute (UDA) is marked as read-only; `false` otherwise.

  Returns:
    `true` if the UDA is marked as read-only; `false` otherwise.
  Throws:
    `ModelException`
  See Also:
    `markAsReadOnly(boolean)`

### markUdaTracking

    public void markUdaTracking(boolean mark)
                         throws ModelException

  Marks the User Defined Attributes (UDA) to track the UDA or not to track the UDA. Setting `mark` to `true` will track this UDA throughout the lifecycle of the process instance. UDA tracking is possible both at the design time of the Process Definition and during the Process Enactment.

  Parameters:
    `mark` - `True` to mark this UDA as UDA tracking; `false` otherwise.
  Throws:
    `ModelException`

### isUdaTracking

    public boolean isUdaTracking()
                          throws ModelException

  Returns `true` if the User Defined Attribute (UDA) is marked as UDA tracking; `false` otherwise.

  Returns:
    `true` if the UDA is marked as UDA tracking; `false` otherwise.
  Throws:
    `ModelException`
  See Also:
    `markAsReadOnly(boolean)`

### getExtendedAttributes

    public org.w3c.dom.Document getExtendedAttributes()
                                               throws ModelException

  Returns the DOM document object that contains all of the User Defined Attributes (UDA) level extended attributes. The term "Extended Attributes" comes from the XPDL standard specification which uses this term to mean extra information that is not part of the standard. We use it here in a similar but not precisely the same way. Here it means 'extra information that is not native the product'. There are four different categories of information which could be associated with a UDA:
  - Category 1: known to the XPDL spec, and native to Interstage BPM. This category will never be in extended attributes. In this case XPDL and Interstage BPM 'agree' and the information is mapped back and forth without needing extended attributes.
  - Category 2: unknown to XPDL, but native to Interstage BPM. This information is encoded by Interstage BPM into extended attributes in the XPDL file when written, and when the XPDL file is read, the extended attributes are encoded back into native Interstage BPM quantities. An example of this is X & Y coordinates which are part of this API, but not a native part of XPDL 1.0, so that extended attributes would have to be used. Those extended attributes appear in the XPDL file, but do not appear here because there are other API calls to retrieve them.
  - Category 3: unknown to XPDL, and unknown to Interstage BMN. This might be extended attributes that were added to the XPDL by a foreign process product. Proper handling of XPDL requires that these values be preserved and included in the process if it is ever written out to XPDL again. These are the extended attributes that you will find represented here as well as in the XPDL file. In some cases, our own BPM clients may understand and make use of this information, so this become a general purpose extension mechanism that special purpose clients can make use of to store meta-data about the process definition, and have some assurance that it will be preserved through XPDL.
  - Category 4: known to XPDL, but not native to Interstage BPM. Theoretically, there could be information that is required to be preserved as part of an XPDL file, which is not native to BPM, and this information could be preserved using this extended attribute mechanism. Therefor it is possible that there could be additional extended attributes from this API that would not be present in the XPDL as extended attributes, but at the time of this writing there were no cases of this.

  Returns:
    The DOM document that contains all of the UDA level extended attributes.
  Throws:
    `ModelException`

### setExtendedAttributes

    public void setExtendedAttributes(org.w3c.dom.Document attrs)
                               throws ModelException

  Sets the DOM document that contains all of the User Defined Attribtes (UDA) level extended attributes.

  Parameters:
    `attrs` - The DOM document that contains all of the UDA level extended attributes.
  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