net.sf.saxon.trans

## Class Mode

- java.lang.Object
- - net.sf.saxon.trans.Mode

- All Implemented Interfaces:
    Serializable

      public class Mode
      extends Object
      implements Serializable

  A Mode is a collection of rules; the selection of a rule to apply to a given element is determined by a Pattern.
  Author:
    Michael H. Kay
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `ACCUMULATOR`
    `static StructuredQName` | `ALL_MODES`
    `static int` | `NAMED_MODE`
    `static int` | `UNNAMED_MODE`
    `static StructuredQName` | `UNNAMED_MODE_NAME`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Mode(int usage, StructuredQName modeName)` Default constructor - creates a Mode containing no rules
    `Mode(Mode omniMode, StructuredQName modeName)` Construct a new Mode, copying the contents of an existing Mode

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addRule(Pattern pattern, RuleTarget action, StylesheetModule module, double priority, boolean explicitMode)` Add a rule to the Mode.
    `void` | `allocatePatternSlots(int slots)` Specify how many slots for local variables are required by a particular pattern
    `TailCall` | `applyTemplates(ParameterSet parameters, ParameterSet tunnelParameters, XPathContextMajor context, int locationId)` Process selected nodes using the handlers registered for this mode.
    `void` | `computeRankings()` Compute a rank for each rule, as a combination of the precedence and priority, to allow rapid comparison.
    `void` | `explainTemplateRules(ExpressionPresenter presenter)` Explain all template rules in this mode by showing their expression tree represented in XML.
    `BuiltInRuleSet` | `getBuiltInRuleSet()` Get the built-in template rules to be used with this Mode in the case where there is no explicit template rule
    `Set<String>` | `getExplicitNamespaces(NamePool pool)` Get the "explicit namespaces" matched by this mode.
    `StructuredQName` | `getModeName()` Get the name of the mode (for diagnostics only)
    `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.
    `int` | `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.
    `Rule` | `getRule(Item item, XPathContext context)` Get the rule corresponding to a given Node, by finding the best Pattern match.
    `Rule` | `getRule(Item item, XPathContext context, net.sf.saxon.trans.Mode.RuleFilter filter)` Get the rule corresponding to a given item, by finding the best Pattern match.
    `void` | `invertStreamableTemplates(Optimizer opt)` For a streamable mode, invert all the templates to generate streamable code
    `boolean` | `isDefaultMode()` Determine if this is the default mode
    `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` | `isStreamable()` Ask whether this mode is streamable
    `void` | `processRules(net.sf.saxon.trans.Mode.RuleAction action)` Walk over all the rules, applying a specified action to each one.
    `void` | `setBuiltInRuleSet(BuiltInRuleSet defaultRules)` Set the built-in template rules to be used with this Mode in the case where there is no explicit template rule
    `void` | `setRecoveryPolicy(int policy)` Set the policy for handling recoverable errrors.
    `void` | `setStreamable(boolean streamable)` Say that this mode is (or is not) streamable

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

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

- - ### Field Detail

    - #### UNNAMED_MODE

          public static final int UNNAMED_MODE

      See Also:
        Constant Field Values

    - #### NAMED_MODE

          public static final int NAMED_MODE

      See Also:
        Constant Field Values

    - #### ACCUMULATOR

          public static final int ACCUMULATOR

      See Also:
        Constant Field Values

    - #### ALL_MODES

          public static final StructuredQName ALL_MODES

    - #### UNNAMED_MODE_NAME

          public static final StructuredQName UNNAMED_MODE_NAME

  - ### Constructor Detail

    - #### Mode

          public Mode(int usage,
              StructuredQName modeName)

      Default constructor - creates a Mode containing no rules
      Parameters:
        `usage` - one of `UNNAMED_MODE`, `NAMED_MODE`
        `modeName` - the name of the mode

    - #### Mode

          public Mode(Mode omniMode,
              StructuredQName modeName)

      Construct a new Mode, copying the contents of an existing Mode
      Parameters:
        `omniMode` - the existing mode. May be null, in which case it is not copied
        `modeName` - the name of the new mode to be created

  - ### Method Detail

    - #### setBuiltInRuleSet

          public void setBuiltInRuleSet(BuiltInRuleSet defaultRules)

      Set the built-in template rules to be used with this Mode in the case where there is no explicit template rule
      Parameters:
        `defaultRules` - the built-in rule set

    - #### getBuiltInRuleSet

          public 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

    - #### isDefaultMode

          public boolean isDefaultMode()

      Determine if this is the default mode
      Returns:
        true if this is the default (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

    - #### isEmpty

          public 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(int policy)

      Set the policy for handling recoverable errrors. 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. The options are `Configuration.RECOVER_SILENTLY`, `Configuration.RECOVER_WITH_WARNINGS`, or `Configuration.DO_NOT_RECOVER`.

    - #### getRecoveryPolicy

          public int 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

    - #### isStreamable

          public boolean isStreamable()

      Ask whether this mode is streamable
      Returns:
        true if this mode is streamable

    - #### getExplicitNamespaces

          public Set<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

    - #### addRule

          public void addRule(Pattern pattern,
                     RuleTarget action,
                     StylesheetModule module,
                     double priority,
                     boolean explicitMode)

      Add a rule to the Mode.
      Parameters:
        `pattern` - a Pattern
        `action` - the Object to return from getRule() when the supplied node matches this Pattern
        `module` - the stylesheet module containing the rule
        `priority` - the priority of the rule
        `explicitMode` - true if adding a template rule for a specific (default or named) mode; false if adding a rule because it applies to all modes

    - #### allocatePatternSlots

          public void allocatePatternSlots(int slots)

      Specify how many slots for local variables are required by a particular pattern
      Parameters:
        `slots` - the number of slots needed

    - #### getRule

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

      Get the rule corresponding to a given Node, 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 Rule getRule(Item item,
                     XPathContext context,
                     net.sf.saxon.trans.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

    - #### processRules

          public void processRules(net.sf.saxon.trans.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

    - #### invertStreamableTemplates

          public void invertStreamableTemplates(Optimizer opt)
                                         throws XPathException

      For a streamable mode, invert all the templates to generate streamable code
      Parameters:
        `opt` - the optimizer (always a Saxon-EE optimizer)
      Throws:
        `XPathException` - if there is a non-streamable template in the mode

    - #### explainTemplateRules

          public void explainTemplateRules(ExpressionPresenter presenter)

      Explain all template rules in this mode by showing their expression tree represented in XML.
      Parameters:
        `presenter` - used to display the expression tree

    - #### computeRankings

          public void computeRankings()
                               throws XPathException

      Compute a rank for each rule, as a combination of the precedence and priority, to allow rapid comparison.
      Throws:
        `XPathException` - if an error occurs processing the rules

    - #### applyTemplates

          public TailCall applyTemplates(ParameterSet parameters,
                                ParameterSet tunnelParameters,
                                XPathContextMajor context,
                                int locationId)
                                  throws XPathException

      Process selected nodes using the handlers 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.
        `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

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.