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, InstructionInfo, 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 and 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 and Description
static StructuredQName	DEFAULT_MODE_NAME
protected StructuredQName	modeName
boolean	mustBeTyped
boolean	mustBeUntyped
static StructuredQName	OMNI_MODE
static StructuredQName	UNNAMED_MODE_NAME

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

body

Constructor Summary

Constructors

Constructor and Description
Mode(StructuredQName modeName)

Method Summary

Modifier and Type	Method and Description
TailCall	applyTemplates(ParameterSet parameters, ParameterSet tunnelParameters, 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.
int	getComponentKind() Get the kind of component that this represents, using integer constants such as StandardNames.XSL_FUNCTION
int	getConstructType() Get the type of construct.
Component.M	getDeclaringComponent()
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() Get a name identifying the object of the expression, for example a function name, template name, variable name, key name, element name, etc.
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.
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	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
protected XPathContext	makeNewContextIfNeeded(XPathContext context) Expand the context to handle stack frame - this should not be called repeatedly on the same context
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	setHasRules(boolean hasRules)
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 net.sf.saxon.expr.instruct.Actor

allocateAllBindingSlots, allocateBindingSlotsRecursive, getBody, getColumnNumber, getDeclaredVisibility, getLineNumber, getLocation, getPackageData, getProperties, getProperty, getPublicId, getRetainedStaticContext, getStackFrameMap, getSystemId, isExportable, makeDeclaringComponent, saveLocation, setBody, setChildExpression, 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

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

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

getComponentKind

public int getComponentKind()

Description copied from class: Actor

Get the kind of component that this represents, using integer constants such as StandardNames.XSL_FUNCTION

Specified by:

getComponentKind in class Actor

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

getConstructType

public int getConstructType()

Description copied from interface: InstructionInfo

Get the type of construct. This will either be the fingerprint of a standard XSLT instruction name (values in StandardNames: all less than 1024) or it will be a constant in class LocationKind.

Returns:

an integer identifying the kind of construct

getObjectName

public StructuredQName getObjectName()

Description copied from interface: InstructionInfo

Get a name identifying the object of the expression, for example a function name, template name, variable name, key name, element name, etc. This is used only where the name is known statically.

Returns:

the QName of the object declared or manipulated by this instruction or expression

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(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.

setHasRules

public void setHasRules(boolean hasRules)

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"

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

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

makeNewContextIfNeeded

protected XPathContext makeNewContextIfNeeded(XPathContext context)

Expand the context to handle stack frame - this should not be called repeatedly on the same context

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,
                               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.

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)
                                        throws XPathException

Return a built-in rule set for a code string. This can be specialised in subclasses for PE/EE

Parameters:

code - the code used in export

Returns:

a suitable ruleset

Throws:

XPathException

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