net.sf.saxon.trans

Class Mode

java.lang.Object

net.sf.saxon.trans.Mode

public class Mode
extends Object

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

Field Summary

Fields

Modifier and Type	Field and Description
static int	ACCUMULATOR
static int	NAMED_MODE
static StructuredQName	OMNI_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	allocateAllPatternSlots() Allocate slots for local variables in all patterns used by the rules in this 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)
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.
String	getPropertyValue(String name) Get the value of a property of this mode, e.g.
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.
int	getStackFrameSlotsNeeded()
void	invertStreamableTemplates() For a streamable mode, invert all the templates to generate streamable code
boolean	isDeclaredStreamable() Ask whether this mode is declared to be streamable
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)
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	setExplicitProperty(String name, String value, int precedence) Set an explicit property at a particular precedence.
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

OMNI_MODE

public static final StructuredQName OMNI_MODE

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

getModeTitle

public String getModeTitle()

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

Returns:

a title for the 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

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"

setExplicitProperty

public void setExplicitProperty(String name,
                       String value,
                       int precedence)

Set an explicit property at a particular precedence. Used for detecting conflicts

Parameters:

name - the name of the property

value - the value of the property

precedence - the import precedence of this property value

getPropertyValue

public String getPropertyValue(String name)

Get the value of a property of this mode, e.g. the "typed" property

Parameters:

name - the property name, e.g. "typed"

Returns:

the property value

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

Parameters:

pool - the NamePool for the configuration

Returns:

the set of all namespace URIs of names explicitly matched by 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()
                               throws XPathException

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

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. This method also checks that there are no conflicts for property values in different xsl:mode declarations

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

allocateAllPatternSlots

public void allocateAllPatternSlots()
                             throws XPathException

Allocate slots for local variables in all patterns used by the rules in this mode. Currently used only for accumulator rules

Throws:

XPathException - if anything goes wrong

getStackFrameSlotsNeeded

public int getStackFrameSlotsNeeded()