Package com.luciad.fusion.platform.resource

Interface ILfnResourceLocation

All Known Implementing Classes:
ALfnHierarchicalResourceLocation
public interface ILfnResourceLocation
The location of a data resource that LuciadFusion Studio potentially can serve. Typically, this denotes the location of a file, regardless of where or how it is stored.

Many data formats are composed of multiple files, sometimes organized in a hierarchical (directory) structure. Decoders for such formats often assume that it is possible to access related files via manipulation of the string representation. ILfnResourceLocation provides explicit control over the meaning of these operations. For formats with hierarchical structure, various service types (e.g. OGC 3D Tiles, HSPC, ...) expect that the entry point location does have a parent.

This interface generally matches the semantics of the Path API, with some extra requirements:

  • a resource location is always absolute. By itself, it identifies a resource. No other information is needed.
  • a resource location is always normalized. There are no redundant parts in its encoded form.
However, there is no requirement that resource locations actually follow a Path-like hierarchical naming scheme. Implementations can determine how to encode locations themselves via getLocation().

Implementations must implement Object.equals(Object) and Object.hashCode() sensibly.

Since:
2022.1
See Also:

  • Method Details

    • getFileName

      String getFileName()
      Retrieves the name of the file identified by this resource location. Resolving the returned name against the parent of this instance (assuming there is a parent) yields a resource location equal to this one.

      The returned name may be null if this location has no parent of its own.

      For a Path-backed resource, this would be equivalent to Path.getFileName()

      Returns:
      the file name, may be null
      See Also:

    • getLocation

      String getLocation()
      Retrieves the encoded location identified by this instance as a string. Providing the returned value to ILfnResourceConnector.get(java.lang.String) of the connector that created this instance yields a resource location equal to this one.

      For a Path-backed resource, this would be equivalent to Path.toString()

      Returns:
      the encoded location
      See Also:

    • getParent

      ILfnResourceLocation getParent()
      Retrieves the parent of this location. For a file, this would be the directory that contains it.

      The returned location does not actually have to exist or be accessible. It will only be used for resolving relative locations against.

      If there is no parent to this location, an implementation must return null. Otherwise, the returned resource location must be compatible with this location.

      Returns:
      the parent location, if available
      See Also:

    • relativize

      String relativize(ILfnResourceLocation aTarget)
      Generates a "relative" location for the given target, using this location as a base.

      The relative location is often encoded using elements like .. to denote a parent and /name to denote a child named name. However, implementations are free to encode the relative location in any way they please. The only requirement is that base.resolve(base.relativize(aTarget)).equals(aTarget).

      If there is no ancestry relationship between the target and this location, implementations must return the full encoded form of the target.

      Parameters:
      aTarget - the location to provide a relative location for
      Returns:
      the relative location, from this location
      Throws:
      IllegalArgumentException - if the given resource location is not compatible with this one
      See Also:

    • resolve

      ILfnResourceLocation resolve(String aRelative)
      Resolve a "relative" location against this resource location.

      The relative location was either produced by relativize(ILfnResourceLocation) or a manipulation of another resource location's file name. Note that this means that the "relative" location may actually be the full encoded form of a resource location.

      If the relative location cannot be resolved, implementations should throw IllegalArgumentException.

      The returned resource location must be compatible with this location.

      Parameters:
      aRelative - the resource location to resolve
      Returns:
      the resolved location
      See Also: