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 Arrow

All Known Subinterfaces:
  ArrowInstance

public interface Arrow

`Arrow`s are simple objects that connect nodes and change the state of their target nodes to an active state. The flow of events passes through the arrow from head to tail (source node to target node).

`Arrow`s have the following set of attributes: ID, Name, and Description. The ID attribute is of the `long` data type and is automatically assigned by the server to provide a unique handle for the process definition. The Description attribute and the Name attribute are optional.

Each arrow that leaves an activity node represents a choice that the activity assignees can make to complete the activity. The Name attributes of the arrows correspond to their choices. For example, if there are two arrows leaving a particular activity node, and the names of those arrows are `Approve` and `Reject`, the choices available on the activity's work items (there is a work item for every activity assignee) will be `Approve` and `Reject`. The Name attribute is also useful for documenting the structure of the process definition.

An assignee makes a particular choice on a work item by calling the `WorkItem.makeChoice` method. After a choice is selected, the process instance follows the path represented by the chosen arrow. Again, the name corresponds to the choice made.

For conditional nodes, the choice made depends on which condition is satisfied. This conditions must be set up within the node specification.

The standard way of constructing a new arrow is to call the method `Plan.addArrow`. The attributes of the arrow can then be modified by methods associated with the arrow's interface (for example `Arrow.setDesc`).

The `String` parameters of all the methods in this class have a length limit. This limit is documented in the Javadoc descriptions 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 the `ModelException` class. For future compatibility, only a `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.

See Also:
  `Plan`, `Node`, `WorkItem`

Field Summary
`static int` | `MAX_ARROW_DESCRIPTION_LENGTH` Specifies the maximum length of the arrow description; currently 256 characters.
`static int` | `MAX_ARROW_NAME_LENGTH` Specifies the maximum length of the arrow name; currently 30 characters.
`static int` | `MAX_ARROW_POINTS` Specifies the maximum points that can be entered for an arrow; set to the number of 24 currently.
`static int` | `TYPE_REGULAR` Deprecated. - all arrows are TYPE_REGULAR

Method Summary
`boolean` | `equals(Arrow arrow)` Deprecated. Use getArrowId() == arrow.getArrowId() instead.
`long` | `getArrowId()` Returns the ID of this arrow.
`java.lang.String` | `getDesc()` Returns the description of this arrow.
`java.awt.Point` | `getEndPoint()` Returns the end point of this arrow.
`org.w3c.dom.Document` | `getExtendedAttributes()` Returns the DOM document object that contains all of the UDA level extended attributes.
`java.lang.String` | `getName()` Returns the name of this arrow.
`Plan` | `getPlan()` Returns the process definition that this arrow belongs to.
`int` | `getPointCount()` Returns the number of defined points between start and end point stored by using method `setPoints`.
`java.awt.Point[]` | `getPoints()` Returns the defined points between start and end point of this arrow.
`Node` | `getSourceNode()` Returns the node in the process definition from which this arrow originates.
`java.awt.Point` | `getStartPoint()` Returns the current starting point coordinates of this arrow.
`Node` | `getTargetNode()` Returns the node of the process definition at which this arrow ends.
`int` | `getType()` Deprecated. - all arrows are TYPE_REGULAR
`void` | `setDesc(java.lang.String description)` Sets the arrow description.
`void` | `setEndPoint(java.awt.Point pos)` Sets the end point of this arrow.
`void` | `setExtendedAttributes(org.w3c.dom.Document attrs)` Sets the DOM document that contains all of the extended attributes of an Arrow.
`void` | `setName(java.lang.String arrowName)` Sets the name of this arrow.
`void` | `setPoints(java.awt.Point[] points)` Stores a set of points for this arrow.
`void` | `setSourceNode(Node node)` Sets the node of the process definition from which this arrow originates.
`void` | `setStartPoint(java.awt.Point pos)` Sets the starting point of this arrow.
`void` | `setTargetNode(Node node)` Sets the node of the process definition at which this arrow ends.

Field Detail

### TYPE_REGULAR

    public static final int TYPE_REGULAR

  Deprecated. - all arrows are TYPE_REGULAR

  See Also:
    Constant Field Values

### MAX_ARROW_NAME_LENGTH

    public static final int MAX_ARROW_NAME_LENGTH

  Specifies the maximum length of the arrow name; currently 30 characters.

  See Also:
    Constant Field Values

### MAX_ARROW_DESCRIPTION_LENGTH

    public static final int MAX_ARROW_DESCRIPTION_LENGTH

  Specifies the maximum length of the arrow description; currently 256 characters.

  See Also:
    Constant Field Values

### MAX_ARROW_POINTS

    public static final int MAX_ARROW_POINTS

  Specifies the maximum points that can be entered for an arrow; set to the number of 24 currently.

  See Also:
    Constant Field Values

Method Detail

### getArrowId

    public long getArrowId()

  Returns the ID of this arrow. Each arrow within a process definition has a unique ID number associated with it. The ID is allocated by the Interstage BPM server whithin creation of the appropriate process definition.

  Returns:
    The ID number of this arrow.

### getName

    public java.lang.String getName()

  Returns the name of this arrow. The name of an arrow is one method of identification. It can serve as a short descriptive name to help document the structure of a process definition and to specify nodes and execute work items.

  The name of the arrow is initialized while adding it to the process definition. It can be changed by calling method `setName(String)`.

  Returns:
    A `String` containing the name of this arrow.

### getDesc

    public java.lang.String getDesc()

  Returns the description of this arrow. The description (if defined) typically contains destination information or instructions for the user why to select one choice over another. Returns an empty `String` if the description was not set before.

  Returns:
    A string containing the description of this arrow.
  See Also:
    `setDesc(String)`

### setName

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

  Sets the name of this arrow. The name of an arrow is one method of identifying it and should be short and descriptive.

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

  Depending on the component this arrow belongs to, edit-mode of process definition or structural edit-mode of process instance is required. Edit-mode of process definition is entered by calling `Plan.startEdit`. Structural edit-mode is entered by calling `ProcessInstance.startStructuralEdit`.

  Parameters:
    `arrowName` - The new name of this arrow.
  Throws:
    `ModelInternalException` - Thrown when the process definition or process instance is not in (structural) edit-mode when this method is called, or the supplied name is invalid or `null`. Should be caught as `ModelException` for future compatibility.
  See Also:
    `Plan.startEdit()`, `ProcessInstance.startStructuralEdit()`, `getName()`

### setDesc

    public void setDesc(java.lang.String description)
                 throws ModelInternalException

  Sets the arrow description. The description is a field to store a long text which contains further information about this arrow.

  The text must not be longer than specified in `MAX_ARROW_DESCRIPTION_LENGTH`.

  Depending on the component this arrow belongs to, edit-mode of process definition or structural edit-mode of process instance is required. Edit-mode of process definition is entered by calling `Plan.startEdit`. Structural edit mode is entered by calling `ProcessInstance.startStructuralEdit`.

  Parameters:
    `description` - The new description of this arrow.
  Throws:
    `ModelInternalException` - Thrown when the process definition is not in edit-mode when this method is called, or the supplied description is invalid or `null`. Should be caught as `ModelException` for future compatibility.
  See Also:
    `Plan.startEdit()`, `ProcessInstance.startStructuralEdit()`, `getDesc()`

### getStartPoint

    public java.awt.Point getStartPoint()

  Returns the current starting point coordinates of this arrow. Arrows can have start and end points that specify the physical location for graphical representation.

  The start point is calculated depending on the position of the source node, if no start point is specified manually.

  Returns:
    A point object that identifies the x and y coordinates of starting point.
  See Also:
    `setStartPoint(Point)`, `getEndPoint()`

### setStartPoint

    public void setStartPoint(java.awt.Point pos)

  Sets the starting point of this arrow. This is used for graphical representation of an arrow.

  The min and max range of x and y coordinate is limited to -32768 and 32767. If the supplied coordinates exceeds this range, the position is not set. It is recommended to use positive values only since it is dependent on the GUI tool whether negative values are supported or not.

  Depending on the component this arrow belongs to, edit-mode of process definition or structural edit-mode of process instance is required. Edit-mode of process definition is entered by calling `Plan.startEdit`. Structural edit mode is entered by calling `ProcessInstance.startStructuralEdit`. When not in edit-mode, calling this method will have no effect.

  Parameters:
    `pos` - The x and y coordinates of starting point.
  See Also:
    `Plan.startEdit()`, `ProcessInstance.startStructuralEdit()`, `setEndPoint(Point)`

### getEndPoint

    public java.awt.Point getEndPoint()

  Returns the end point of this arrow. Arrows have end points that specify the physical location of the end of the arrow in x and y coordinates. This is used for the graphical representation of an arrow.

  The end point is calculated depending on the position of the target node, if no end point is specified manually.

  Returns:
    A Point object that identifies the x and y coordinates of end point.
  See Also:
    `setEndPoint(Point)`, `getStartPoint()`

### setEndPoint

    public void setEndPoint(java.awt.Point pos)

  Sets the end point of this arrow. This is used for graphical representation of an arrow.

  The min and max range of x and y coordinate is limited to -32768 and 32767. If the supplied coordinates exceeds this range, the position is not set. It is recommended to use positive values only since it is dependent on the GUI tool whether negative values are supported or not.

  Depending on the component this arrow belongs to, edit-mode of process definition or structural edit-mode of process instance is required. Edit-mode of process definition is entered by calling `Plan.startEdit`. Structural edit mode is entered by calling `ProcessInstance.startStructuralEdit`. When not in edit-mode, calling this method will have no effect.

  Parameters:
    `pos` - The x and y coordinates of end point.
  See Also:
    `Plan.startEdit()`, `ProcessInstance.startStructuralEdit()`, `setStartPoint(Point)`

### getType

    public int getType()

  Deprecated. - all arrows are TYPE_REGULAR

### getSourceNode

    public Node getSourceNode()

  Returns the node in the process definition from which this arrow originates.

  The source node is initialized while adding it to the process definition. It can be changed by calling method `setSourceNode(Node)`.

  Returns:
    The node object where this arrow starts.
  See Also:
    `setSourceNode(Node)`

### setSourceNode

    public void setSourceNode(Node node)

  Sets the node of the process definition from which this arrow originates.

  Depending on the component this arrow belongs to, edit-mode of process definition or structural edit-mode of process instance is required. Edit-mode of process definition is entered by calling `Plan.startEdit`. Structural edit mode is entered by calling `ProcessInstance.startStructuralEdit`. When not in edit-mode, calling this method will have no effect.

  Parameters:
    `node` - The node object that specifies the source node of the arrow.
  See Also:
    `Plan.startEdit()`, `ProcessInstance.startStructuralEdit()`, `getSourceNode()`

### getTargetNode

    public Node getTargetNode()

  Returns the node of the process definition at which this arrow ends.

  The target node is initialized while adding it to the process definition. It can be changed by calling method `setTargetNode(Node)`.

  Returns:
    The node object where this arrow ends.
  See Also:
    `setTargetNode(Node)`

### setTargetNode

    public void setTargetNode(Node node)

  Sets the node of the process definition at which this arrow ends.

  Depending on the component this arrow belongs to, edit-mode of process definition or structural edit-mode of process instance is required. Edit-mode of process definition is entered by calling `Plan.startEdit`. Structural edit mode is entered by calling `ProcessInstance.startStructuralEdit`. When not in edit-mode, calling this method will have no effect.

  Parameters:
    `node` - The node object that specifies the target for this arrow.
  See Also:
    `Plan.startEdit()`, `ProcessInstance.startStructuralEdit()`, `getTargetNode()`, `setSourceNode(Node)`

### getPlan

    public Plan getPlan()

  Returns the process definition that this arrow belongs to.

  With initializing the arrow it is automatically added to a process definition.

  Returns:
    The process definition.

### equals

    public boolean equals(Arrow arrow)

  Deprecated. Use getArrowId() == arrow.getArrowId() instead.

### getPoints

    public java.awt.Point[] getPoints()

  Returns the defined points between start and end point of this arrow.

  Returns:
    An array of point objects containing the specified coordinates between start and end point. Returns `null` if not points are defined.
  See Also:
    `setPoints(Point[])`, `getPointCount()`

### setPoints

    public void setPoints(java.awt.Point[] points)
                   throws ModelInternalException

  Stores a set of points for this arrow. This method is used for graphical representation of an arrow.

  It is possible that a process definition contains bi-directional connections between nodes. In such a case the visualisation of arrows is difficult if only a start and an end point is defined because the arrows would lay on top of each other. To avoid this, the path can be specified more deeply by splitting it into a list of points.

  The min and max range of x and y coordinates is limited to -32768 and 32767. If the coordinates of supplied points exceeds this range, the position is not set. It is recommended to use positive values only since it is dependent on the GUI tool whether negative values are supported or not.

  The length of list must not be longer than defined in `MAX_ARROW_POINTS`. The regarding process definition has to be in edit-mode before calling `setPoints` of this arrow. Edit-mode is entered by calling `Plan.startEdit`. If the arrow still belongs to a process instance, that process instance must be in structural edit-mode before calling this method. Structural edit-mode is entered by calling `ProcessInstance.startStructuralEdit`.

  Throws:
    `ModelInternalException` - Thrown when the process definition is not in edit-mode when this method is called, or if length of list is invalid or `null`. Should be caught as `ModelException` for future compatibility.
  See Also:
    `Plan.startEdit()`, `ProcessInstance.startStructuralEdit()`, `getPoints()`

### getPointCount

    public int getPointCount()

  Returns the number of defined points between start and end point stored by using method `setPoints`.

  Returns:
    The number of defined points excluding start and end point. Returns 0 if no points between start and end point are defined.
  See Also:
    `getPoints()`, `setPoints(Point[])`

### getExtendedAttributes

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

  Returns the DOM document object that contains all of the 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 an arrow:
  - 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 extended attributes.
  Throws:
    `ModelException` - Thrown when this operation is called from a `ArrowInstance`. This operation is only supported on the arrow definition level. It is not possible to get the extended attributes from an instance of a node.
  See Also:
    `setExtendedAttributes(Document)`

### setExtendedAttributes

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

  Sets the DOM document that contains all of the extended attributes of an Arrow. See getExtendedAttributes for an explanation of how this works.

  Parameters:
    `attrs` - The DOM document that contains all of the UDA level extended attributes.
  Throws:
    `ModelException` - Thrown when this operation is called from a `ArrowInstance`. This operation is only supported on the arrow definition level. It is not possible to get the extended attributes from an instance of a node.
  See Also:
    `getExtendedAttributes()`

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