Package com.polarion.subterra.base.location

Interface ILocation

All Known Implementing Classes:
Location
public interface ILocation
This interface represents location of some resource inside some repository. Sole implementation of this interface is Location.

The notion of repository is in domain of the user of this interface. It may be anything from server URL to inner file directory id. There are no restrictions on repository names. Repository names are case-sensitive.

Resource location inside the repository is represented by location path. Location path is broken down to location components which are concatenated with slash ('/'; COMPONENT_DELIM and COMPONENT_DELIM_CHAR). Component can't contain slash ('/') or backslash ('\'). Absolute location path starts with slash. Location paths are case-sensitive. If the path contain more slashes in row, then they are automatically replaced by one slash (e.g. "my//folder" becomes "my/folder") during ILocation creation.

Trailing slashes are stripped from location paths as early as possible.

Location may optionally contain revision which is an arbitrary string.

Implementations of this class must be immutable.

Author:
Stepan Roh, Polarion Software

  • Field Details

  • Method Details

    • containsRepositoryName

      boolean containsRepositoryName()
      Whether this location has repository name.
      Returns:
      true if this location contains repository name

    • isRelative

      boolean isRelative()
      Whether this location is relative (locations with repository names are always absolute).
      Returns:
      true if this location is relative

    • getAbsoluteLocation

      ILocation getAbsoluteLocation(ILocation root)
      Compute absolute location from root location and this location and return new location.
      Parameters:
      root - root absolute location
      Returns:
      new location or this location if it is already absolute
      Throws:
      IllegalArgumentException - if root is null
      IllegalArgumentException - if given root is not absolute
      IllegalArgumentException - if repositories differ

    • getRelativeLocation

      ILocation getRelativeLocation(ILocation root)
      Relativize this location against given root (which may be relative) and return new location.
      Parameters:
      root - root location
      Returns:
      new location
      Throws:
      IllegalArgumentException - if root is null
      IllegalArgumentException - if given root is not root of this location
      IllegalArgumentException - if repositories differ

    • hasRootLocation

      boolean hasRootLocation(ILocation root)
      Whether given location is root of this location.

      Positive answer allows getRelativeLocation(ILocation) to succeed.

      Parameters:
      root - root location
      Returns:
      true if given location is root of this location
      Throws:
      IllegalArgumentException - if root is null

    • getComponentCount

      int getComponentCount()
      Returns:
      Number of components in this location, or path depth.

    • getLastComponent

      String getLastComponent()
      Return last component of this location.

      Same as getComponent(getComponentCount()-1)

      Returns:
      last component name or null for empty location
      See Also:

    • getLastComponentExtension

      @Nullable String getLastComponentExtension()
      Returns the extension of the last component of this location, i.e. the suffix of the last component starting with the last '.'. Returns an empty string if there is no '.' in the last component. Returns null if this location is empty (i.e. if getLastComponent() returns null).
      Since:
      3.17.0

    • getLastComponentWithoutExtension

      @Nullable String getLastComponentWithoutExtension()
      Returns the last component of this location without the extension, i.e. the prefix of the last component before the last '.'. Returns the entire last component if there is no '.' in it. Returns null if this location is empty (i.e. if getLastComponent() returns null).
      Since:
      3.17.0

    • getFirstComponent

      String getFirstComponent()
      Returns the first coponent of this location.

      Same as getComponent(0)

      Returns:
      first component name or null for empty location
      See Also:

    • getComponent

      String getComponent(int n)
      Returns n-th component of the location. The n can range from 0 (first component) to getComponentCount()-1 (lastComponent).
      Returns:
      The given component or null if such component does not exist in this location.
      See Also:

    • getComponents

      List getComponents()
      The resulting list is unmodifiable.
      Returns:
      The list of string component names, as if returned by getComponent(int), the list lenght is the same as getComponentCount().

    • findComponentSequence

      int findComponentSequence(List sequence)
      Searches this path components for the given sequence and if found, returns the position of the first component from the sequence in this location's getComponents().
      Parameters:
      sequence - List of String
      Returns:
      Position of first component from sequence or -1 if not found.

    • findComponentSequence

      int findComponentSequence(String sequence)
      Same as findComponentSequence(List) but sequence defined as String (e.g. "/some/sequence") the leading and trailing slashes are ignored.
      Parameters:
      sequence -
      Returns:
      Position of first component from sequence or -1 if not found.

    • containsComponentSequence

      boolean containsComponentSequence(List sequence)
      Shortcut for findComponentSequence(sequence) != -1
      Parameters:
      sequence - List of String
      Returns:
      true if this location contains the specified sequence
      See Also:

    • containsComponentSequence

      boolean containsComponentSequence(String sequence)
      Same as containsComponentSequence(List) but sequence defined as String (e.f. "/some/sequence") the leading and trailing / have no meaning.
      Parameters:
      sequence -
      Returns:
      true if this location contains the specified sequence

    • containsComponent

      boolean containsComponent(String component)

    • startsWithComponentSequence

      boolean startsWithComponentSequence(List sequence)
      Shortcut for findComponentSequence(sequence) == 0
      Parameters:
      sequence -
      Returns:
      true if this location strts with the specified sequence
      See Also:

    • startsWithComponentSequence

      boolean startsWithComponentSequence(String sequence)
      Same as startsWithComponentSequence(List) but sequence defined as String (e.f. "/some/sequence") the leading and trailing / have no meaning.
      Parameters:
      sequence -
      Returns:
      true if this location strts with the specified sequence

    • removeFirstComponents

      ILocation removeFirstComponents(int n)
      Removes the first n components from the location path.
      Parameters:
      n -
      Returns:
      Returns this if n == 0 or relative location, obtained from this by removing n components.
      Throws:
      IllegalArgumentException - If n > getComponentCount().

    • setComponent

      ILocation setComponent(int n, String newComponent)
      Creates new location, which is same as this one, but has newComponent on the nth place.
      Parameters:
      n - Component number, 0..getComponentCount() (inclusive, exclusive)
      newComponent - the new content of the component to be replaced
      Returns:
      the component with replaced component
      Throws:
      IllegalArgumentException - if n is greater or equal to the component count or negative.
      IllegalArgumentException - if newComponent is null or it contains "/" (component separator) character.

    • addOneComponentTowards

      ILocation addOneComponentTowards(String path)
      Returns the location for which it holds: new_location.getParentLocation().equals(this) The extra segment is taken from the given path.

      Example: 

       this: [REPO]/some/
 path: /some/longer/path/to/go

 result: [REPO]/some/longer/
      Parameters:
      path - Such that this.getLocationPath() is parent of the given path.
      Returns:
      New locations, such that new_location.getParentLocation().equals(this).
      Throws:
      IllegalArgumentException - if no such exists;

    • append

      ILocation append(String locPath)
      Append given location path to this location and return new location.
      Parameters:
      locPath - location path to append
      Returns:
      new location
      Throws:
      IllegalArgumentException - if locPath is null
      IllegalArgumentException - if given location path is not relative

    • append

      ILocation append(ILocation loc)
      Append given location to this location and return new location. Revision of given location is ignored.
      Parameters:
      loc - string location to append
      Returns:
      new location
      Throws:
      IllegalArgumentException - if loc is null
      IllegalArgumentException - if given location is not relative

    • getRepositoryName

      String getRepositoryName()
      Return repository name (if any).
      Returns:
      repository name or null

    • setRepositoryName

      @NotNull ILocation setRepositoryName(@Nullable String repositoryName)
      Returns new location with specified repository name.
      Returns:
      new location
      Since:
      3.17.1

    • removeRepositoryName

      ILocation removeRepositoryName()
      Remove repository name (if any) from this location and return new location.
      Returns:
      new location

    • getLocationPath

      String getLocationPath()
      Return location path.
      Returns:
      location path

    • getParentLocation

      ILocation getParentLocation()
      Return parent location (location without last component).
      Returns:
      new location or null if there is no parent

    • getRevision

      String getRevision()
      Return revision (if any).
      Returns:
      revision or null

    • removeRevision

      ILocation removeRevision()
      Remove revision from this location and return new location.
      Returns:
      new location

    • setRevision

      ILocation setRevision(String revision)
      Set revision of this location and return new location.
      Parameters:
      revision - revision
      Returns:
      new location
      Throws:
      IllegalArgumentException - if revision is null

    • replaceLocationPath

      ILocation replaceLocationPath(String locPath)
      Replace current location path with given location path and return new location.
      Parameters:
      locPath - location path to replace with
      Returns:
      new location
      Throws:
      IllegalArgumentException - if locPath is null

    • hasRevision

      boolean hasRevision()
      Whether this location has revision.
      Returns:
      true if this location has revision

    • serialize

      String serialize()
      Converts the location into String. The exact format of the resulting string is not defined. Use Location.deserializeLocation(String) to convert the resulting string back to object.

      The resulting String should be human readable.

      Returns:
      the serialized form of this location