public interface ILfnResourceLocation
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:
encoded form
.
getLocation()
.
Implementations must implement Object.equals(Object)
and Object.hashCode()
sensibly.
ILfnResourceConnector
Modifier and Type | Method and Description |
---|---|
String |
getFileName()
Retrieves the name of the file identified by this resource location.
|
String |
getLocation()
Retrieves the encoded location identified by this instance as a string.
|
ILfnResourceLocation |
getParent()
Retrieves the parent of this location.
|
String |
relativize(ILfnResourceLocation aTarget)
Generates a "relative" location for the given target, using this location as a base.
|
ILfnResourceLocation |
resolve(String aRelative)
Resolve a "relative" location against this resource location.
|
String getFileName()
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()
null
Path.getFileName()
String getLocation()
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()
Path.toString()
ILfnResourceLocation getParent()
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.
Path.getParent()
String relativize(ILfnResourceLocation aTarget)
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.
aTarget
- the location to provide a relative location forIllegalArgumentException
- if the given resource location is not compatible with this onePath.relativize(Path)
ILfnResourceLocation resolve(String aRelative)
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.
aRelative
- the resource location to resolvePath.resolve(Path)