org.eclipse.wst.common.environment.uri.IURI Maven / Gradle / Ivy
The newest version!
/*******************************************************************************
* 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 ();
}