Package org.apache.torque.generator.source

## Class SourcePath

- java.lang.Object
- - org.apache.torque.generator.source.SourcePath

-     public final class SourcePath
      extends Object

  Methods for traversing a source tree.

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static SourceElement` | `getElement​(SourceElement sourceElement, String path, boolean acceptEmpty)` | Gets a single source element which can be reached from the start element by a given path.
    `static List<SourceElement>` | `getElements​(SourceElement sourceElement, String path)` | Gets the elements which can be reached from the start element by a given path.
    `static List<SourceElement>` | `getElementsFromRoot​(SourceElement rootElement, String path)` | Gets the elements which can be reached from the root element by a given path.
    `static List<SourceElement>` | `getFollowing​(SourceElement sourceElement, String name)` | Returns all the following elements in the child list of the default parent which appear after this element with the given name.
    `static Object` | `getObject​(SourceElement root, String pathToBase, SourceElement sourceElement, String path, boolean acceptEmpty)` | Gets a single source element which can be reached from the start element by a given path.
    `static String` | `getPathAsString​(SourceElement sourceElement)` | Returns the path from the root element to the source element.
    `static List<SourceElement>` | `getPreceding​(SourceElement sourceElement, String name)` | Returns all the preceding elements in the child list of the default parent which appear before this element with the given name.
    `protected static ListIterator<SourceElement>` | `getSiblingIteratorPositionedOnSelf​(SourceElement sourceElement, SourceElement parent)` | Returns a ListIterator of the siblings of the input source element.
    `static boolean` | `hasChild​(SourceElement sourceElement, String name)` | Returns whether children with the given name exist.
    `static boolean` | `hasFollowing​(SourceElement sourceElement)` | Returns whether a following element exists as a child of the parent of this element.
    `static boolean` | `hasFollowingSibling​(SourceElement sourceElement)` | Returns whether a following element exists as a child of the parent of this element, which has the same name as this source element.
    `static boolean` | `hasPreceding​(SourceElement sourceElement)` | Returns whether an preceding exists as a child of the parent of this element.
    `static boolean` | `hasPrecedingSibling​(SourceElement sourceElement)` | Returns whether an preceding exists as a child of the parent of this element, which has the same name as this source element.
    `static Iterator<SourcePathPointer>` | `iteratePointer​(Object root, String pathToBase, Object base, String path)` | Gets the elements which can be reached from the start element by a given path.

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

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

- - ### Method Detail

    - #### hasChild

          public static boolean hasChild​(SourceElement sourceElement,
                                         String name)

      Returns whether children with the given name exist.
      Parameters:
        `sourceElement` - the start element, not null.
        `name` - the name of the child element, not null.
      Returns:
        true if children with the given name exist, false otherwise.
      Throws:
        `NullPointerException` - if name is null.

    - #### hasFollowing

          public static boolean hasFollowing​(SourceElement sourceElement)

      Returns whether a following element exists as a child of the parent of this element.
      Parameters:
        `sourceElement` - the start element, not null.
      Returns:
        true if a following element exists, false if not.

    - #### hasPreceding

          public static boolean hasPreceding​(SourceElement sourceElement)

      Returns whether an preceding exists as a child of the parent of this element.
      Parameters:
        `sourceElement` - the start element, not null.
      Returns:
        true if a preceding element exists, false if not.

    - #### hasFollowingSibling

          public static boolean hasFollowingSibling​(SourceElement sourceElement)

      Returns whether a following element exists as a child of the parent of this element, which has the same name as this source element.
      Parameters:
        `sourceElement` - the start element, not null.
      Returns:
        true if a following sibling exists, false if not.

    - #### hasPrecedingSibling

          public static boolean hasPrecedingSibling​(SourceElement sourceElement)

      Returns whether an preceding exists as a child of the parent of this element, which has the same name as this source element.
      Parameters:
        `sourceElement` - the start element, not null.
      Returns:
        true if a preceding sibling exists, false if not.

    - #### getPreceding

          public static List<SourceElement> getPreceding​(SourceElement sourceElement,
                                                         String name)

      Returns all the preceding elements in the child list of the default parent which appear before this element with the given name. If name is null, all preceding elements are returned. If this element has no parent, an empty list is returned.
      Parameters:
        `sourceElement` - the start element, not null.
        `name` - the name of the preceding elements to select, or null to select all preceding elements.
      Returns:
        a list containing the preceding elements with the given name, never null.
      See Also:
        xpath axes

    - #### getFollowing

          public static List<SourceElement> getFollowing​(SourceElement sourceElement,
                                                         String name)

      Returns all the following elements in the child list of the default parent which appear after this element with the given name. If name is null, all following elements are returned. If this element has no parent, an empty list is returned.
      Parameters:
        `sourceElement` - the start element, not null.
        `name` - the name of the following elements to select, or null to select all following elements.
      Returns:
        a list containing the following elements with the given name, never null.
      See Also:
        xpath axes

    - #### getSiblingIteratorPositionedOnSelf

          protected static ListIterator<SourceElement> getSiblingIteratorPositionedOnSelf​(SourceElement sourceElement,
                                                                                          SourceElement parent)

      Returns a ListIterator of the siblings of the input source element. The iterator is positioned such that the next method returns the element after the input element, and the previous method returns the input element.
      Parameters:
        `sourceElement` - the source element for which the sibling iterator should be created, not null.
        `parent` - the parent for the source element.
      Returns:
        the sibling iterator, or null if the input source element has no parent.
      Throws:
        `IllegalArgumentException` - if the element cannot be found in the list of children of its parent.

    - #### iteratePointer

          public static Iterator<SourcePathPointer> iteratePointer​(Object root,
                                                                   String pathToBase,
                                                                   Object base,
                                                                   String path)

      Gets the elements which can be reached from the start element by a given path. If the model root is null, only objects which are children of base can be retrieved.
      Parameters:
        `root` - the model root, or null if no model root exists (in the latter case, no elements only reachable via base's parent can be accessed)
        `pathToBase` - the path from root to base, must be not null if root is not null, is disregarded if root is null.
        `base` - the base object, not null.
        `path` - the path to use, or null (which refers base).
      Returns:
        the list of matching source elements, not null, may be empty.
      See Also:
        xpath axes

    - #### getElements

          public static List<SourceElement> getElements​(SourceElement sourceElement,
                                                        String path)

      Gets the elements which can be reached from the start element by a given path.
      Parameters:
        `sourceElement` - the start element, not null.
        `path` - the path to use, not null.
      Returns:
        the list of matching source elements, not null, may be empty.
      See Also:
        xpath axes

    - #### getElementsFromRoot

          public static List<SourceElement> getElementsFromRoot​(SourceElement rootElement,
                                                                String path)

      Gets the elements which can be reached from the root element by a given path. The name of the root element must appear first in the path, otherwise nothing is selected.
      Parameters:
        `rootElement` - the root element of the source tree, not null.
        `path` - the path to use, null selects the root element.
      Returns:
        the list of matching source elements, not null, may be empty.
      See Also:
        xpath axes

    - #### getObject

          public static Object getObject​(SourceElement root,
                                         String pathToBase,
                                         SourceElement sourceElement,
                                         String path,
                                         boolean acceptEmpty)
                                  throws GeneratorException

      Gets a single source element which can be reached from the start element by a given path.
      Parameters:
        `root` - the model root, or null if no model root exists (in the latter case, no elements only reachable via base's parent can be accessed)
        `pathToBase` - the path from root to base, must be not null if root is not null, is disregarded if root is null.
        `sourceElement` - the start element, not null.
        `path` - the path to use, not null.
        `acceptEmpty` - whether no match is an error(acceptEmpty=false) or not (acceptEmpty=true)
      Returns:
        the single matching source elements, may be null only if acceptEmpty=true.
      Throws:
        `GeneratorException` - if more than one source element matches, or if no source element matches and acceptEmpty=false
      See Also:
        xpath axes

    - #### getElement

          public static SourceElement getElement​(SourceElement sourceElement,
                                                 String path,
                                                 boolean acceptEmpty)
                                          throws GeneratorException

      Gets a single source element which can be reached from the start element by a given path.
      Parameters:
        `sourceElement` - the start element, not null.
        `path` - the path to use, not null.
        `acceptEmpty` - whether no match is an error(acceptEmpty=false) or not (acceptEmpty=true)
      Returns:
        the single matching source elements, may be null only if acceptEmpty=true.
      Throws:
        `GeneratorException` - if more than one source element matches, or if no source element matches and acceptEmpty=false
      See Also:
        xpath axes

    - #### getPathAsString

          public static String getPathAsString​(SourceElement sourceElement)
                                        throws GeneratorException

      Returns the path from the root element to the source element. The element names are separated by slashes. Example: root/firstLevelElement/secondLevelElement/currentNode
      Parameters:
        `sourceElement` - the element to output, not null.
      Returns:
        the path from root, not null.
      Throws:
        `GeneratorException` - if the parent chain contains a closed loop.