org.eclipse.wst.common.environment.uri
Interface IURI


public interface IURI

A IURI represents a Univeral Resource Identifer.

Since:
1.0

Method Summary
 IURI append(IURI relativeURI)
           
 java.io.File asFile()
           
 java.lang.String asString()
           
 java.net.URL asURL()
           
 void erase()
          Erases the resource identified by this IURI.
 java.io.InputStream getInputStream()
           
 java.io.OutputStream getOutputStream()
           
 IURIScheme getURIScheme()
           
 boolean isAvailableAsFile()
           
 boolean isAvailableAsURL()
           
 boolean isHierarchical()
           
 boolean isLeaf()
           
 boolean isPresent()
           
 boolean isReadable()
           
 boolean isRelative()
           
 boolean isWritable()
           
 IURI[] list()
          Returns a list of URIs for the immediate children of the given hierarchical, non-leaf IURI.
 IURI[] list(IURIFilter uriFilter)
          As for list(), except only URIs that are accepted by the given filter are returned in the array.
 IURI parent()
           
 void rename(IURI newURI)
          Renames or moves the resource identified by this IURI to the new IURI.
 java.lang.String toString()
           
 void touchFolder()
          Creates a new folder resource at the location identified by the IURI.
 void touchLeaf()
          Creates a new, empty resource at the location identified by the IURI.
 void visit(IURIVisitor uriVisitor)
          Visits this resource and its decendants in pre-order fashion.
 void visit(IURIVisitor uriVisitor, IURIFilter uriFilter)
          As for visit(IURIVisitor), except only resource URIs that are accepted by the given filter are visited.
 

Method Detail

toString

java.lang.String toString()
Overrides:
toString in class java.lang.Object
Returns:
Returns the string form of the IURI. The resource need not exist.

getURIScheme

IURIScheme getURIScheme()
Returns:
Returns the IURIScheme for the scheme of this IURI. The resource need not exist.

isPresent

boolean isPresent()
Returns:
Returns true iff the resource identified by this IURI exists.

isLeaf

boolean isLeaf()
Returns:
Returns true iff the resource identified by this IURI exists and is a leaf. Returns true always for non-hierarchical schemes.

isReadable

boolean isReadable()
Returns:
Returns true iff the resource identified by this IURI exists and is readable. A readable leaf resource indicates that an input stream can be opened on the resource. A readable folder resource indicates that the children of the folder, if any, can be determined via the list() or visit() methods.

isWritable

boolean isWritable()
Returns:
Returns true iff the resource identified by this IURI exists and is writable. A writable leaf resource indicates that an output stream can be opened on the resource. A writable folder resource indicates that new resources can be created in the folder.

isHierarchical

boolean isHierarchical()
Returns:
Returns true iff this IURI belongs to a hierarchical scheme. The resource need not exist. this.isHierarchical() == this.getURIScheme().isHierarchical().

isRelative

boolean isRelative()
Returns:
Returns true iff this IURI is a relative IURI. The resource need not exist.

parent

IURI parent()
            throws URIException
Returns:
Returns the IURI of the folder containing this IURI. The resource need not exist.
Throws:
URIException - if there is no parent URI.

append

IURI append(IURI relativeURI)
            throws URIException
Parameters:
relativeURI - a relative URI.
Returns:
Returns a new, normalized IURI formed by appending the given relative IURI to this IURI. Both URIs must be hierarchical. The resulting IURI will always be hierarchical. The given IURI must be relative. This IURI can be relative or absolute. the resulting IURI will be equivalently relative or absolute.
Throws:
URIException - if relativeURI is not relative.

getInputStream

java.io.InputStream getInputStream()
                                   throws URIException
Returns:
Gets an InputStream for reading from the resource identified by this leaf or non-hierarchical IURI.
Throws:
URIException - if a stream for this URI can not be created.

getOutputStream

java.io.OutputStream getOutputStream()
                                     throws URIException
Returns:
Gets an OutputStream for writing to the resource identified by this leaf or non-hierarchical IURI.
Throws:
URIException - if a stream for this URI can not be created.

touchLeaf

void touchLeaf()
               throws URIException
Creates a new, empty resource at the location identified by the IURI. On completion, this.isLeaf() == true. If a leaf resource already exists, this method does nothing. If a non-leaf resource already exists under this IURI, creation will fail and an exception will be thrown.

Throws:
URIException - if an error occurs touching this leaf resource.

touchFolder

void touchFolder()
                 throws URIException
Creates a new folder resource at the location identified by the IURI. The scheme of the IURI must be hierarchical. On completion, this.isLeaf() == false. If a folder resource already exists, this method does nothing. If a leaf resource already exists under this IURI, creation will fail and an exception will be thrown.

Throws:
URIException - if an error occurs touching this folder resource.

erase

void erase()
           throws URIException
Erases the resource identified by this IURI.

Throws:
URIException - if an error occurs erasing this resource.

rename

void rename(IURI newURI)
            throws URIException
Renames or moves the resource identified by this IURI to the new IURI.

Parameters:
newURI - the new URI name for this URI.
Throws:
URIException - if an error occurs renaming this resource.

visit

void visit(IURIVisitor uriVisitor)
           throws URIException
Visits this resource and its decendants in pre-order fashion. For each resource, whether a folder or a leaf, the given IURIVisitor's visit() method is called with the IURI of the resource. If IURIVisitor.visit() returns false, the visiting algorithm will "prune" the decendants of the resource and carry on visiting the rest of the tree. If IURIVisitor.visit() returns true, the visiting algorithm will continue its walk down the resource's descendants.

Parameters:
uriVisitor - the visitor that will be called for each resource visited.
Throws:
URIException - if an error occurs visiting this resource and its children.

visit

void visit(IURIVisitor uriVisitor,
           IURIFilter uriFilter)
           throws URIException
As for visit(IURIVisitor), except only resource URIs that are accepted by the given filter are visited. If a folder resource fails to be accepted by the filter, this will not prevent the visiting algorithm from walking the resource's descendants. It remains the job of the visitor to choose whether or not to prune a branch by returning false or true.

Parameters:
uriVisitor - the visitor that will be called for each resource visited.
uriFilter - the resource filter.
Throws:
URIException - if an error occurs visiting this resource and its children.

list

IURI[] list()
            throws URIException
Returns a list of URIs for the immediate children of the given hierarchical, non-leaf IURI. This method never returns null, though it may return a zero length array.

Returns:
returns the children for this URI.
Throws:
URIException - if an error occurs locating the children for this URI.

list

IURI[] list(IURIFilter uriFilter)
            throws URIException
As for list(), except only URIs that are accepted by the given filter are returned in the array. This method never returns null, though it may return a zero length array.

Parameters:
uriFilter - the child filter.
Returns:
returns the filtered children for this URI.
Throws:
URIException - if an error occurs locating the children for this URI.

isAvailableAsURL

boolean isAvailableAsURL()
Returns:
Returns true if the asURL() method is fair game, in other words, if this IURI can be converted into a URL.

asURL

java.net.URL asURL()
                   throws URIException
Returns:
Returns a URL object for the resource under this IURI. There are many URIs and URISchemes for which this method will fail and throw an exception. It should be used only in cases where URIs are known to be representable as URLs.
Throws:
URIException - if an error occurs returning this URL.

isAvailableAsFile

boolean isAvailableAsFile()
Returns:
Returns true if the asFile() method is fair game, in other words, if this IURI can be converted into a File.

asFile

java.io.File asFile()
                    throws URIException
Returns:
Returns a File object for the resource under this IURI. There are many URIs and URISchemes for which this method will fail and throw an exception. It should be used only in cases where URIs are known to be backed by physical files.
Throws:
URIException - if an error occurs returning this File.

asString

java.lang.String asString()
Returns:
Returns the IURI as a string. Equivalent to toString().