org.inria.ns.reflex.processor.asl
Class ItemMatcher

java.lang.Object
  extended by org.inria.ns.reflex.processor.asl.ItemMatcher
All Implemented Interfaces:
Reducible
Direct Known Subclasses:
AttributeAction.Matcher, ElementAction.Matcher, TextAction.Matcher, TypeMatcher

public abstract class ItemMatcher
extends Object
implements Reducible

An item matcher used to build a mixed list of elements and text content, a list of attributes, a list of types, or a list of assertions.

The min rest may be tested to reveal whether an attribute is optional or not, but with attributes, the use() method has no sense, except for generic attributes matchers that refers to a namespace URI.

The matches() method is used to test if an object matches this matcher. In this case, the result is a TypedData if the result carries datas, or the marker object FOUND. If the object doesn't match this matcher, the marker object NOT_FOUND is returned. Usually, the matches() method works like a boolean and return FOUND or NOT_FOUND.

A TypedData is provided only when a Type is involved. An item matcher is tested upon a candidate material by a SchemaClientHandler, that will report an error only if this matcher must match the candidate material.

Author:
Philippe Poulard

Field Summary
static TypedData FOUND
          Denotes that an item to match was found.
static TypedData NOT_FOUND
          Denotes that an item to match was not found.
 
Constructor Summary
ItemMatcher()
          Create a matcher that must be use once and only once.
ItemMatcher(int maxOccurs, int minOccurs)
          Create the matcher.
 
Method Summary
 boolean canUse()
          Indicates whether this material can be used or not.
abstract  AbstractAction getAction()
          Return the action that has created this material item (used to report errors).
 List getExceptions()
          Return the materials that are exceptions to this material.
 InterimStepAction getInterimStep()
          Return the interim step (used to report errors).
 int getMaxInit()
          Return the max init value.
 int getMaxRest()
          Return the max value resting.
 int getMinInit()
          Return the min init value.
 int getMinRest()
          Return the min value resting.
abstract  TypedData matches(Object o, DataSet dataSet)
          Test if an object matches this material.
 boolean mustUse()
          Indicates whether this material must be used or not.
abstract  ValidationError reportError(Element element, Node candidate)
          Raise an error.
 void reset()
          Reset the min and max occurences used to their initial values.
 boolean runInterim(DataSet dataSet)
          Run the interim step.
 void setBoundaries(int maxOccurs, int minOccurs)
          Set the boundaries.
 void setInterimStep(InterimStepAction interimStep)
          Set the interim step to use when this matcher matches.
 void use()
          Uses the material, that is to say decrements the min and max occurences that remains.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FOUND

public static final TypedData FOUND
Denotes that an item to match was found. This marker contains no data and no type.


NOT_FOUND

public static final TypedData NOT_FOUND
Denotes that an item to match was not found. This marker contains no data and no type.

Constructor Detail

ItemMatcher

public ItemMatcher(int maxOccurs,
                   int minOccurs)
Create the matcher.

Parameters:
maxOccurs - The number max of occurrences to use this material.
minOccurs - The number min of occurrences to use this material.

ItemMatcher

public ItemMatcher()
Create a matcher that must be use once and only once.

Method Detail

setBoundaries

public void setBoundaries(int maxOccurs,
                          int minOccurs)
Set the boundaries.

Parameters:
maxOccurs - The number max of occurrences to use this matcher.
minOccurs - The number min of occurrences to use this matcher.

setInterimStep

public void setInterimStep(InterimStepAction interimStep)
Set the interim step to use when this matcher matches.

Parameters:
interimStep - The interim step of this matcher.

runInterim

public boolean runInterim(DataSet dataSet)
                   throws ExecutionException
Run the interim step.

Parameters:
dataSet - The data set to use.
Returns:
true if the interim step must replace the disrupted step, false otherwise.
Throws:
ExecutionException

getInterimStep

public InterimStepAction getInterimStep()
Return the interim step (used to report errors).

Returns:
The interim step, or null.

reset

public void reset()
Reset the min and max occurences used to their initial values.


use

public void use()
Uses the material, that is to say decrements the min and max occurences that remains.


getMaxInit

public int getMaxInit()
Return the max init value.

Returns:
The max init value.

getMinInit

public int getMinInit()
Return the min init value.

Returns:
The min init value.

getMaxRest

public int getMaxRest()
Return the max value resting.

Returns:
The max value resting.

getMinRest

public int getMinRest()
Return the min value resting.

Returns:
The min value resting.

canUse

public boolean canUse()
Indicates whether this material can be used or not.

Returns:
true if this material can be use according to its use and max boundary , false otherwise.

mustUse

public boolean mustUse()
Indicates whether this material must be used or not.

Returns:
true if this material must be use according to its use and min boundary , false otherwise.

matches

public abstract TypedData matches(Object o,
                                  DataSet dataSet)
Test if an object matches this material.

Parameters:
o - The object to test.
dataSet - The set of data that may contain useful properties for matchers that are parsing data types. Particularly, types defined with the <asl:type> element are using a data set. The data set should contain the schema client handler on behalf this parsing will be performed. User defined data parsers uses the client when it is defined with active tags such as <asl:sequence>, <asl:choice> etc. Built-in data parsers usually ignore it. Additionally, the data set is used to store the typed data currently parsing, $asl:data.
Returns:
FOUND if the object matches this material and carries no data, a TypedData if the object matches this material and carries a data, NOT_FOUND otherwise.

getAction

public abstract AbstractAction getAction()
Return the action that has created this material item (used to report errors).

Returns:
The action that has created this material item.

reportError

public abstract ValidationError reportError(Element element,
                                            Node candidate)
Raise an error. This method is used by the SchemaClientHandler when a candidate material failed to match whereas it is expected.

Parameters:
element - The element in fault.
candidate - The candidate node that cause the fault.
Returns:
The validation error raised.

getExceptions

public List getExceptions()
Return the materials that are exceptions to this material.

Specified by:
getExceptions in interface Reducible
Returns:
The non null list of ItemMatcher exceptions. If this method is not overriden, an empty list is returned.