com.caucho.vfs
Class Path

java.lang.Object
  |
  +--com.caucho.vfs.Path
Direct Known Subclasses:
FilesystemPath, MailtoPath, NullPath, TcpPath

public abstract class Path
extends java.lang.Object

A virtual filesystem path, essentially represented by a URL. Its API resembles a combination of the JDK File object and the URL object.

Paths are, in general, given with the canonical file separator of forward slash, '/'. The filesystems will take care of any necessary translation.

Currently available filesystems:

file:/path/to/file
Java file
http://host:port/path/name?query
HTTP request
tcp://host:port
Raw TCP connection
mailto:user@host?subject='foo'+cc='user2'
Mail to a user.
log:/group/subgroup/item
Logging based on the configuration file.
stdout:
System.out
stderr:
System.err
null:
The equivalent of /dev/null


Field Summary
protected static L10N L
           
protected  SchemeMap schemeMap
           
 
Constructor Summary
protected Path(Path root)
          Creates a new Path object.
 
Method Summary
 void bind(Path context)
          Binds the context to the current path.
 boolean canRead()
          Tests if the file can be read.
 boolean canWrite()
          Tests if the file can be written.
 boolean createNewFile()
          Creates the file named by this Path and returns true if the file is new.
 Path createRoot()
          Creates a restricted root, like the Unix chroot call.
 Path createRoot(SchemeMap schemeMap)
           
 Path createTempFile(java.lang.String prefix, java.lang.String suffix)
          Creates a unique temporary file as a child of this directory.
 boolean equals(java.lang.Object o)
           
 boolean exists()
          Tests if the file exists.
 java.lang.Object getAttribute(java.lang.String name)
          Gets an attribute of the object.
 java.util.Iterator getAttributeNames()
          Returns a iterator of all attribute names set for this object.
 java.lang.String getContentType()
          Returns the mime-type of the file.
 java.lang.String getFullPath()
          Returns the full path, including the restricted root.
 java.lang.String getHost()
          Returns the hostname
 long getLastModified()
          Returns the last modified time of the file.
 long getLength()
          Returns the length of the file in bytes.
 java.lang.String getNativePath()
          Returns the native representation of the path.
 java.lang.Object getObject()
          Returns the object at this path.
 Path getParent()
          Returns the parent path.
abstract  java.lang.String getPath()
          Returns the path.
 int getPort()
          Returns the port.
 java.lang.String getQuery()
          Returns the query string of the path.
abstract  java.lang.String getScheme()
          Returns the url scheme
 java.lang.String getTail()
          Returns the last segment of the path.
 java.lang.String getURL()
          Returns the full url for the given path.
 java.lang.String getUserPath()
          Returns the last string used as a lookup, if available.
 java.lang.Object getValue()
          Gets the object at the path.
 boolean isDirectory()
          Tests if the path refers to a directory.
 boolean isFile()
          Tests if the path refers to a file.
 boolean isObject()
          Tests if the path refers to an object.
 java.util.Iterator iterator()
          Returns a jdk1.2 Iterator for the contents of this directory.
 java.lang.String[] list()
           
 Path lookup(java.lang.String name)
          Looks up a new path based on the old path.
 Path lookup(java.lang.String userPath, java.util.Map newAttributes)
          Returns a new path relative to the current one.
 Path lookupNative(java.lang.String name)
          Looks up a path using the local filesystem conventions.
 Path lookupNative(java.lang.String name, java.util.Map attributes)
          Looks up a native path, adding attributes.
 boolean mkdir()
          Creates the directory named by this path.
 boolean mkdirs()
          Creates the directory named by this path and any parent directories.
 WriteStream openAppend()
          Opens a resin stream for appending.
protected  StreamImpl openAppendImpl()
           
 ReadStream openRead()
          Opens a resin ReadStream for reading.
protected  StreamImpl openReadImpl()
           
 ReadWritePair openReadWrite()
          Opens a resin ReadWritePair for reading and writing.
protected  StreamImpl openReadWriteImpl()
           
 WriteStream openWrite()
          Opens a resin WriteStream for writing.
protected  StreamImpl openWriteImpl()
           
 boolean remove()
          Removes the file or directory named by this path.
 void removeAttribute(java.lang.String name)
          Remove an attribute.
 boolean renameTo(Path path)
          Renames the file or directory to the name given by the path.
 boolean renameTo(java.lang.String path)
          Renames the file or directory to the name given by the path.
protected  java.lang.String scanScheme(java.lang.String uri)
          Returns the scheme portion of a uri.
protected abstract  Path schemeWalk(java.lang.String userPath, java.util.Map newAttributes, java.lang.String newPath, int offset)
          Path-specific lookup.
 void setAttribute(java.lang.String name, java.lang.Object value)
          Sets an attribute of the path.
 void setLastModified(long time)
           
 void setObject(java.lang.Object obj)
          Sets the object at this path.
 void setUserPath(java.lang.String userPath)
          Sets the user path.
 void setValue(java.lang.Object obj)
          Sets the object at the path.
 java.lang.String toString()
           
 void unbind()
          unbinds a link.
 void writeToStream(java.io.OutputStream os)
          Utility to write the contents of this path to the destination stream.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

L

protected static L10N L

schemeMap

protected SchemeMap schemeMap
Constructor Detail

Path

protected Path(Path root)
Creates a new Path object.
Parameters:
root - the new Path root.
Method Detail

lookup

public final Path lookup(java.lang.String name)
Looks up a new path based on the old path.
Parameters:
name - relative url to the new path
Returns:
The new path.

lookup

public Path lookup(java.lang.String userPath,
                   java.util.Map newAttributes)
Returns a new path relative to the current one.

Path only handles scheme:xxx. Subclasses of Path will specialize the xxx.

Parameters:
userPath - relative or absolute path, essentially any url.
newAttributes - attributes for the new path.
Returns:
the new path or null if the scheme doesn't exist

lookupNative

public final Path lookupNative(java.lang.String name)
Looks up a path using the local filesystem conventions. e.g. on Windows, a name of 'd:\foo\bar\baz.html' will look up the baz.html on drive d.
Parameters:
name - relative url using local filesystem separators.

lookupNative

public Path lookupNative(java.lang.String name,
                         java.util.Map attributes)
Looks up a native path, adding attributes.

getParent

public Path getParent()
Returns the parent path.

scanScheme

protected java.lang.String scanScheme(java.lang.String uri)
Returns the scheme portion of a uri. Since schemes are case-insensitive, normalize them to lower case.

schemeWalk

protected abstract Path schemeWalk(java.lang.String userPath,
                                   java.util.Map newAttributes,
                                   java.lang.String newPath,
                                   int offset)
Path-specific lookup. Path implementations will override this.
Parameters:
userPath - the user's lookup() path.
newAttributes - the attributes for the new path.
newPath - the lookup() path
offset - offset into newPath to start lookup.
Returns:
the found path

getURL

public java.lang.String getURL()
Returns the full url for the given path.

getScheme

public abstract java.lang.String getScheme()
Returns the url scheme

getHost

public java.lang.String getHost()
Returns the hostname

getPort

public int getPort()
Returns the port.

getPath

public abstract java.lang.String getPath()
Returns the path. e.g. for HTTP, returns the part after the host and port.

getTail

public java.lang.String getTail()
Returns the last segment of the path.

e.g. for http://www.caucho.com/products/index.html, getTail() returns 'index.html'


getQuery

public java.lang.String getQuery()
Returns the query string of the path.

getNativePath

public java.lang.String getNativePath()
Returns the native representation of the path. On Windows, getNativePath() returns 'd:\\foo\bar.html', getPath() returns '/d:/foo/bar.html'

getUserPath

public java.lang.String getUserPath()
Returns the last string used as a lookup, if available. This allows parsers to give intelligent error messages, with the user's path instead of the whole path. The following will print '../test.html':
 Path path = Pwd.lookup("/some/dir").lookup("../test.html");
 System.out.println(path.getUserPath());
 

setUserPath

public void setUserPath(java.lang.String userPath)
Sets the user path. Useful for temporary files caching another URL.

getFullPath

public java.lang.String getFullPath()
Returns the full path, including the restricted root.

For the following, path.getPath() returns '/file.html', while path.getFullPath() returns '/chroot/file.html'.

 Path chroot = Pwd.lookup("/chroot").createRoot();
 Path path = chroot.lookup("/file.html");
 

exists

public boolean exists()
Tests if the file exists.

getContentType

public java.lang.String getContentType()
Returns the mime-type of the file.

Mime-type ignorant filesystems return 'application/octet-stream'


isDirectory

public boolean isDirectory()
Tests if the path refers to a directory.

isFile

public boolean isFile()
Tests if the path refers to a file.

isObject

public boolean isObject()
Tests if the path refers to an object.

getLength

public long getLength()
Returns the length of the file in bytes.
Returns:
0 for non-files

getLastModified

public long getLastModified()
Returns the last modified time of the file. According to the jdk, this may not correspond to the system time.
Returns:
0 for non-files.

setLastModified

public void setLastModified(long time)

canRead

public boolean canRead()
Tests if the file can be read.

canWrite

public boolean canWrite()
Tests if the file can be written.

list

public java.lang.String[] list()
                        throws java.io.IOException
Returns:
The contents of this directory or null if the path does not refer to a directory.

iterator

public java.util.Iterator iterator()
                            throws java.io.IOException
Returns a jdk1.2 Iterator for the contents of this directory.

mkdir

public boolean mkdir()
              throws java.io.IOException
Creates the directory named by this path.
Returns:
true if successful.

mkdirs

public boolean mkdirs()
               throws java.io.IOException
Creates the directory named by this path and any parent directories.
Returns:
true if successful.

remove

public boolean remove()
               throws java.io.IOException
Removes the file or directory named by this path.
Returns:
true if successful.

renameTo

public boolean renameTo(Path path)
                 throws java.io.IOException
Renames the file or directory to the name given by the path.
Returns:
true if successful

renameTo

public final boolean renameTo(java.lang.String path)
                       throws java.io.IOException
Renames the file or directory to the name given by the path.
Returns:
true if successful

createRoot

public Path createRoot()
Creates a restricted root, like the Unix chroot call. Restricted roots cannot access schemes, so file:/etc/passwd cannot be used.

createRoot is useful for restricting JavaScript scripts without resorting to the dreadfully slow security manager.


createRoot

public Path createRoot(SchemeMap schemeMap)

bind

public void bind(Path context)
Binds the context to the current path. Later lookups will return the new context instead of the current path. Essentially, this is a software symbolic link.

unbind

public void unbind()
unbinds a link.

getValue

public java.lang.Object getValue()
                          throws java.lang.Exception
Gets the object at the path. Normal filesystems will generally typically return null.

A bean filesystem or a mime-type aware filesystem could deserialize the contents of the file.


setValue

public void setValue(java.lang.Object obj)
              throws java.lang.Exception
Sets the object at the path.

Normal filesystems will generally do nothing. However, a bean filesystem or a mime-type aware filesystem could serialize the object and store it.


getAttribute

public java.lang.Object getAttribute(java.lang.String name)
                              throws java.io.IOException
Gets an attribute of the object.

setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.Object value)
                  throws java.io.IOException
Sets an attribute of the path.

removeAttribute

public void removeAttribute(java.lang.String name)
                     throws java.io.IOException
Remove an attribute.

getAttributeNames

public java.util.Iterator getAttributeNames()
                                     throws java.io.IOException
Returns a iterator of all attribute names set for this object.
Returns:
null if path has no attributes.

openRead

public final ReadStream openRead()
                          throws java.io.IOException
Opens a resin ReadStream for reading.

openWrite

public final WriteStream openWrite()
                            throws java.io.IOException
Opens a resin WriteStream for writing.

openReadWrite

public ReadWritePair openReadWrite()
                            throws java.io.IOException
Opens a resin ReadWritePair for reading and writing.

A chat channel, for example, would open its socket using this interface.


openAppend

public WriteStream openAppend()
                       throws java.io.IOException
Opens a resin stream for appending.

createNewFile

public boolean createNewFile()
                      throws java.io.IOException
Creates the file named by this Path and returns true if the file is new.

createTempFile

public Path createTempFile(java.lang.String prefix,
                           java.lang.String suffix)
                    throws java.io.IOException
Creates a unique temporary file as a child of this directory.
Parameters:
prefix - filename prefix
suffix - filename suffix, defaults to .tmp
Returns:
Path to the new file.

writeToStream

public void writeToStream(java.io.OutputStream os)
                   throws java.io.IOException
Utility to write the contents of this path to the destination stream.
Parameters:
os - destination stream.

getObject

public java.lang.Object getObject()
                           throws java.io.IOException
Returns the object at this path. Normally, only paths like JNDI will support this.

setObject

public void setObject(java.lang.Object obj)
               throws java.io.IOException
Sets the object at this path. Normally, only paths like JNDI will support this.

equals

public boolean equals(java.lang.Object o)
Overrides:
equals in class java.lang.Object

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

openReadImpl

protected StreamImpl openReadImpl()
                           throws java.io.IOException

openWriteImpl

protected StreamImpl openWriteImpl()
                            throws java.io.IOException

openReadWriteImpl

protected StreamImpl openReadWriteImpl()
                                throws java.io.IOException

openAppendImpl

protected StreamImpl openAppendImpl()
                             throws java.io.IOException