FsPath (TrueZIP Kernel 7.2-rc-2 API)

java.lang.Object
- de.schlichtherle.truezip.fs.FsPath

All Implemented Interfaces:: java.io.Serializable, java.lang.Comparable<FsPath>

@Immutable
@DefaultAnnotation(value=edu.umd.cs.findbugs.annotations.NonNull.class)
public final class FsPath
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable<FsPath>

Addresses an entry in a file system. The purpose of a file system path is to parse a URI and decompose it into a mount point of a file system and its relative entry name.

Specification

A path adds the following syntax constraints to a Uniform Resource Identifier:

The URI must not define a fragment component.

If the URI is opaque, its scheme specific part must contain at least one mount point separator "!/". The part up to the last mount point separator is parsed according to the syntax constraints for an FsMountPoint and set as the value of the mountPoint property. The part after the last mount point separator is parsed according to the syntax constraints for an FsEntryName and set as the value of the entryName property.
Otherwise, if the URI is absolute, it's resolved with ".", parsed according to the syntax constraints for an FsMountPoint and set as the value of the mountPoint property. The URI relativized to this mount point is parsed according to the syntax constraints for an FsEntryName and set as the value of the entryName property.
Otherwise, the value of the mountPoint property is set to null and the URI is parsed according to the syntax constraints for an FsEntryName and set as the value of the entryName property.

For opaque URIs of the form jar:<url>!/<entry>, these constraints build a close subset of the syntax allowed by a JarURLConnection.

Examples

Examples for valid path URIs are:

`uri` property	`mountPoint` URI	`entryName` URI
`foo`	(null)	`foo`
`foo:/bar`	`foo:/`	`bar`
`foo:/bar/`	`foo:/bar`	(empty - not null)
`foo:bar:/baz!/bang`	`foo:bar:/baz!/`	`bang`

Examples for invalid path URIs are:

URI	Issue
`/foo`	leading slash separator not allowed if URI is not absolute
`foo/`	trailing slash separator not allowed if URI is not absolute
`foo:bar`	missing mount point separator in opaque URI
`foo:bar:baz:/bang!/boom`	dito for `bar:baz:/bang`

Identities

For any path p, it's generally true that new FsPath(p.toUri()).equals(p).

Furthermore, it's generally true that new FsPath(p.getMountPoint(), p.getEntryName()).equals(p).

Serialization

This class supports serialization with both ObjectOutputStream and XMLEncoder.

Author:: Christian Schlichtherle
See Also:

Field Summary

Fields
Modifier and Type	Field and Description
`private static java.net.URI`	`DOT`
`private FsEntryName`	`entryName`
`private java.net.URI`	`hierarchical`
`private FsMountPoint`	`mountPoint`
`private static long`	`serialVersionUID`
`private java.net.URI`	`uri`

Constructor Summary

Constructors
Constructor and Description
`FsPath(java.io.File file)` Equivalent to `new FsPath(file.toURI(), FsUriModifier.CANONICALIZE)`.
`FsPath(FsMountPoint mountPoint, FsEntryName entryName)` Constructs a new path by composing its URI from the given nullable mount point and entry name.
`FsPath(java.lang.String uri)` Deprecated. This constructor does not quote characters with a special meaning in a URI - use the constructor variant with the URI parameter instead.
`FsPath(java.lang.String uri, FsUriModifier modifier)` Deprecated. This constructor does not quote characters with a special meaning in a URI - use the constructor variant with the URI parameter instead.
`FsPath(java.net.URI uri)` Equivalent to `new FsPath(uri, FsUriModifier.NULL)`.
`FsPath(java.net.URI uri, FsUriModifier modifier)` Constructs a new path by parsing the given URI.

Method Summary

Methods
Modifier and Type	Method and Description
`int`	`compareTo(FsPath that)` Implements a natural ordering which is consistent with `equals(Object)`.
`static FsPath`	`create(java.lang.String uri)` Deprecated. This method does not quote characters with a special meaning in a URI - use the method variant with the URI parameter instead.
`static FsPath`	`create(java.lang.String uri, FsUriModifier modifier)` Deprecated. This method does not quote characters with a special meaning in a URI - use the method variant with the URI parameter instead.
`static FsPath`	`create(java.net.URI uri)` Equivalent to `create(uri, FsUriModifier.NULL)`.
`static FsPath`	`create(java.net.URI uri, FsUriModifier modifier)` Constructs a new path by parsing the given URI.
`boolean`	`equals(java.lang.Object that)` Returns `true` iff the given object is a path name and its URI `equals` the URI of this path name.
`FsEntryName`	`getEntryName()` Returns the entry name component.
`java.net.URI`	`getHierarchicalUri()` Deprecated.
`FsMountPoint`	`getMountPoint()` Returns the mount point component or `null` iff this path's `URI` is not absolute.
`java.net.URI`	`getUri()` Deprecated.
`int`	`hashCode()` Returns a hash code which is consistent with `equals(Object)`.
`private boolean`	`invariants()`
`private void`	`parse(java.net.URI uri, FsUriModifier modifier)`
`private void`	`readObject(java.io.ObjectInputStream in)`
`FsPath`	`resolve(FsEntryName entryName)` Resolves the given entry name against this path.
`private static java.lang.String`	`toDecodedUri(FsEntryName entryName)`
`java.net.URI`	`toHierarchicalUri()` Returns a URI which is recursively transformed from the URI of this path so that it's absolute and hierarchical.
`java.lang.String`	`toString()` Equivalent to calling `URI.toString()` on `toUri()`.
`java.net.URI`	`toUri()` Returns the URI for this path.
`private void`	`writeObject(java.io.ObjectOutputStream out)`

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - serialVersionUID
```
private static final long serialVersionUID
```
    See Also:
    Constant Field Values
  - DOT
```
private static final java.net.URI DOT
```
  - uri
```
private java.net.URI uri
```
  - mountPoint
```
@Nullable
private transient FsMountPoint mountPoint
```
  - entryName
```
private transient FsEntryName entryName
```
  - hierarchical
```
@Nullable
private transient volatile java.net.URI hierarchical
```
- Constructor Detail
  - FsPath
```
@Deprecated
public FsPath(java.lang.String uri)
       throws java.net.URISyntaxException
```
    Deprecated. This constructor does not quote characters with a special meaning in a URI - use the constructor variant with the URI parameter instead.
    
    Equivalent to new FsPath(uri, FsUriModifier.NULL).
    
    Throws:
    
    java.net.URISyntaxException
  - FsPath
```
@Deprecated
public FsPath(java.lang.String uri,
                 FsUriModifier modifier)
       throws java.net.URISyntaxException
```
    Deprecated. This constructor does not quote characters with a special meaning in a URI - use the constructor variant with the URI parameter instead.
    
    Constructs a new path by calling new URI(uri) and parsing the resulting URI.
    
    Parameters:
    uri - the URI string representation.
    modifier - the URI modifier.
    
    Throws:
    
    java.net.URISyntaxException - if uri does not conform to the syntax constraints for paths.
  - FsPath
```
public FsPath(java.io.File file)
```
    Equivalent to new FsPath(file.toURI(), FsUriModifier.CANONICALIZE). Note that this constructor is expected not to throw any exceptions.
  - FsPath
```
public FsPath(java.net.URI uri)
       throws java.net.URISyntaxException
```
    Equivalent to new FsPath(uri, FsUriModifier.NULL).
    
    Throws:
    
    java.net.URISyntaxException
  - FsPath
```
public FsPath(java.net.URI uri,
      FsUriModifier modifier)
       throws java.net.URISyntaxException
```
    Constructs a new path by parsing the given URI.
    
    Parameters:
    uri - the non-null URI.
    modifier - the URI modifier.
    
    Throws:
    
    java.net.URISyntaxException - if uri does not conform to the syntax constraints for paths.
  - FsPath
```
public FsPath(@CheckForNull
      FsMountPoint mountPoint,
      FsEntryName entryName)
```
    Constructs a new path by composing its URI from the given nullable mount point and entry name.
    
    Parameters:
    mountPoint - the nullable mount point.
    entryName - the entry name.
    
    Throws:
    
    java.net.URISyntaxException - if the composed path URI would not conform to the syntax constraints for paths.
- Method Detail
  - create
```
@Deprecated
public static FsPath create(java.lang.String uri)
```
    Deprecated. This method does not quote characters with a special meaning in a URI - use the method variant with the URI parameter instead.
    
    Equivalent to create(uri, FsUriModifier.NULL).
  - create
```
@Deprecated
public static FsPath create(java.lang.String uri,
                       FsUriModifier modifier)
```
    Deprecated. This method does not quote characters with a special meaning in a URI - use the method variant with the URI parameter instead.
    
    Constructs a new path by constructing a new URI from the given string representation and parsing the result. This static factory method calls new FsPath(uri, modifier) and wraps any thrown URISyntaxException in an IllegalArgumentException.
    
    Parameters:
    uri - the URI string representation.
    modifier - the URI modifier.
    
    Returns:
    A new path.
    
    Throws:
    
    java.lang.IllegalArgumentException - if uri does not conform to the syntax constraints for paths.
  - create
```
public static FsPath create(java.net.URI uri)
```
    Equivalent to create(uri, FsUriModifier.NULL).
  - create
```
public static FsPath create(java.net.URI uri,
            FsUriModifier modifier)
```
    Constructs a new path by parsing the given URI. This static factory method calls new FsPath(uri, modifier) and wraps any thrown URISyntaxException in an IllegalArgumentException.
    
    Parameters:
    uri - the URI.
    modifier - the URI modifier.
    
    Returns:
    A new path.
    
    Throws:
    
    java.lang.IllegalArgumentException - if uri does not conform to the syntax constraints for paths.
  - writeObject
```
private void writeObject(java.io.ObjectOutputStream out)
                  throws java.io.IOException
```
    Throws:
    
    java.io.IOException
  - readObject
```
private void readObject(java.io.ObjectInputStream in)
                 throws java.io.IOException,
                        java.lang.ClassNotFoundException
```
    Throws:
    
    java.io.IOException
    
    java.lang.ClassNotFoundException
  - parse
```
private void parse(java.net.URI uri,
         FsUriModifier modifier)
            throws java.net.URISyntaxException
```
    Throws:
    
    java.net.URISyntaxException
  - toDecodedUri
```
private static java.lang.String toDecodedUri(FsEntryName entryName)
```
  - invariants
```
private boolean invariants()
```
  - toUri
```
public java.net.URI toUri()
```
    Returns the URI for this path.
    
    Returns:
    The URI for this path.
    Since:
    
    TrueZIP 7.1.1
  - getUri
```
@Deprecated
public java.net.URI getUri()
```
    Deprecated.
    
    See Also:
    toUri()
  - toHierarchicalUri
```
public java.net.URI toHierarchicalUri()
```
    Returns a URI which is recursively transformed from the URI of this path so that it's absolute and hierarchical. If this path is already in hierarchical form, its URI is returned.
    For example, the path URIs zip:file:/archive!/entry and tar:file:/archive!/entry would both produce the hierarchical URI file:/archive/entry.
    
    Returns:
    A URI which is recursively transformed from the URI of this path so that it's absolute and hierarchical.
    Since:
    
    TrueZIP 7.1.1
  - getHierarchicalUri
```
@Deprecated
public java.net.URI getHierarchicalUri()
```
    Deprecated.
    
    See Also:
    toHierarchicalUri()
  - getMountPoint
```
@Nullable
public FsMountPoint getMountPoint()
```
    Returns the mount point component or null iff this path's URI is not absolute.
    
    Returns:
    The nullable mount point.
  - getEntryName
```
public FsEntryName getEntryName()
```
    Returns the entry name component. This may be empty, but is never null.
    
    Returns:
    The entry name.
  - resolve
```
public FsPath resolve(FsEntryName entryName)
```
    Resolves the given entry name against this path.
    
    Parameters:
    entryName - an entry name relative to this path.
    
    Returns:
    A new path with an absolute URI.
  - equals
```
public boolean equals(@CheckForNull
             java.lang.Object that)
```
    Returns true iff the given object is a path name and its URI equals the URI of this path name. Note that this ignores the mount point and entry name.
    
    Overrides:
    
    equals in class java.lang.Object
  - compareTo
```
public int compareTo(FsPath that)
```
    Implements a natural ordering which is consistent with equals(Object).
    
    Specified by:
    
    compareTo in interface java.lang.Comparable<FsPath>
  - hashCode
```
public int hashCode()
```
    Returns a hash code which is consistent with equals(Object).
    
    Overrides:
    
    hashCode in class java.lang.Object
  - toString
```
public java.lang.String toString()
```
    Equivalent to calling URI.toString() on toUri().
    
    Overrides:
    
    toString in class java.lang.Object

Class FsPath

Specification

Examples

Identities

Serialization

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

serialVersionUID

DOT

uri

mountPoint

entryName

hierarchical

Constructor Detail

FsPath

FsPath

FsPath

FsPath

FsPath

FsPath

Method Detail

create

create

create

create

writeObject

readObject

parse

toDecodedUri

invariants

toUri

getUri

toHierarchicalUri

getHierarchicalUri

getMountPoint

getEntryName

resolve

equals

compareTo

hashCode

toString