Overview  Package   Class  Use  Tree  Deprecated  Index 
TrueZIP Kernel 7.0-rc1
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

de.schlichtherle.truezip.fs
Class FsPath

java.lang.Object
  extended by de.schlichtherle.truezip.fs.FsPath
All Implemented Interfaces:
Serializable, Comparable<FsPath>
@Immutable
public final class FsPath
extends Object
implements Serializable, Comparable<FsPath>

Addresses an entry in a file system. A path is usually constructed from a Uniform Resource Identifier in order to assert the following additional syntax constraints:

  1. The URI must not have a fragment.
  2. 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 a FsMountPoint and set as the value of the property mount point. 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 property entry name.
  3. Otherwise, if the URI is absolute, it's resolved with ".", parsedaccording to the syntax constraints for a FsMountPoint and set as the value of the property mount point. The value of the property entry name is then set to the URI relativized to this mount point.
  4. Otherwise, the value of the property mount point is set to null and the URI is parsed according to the syntax constraints for an FsEntryName and set as the value of the property entry name.
For opaque URIs, the constraints build a close subset of the syntax allowed with a JarURLConnection, so that any opaque URL obtained from an instance of this class could be used to create a JarURLConnection object.

Examples for valid path URIs are:

Examples for invalid path URIs are:

This class supports serialization with both ObjectOutputStream and XMLEncoder.

Author:
Christian Schlichtherle
See Also:
Serialized Form

Field Summary
private  FsEntryName entryName
           
private  FsPath hierarchical
           
static String MOUNT_POINT_SEPARATOR
          The separator which is used to split opaque path names into mount points and entry names.
private  FsMountPoint mountPoint
           
private static long serialVersionUID
           
private  URI uri
           
 
Constructor Summary
FsPath(File file)
          Equivalent to new FsPath(file.toURI(), FsUriModifier.CANONICALIZE).
FsPath(FsMountPoint mountPoint, FsEntryName entryName)
          Constructs a new path by synthesizing its URI from the given nullable mount point and entry name.
FsPath(String uri)
          Equivalent to new FsPath(uri, FsUriModifier.NULL).
FsPath(String uri, FsUriModifier modifier)
          Constructs a new path by calling new URI(uri) and parsing the resulting URI.
FsPath(URI uri)
          Equivalent to new FsPath(uri, FsUriModifier.NULL).
FsPath(URI uri, FsUriModifier modifier)
          Constructs a new path by parsing the given URI.
 
Method Summary
 int compareTo(FsPath that)
          Implements a natural ordering which is consistent with equals(Object).
static FsPath create(String uri)
          Equivalent to create(uri, FsUriModifier.NULL).
static FsPath create(String uri, FsUriModifier modifier)
          Constructs a new path by constructing a new URI from the given string representation and parsing the result.
static FsPath create(URI uri)
          Equivalent to create(uri, FsUriModifier.NULL).
static FsPath create(URI uri, FsUriModifier modifier)
          Constructs a new path by parsing the given URI.
 boolean equals(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.
 FsMountPoint getMountPoint()
          Returns the mount point or null iff this path's URI is not absolute.
 URI getUri()
          Returns the URI of this path.
 int hashCode()
          Returns a hash code which is consistent with equals(Object).
 FsPath hierarchicalize()
          Returns a hierarchical URI for this path.
private  boolean invariants()
           
private  void parse(URI uri, FsUriModifier modifier)
           
private static String quote(Object s)
           
private  void readObject(ObjectInputStream in)
           
 FsPath resolve(FsEntryName entryName)
          Resolves the given entry name against this path.
 String toString()
          Equivalent to calling URI.toString() on getUri().
private  void writeObject(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

MOUNT_POINT_SEPARATOR

public static final String MOUNT_POINT_SEPARATOR
The separator which is used to split opaque path names into mount points and entry names. This is identical to the separator in the class JarURLConnection.

See Also:
Constant Field Values

uri

@NonNull
private URI uri

mountPoint

@Nullable
private transient FsMountPoint mountPoint

entryName

@NonNull
private transient FsEntryName entryName

hierarchical

@Nullable
private transient volatile FsPath hierarchical
Constructor Detail

FsPath

public FsPath(@NonNull
              String uri)
       throws URISyntaxException
Equivalent to new FsPath(uri, FsUriModifier.NULL).

Throws:
URISyntaxException

FsPath

public FsPath(@NonNull
              String uri,
              @NonNull
              FsUriModifier modifier)
       throws URISyntaxException
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:
URISyntaxException - if uri does not conform to the syntax constraints for paths.

FsPath

public FsPath(@NonNull
              File file)
Equivalent to new FsPath(file.toURI(), FsUriModifier.CANONICALIZE). Note that this constructor is expected not to throw any exceptions.

FsPath

public FsPath(@NonNull
              URI uri)
       throws URISyntaxException
Equivalent to new FsPath(uri, FsUriModifier.NULL).

Throws:
URISyntaxException

FsPath

public FsPath(@NonNull
              URI uri,
              @NonNull
              FsUriModifier modifier)
       throws URISyntaxException
Constructs a new path by parsing the given URI.

Parameters:
uri - the non-null URI.
modifier - the URI modifier.
Throws:
URISyntaxException - if uri does not conform to the syntax constraints for paths.

FsPath

public FsPath(@CheckForNull
              FsMountPoint mountPoint,
              @NonNull
              FsEntryName entryName)
Constructs a new path by synthesizing its URI from the given nullable mount point and entry name.

Parameters:
mountPoint - the nullable mount point.
entryName - the entry name.
Throws:
URISyntaxException - if the synthesized path URI would not conform to the syntax constraints for paths.
Method Detail

create

@NonNull
public static FsPath create(@NonNull
                                    String uri)
Equivalent to create(uri, FsUriModifier.NULL).

create

@NonNull
public static FsPath create(@NonNull
                                    String uri,
                                    @NonNull
                                    FsUriModifier modifier)
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:
IllegalArgumentException - if uri does not conform to the syntax constraints for paths.

create

@NonNull
public static FsPath create(@NonNull
                                    URI uri)
Equivalent to create(uri, FsUriModifier.NULL).

create

@NonNull
public static FsPath create(@NonNull
                                    URI uri,
                                    @NonNull
                                    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:
IllegalArgumentException - if uri does not conform to the syntax constraints for paths.

writeObject

private void writeObject(@NonNull
                         ObjectOutputStream out)
                  throws IOException
Throws:
IOException

readObject

private void readObject(@NonNull
                        ObjectInputStream in)
                 throws IOException,
                        ClassNotFoundException
Throws:
IOException
ClassNotFoundException

parse

private void parse(@NonNull
                   URI uri,
                   @NonNull
                   FsUriModifier modifier)
            throws URISyntaxException
Throws:
URISyntaxException

quote

private static String quote(Object s)

invariants

private boolean invariants()

getMountPoint

@Nullable
public FsMountPoint getMountPoint()
Returns the mount point or null iff this path's URI is not absolute.

Returns:
The nullable mount point.

getEntryName

@NonNull
public FsEntryName getEntryName()
Returns the entry name. This may be empty, but is never null.

Returns:
The entry name.

getUri

@NonNull
public URI getUri()
Returns the URI of this path.

Returns:
The URI of this path.

resolve

@NonNull
public FsPath resolve(@NonNull
                              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.

hierarchicalize

@NonNull
public FsPath hierarchicalize()
Returns a hierarchical URI for this path. If this path's URI is opaque, the hierarchical URI of its mount point with its entry name resolved against it is returned. Otherwise, this path is returned.

Note that this function is idempotent, so calling it repeatedly will produce the same result again. However, this function is not injective, so two different paths may produce equal results. For example, the path URIs zip:file:/archive!/entry and tar:file:/archive!/entry both have the same hierarchical URI file:/archive/entry.

Returns:
A hierarchical URI for this path.

equals

public boolean equals(@CheckForNull
                      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 Object

compareTo

public int compareTo(@NonNull
                     FsPath that)
Implements a natural ordering which is consistent with equals(Object).

Specified by:
compareTo in interface Comparable<FsPath>

hashCode

public int hashCode()
Returns a hash code which is consistent with equals(Object).

Overrides:
hashCode in class Object

toString

@NonNull
public String toString()
Equivalent to calling URI.toString() on getUri().

Overrides:
toString in class Object
Overview  Package   Class  Use  Tree  Deprecated  Index 
TrueZIP Kernel 7.0-rc1
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2005-2011 Schlichtherle IT Services. All Rights Reserved.