Package net.sf.saxon.trans

## Class Mode

- java.lang.Object
- - net.sf.saxon.expr.instruct.Actor
  - - net.sf.saxon.trans.Mode

- All Implemented Interfaces:
    `javax.xml.transform.SourceLocator`, `ExpressionOwner`, `Location`, `org.xml.sax.Locator`
  Direct Known Subclasses:
    `CompoundMode`, `SimpleMode`

      public abstract class Mode
      extends Actor

  A Mode is a collection of rules; the selection of a rule to apply to a given element is determined by a Pattern. A SimpleMode is a mode contained within a single package, as opposed to a CompoundMode which can combine rules from several packages

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static interface` | `Mode.RuleAction` | Interface for helper classes used to process all the rules in the Mode
    `protected static interface` | `Mode.RuleFilter` | Interface for helper classes used to filter a chain of rules

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static StructuredQName` | `DEFAULT_MODE_NAME` |
    `protected StructuredQName` | `modeName` |
    `boolean` | `mustBeTyped` |
    `boolean` | `mustBeUntyped` |
    `static StructuredQName` | `OMNI_MODE` |
    `static int` | `RECOVER_WITH_WARNINGS` |
    `static StructuredQName` | `UNNAMED_MODE_NAME` |

    - ### Fields inherited from class net.sf.saxon.expr.instruct.Actor

      `body`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Mode​(StructuredQName modeName)` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `TailCall` | `applyTemplates​(ParameterSet parameters, ParameterSet tunnelParameters, NodeInfo separator, Outputter output, XPathContextMajor context, Location locationId)` | Process selected nodes using the template rules registered for this mode.
    `abstract void` | `computeRankings​(int start)` | Compute a rank for each rule, as a combination of the precedence and priority, to allow rapid comparison.
    `void` | `explain​(ExpressionPresenter presenter)` |
    `abstract void` | `explainTemplateRules​(ExpressionPresenter out)` | Explain all template rules in this mode in a form that can be re-imported.
    `void` | `export​(ExpressionPresenter presenter)` | Export expression structure.
    `abstract void` | `exportTemplateRules​(ExpressionPresenter out)` | Export all template rules in this mode in a form that can be re-imported.
    `protected void` | `exportUseAccumulators​(ExpressionPresenter presenter)` |
    `java.util.Set<? extends Accumulator>` | `getAccumulators()` | Get the list of accumulators declared on the xsl:mode/@use-accumulators attribute
    `abstract SimpleMode` | `getActivePart()` | Get the active component of this mode.
    `abstract BuiltInRuleSet` | `getBuiltInRuleSet()` | Get the built-in template rules to be used with this Mode in the case where there is no explicit template rule
    `BuiltInRuleSet` | `getBuiltInRuleSetForCode​(java.lang.String code)` | Return a built-in rule set for a code string.
    `java.lang.String` | `getCodeForBuiltInRuleSet​(BuiltInRuleSet builtInRuleSet)` | Return a code string for a built-in rule set.
    `Component.M` | `getDeclaringComponent()` |
    `SequenceType` | `getDefaultResultType()` |
    `abstract java.util.Set<java.lang.String>` | `getExplicitNamespaces​(NamePool pool)` | Get the "explicit namespaces" matched by this mode.
    `abstract int` | `getMaxPrecedence()` | Get the maximum precedence of the rules in this mode
    `abstract int` | `getMaxRank()` | Get the highest rank of the rules in this mode
    `StructuredQName` | `getModeName()` | Get the name of the mode (for diagnostics only)
    `java.lang.String` | `getModeTitle()` | Get a title for the mode: either "Mode mode-name" or "The unnamed mode" as appropriate
    `Rule` | `getNextMatchRule​(Item item, Rule currentRule, XPathContext context)` | Get the rule corresponding to a given Node, by finding the next-best Pattern match after the specified object.
    `StructuredQName` | `getObjectName()` |
    `RecoveryPolicy` | `getRecoveryPolicy()` | Get the policy for handling recoverable errors.
    `Rule` | `getRule​(Item item, int min, int max, XPathContext context)` | Get the rule corresponding to a given Node, by finding the best Pattern match, subject to a minimum and maximum precedence.
    `abstract Rule` | `getRule​(Item item, XPathContext context)` | Get the rule corresponding to a given item, by finding the best pattern match.
    `abstract Rule` | `getRule​(Item item, XPathContext context, Mode.RuleFilter filter)` | Get the rule corresponding to a given item, by finding the best Pattern match.
    `abstract int` | `getStackFrameSlotsNeeded()` |
    `SymbolicName` | `getSymbolicName()` | Get the symbolic name of the component
    `boolean` | `isDeclaredStreamable()` | Ask whether this mode is declared to be streamable
    `abstract boolean` | `isEmpty()` | Ask whether there are any template rules in this mode (a mode could exist merely because it is referenced in apply-templates)
    `boolean` | `isModeTracing()` |
    `boolean` | `isMustBeTyped()` |
    `boolean` | `isUnnamedMode()` | Determine if this is the unnamed mode
    `XPathContext` | `makeNewContext​(XPathContext context)` | Make a new XPath context for evaluating patterns if there is any possibility that the pattern uses local variables
    `abstract void` | `processRules​(Mode.RuleAction action)` | Walk over all the rules, applying a specified action to each one.
    `void` | `setAccumulators​(java.util.Set<? extends Accumulator> accumulators)` | Set the list of accumulators declared on the xsl:mode/@use-accumulators attribute
    `void` | `setDefaultResultType​(SequenceType type)` |
    `void` | `setHasRules​(boolean hasRules)` |
    `void` | `setModeTracing​(boolean tracing)` | Switch tracing on or off
    `void` | `setRecoveryPolicy​(RecoveryPolicy policy)` | Set the policy for handling recoverable errors.
    `void` | `setStreamable​(boolean streamable)` | Say that this mode is (or is not) streamable

    - ### Methods inherited from class net.sf.saxon.expr.instruct.Actor

      `allocateAllBindingSlots, allocateBindingSlotsRecursive, getBody, getChildExpression, getColumnNumber, getComponentName, getDeclaredVisibility, getLineNumber, getLocation, getPackageData, getProperties, getProperty, getPublicId, getRetainedStaticContext, getStackFrameMap, getSystemId, getTracingTag, isExportable, makeDeclaringComponent, obtainDeclaringComponent, saveLocation, setBody, setChildExpression, setColumnNumber, setDeclaredVisibility, setDeclaringComponent, setLineNumber, setPackageData, setRetainedStaticContext, setStackFrameMap, setSystemId`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### OMNI_MODE

          public static final StructuredQName OMNI_MODE

    - #### UNNAMED_MODE_NAME

          public static final StructuredQName UNNAMED_MODE_NAME

    - #### DEFAULT_MODE_NAME

          public static final StructuredQName DEFAULT_MODE_NAME

    - #### modeName

          protected StructuredQName modeName

    - #### RECOVER_WITH_WARNINGS

          public static final int RECOVER_WITH_WARNINGS

      See Also:
        Constant Field Values

    - #### mustBeTyped

          public boolean mustBeTyped

    - #### mustBeUntyped

          public boolean mustBeUntyped

  - ### Constructor Detail

    - #### Mode

          public Mode​(StructuredQName modeName)

  - ### Method Detail

    - #### getDeclaringComponent

          public Component.M getDeclaringComponent()

      Overrides:
        `getDeclaringComponent` in class `Actor`

    - #### getBuiltInRuleSet

          public abstract BuiltInRuleSet getBuiltInRuleSet()

      Get the built-in template rules to be used with this Mode in the case where there is no explicit template rule
      Returns:
        the built-in rule set, defaulting to the TextOnlyCopyRuleSet if no other rule set has been supplied

    - #### isUnnamedMode

          public boolean isUnnamedMode()

      Determine if this is the unnamed mode
      Returns:
        true if this is the unnamed mode

    - #### getModeName

          public StructuredQName getModeName()

      Get the name of the mode (for diagnostics only)
      Returns:
        the mode name. Null for the default (unnamed) mode

    - #### getActivePart

          public abstract SimpleMode getActivePart()

      Get the active component of this mode. For a simple mode this is the mode itself; for a compound mode it is the "overriding" part

    - #### getMaxPrecedence

          public abstract int getMaxPrecedence()

      Get the maximum precedence of the rules in this mode

    - #### getMaxRank

          public abstract int getMaxRank()

      Get the highest rank of the rules in this mode
      Returns:
        the highest rank

    - #### computeRankings

          public abstract void computeRankings​(int start)
                                        throws XPathException

      Compute a rank for each rule, as a combination of the precedence and priority, to allow rapid comparison. This method also checks that there are no conflicts for property values in different xsl:mode declarations
      Parameters:
        `start` - the lowest rank to use
      Throws:
        `XPathException` - if an error occurs processing the rules

    - #### getModeTitle

          public java.lang.String getModeTitle()

      Get a title for the mode: either "Mode mode-name" or "The unnamed mode" as appropriate
      Returns:
        a title for the mode

    - #### setModeTracing

          public void setModeTracing​(boolean tracing)

      Switch tracing on or off

    - #### isModeTracing

          public boolean isModeTracing()

    - #### getAccumulators

          public java.util.Set<? extends Accumulator> getAccumulators()

      Get the list of accumulators declared on the xsl:mode/@use-accumulators attribute
      Returns:
        the list of accumulators applicable when this is the initial mode

    - #### setAccumulators

          public void setAccumulators​(java.util.Set<? extends Accumulator> accumulators)

      Set the list of accumulators declared on the xsl:mode/@use-accumulators attribute
      Parameters:
        `accumulators` - the list of accumulators applicable when this is the initial mode

    - #### getSymbolicName

          public SymbolicName getSymbolicName()

      Description copied from class: `Actor`
      Get the symbolic name of the component
      Specified by:
        `getSymbolicName` in class `Actor`
      Returns:
        the symbolic name

    - #### getObjectName

          public StructuredQName getObjectName()

    - #### isEmpty

          public abstract boolean isEmpty()

      Ask whether there are any template rules in this mode (a mode could exist merely because it is referenced in apply-templates)
      Returns:
        true if no template rules exist in this mode

    - #### setRecoveryPolicy

          public void setRecoveryPolicy​(RecoveryPolicy policy)

      Set the policy for handling recoverable errors. Note that for some errors the decision can be made at run-time, but for the "ambiguous template match" error, the decision is (since 9.2) fixed at compile time.
      Parameters:
        `policy` - the recovery policy to be used.

    - #### setHasRules

          public void setHasRules​(boolean hasRules)

    - #### getRecoveryPolicy

          public RecoveryPolicy getRecoveryPolicy()

      Get the policy for handling recoverable errors. Note that for some errors the decision can be made at run-time, but for the "ambiguous template match" error, the decision is (since 9.2) fixed at compile time.
      Returns:
        the current policy.

    - #### setStreamable

          public void setStreamable​(boolean streamable)

      Say that this mode is (or is not) streamable
      Parameters:
        `streamable` - true if this mode is a streamable mode

    - #### isDeclaredStreamable

          public boolean isDeclaredStreamable()

      Ask whether this mode is declared to be streamable
      Returns:
        true if this mode is declared with the option streamable="yes"

    - #### getExplicitNamespaces

          public abstract java.util.Set<java.lang.String> getExplicitNamespaces​(NamePool pool)

      Get the "explicit namespaces" matched by this mode. Returns a set containing all the namespaces matched by specific template rules in this mode
      Parameters:
        `pool` - the NamePool for the configuration
      Returns:
        the set of all namespace URIs of names explicitly matched by rules in this mode

    - #### setDefaultResultType

          public void setDefaultResultType​(SequenceType type)

    - #### getDefaultResultType

          public SequenceType getDefaultResultType()

    - #### processRules

          public abstract void processRules​(Mode.RuleAction action)
                                     throws XPathException

      Walk over all the rules, applying a specified action to each one.
      Parameters:
        `action` - an action that is to be applied to all the rules in this Mode
      Throws:
        `XPathException` - if an error occurs processing any of the rules

    - #### makeNewContext

          public XPathContext makeNewContext​(XPathContext context)

      Make a new XPath context for evaluating patterns if there is any possibility that the pattern uses local variables
      Parameters:
        `context` - The existing XPath context
      Returns:
        a new XPath context

    - #### getRule

          public abstract Rule getRule​(Item item,
                                       XPathContext context)
                                throws XPathException

      Get the rule corresponding to a given item, by finding the best pattern match.
      Parameters:
        `item` - the item to be matched
        `context` - the XPath dynamic evaluation context
      Returns:
        the best matching rule, if any (otherwise null).
      Throws:
        `XPathException` - if an error occurs matching a pattern

    - #### getRule

          public abstract Rule getRule​(Item item,
                                       XPathContext context,
                                       Mode.RuleFilter filter)
                                throws XPathException

      Get the rule corresponding to a given item, by finding the best Pattern match.
      Parameters:
        `item` - the item to be matched
        `context` - the XPath dynamic evaluation context
        `filter` - a filter to select which rules should be considered
      Returns:
        the best matching rule, if any (otherwise null).
      Throws:
        `XPathException` - if an error occurs

    - #### getRule

          public Rule getRule​(Item item,
                              int min,
                              int max,
                              XPathContext context)
                       throws XPathException

      Get the rule corresponding to a given Node, by finding the best Pattern match, subject to a minimum and maximum precedence. (This supports xsl:apply-imports)
      Parameters:
        `item` - the item to be matched
        `min` - the minimum import precedence
        `max` - the maximum import precedence
        `context` - the XPath dynamic evaluation context
      Returns:
        the Rule registered for that node, if any (otherwise null).
      Throws:
        `XPathException` - if an error occurs evaluating match patterns

    - #### getNextMatchRule

          public Rule getNextMatchRule​(Item item,
                                       Rule currentRule,
                                       XPathContext context)
                                throws XPathException

      Get the rule corresponding to a given Node, by finding the next-best Pattern match after the specified object.
      Parameters:
        `item` - the NodeInfo referring to the node to be matched
        `currentRule` - the current rule; we are looking for the next match after the current rule
        `context` - the XPath dynamic evaluation context
      Returns:
        the object (e.g. a NodeHandler) registered for that element, if any (otherwise null).
      Throws:
        `XPathException` - if an error occurs matching a pattern

    - #### exportTemplateRules

          public abstract void exportTemplateRules​(ExpressionPresenter out)
                                            throws XPathException

      Export all template rules in this mode in a form that can be re-imported. Note that template rules with union patterns may have been split into multiple rules. We need to avoid outputting them more than once.
      Parameters:
        `out` - used to display the expression tree
      Throws:
        `XPathException`

    - #### explainTemplateRules

          public abstract void explainTemplateRules​(ExpressionPresenter out)
                                             throws XPathException

      Explain all template rules in this mode in a form that can be re-imported. Note that template rules with union patterns may have been split into multiple rules. We need to avoid outputting them more than once.
      Parameters:
        `out` - used to display the expression tree
      Throws:
        `XPathException`

    - #### applyTemplates

          public TailCall applyTemplates​(ParameterSet parameters,
                                         ParameterSet tunnelParameters,
                                         NodeInfo separator,
                                         Outputter output,
                                         XPathContextMajor context,
                                         Location locationId)
                                  throws XPathException

      Process selected nodes using the template rules registered for this mode.
      Parameters:
        `parameters` - A ParameterSet containing the parameters to the handler/template being invoked. Specify null if there are no parameters.
        `tunnelParameters` - A ParameterSet containing the parameters to the handler/template being invoked. Specify null if there are no parameters.
        `separator` - Text node to be inserted between the output of successive input items; may be null
        `output` - The destination for the result of the selected templates
        `context` - A newly-created context object (this must be freshly created by the caller, as it will be modified by this method). The nodes to be processed are those selected by the currentIterator in this context object. There is also a precondition that this mode must be the current mode in this context object.
        `locationId` - location of this apply-templates instruction in the stylesheet
      Returns:
        a TailCall returned by the last template to be invoked, or null, indicating that there are no outstanding tail calls.
      Throws:
        `XPathException` - if any dynamic error occurs

    - #### getStackFrameSlotsNeeded

          public abstract int getStackFrameSlotsNeeded()

    - #### getCodeForBuiltInRuleSet

          public java.lang.String getCodeForBuiltInRuleSet​(BuiltInRuleSet builtInRuleSet)

      Return a code string for a built-in rule set. This can be specialised in subclasses for PE/EE
      Parameters:
        `builtInRuleSet` - the rule set to get a code
      Returns:
        a simple string code or "???" if the ruleset is unknown

    - #### getBuiltInRuleSetForCode

          public BuiltInRuleSet getBuiltInRuleSetForCode​(java.lang.String code)

      Return a built-in rule set for a code string.
      Parameters:
        `code` - the code used in export
      Returns:
        a suitable ruleset

    - #### export

          public final void export​(ExpressionPresenter presenter)
                            throws XPathException

      Description copied from class: `Actor`
      Export expression structure. The abstract expression tree is written to the supplied outputstream.
      Specified by:
        `export` in class `Actor`
      Parameters:
        `presenter` - the expression presenter used to generate the XML representation of the structure
      Throws:
        `XPathException`

    - #### exportUseAccumulators

          protected void exportUseAccumulators​(ExpressionPresenter presenter)

    - #### isMustBeTyped

          public boolean isMustBeTyped()

    - #### explain

          public void explain​(ExpressionPresenter presenter)
                       throws XPathException

      Throws:
        `XPathException`