## 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
`static StructuredQName` `ALL_MODES`
`static int` `NAMED_MODE`
`static int` `STRIPPER_MODE`
`static int` `UNNAMED_MODE`
`static StructuredQName` `UNNAMED_MODE_NAME`

Constructor Summary
`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
`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
`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
`StructuredQName` `getModeName()` Get the name of the mode (for diagnostics only)
`Rule` `getNextMatchRule(NodeInfo node, 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(NodeInfo node, 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(NodeInfo node, XPathContext context)` Get the rule corresponding to a given Node, by finding the best Pattern match.
`Rule` `getRule(NodeInfo node, XPathContext context, net.sf.saxon.trans.Mode.RuleFilter filter)` Get the rule corresponding to a given Node, 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

### STRIPPER_MODE

    public static final int STRIPPER_MODE

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`, `STRIPPER_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 StringifyRuleSet 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)
                       throws XPathException

  Say that this mode is (or is not) streamable

  Parameters:
    `streamable` - true if this mode is a streamable mode
  Throws:
    `XPathException`

### isStreamable

    public boolean isStreamable()

  Ask whether this mode is streamable

  Returns:
    true if this mode is streamable

### 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
    `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(NodeInfo node,
                        XPathContext context)
                 throws XPathException

  Get the rule corresponding to a given Node, by finding the best Pattern match.

  Parameters:
    `node` - the NodeInfo referring to the node to be matched
    `context` - the XPath dynamic evaluation context
  Returns:
    the best matching rule, if any (otherwise null).
  Throws:
    `XPathException`

### getRule

    public Rule getRule(NodeInfo node,
                        XPathContext context,
                        net.sf.saxon.trans.Mode.RuleFilter filter)
                 throws XPathException

  Get the rule corresponding to a given Node, by finding the best Pattern match.

  Parameters:
    `node` - the NodeInfo referring to the node to be matched
    `context` - the XPath dynamic evaluation context
  Returns:
    the best matching rule, if any (otherwise null).
  Throws:
    `XPathException`

### getRule

    public Rule getRule(NodeInfo node,
                        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:
    `node` - the NodeInfo referring to the node 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`

### getNextMatchRule

    public Rule getNextMatchRule(NodeInfo node,
                                 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:
    `node` - 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`

### 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`

### invertStreamableTemplates

    public void invertStreamableTemplates(Optimizer opt)
                                   throws XPathException

  For a streamable mode, invert all the templates to generate streamable code

  Throws:
    `XPathException`

### 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`

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