net.sf.saxon.expr.parser

## Class PathMap

- java.lang.Object
- - net.sf.saxon.expr.parser.PathMap

-     public class PathMap
      extends Object

  A PathMap is a description of all the paths followed by an expression. It is a set of trees. Each tree contains as its root an expression that selects nodes without any dependency on the context. The arcs in the tree are axis steps. So the expression doc('a.xml')/a[b=2]/c has a single root (the call on doc()), with a single arc representing child::a, this leads to a node which has two further arcs representing child::b and child::c. Because element b is atomized, there will also be an arc for the step descendant::text() indicating the requirement to access the text nodes of the element.

  The current implementation works only for XPath 2.0 expressions (for example, constructs like xsl:for-each-group are not handled.)

  This class, together with the overloaded method `Expression.addToPathMap(PathMap, PathMap.PathMapNodeSet)` can be seen as an implementation of the static path analysis algorithm given in section 4 of A. Marian and J. Simeon, Projecting XML Documents, VLDB 2003.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `PathMap.PathMapArc` An arc joining two nodes in the path map.
    `static class` | `PathMap.PathMapNode` A node in the path map.
    `static class` | `PathMap.PathMapNodeSet` A (mutable) set of nodes in the path map
    `static class` | `PathMap.PathMapRoot` A root node in the path map.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PathMap(Expression exp)` Create the PathMap for an expression

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `diagnosticDump(PrintStream out)` Display a printed representation of the path map
    `PathMap.PathMapRoot` | `getContextDocumentRoot()` Get the path map root for the context document
    `PathMap.PathMapRoot` | `getContextItemRoot()` Get the path map root for the context item
    `PathMap.PathMapNodeSet` | `getPathForVariable(Binding binding)` Get the path used when evaluating a given variable binding
    `PathMap.PathMapRoot[]` | `getPathMapRoots()` Get all the root expressions from the path map
    `PathMap.PathMapRoot` | `getRootForDocument(String requiredUri)` Get the path map root for a call on the doc() or document() function with a given literal argument
    `static void` | `main(String[] args)` Main method for testing
    `PathMap.PathMapRoot` | `makeNewRoot(Expression exp)` Make a new root node in the path map.
    `PathMap.PathMapRoot` | `reduceToDownwardsAxes(PathMap.PathMapRoot root)` Given a PathMapRoot, simplify the tree rooted at this node so that it only contains downwards selections: specifically, so that the only axes used are child, attribute, namespace, and descendant.
    `void` | `registerPathForVariable(Binding binding, PathMap.PathMapNodeSet nodeset)` Register the path used when evaluating a given variable binding

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

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

- - ### Constructor Detail

    - #### PathMap

          public PathMap(Expression exp)

      Create the PathMap for an expression
      Parameters:
        `exp` - the expression whose PathMap is required

  - ### Method Detail

    - #### makeNewRoot

          public PathMap.PathMapRoot makeNewRoot(Expression exp)

      Make a new root node in the path map. However, if there is already a root for the same expression, the existing root for that expression is returned.
      Parameters:
        `exp` - the expression represented by this root node
      Returns:
        the new root node

    - #### getPathMapRoots

          public PathMap.PathMapRoot[] getPathMapRoots()

      Get all the root expressions from the path map
      Returns:
        an array containing the root expressions

    - #### registerPathForVariable

          public void registerPathForVariable(Binding binding,
                                     PathMap.PathMapNodeSet nodeset)

      Register the path used when evaluating a given variable binding
      Parameters:
        `binding` - the variable binding
        `nodeset` - the set of PathMap nodes reachable when evaluating that variable

    - #### getPathForVariable

          public PathMap.PathMapNodeSet getPathForVariable(Binding binding)

      Get the path used when evaluating a given variable binding
      Parameters:
        `binding` - the variable binding
      Returns:
        the set of PathMap nodes reachable when evaluating that variable

    - #### getContextDocumentRoot

          public PathMap.PathMapRoot getContextDocumentRoot()

      Get the path map root for the context document
      Returns:
        the path map root for the context document if there is one, or null if none is found.
      Throws:
        `IllegalStateException` - if there is more than one path map root for the context document

    - #### getContextItemRoot

          public PathMap.PathMapRoot getContextItemRoot()

      Get the path map root for the context item
      Returns:
        the path map root for the context item if there is one, or null if none is found.
      Throws:
        `IllegalStateException` - if there is more than one path map root for the context item

    - #### getRootForDocument

          public PathMap.PathMapRoot getRootForDocument(String requiredUri)

      Get the path map root for a call on the doc() or document() function with a given literal argument
      Parameters:
        `requiredUri` - the literal argument we are looking for
      Returns:
        the path map root for the specified document if there is one, or null if none is found.
      Throws:
        `IllegalStateException` - if there is more than one path map root for the specified document

    - #### reduceToDownwardsAxes

          public PathMap.PathMapRoot reduceToDownwardsAxes(PathMap.PathMapRoot root)

      Given a PathMapRoot, simplify the tree rooted at this node so that it only contains downwards selections: specifically, so that the only axes used are child, attribute, namespace, and descendant. If the root expression is a ContextItemExpression (that is, the path can start at any node) then it is rebased to start at a root node, which means in effect that a path such as a/b/c is treated as //a/b/c.
      Parameters:
        `root` - the root of the path to be simplified
      Returns:
        the path map root after converting the tree to use downwards axes only

    - #### diagnosticDump

          public void diagnosticDump(PrintStream out)

      Display a printed representation of the path map
      Parameters:
        `out` - the output stream to which the output will be written

    - #### main

          public static void main(String[] args)
                           throws Exception

      Main method for testing
      Parameters:
        `args` - Takes one argument, the XPath expression to be analyzed
      Throws:
        `Exception`

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