Package org.apache.cayenne.exp.path

# Interface CayennePath

All Superinterfaces:
  `Iterable<CayennePathSegment>`, `Serializable`

public interface CayennePath extends Iterable<CayennePathSegment>, Serializable

This interface represents some path in the Cayenne model. Value is just a string of comma-separated identifiers.

Usage:

          CayennePath path = CayennePath.of("a.b+");
          CayennePath nextPath = path.dot("c+");
          CayennePath root = path.head(1);
          CayennePathSegment last = path.last();
          if(last.isOuterJoin()) {
              // ...
          }

It could be used in expressions or in the internal processing logic. Implementation tries to optimize performance of the common path-related logic or at least shift costs from operation side to the initialization.

Since:
  5.0

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final CayennePath`
  `EMPTY_PATH`
  Constant value for an empty path
  `static final int`
  `NO_MARKER`
  No special markers
  `static final int`
  `PREFETCH_MARKER`
  Prefetch path marker TODO: this marker used only for prefetch processing

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default CayennePath`
  `dot(String next)`
  Create new path appending next segment to this.
  `default CayennePath`
  `dot(CayennePath next)`
  Create new path appending all segments of the next path to this.
  `default CayennePath`
  `dot(CayennePathSegment next)`
  Create new path appending next segment to this.
  `default CayennePathSegment`
  `first()`
  Get the first segment of this path if it's not empty
  `default boolean`
  `hasMarker(int marker)`
  Check if this path has required marker
  `default CayennePath`
  `head(int end)`
  Create sub path from this path from the first element and ending at the given index.
  `default boolean`
  `isEmpty()`
  Check if this path is empty
  `default CayennePathSegment`
  `last()`
  Get the last segment of this path if it's not empty
  `default int`
  `length()`
  Get length of this path is segments
  `default int`
  `marker()`
  Get marker of this path or `NO_MARKER` if non set
  `static CayennePath`
  `of(String path)`
  Create path from a given String
  `static CayennePath`
  `of(String path, int marker)`
  Create path from a given String with a marker.
  `static CayennePath`
  `of(List<CayennePathSegment> segments)`
  Create path from a given list of `CayennePathSegment`
  `static CayennePath`
  `of(List<CayennePathSegment> segments, int marker)`
  Create path from a given list of `CayennePathSegment` and a marker
  `static CayennePath`
  `of(CayennePath path, int marker)`
  Clone given path with a different marker
  `default CayennePath`
  `parent()`
  Get the parent path, that is a path up to the last segment of this path.
  `static CayennePathSegment`
  `segmentOf(String segment)`
  `static CayennePathSegment`
  `segmentOf(String segment, boolean outer)`
  `List<CayennePathSegment>`
  `segments()`
  Get all segments of this path
  `default CayennePath`
  `tail(int start)`
  Create sub path from this path starting from the given index and to the end.
  `String`
  `toString()`
  `default String`
  `value()`
  Get string representation of this path, it'll be dot-separated segments of this path.
  `default CayennePath`
  `withMarker(int marker)`
  Clone this path with new marker

  ### Methods inherited from interface java.lang.Iterable

  `forEach, iterator, spliterator`

- ## Field Details

  - ### NO_MARKER

    static final int NO_MARKER
    No special markers
    See Also:
      - Constant Field Values

  - ### PREFETCH_MARKER

    static final int PREFETCH_MARKER
    Prefetch path marker TODO: this marker used only for prefetch processing
    See Also:
      - Constant Field Values

  - ### EMPTY_PATH

    static final CayennePath EMPTY_PATH
    Constant value for an empty path

- ## Method Details

  - ### of

    static CayennePath of(String path)
    Create path from a given String

    This method will return `EMPTY_PATH` if `null` or an empty string is provided as an argument.

    This method will throw `IllegalArgumentException` if path value is malformed (e.g. containing dot at the start of two consecutive dots).

    Parameters:
      `path` - dot-separated path value
    Returns:
      path for the given value

  - ### of

    static CayennePath of(String path, int marker)
    Create path from a given String with a marker.

    This method will return `EMPTY_PATH` if `null` or an empty string is provided as an argument.

    This method will throw `IllegalArgumentException` if path value is malformed (e.g. containing dot at the start of two consecutive dots).

    Parameters:
      `path` - dot-separated path value
      `marker` - to use for a path
    Returns:
      path for the given value
    See Also:
      - `NO_MARKER`
      - `PREFETCH_MARKER`

  - ### of

    static CayennePath of(CayennePath path, int marker)
    Clone given path with a different marker
    Parameters:
      `path` - to clone
      `marker` - to set
    Returns:
      clone of a given path with new marker
    See Also:
      - `NO_MARKER`
      - `PREFETCH_MARKER`

  - ### of

    static CayennePath of(List<CayennePathSegment> segments)
    Create path from a given list of `CayennePathSegment`
    Parameters:
      `segments` - list of path segments
    Returns:
      path containing given segments

  - ### of

    static CayennePath of(List<CayennePathSegment> segments, int marker)
    Create path from a given list of `CayennePathSegment` and a marker
    Parameters:
      `segments` - list of path segments
      `marker` - to set
    Returns:
      path containing given segments
    See Also:
      - `NO_MARKER`
      - `PREFETCH_MARKER`

  - ### segmentOf

    static CayennePathSegment segmentOf(String segment, boolean outer)

  - ### segmentOf

    static CayennePathSegment segmentOf(String segment)

  - ### segments

    List<CayennePathSegment> segments()
    Get all segments of this path
    Returns:
      list of segments

  - ### marker

    default int marker()
    Get marker of this path or `NO_MARKER` if non set
    Returns:
      marker
    See Also:
      - `NO_MARKER`
      - `PREFETCH_MARKER`

  - ### withMarker

    default CayennePath withMarker(int marker)
    Clone this path with new marker
    Parameters:
      `marker` - to use
    Returns:
      new path with a marker
    See Also:
      - `NO_MARKER`
      - `PREFETCH_MARKER`

  - ### hasMarker

    default boolean hasMarker(int marker)
    Check if this path has required marker
    Parameters:
      `marker` - to check
    Returns:
      true if this path has the marker
    See Also:
      - `PREFETCH_MARKER`

  - ### length

    default int length()
    Get length of this path is segments
    Returns:
      segments count

  - ### isEmpty

    default boolean isEmpty()
    Check if this path is empty
    Returns:
      true if this path has no segments

  - ### toString

    String toString()
    Overrides:
      `toString` in class `Object`

  - ### value

    default String value()
    Get string representation of this path, it'll be dot-separated segments of this path.
    Returns:
      string value for this path

  - ### first

    default CayennePathSegment first()
    Get the first segment of this path if it's not empty
    Returns:
      segment or null if path is empty

  - ### last

    default CayennePathSegment last()
    Get the last segment of this path if it's not empty
    Returns:
      segment or null if path is empty

  - ### tail

    default CayennePath tail(int start)
    Create sub path from this path starting from the given index and to the end.
    Parameters:
      `start` - index from
    Returns:
      a new path starting from the start index

  - ### head

    default CayennePath head(int end)
    Create sub path from this path from the first element and ending at the given index.
    Parameters:
      `end` - index to
    Returns:
      a new path ending at the end index

  - ### parent

    default CayennePath parent()
    Get the parent path, that is a path up to the last segment of this path.
    Returns:
      parent path

  - ### dot

    default CayennePath dot(String next)
    Create new path appending next segment to this.
    Parameters:
      `next` - segment to append
    Returns:
      new path equal to this path + next segment

  - ### dot

    default CayennePath dot(CayennePathSegment next)
    Create new path appending next segment to this.
    Parameters:
      `next` - segment to append
    Returns:
      new path equal to this path + next segment

  - ### dot

    default CayennePath dot(CayennePath next)
    Create new path appending all segments of the next path to this.
    Parameters:
      `next` - path to append
    Returns:
      new path equal to this path + next path