## gate.fsm
Class FSMInstance

    java.lang.Object
      |
      +--gate.fsm.FSMInstance

All Implemented Interfaces:
  Cloneable, Comparable, Serializable

public class FSMInstance
extends Object
implements Comparable, Cloneable, Serializable

The objects of this class represent instances of working Finite State Machine during parsing a gate document (annotation set). In order to completely define the state a FSM is in one needs to store information regarding: -the position in the FSM transition graph -the position in the annotation graph -the set of bindings that occured up to the current state. note that a set of bindings is an object of type Map that maps names (java.lang.String) to bags of annotations (gate.AnnotationSet)

See Also:
  Serialized Form

Constructor Summary
`FSMInstance(FSM supportGraph, State FSMPosition, Node startNode, Node AGPosition, HashMap bindings, Document document)` Creates a new FSMInstance object.

Method Summary
`static void` `clearInstances()` Release all the FSMInstances that are not currently in use
`Object` `clone()` Returns a clone of this object.
`int` `compareTo(Object obj)` Implementation of the compareTo method required by the Comparable interface.
`boolean` `equals(Object other)`
`Node` `getAGPosition()` Returns the node up to which this FSM instance advanced in the Annotation graph during the matching process.
`HashMap` `getBindings()` Gets the map representing the bindings that took place during the matching process this FSM instance performed.
`int` `getFileIndex()` Returns the index in the Jape definition file of the rule that caused the generation of the FSM state this instance is in.
`State` `getFSMPosition()` Returns the position in the support graph for this FSM instance
`long` `getLength()` Returns the length of the parsed region in the document under scrutiny.
`static FSMInstance` `getNewInstance(FSM supportGraph, State FSMPosition, Node startNode, Node AGPosition, HashMap bindings, Document doc)` Static method that provides new FSM instances.
`Node` `getStartAGPosition()` Returns the node in the AnnotationGraph from which this FSM instance started the matching process.
`FSM` `getSupportGraph()` Returns the FSM transition graph that backs this FSM instance
`int` `hashCode()` Overrides the hashCode method from Object so this obejcts can be stored in hash maps and hash sets.
`static void` `returnInstance(FSMInstance ins)` Static method used to return a FSMInstance that is not needed anymore
`void` `setAGPosition(Node node)` Sets the current position in the AnnotationGraph.
`void` `setFSMPosition(State newFSMPos)` Sets the position in the support transition graph for this FSM instance Convenience method for when the state is not known at construction time.
`String` `toString()` Returns a textual representation of this FSM instance.

Methods inherited from class java.lang.Object
`getClass, notify, notifyAll, wait, wait, wait`

Constructor Detail

### FSMInstance

    public FSMInstance(FSM supportGraph,
                       State FSMPosition,
                       Node startNode,
                       Node AGPosition,
                       HashMap bindings,
                       Document document)

  Creates a new FSMInstance object.
  Parameters:
    `supportGraph` - the transition graph of the FSM
    `FSMPosition` - the state this instance will be in
    `startNode` - the node in the AnnotationGraph where this FSM instance started the matching
    `bindings` - a HashMap that maps from labels (objects of type String) to sets of annotations (objects of type AnnotationSet). This map stores all the bindings that took place during the matching process. This FSMInstance started the matching on an AnnotationSet from "startNode" and advanced to "AGPosition"; during this process it traversed the path in the transition graph "supportGraph" from the initial state to "FSMPosition" and made the bindings stored in "bindings".

Method Detail

### getSupportGraph

    public FSM getSupportGraph()

  Returns the FSM transition graph that backs this FSM instance
  Returns:
    an FSM object

### getFSMPosition

    public State getFSMPosition()

  Returns the position in the support graph for this FSM instance
  Returns:
    an object of type State

### setFSMPosition

    public void setFSMPosition(State newFSMPos)

  Sets the position in the support transition graph for this FSM instance Convenience method for when the state is not known at construction time.

### getFileIndex

    public int getFileIndex()

  Returns the index in the Jape definition file of the rule that caused the generation of the FSM state this instance is in. This value is correct if and only if this FSM instance is in a final state of the FSM transition graph.
  Returns:
    an int value.

### getStartAGPosition

    public Node getStartAGPosition()

  Returns the node in the AnnotationGraph from which this FSM instance started the matching process.
  Returns:
    a gate.Node object

### getAGPosition

    public Node getAGPosition()

  Returns the node up to which this FSM instance advanced in the Annotation graph during the matching process.
  Returns:
    a gate.Node object

### setAGPosition

    public void setAGPosition(Node node)

  Sets the current position in the AnnotationGraph. Convenience method for cases when this value is not known at construction time.
  Parameters:
    `node` - a position in the AnnotationGraph

### getBindings

    public HashMap getBindings()

  Gets the map representing the bindings that took place during the matching process this FSM instance performed.
  Returns:
    a HashMap object

### getLength

    public long getLength()

  Returns the length of the parsed region in the document under scrutiny. More precisely this is the distnace between the Node in the annotation graph where the matching started and the current position.
  Returns:
    a long value

### hashCode

    public int hashCode()

  Overrides the hashCode method from Object so this obejcts can be stored in hash maps and hash sets.
  Overrides:
    `hashCode` in class `Object`

### equals

    public boolean equals(Object other)

  Overrides:
    `equals` in class `Object`

### clone

    public Object clone()

  Returns a clone of this object. The cloning is done bitwise except for the bindings that are cloned by themselves
  Returns:
    an Object value that is actually a FSMInstance object

### compareTo

    public int compareTo(Object obj)

  Implementation of the compareTo method required by the Comparable interface. The comparison is based on the size of the matched region and the index in the definition file of the rule associated to this FSM instance (which needs to be in a final state) The order imposed by this method is the priority needed in case of a multiple match.
  Specified by:
    `compareTo` in interface `Comparable`

### toString

    public String toString()

  Returns a textual representation of this FSM instance.
  Overrides:
    `toString` in class `Object`

### getNewInstance

    public static FSMInstance getNewInstance(FSM supportGraph,
                                             State FSMPosition,
                                             Node startNode,
                                             Node AGPosition,
                                             HashMap bindings,
                                             Document doc)

  Static method that provides new FSM instances. This method handles some basic object pooling in order to reuse the FSMInstance objects. This is considered to be a good idea because during jape transducing a large number of FSMIntances are needed for short periods.

### returnInstance

    public static void returnInstance(FSMInstance ins)

  Static method used to return a FSMInstance that is not needed anymore

### clearInstances

    public static void clearInstances()

  Release all the FSMInstances that are not currently in use