[116807] wst.common APIs need javadoc.
diff --git a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/Choice.java b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/Choice.java
index 88ffa15..7ec982c 100644
--- a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/Choice.java
+++ b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/Choice.java
@@ -16,12 +16,13 @@
* It allows code that is reporting status to specify choices to the user
* which this reporting code can react to.
*
+ * @since 1.0
*/
public class Choice {
- protected char shortcut = ' ';
- protected String label = null;
- protected String description = null;
+ private char shortcut = ' ';
+ private String label = null;
+ private String description = null;
/**
* Constructor for Choice.
@@ -31,8 +32,8 @@
/**
* Constructor for Choice.
- * @param shortcut
- * @param label
+ * @param shortcut the single letter shortcut for this choice.
+ * @param label the label to be displayed to the user for this choice.
*/
public Choice(char shortcut, String label) {
this.shortcut = shortcut;
@@ -41,9 +42,9 @@
/**
* Constructor for Choice.
- * @param shortcut
- * @param label
- * @param description
+ * @param shortcut the single letter shortcut for this choice.
+ * @param label the label to be displayed to the user for this choice.
+ * @param description the description for this choice.
*/
public Choice(char shortcut, String label, String description) {
this.shortcut = shortcut;
diff --git a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/EnvironmentException.java b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/EnvironmentException.java
index 5cc3c59..6e3f70b 100644
--- a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/EnvironmentException.java
+++ b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/EnvironmentException.java
@@ -14,6 +14,8 @@
/**
* This is the exception class for conditions raised by the IEnvironment.
+ *
+ * @since 1.0
*/
public class EnvironmentException extends Exception
{
@@ -22,6 +24,9 @@
*/
private static final long serialVersionUID = 3978983275899402036L;
+ /**
+ * The status for this exception.
+ */
protected IStatus status = null;
/**
@@ -34,6 +39,8 @@
/**
* Creates a new EnvironmentException.
+ *
+ * @param status the status for this exception.
*/
public EnvironmentException ( IStatus status )
{
@@ -43,6 +50,8 @@
/**
* Returns the Status object.
+ *
+ * @return the status for this exception.
*/
public IStatus getStatus()
{
diff --git a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/EnvironmentService.java b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/EnvironmentService.java
index 0fe28aa..5663fec 100644
--- a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/EnvironmentService.java
+++ b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/EnvironmentService.java
@@ -17,6 +17,8 @@
* This class creates a console environment. It also contains static
* conviences methods for creating an ILog object as well as an Eclipse and
* File Scheme.
+ *
+ * @since 1.0
*
*/
public class EnvironmentService
diff --git a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/IEnvironment.java b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/IEnvironment.java
index 0f579e7..568a4f4 100644
--- a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/IEnvironment.java
+++ b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/IEnvironment.java
@@ -21,16 +21,22 @@
* <li>A status handler for receiving and processing status reports,</li>
* <li>A factory for the handling of URIs (resources).</li>
* </ol>
+ *
+ * @since 1.0
*/
public interface IEnvironment
{
/**
* Returns a logging facility.
+ *
+ * @return returns a logging facility.
*/
public ILog getLog ();
/**
* Returns a status handler.
+ *
+ * @return returns a status handler.
*/
public IStatusHandler getStatusHandler ();
@@ -39,6 +45,8 @@
* Hint: Implementers should insure that the Factory they return
* has a reference to this IEnvironment so that IURI objects can
* report progress and announce status.
+ *
+ * @return returns a URI factory.
*/
public IURIFactory getURIFactory ();
}
diff --git a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/ILog.java b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/ILog.java
index 50a211a..925ed24 100644
--- a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/ILog.java
+++ b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/ILog.java
@@ -14,12 +14,29 @@
/**
* ILog objects provide a means for logging information for FFDC etc.
+ *
+ * @since 1.0
*/
public interface ILog
{
+ /**
+ * This constant indicates that a logging message is Ok.
+ */
public static final int OK = 0;
+
+ /**
+ * This constant indicates that a logging message is informational.
+ */
public static final int INFO = 1;
+
+ /**
+ * This constant indicates that a logging message is warning.
+ */
public static final int WARNING = 2;
+
+ /**
+ * This constant indicates that a logging message is an error.
+ */
public static final int ERROR = 4;
/**
@@ -35,7 +52,10 @@
public boolean isEnabled ();
/**
- * Returns true if the the debug option is set to true.
+ * Returns true if this debug option is set to true.
+ *
+ * @param option this debug option string.
+ * @return returns true if this debug option is set to true.
*/
public boolean isEnabled (String option);
@@ -53,7 +73,7 @@
/**
* Logs a <code>Throwable</code>.
* @param severity The severity of the logging entry.
- * @param debug option
+ * @param option this debug option string.
* @param messageNum The message number.
* @param caller The object (for non-static methods) or class (for
* static methods) doing the logging.
@@ -76,7 +96,7 @@
/**
* Logs a <code>Status</code>.
* @param severity The severity of the logging entry.
- * @param debug option
+ * @param option this debug option string.
* @param messageNum The message number.
* @param caller The object (for non-static methods) or class (for
* static methods) doing the logging.
@@ -99,7 +119,7 @@
/**
* Logs an <code>Object</code>.
* @param severity The severity of the logging entry.
- * @param debug option
+ * @param option this debug option string.
* @param messageNum The message number.
* @param caller The object (for non-static methods) or class (for
* static methods) doing the logging.
diff --git a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/IStatusHandler.java b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/IStatusHandler.java
index f6165a7..9c3aee6 100644
--- a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/IStatusHandler.java
+++ b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/IStatusHandler.java
@@ -17,32 +17,38 @@
* indication of choices made by the recipient of the status and
* may raise an exception against the caller to have them abort
* procesing.
+ *
+ * @since 1.0
*/
public interface IStatusHandler
{
/**
* Reports the given Status and set of possible responses.
- * Returns the choice made by the handler.
+ *
+ * @param status the status to report.
+ * @param choices the choices that will be displayed to the user.
+ * @return returns the choice made by the user/handler.
*/
public Choice report ( IStatus status, Choice[] choices );
/**
* Reports the given Status with implied options to either
* continue or abort.
- * Throws an exception if the handler decides the caller
+ * @param status the status to report.
+ * @throws StatusException Throws an exception if the handler decides the caller
* should stop processing.
*/
public void report ( IStatus status ) throws StatusException;
/**
* Report the given Error Status. No user feedback is provided.
- * @param status
+ * @param status the error status to report.
*/
public void reportError( IStatus status );
/**
* Report the given Info Status. No user feedback is provided.
- * @param status
+ * @param status the info status to report.
*/
public void reportInfo( IStatus status );
}
diff --git a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/NullStatusHandler.java b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/NullStatusHandler.java
index e4c7b9b..3e22891 100644
--- a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/NullStatusHandler.java
+++ b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/NullStatusHandler.java
@@ -15,6 +15,8 @@
/**
*
* This class provides a default implementation of the IStatusHandler interface.
+ *
+ * @since 1.0
*
*/
public class NullStatusHandler implements IStatusHandler
diff --git a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/StatusException.java b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/StatusException.java
index b450934..e747ed0 100644
--- a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/StatusException.java
+++ b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/StatusException.java
@@ -15,6 +15,8 @@
/**
* This is the exception class used by StatusHandlers to tell their
* callers that processing should stop.
+ *
+ * @since 1.0
*/
public class StatusException extends EnvironmentException
{
@@ -31,6 +33,7 @@
/**
* Creates a new StatusException with the given Status.
+ * @param status the status for this exception.
*/
public StatusException( IStatus status )
{
@@ -40,6 +43,7 @@
/**
* Creates a new StatusException with the given Choice.
* The Choice may be null.
+ * @param choice the choice for this exception.
*/
public StatusException ( Choice choice )
{
@@ -50,6 +54,9 @@
/**
* Creates a new StatusException with the given Choice
* and status object. The Choice may be null.
+ *
+ * @param status the status for this exception.
+ * @param choice the choice for this exception.
*/
public StatusException ( IStatus status, Choice choice )
{
@@ -58,7 +65,7 @@
}
/**
- * Returns the Choice object inside this exception.
+ * @return Returns the Choice object inside this exception.
*/
public Choice getChoice ()
{
diff --git a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURI.java b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURI.java
index d2694ca..9352326 100644
--- a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURI.java
+++ b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURI.java
@@ -17,34 +17,36 @@
/**
* A IURI represents a Univeral Resource Identifer.
+ *
+ * @since 1.0
*/
public interface IURI
{
/**
- * Returns the string form of the IURI.
+ * @return Returns the string form of the IURI.
* The resource need not exist.
*/
public String toString ();
/**
- * Returns the IURIScheme for the scheme of this IURI.
+ * @return Returns the IURIScheme for the scheme of this IURI.
* The resource need not exist.
*/
public IURIScheme getURIScheme ();
/**
- * Returns true iff the resource identified by this IURI exists.
+ * @return Returns true iff the resource identified by this IURI exists.
*/
public boolean isPresent ();
/**
- * Returns true iff the resource identified by this IURI exists
+ * @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 ();
/**
- * Returns true iff the resource identified by this IURI exists
+ * @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,
@@ -53,7 +55,7 @@
public boolean isReadable ();
/**
- * Returns true iff the resource identified by this IURI exists
+ * @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.
@@ -61,42 +63,48 @@
public boolean isWritable ();
/**
- * Returns true iff this IURI belongs to a hierarchical scheme.
+ * @return Returns true iff this IURI belongs to a hierarchical scheme.
* The resource need not exist.
* this.isHierarchical() == this.getURIScheme().isHierarchical().
*/
public boolean isHierarchical ();
/**
- * Returns true iff this IURI is a relative IURI.
+ * @return Returns true iff this IURI is a relative IURI.
* The resource need not exist.
*/
public boolean isRelative ();
/**
- * Returns the IURI of the folder containing this IURI.
+ * @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;
/**
- * Returns a new, normalized IURI formed by appending the given
+ * @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;
/**
- * Gets an InputStream for reading from the resource
+ * @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;
/**
- * Gets an OutputStream for writing to the resource
+ * @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;
@@ -106,6 +114,7 @@
* 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;
@@ -116,17 +125,21 @@
* 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;
@@ -139,6 +152,8 @@
* 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;
@@ -149,6 +164,9 @@
* 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;
@@ -156,6 +174,8 @@
* 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;
@@ -163,39 +183,44 @@
* 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;
/**
- * Returns true if the asURL() method is fair game,
+ * @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 ();
/**
- * Returns a URL object for the resource under this IURI.
+ * @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;
/**
- * Returns true if the asFile() method is fair game,
+ * @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 ();
/**
- * Returns a File object for the resource under this IURI.
+ * @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;
/**
- * Returns the IURI as a string.
+ * @return Returns the IURI as a string.
* Equivalent to toString().
*/
public String asString ();
diff --git a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURIFactory.java b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURIFactory.java
index 011c2c5..f8a3123 100644
--- a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURIFactory.java
+++ b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURIFactory.java
@@ -14,16 +14,24 @@
/**
* This is a factory for creating new IURI and IURIScheme objects.
+ *
+ * @since 1.0
*/
public interface IURIFactory
{
/**
* Creates and returns a new IURI for the given string.
+ * @param uri the uri to be created.
+ * @return the new URI.
+ * @throws URIException if the uri parameter is not a valid URI.
*/
public IURI newURI ( String uri ) throws URIException;
/**
* Creates and returns a new IURI for the given URL.
+ * @param url the url to use to create this URI
+ * @return the new URI.
+ * @throws URIException if the url parameter is not a valid url.
*/
public IURI newURI ( URL url ) throws URIException;
@@ -34,6 +42,11 @@
* substring up to but excluding the first colon is interpretted as the
* name of the scheme, meaning the caller can pass in any IURI string in
* order to get a IURIScheme object.
+ *
+ * @param schemeOrURI the scheme or URI from which to create the scheme.
+ * @return the new Scheme.
+ * @throws URIException if schemeOrUri parameter does not contain
+ * a valid scheme or URI name.
*/
public IURIScheme newURIScheme ( String schemeOrURI ) throws URIException;
}
diff --git a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURIFilter.java b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURIFilter.java
index f029330..3e41c8e 100644
--- a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURIFilter.java
+++ b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURIFilter.java
@@ -13,6 +13,8 @@
/**
* This interface is implemented by classes that visit or list URIs.
* Refer to {@link IURI#getChildren}.
+ *
+ * @since 1.0
*/
public interface IURIFilter
{
@@ -21,6 +23,8 @@
* @param uri The resource to filter.
* @return True if the resource matches the filter,
* false if it does not.
+ * @param uri the uri that will be accepted or rejected.
+ * @return returns true if this uri is accepted.
* @throws URIException If the filter fails to analyze the resource.
*/
public boolean accepts ( IURI uri ) throws URIException;
diff --git a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURIScheme.java b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURIScheme.java
index 52e1258..61177ce 100644
--- a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURIScheme.java
+++ b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURIScheme.java
@@ -17,36 +17,48 @@
* A IURIScheme represents a single scheme for some a family of
* Univeral Resource Identifiers. Examples include "file", "http"
* and "platform" (Eclipse).
+ *
+ * @since 1.0
*/
public interface IURIScheme
{
/**
- * Returns a new IURI.
+ * @param uri the URI to be created.
+ * @return Returns a new IURI.
+ * @throws URIException if the uri specified is not valid or
+ * can not be created.
*/
public IURI newURI ( String uri ) throws URIException;
/**
- * Returns a new IURI.
+ * @param url the url used to create the URI.
+ * @return Returns a new IURI.
+ * @throws URIException if the url specified is not valid or
+ * can not be created.
*/
public IURI newURI ( URL url ) throws URIException;
/**
- * Returns a new IURI.
+ * @param uri the URI to be created.
+ * @return Returns a new IURI.
+ * @throws URIException if the uri specified is not valid or
+ * can not be created.
*/
public IURI newURI ( IURI uri ) throws URIException;
/**
- * Returns the proper name of the scheme.
+ * @return Returns the proper name of the scheme.
*/
public String toString ();
/**
- * Returns true if and only if this is a hierarchical scheme.
+ * @return Returns true if and only if this is a hierarchical scheme.
*/
public boolean isHierarchical ();
/**
- * Returns true if and only if the given IURI satisfies the
+ * @param uri the uri to check for validity.
+ * @return Returns true if and only if the given IURI satisfies the
* grammatical requirements of the scheme. Absolute URIs must
* begin with "<scheme>:". Relative URIs must either not contain
* a colon, ":", or it must begin with "./".
@@ -54,7 +66,8 @@
public boolean isValid ( IURI uri );
/**
- * Returns a Status object indicating whether or not the given
+ * @param uri the uri to check for validity.
+ * @return Returns a Status object indicating whether or not the given
* IURI is valid. The severity and message of the Status object
* will describe this.
*/
diff --git a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURIVisitor.java b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURIVisitor.java
index 689a1b1..aa752eb 100644
--- a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURIVisitor.java
+++ b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/IURIVisitor.java
@@ -13,6 +13,8 @@
/**
* This interface is implemented by classes that visit URIs.
* Refer to {@link IURI#visit}.
+ *
+ * @since 1.0
*/
public interface IURIVisitor
{
diff --git a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/SimpleURIFactory.java b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/SimpleURIFactory.java
index d0906c6..90945ac 100644
--- a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/SimpleURIFactory.java
+++ b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/SimpleURIFactory.java
@@ -21,14 +21,17 @@
/**
*
* This class provides a default implementation of the IURIFactory interface.
- *
+ *
+ * @since 1.0
*/
public class SimpleURIFactory implements IURIFactory
{
private Hashtable schemes_ = new Hashtable();
/**
- * Creates and returns a new IURI for the given string.
+ * @param uri the uri to be created.
+ * @return Creates and returns a new IURI for the given string.
+ * @throws URIException if an error occurs creating this URI.
*/
public IURI newURI(String uri) throws URIException
{
@@ -38,7 +41,9 @@
}
/**
- * Creates and returns a new IURI for the given URL.
+ * @param url the url to use to create this uri.
+ * @return Creates and returns a new IURI for the given URL.
+ * @throws URIException if an error occurs creating this URI.
*/
public IURI newURI(URL url) throws URIException
{
@@ -48,18 +53,27 @@
}
/**
- * Creates and returns a new IURIScheme for the given scheme string.
+ * @param schemeOrURI the scheme name or URI from which this scheme is
+ * to be created.
+ * @return Creates and returns a new IURIScheme for the given scheme string.
* If the string contains no colons, the entire string is interpretted
* as the name of the scheme. If the string contains a colon, then the
* substring up to but excluding the first colon is interpretted as the
* name of the scheme, meaning the caller can pass in any IURI string in
* order to get a IURIScheme object.
+ * @throws URIException if an error occurs creating this URI scheme.
*/
public IURIScheme newURIScheme(String schemeOrURI) throws URIException
{
return newURIScheme( schemeOrURI, true );
}
+ /**
+ * This method registers a scheme for a particular protocol.
+ *
+ * @param protocol the protocol.
+ * @param scheme the scheme.
+ */
public void registerScheme( String protocol, IURIScheme scheme )
{
schemes_.put( protocol, scheme );
diff --git a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/URIException.java b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/URIException.java
index 5d5b1e1..e1aee84 100644
--- a/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/URIException.java
+++ b/plugins/org.eclipse.wst.common.environment/src/org/eclipse/wst/common/environment/uri/URIException.java
@@ -17,6 +17,8 @@
* Every URIException carries a IURI and a Status, each of which may
* be null. The getMessage() method as inherited from Exception will
* return the message from the URIExceptin's Status object, if any.
+ *
+ * @since 1.0
*/
public class URIException extends Exception
{
@@ -40,6 +42,8 @@
/**
* Creates a new URIException with the given Status.
* The status may be null.
+ *
+ * @param status the staus for this exception.
*/
public URIException ( IStatus status )
{
@@ -50,6 +54,9 @@
/**
* Creates a new URIException for the given Status and IURI,
* each of which may be null.
+ *
+ * @param status the status for this exception.
+ * @param uri the uri that caused this exception.
*/
public URIException ( IStatus status, IURI uri )
{
@@ -59,7 +66,7 @@
}
/**
- * Returns the Status object inside this exception.
+ * @return returns the Status object inside this exception.
*/
public IStatus getStatus ()
{
@@ -67,7 +74,7 @@
}
/**
- * Returns the IURI inside this exception.
+ * @return returns the IURI inside this exception.
*/
public IURI getURI ()
{
