Package net.sf.saxon.expr.instruct

## Class TemplateRule

- java.lang.Object
- - net.sf.saxon.expr.instruct.TemplateRule

- All Implemented Interfaces:
    `javax.xml.transform.SourceLocator`, `ExpressionOwner`, `Locatable`, `Location`, `Traceable`, `TraceableComponent`, `RuleTarget`, `org.xml.sax.Locator`
  Direct Known Subclasses:
    `TemplateRuleEE`

      public class TemplateRule
      extends java.lang.Object
      implements RuleTarget, Location, ExpressionOwner, TraceableComponent

  The runtime object corresponding to an xsl:template element in the stylesheet.

  Note that the Template object no longer has precedence information associated with it; this is now only in the Rule object that references this Template. This allows two rules to share the same template, with different precedences. This occurs when a stylesheet module is imported more than once, from different places, with different import precedences.

  From Saxon 9.7, the old Template class is split into NamedTemplate and TemplateRule.

  From Saxon 9.8, a subclass is used in Saxon-EE

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected Expression` | `body` |
    `protected Pattern` | `matchPattern` |
    `protected java.util.List<TemplateRule>` | `slaveCopies` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TemplateRule()` | Create a template

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `apply​(Outputter output, XPathContextMajor context)` | Process the template, without returning any tail calls.
    `TailCall` | `applyLeavingTail​(Outputter output, XPathContext context)` | Process this template, with the possibility of returning a tail call package if the template contains any tail calls that are to be performed by the caller.
    `TemplateRule` | `copy()` | Create a copy of a template rule.
    `protected void` | `copyTo​(TemplateRule tr)` |
    `void` | `explainProperties​(ExpressionPresenter presenter)` |
    `void` | `export​(ExpressionPresenter presenter)` | Output diagnostic explanation to an ExpressionPresenter
    `void` | `gatherProperties​(java.util.function.BiConsumer<java.lang.String,​java.lang.Object> consumer)` | Get the properties of this object to be included in trace messages, by supplying the property values to a supplied consumer function
    `Expression` | `getBody()` | Get the expression at the root of the expression tree used to evaluate this construct
    `Expression` | `getChildExpression()` |
    `int` | `getColumnNumber()` | Get the column number.
    `int` | `getComponentKind()` |
    `int` | `getContainerGranularity()` |
    `Expression` | `getInterpretedBody()` |
    `int` | `getLineNumber()` | Get the line number.
    `java.util.List<LocalParam>` | `getLocalParams()` |
    `Location` | `getLocation()` | Get the location of the construct
    `Pattern` | `getMatchPattern()` | Get the match pattern used with this template
    `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.
    `PackageData` | `getPackageData()` |
    `java.lang.String` | `getPublicId()` | Get the Public ID
    `ItemType` | `getRequiredContextItemType()` |
    `SequenceType` | `getRequiredType()` | Get the required type to be returned by this template
    `java.util.List<Rule>` | `getRules()` | Get the rules that use this template.
    `SlotManager` | `getStackFrameMap()` |
    `java.lang.String` | `getSystemId()` | Get the system ID.
    `java.lang.String` | `getTracingTag()` | Get a string to identify the type of component
    `boolean` | `hasRequiredParams()` | Ask whether this template has one or more required parameters
    `void` | `initialize()` | Ensure that any first-time initialization has been done.
    `boolean` | `isAbsentFocus()` |
    `boolean` | `isDeclaredStreamable()` |
    `void` | `prepareInitializer​(Compilation compilation, ComponentDeclaration decl, StructuredQName modeName)` | Prepare for JIT compilation.
    `void` | `registerRule​(Rule rule)` | Register a rule for which this is the target
    `Location` | `saveLocation()` | Get an immutable copy of this Location object.
    `void` | `setBody​(Expression body)` | Set the expression that forms the body of the template
    `void` | `setChildExpression​(Expression expr)` |
    `void` | `setColumnNumber​(int col)` |
    `void` | `setContextItemRequirements​(ItemType type, boolean absentFocus)` | Set the required context item type.
    `void` | `setDeclaredStreamable​(boolean streamable)` | Say whether or not this template is declared as streamable
    `void` | `setHasRequiredParams​(boolean has)` | Set whether this template has one or more required parameters
    `void` | `setLineNumber​(int line)` |
    `void` | `setMatchPattern​(Pattern pattern)` | Set the match pattern used with this template
    `void` | `setPackageData​(PackageData data)` |
    `void` | `setRequiredType​(SequenceType type)` | Set the required type to be returned by this template
    `void` | `setStackFrameMap​(SlotManager map)` |
    `void` | `setSystemId​(java.lang.String id)` |
    `void` | `updateSlaveCopies()` | Update the properties of template rules that have been marked as slave copies of this one (typically the same template, but in a different mode).

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

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

- - ### Field Detail

    - #### body

          protected Expression body

    - #### matchPattern

          protected Pattern matchPattern

    - #### slaveCopies

          protected java.util.List<TemplateRule> slaveCopies

  - ### Constructor Detail

    - #### TemplateRule

          public TemplateRule()

      Create a template

  - ### Method Detail

    - #### setMatchPattern

          public void setMatchPattern​(Pattern pattern)

      Set the match pattern used with this template
      Parameters:
        `pattern` - the match pattern (may be null for a named template)

    - #### getBody

          public Expression getBody()

      Description copied from interface: `TraceableComponent`
      Get the expression at the root of the expression tree used to evaluate this construct
      Specified by:
        `getBody` in interface `TraceableComponent`
      Returns:
        the root expression

    - #### getChildExpression

          public Expression getChildExpression()

      Specified by:
        `getChildExpression` in interface `ExpressionOwner`

    - #### getLocation

          public Location getLocation()

      Description copied from interface: `Locatable`
      Get the location of the construct
      Specified by:
        `getLocation` in interface `Locatable`
      Returns:
        the location. If no location information is available, the method should return `Loc.NONE` rather than returning null. However, callers would be well advised to check for the result being null.

    - #### gatherProperties

          public void gatherProperties​(java.util.function.BiConsumer<java.lang.String,​java.lang.Object> consumer)

      Get the properties of this object to be included in trace messages, by supplying the property values to a supplied consumer function
      Specified by:
        `gatherProperties` in interface `Traceable`
      Parameters:
        `consumer` - the function to which the properties should be supplied, as (property name, value) pairs.

    - #### setContextItemRequirements

          public void setContextItemRequirements​(ItemType type,
                                                 boolean absentFocus)

      Set the required context item type. Used when there is an xsl:context-item child element
      Parameters:
        `type` - the required context item type
        `absentFocus` - true if the context item is treated as absent even if supplied (use="absent")

    - #### getComponentKind

          public int getComponentKind()

    - #### getMatchPattern

          public Pattern getMatchPattern()

      Get the match pattern used with this template
      Returns:
        the match pattern, or null if this is a named template with no match pattern. In the case of a template rule whose pattern is a union pattern, this will be the original union pattern; the individual Rule objects contain the branches of the union pattern.

    - #### setBody

          public void setBody​(Expression body)

      Set the expression that forms the body of the template
      Specified by:
        `setBody` in interface `TraceableComponent`
      Parameters:
        `body` - the body of the template

    - #### setStackFrameMap

          public void setStackFrameMap​(SlotManager map)

    - #### getStackFrameMap

          public SlotManager getStackFrameMap()

    - #### setHasRequiredParams

          public void setHasRequiredParams​(boolean has)

      Set whether this template has one or more required parameters
      Parameters:
        `has` - true if the template has at least one required parameter

    - #### hasRequiredParams

          public boolean hasRequiredParams()

      Ask whether this template has one or more required parameters
      Returns:
        true if this template has at least one required parameter

    - #### setRequiredType

          public void setRequiredType​(SequenceType type)

      Set the required type to be returned by this template
      Parameters:
        `type` - the required type as defined in the "as" attribute on the xsl:template element

    - #### getRequiredType

          public SequenceType getRequiredType()

      Get the required type to be returned by this template
      Returns:
        the required type as defined in the "as" attribute on the xsl:template element

    - #### registerRule

          public void registerRule​(Rule rule)

      Register a rule for which this is the target
      Specified by:
        `registerRule` in interface `RuleTarget`
      Parameters:
        `rule` - a rule in which this is the target

    - #### getRules

          public java.util.List<Rule> getRules()

      Get the rules that use this template. For a template with no match pattern, this will be an empty list. For a union pattern, there will be one rule for each branch of the union.
      Returns:
        the rules corresponding to this template.

    - #### getContainerGranularity

          public int getContainerGranularity()

    - #### getPackageData

          public PackageData getPackageData()

    - #### setPackageData

          public void setPackageData​(PackageData data)

    - #### getPublicId

          public java.lang.String getPublicId()

      Description copied from interface: `Location`
      Get the Public ID
      Specified by:
        `getPublicId` in interface `Location`
      Specified by:
        `getPublicId` in interface `org.xml.sax.Locator`
      Specified by:
        `getPublicId` in interface `javax.xml.transform.SourceLocator`
      Returns:
        usually null

    - #### getSystemId

          public java.lang.String getSystemId()

      Description copied from interface: `Location`
      Get the system ID. This should be the system identifier of an XML external entity; if a stylesheet module comprises multiple external entities, the distinction should be retained. This means, for example, that an instruction in a stylesheet can have a different system identifier from its parent instruction. However, SAX parsers only provide location information at the element level, so when part of an XPath expression is in a different external entity from other parts of the same expression, this distinction is lost.

      The system identifier of a node is in general not the same as its base URI. The base URI is affected by xml:base attributes; the system identifier is not.

      Specified by:
        `getSystemId` in interface `Location`
      Specified by:
        `getSystemId` in interface `org.xml.sax.Locator`
      Specified by:
        `getSystemId` in interface `javax.xml.transform.SourceLocator`
      Returns:
        the system ID, or null if the information is not available.

    - #### setSystemId

          public void setSystemId​(java.lang.String id)

    - #### getLineNumber

          public int getLineNumber()

      Description copied from interface: `Location`
      Get the line number. This line number is relative to the external entity identified by the system identifier. Line numbers start at 1. The value may be an approximation; SAX parsers only provide line number information at the level of element nodes.
      Specified by:
        `getLineNumber` in interface `Location`
      Specified by:
        `getLineNumber` in interface `org.xml.sax.Locator`
      Specified by:
        `getLineNumber` in interface `javax.xml.transform.SourceLocator`
      Returns:
        the line number, or -1 if the information is not available.

    - #### setLineNumber

          public void setLineNumber​(int line)

    - #### setColumnNumber

          public void setColumnNumber​(int col)

    - #### getColumnNumber

          public int getColumnNumber()

      Description copied from interface: `Location`
      Get the column number. This column number is relative to the line identified by the line number. Column numbers start at 1.
      Specified by:
        `getColumnNumber` in interface `Location`
      Specified by:
        `getColumnNumber` in interface `org.xml.sax.Locator`
      Specified by:
        `getColumnNumber` in interface `javax.xml.transform.SourceLocator`
      Returns:
        the column number, or -1 if the information is not available.

    - #### saveLocation

          public Location saveLocation()

      Get an immutable copy of this Location object. By default Location objects may be mutable, so they should not be saved for later use. The result of this operation holds the same location information, but in an immutable form.
      Specified by:
        `saveLocation` in interface `Location`
      Returns:
        an immutable copy (which may be the original object, if it is already immutable)

    - #### getRequiredContextItemType

          public ItemType getRequiredContextItemType()

    - #### isAbsentFocus

          public boolean isAbsentFocus()

    - #### getLocalParams

          public java.util.List<LocalParam> getLocalParams()

    - #### prepareInitializer

          public void prepareInitializer​(Compilation compilation,
                                         ComponentDeclaration decl,
                                         StructuredQName modeName)

      Prepare for JIT compilation.
      Parameters:
        `compilation` - the XSLT compilation
        `decl` - the component declaration of this template rule

    - #### initialize

          public void initialize()
                          throws XPathException

      Ensure that any first-time initialization has been done. Used in Saxon-EE to do JIT compilation
      Throws:
        `XPathException`

    - #### apply

          public void apply​(Outputter output,
                            XPathContextMajor context)
                     throws XPathException

      Process the template, without returning any tail calls. This path is used by xsl:apply-imports and xsl:next-match
      Parameters:
        `output` - the destination for the result
        `context` - The dynamic context, giving access to the current node,
      Throws:
        `XPathException` - if a dynamic error occurs while evaluating the template

    - #### applyLeavingTail

          public TailCall applyLeavingTail​(Outputter output,
                                           XPathContext context)
                                    throws XPathException

      Process this template, with the possibility of returning a tail call package if the template contains any tail calls that are to be performed by the caller.
      Parameters:
        `output` - the destination for the result
        `context` - the XPath dynamic context
      Returns:
        null if the template exited normally; but if it was a tail call, details of the call that hasn't been made yet and needs to be made by the caller
      Throws:
        `XPathException` - if a dynamic error occurs while evaluating the template

    - #### export

          public void export​(ExpressionPresenter presenter)
                      throws XPathException

      Output diagnostic explanation to an ExpressionPresenter
      Specified by:
        `export` in interface `RuleTarget`
      Parameters:
        `presenter` - the destination for the explanation
      Throws:
        `XPathException` - if output fails

    - #### setDeclaredStreamable

          public void setDeclaredStreamable​(boolean streamable)

      Say whether or not this template is declared as streamable
      Parameters:
        `streamable` - true if the template belongs to a streamable mode; set to false if it does not belong to a streamable mode, or if it is found that the template is not actually streamable, and fallback to non-streaming has been requested.

    - #### isDeclaredStreamable

          public boolean isDeclaredStreamable()

    - #### explainProperties

          public void explainProperties​(ExpressionPresenter presenter)
                                 throws XPathException

      Throws:
        `XPathException`

    - #### getInterpretedBody

          public Expression getInterpretedBody()

    - #### copy

          public TemplateRule copy()

      Create a copy of a template rule. This is needed when copying a rule from the "omniMode" (mode=#all) to a specific mode. Because we want the rules to be chained in the right order within the mode object, we create the copy as soon as we know it is needed. The problem is that at this stage many of the properties of the template rule are still uninitialised. So we mark the new copy as a slave of the original, and at the end of the compilation process we update all the slave copies to match the properties of the original.

    - #### updateSlaveCopies

          public void updateSlaveCopies()

      Update the properties of template rules that have been marked as slave copies of this one (typically the same template, but in a different mode).

    - #### copyTo

          protected void copyTo​(TemplateRule tr)

    - #### setChildExpression

          public void setChildExpression​(Expression expr)

      Specified by:
        `setChildExpression` in interface `ExpressionOwner`

    - #### getObjectName

          public StructuredQName getObjectName()

      Description copied from interface: `Traceable`
      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.
      Specified by:
        `getObjectName` in interface `Traceable`
      Returns:
        the QName of the object declared or manipulated by this instruction or expression

    - #### getTracingTag

          public java.lang.String getTracingTag()

      Description copied from interface: `TraceableComponent`
      Get a string to identify the type of component
      Specified by:
        `getTracingTag` in interface `TraceableComponent`
      Returns:
        an identifying string