| /******************************************************************************* |
| * Copyright (c) 2004, 2005 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.wst.common.environment.uri; |
| |
| import java.io.File; |
| import java.io.InputStream; |
| import java.io.OutputStream; |
| import java.net.URL; |
| |
| /** |
| * A IURI represents a Univeral Resource Identifer. |
| * |
| * @since 1.0 |
| */ |
| public interface IURI |
| { |
| /** |
| * @return Returns the string form of the IURI. |
| * The resource need not exist. |
| */ |
| public String toString (); |
| |
| /** |
| * @return Returns the IURIScheme for the scheme of this IURI. |
| * The resource need not exist. |
| */ |
| public IURIScheme getURIScheme (); |
| |
| /** |
| * @return Returns true iff the resource identified by this IURI exists. |
| */ |
| public boolean isPresent (); |
| |
| /** |
| * @return Returns true iff the resource identified by this IURI exists |
| * and is a leaf. Returns true always for non-hierarchical schemes. |
| */ |
| public boolean isLeaf (); |
| |
| /** |
| * @return 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. |
| */ |
| public boolean isReadable (); |
| |
| /** |
| * @return 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. |
| */ |
| public boolean isWritable (); |
| |
| /** |
| * @return Returns true iff this IURI belongs to a hierarchical scheme. |
| * The resource need not exist. |
| * this.isHierarchical() == this.getURIScheme().isHierarchical(). |
| */ |
| public boolean isHierarchical (); |
| |
| /** |
| * @return Returns true iff this IURI is a relative IURI. |
| * The resource need not exist. |
| */ |
| public boolean isRelative (); |
| |
| /** |
| * @return Returns the IURI of the folder containing this IURI. |
| * The resource need not exist. |
| * @throws URIException if there is no parent URI. |
| */ |
| public IURI parent () throws URIException; |
| |
| /** |
| * @param relativeURI a relative URI. |
| * @return 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. |
| */ |
| public IURI append ( IURI relativeURI ) throws URIException; |
| |
| /** |
| * @return 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. |
| */ |
| public InputStream getInputStream () throws URIException; |
| |
| /** |
| * @return 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. |
| */ |
| public OutputStream getOutputStream () 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. |
| */ |
| public void touchLeaf () 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. |
| */ |
| public void touchFolder () throws URIException; |
| |
| /** |
| * Erases the resource identified by this IURI. |
| * @throws URIException if an error occurs erasing this resource. |
| */ |
| public void erase () throws URIException; |
| |
| /** |
| * Renames or moves the resource identified by this IURI |
| * to the new IURI. |
| * @param newURI the new URI name for this URI. |
| * @throws URIException if an error occurs renaming this resource. |
| */ |
| public void rename ( IURI newURI ) 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. |
| * @param uriVisitor the visitor that will be called for each resource visited. |
| * @throws URIException if an error occurs visiting this resource and its children. |
| */ |
| public void visit ( IURIVisitor uriVisitor ) 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. |
| * @param uriVisitor the visitor that will be called for each resource visited. |
| * @param uriFilter the resource filter. |
| * @throws URIException if an error occurs visiting this resource and its children. |
| */ |
| public void visit ( IURIVisitor uriVisitor, IURIFilter uriFilter ) 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. |
| * @return returns the children for this URI. |
| * @throws URIException if an error occurs locating the children for this URI. |
| */ |
| public IURI[] list () 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. |
| * @param uriFilter the child filter. |
| * @return returns the filtered children for this URI. |
| * @throws URIException if an error occurs locating the children for this URI. |
| */ |
| public IURI[] list ( IURIFilter uriFilter ) throws URIException; |
| |
| /** |
| * @return Returns true if the asURL() method is fair game, |
| * in other words, if this IURI can be converted into a URL. |
| */ |
| public boolean isAvailableAsURL (); |
| |
| /** |
| * @return 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. |
| */ |
| public URL asURL () throws URIException; |
| |
| /** |
| * @return Returns true if the asFile() method is fair game, |
| * in other words, if this IURI can be converted into a File. |
| */ |
| public boolean isAvailableAsFile (); |
| |
| /** |
| * @return 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. |
| */ |
| public File asFile () throws URIException; |
| |
| /** |
| * @return Returns the IURI as a string. |
| * Equivalent to toString(). |
| */ |
| public String asString (); |
| } |