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 Detail

      • COMPONENT_DELIM

        static final java.lang.String COMPONENT_DELIM
        Location component delimiter (as String).
        See Also:
        Constant Field Values
      • COMPONENT_DELIM_CHAR

        static final char COMPONENT_DELIM_CHAR
        Location component delimiter (as char).
        See Also:
        Constant Field Values
    • Method Detail

      • 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:
        java.lang.IllegalArgumentException - if root is null
        java.lang.IllegalArgumentException - if given root is not absolute
        java.lang.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:
        java.lang.IllegalArgumentException - if root is null
        java.lang.IllegalArgumentException - if given root is not root of this location
        java.lang.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:
        java.lang.IllegalArgumentException - if root is null
      • getComponentCount

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

        java.lang.String getLastComponent()
        Return last component of this location.

        Same as getComponent(getComponentCount()-1)

        Returns:
        last component name or null for empty location
        See Also:
        getComponent(int)
      • getLastComponentExtension

        @Nullable
        java.lang.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
        java.lang.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

        java.lang.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(int)
      • getComponent

        java.lang.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:
        getFirstComponent(), getLastComponent()
      • getComponents

        java.util.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​(java.util.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​(java.lang.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​(java.util.List sequence)
        Shortcut for findComponentSequence(sequence) != -1
        Parameters:
        sequence - List of String
        Returns:
        true if this location contains the specified sequence
        See Also:
        findComponentSequence(List)
      • containsComponentSequence

        boolean containsComponentSequence​(java.lang.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​(java.lang.String component)
      • startsWithComponentSequence

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

        boolean startsWithComponentSequence​(java.lang.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:
        java.lang.IllegalArgumentException - If n > getComponentCount().
      • setComponent

        ILocation setComponent​(int n,
                               java.lang.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:
        java.lang.IllegalArgumentException - if n is greater or equal to the component count or negative.
        java.lang.IllegalArgumentException - if newComponent is null or it contains "/" (component separator) character.
      • addOneComponentTowards

        ILocation addOneComponentTowards​(java.lang.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:
        java.lang.IllegalArgumentException - if no such exists;
      • append

        ILocation append​(java.lang.String locPath)
        Append given location path to this location and return new location.
        Parameters:
        locPath - location path to append
        Returns:
        new location
        Throws:
        java.lang.IllegalArgumentException - if locPath is null
        java.lang.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:
        java.lang.IllegalArgumentException - if loc is null
        java.lang.IllegalArgumentException - if given location is not relative
      • getRepositoryName

        java.lang.String getRepositoryName()
        Return repository name (if any).
        Returns:
        repository name or null
      • setRepositoryName

        @NotNull
        ILocation setRepositoryName​(@Nullable
                                    java.lang.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

        java.lang.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

        java.lang.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​(java.lang.String revision)
        Set revision of this location and return new location.
        Parameters:
        revision - revision
        Returns:
        new location
        Throws:
        java.lang.IllegalArgumentException - if revision is null
      • replaceLocationPath

        ILocation replaceLocationPath​(java.lang.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:
        java.lang.IllegalArgumentException - if locPath is null
      • hasRevision

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

        java.lang.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