[dna-commits] DNA SVN: r222 - trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph.

[dna-commits at lists.jboss.org]

Author: jverhaeg at redhat.com
Date: 2008-06-02 14:00:06 -0400 (Mon, 02 Jun 2008)
New Revision: 222

Modified:
   trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/NamespaceRegistry.java
Log:
DNA-85: Changed JavaDocs to indicate when null will be returned.

Modified: trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/NamespaceRegistry.java
===================================================================
--- trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/NamespaceRegistry.java	2008-06-02 17:56:41 UTC (rev 221)
+++ trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/NamespaceRegistry.java	2008-06-02 18:00:06 UTC (rev 222)
@@ -2,7 +2,7 @@
  * JBoss, Home of Professional Open Source.
  * Copyright 2008, Red Hat Middleware LLC, and individual contributors
  * as indicated by the @author tags. See the copyright.txt file in the
- * distribution for a full listing of individual contributors. 
+ * distribution for a full listing of individual contributors.
  *
  * This is free software; you can redistribute it and/or modify it
  * under the terms of the GNU Lesser General Public License as
@@ -26,58 +26,68 @@
 
 /**
  * Registry of namespaces, which are used to provide isolated and independent domains for {@link Name names}.
+ *
  * @author Randall Hauch
  */
 @ThreadSafe
 public interface NamespaceRegistry {
 
-    /**
-     * Return the namespace URI that is currently mapped to the empty prefix, or null if there is no current default namespace.
-     * @return the namespace URI that represents the default namespace, or null if there is no default namespace
-     */
-    String getDefaultNamespaceUri();
+	/**
+	 * Return the namespace URI that is currently mapped to the empty prefix, or null if there is no current default namespace.
+	 *
+	 * @return the namespace URI that represents the default namespace, or null if there is no default namespace
+	 */
+	String getDefaultNamespaceUri();
 
-    /**
-     * Get the namespace URI for the supplied prefix.
-     * @param prefix the namespace prefix
-     * @return the namespace URI for the supplied prefix, or null if there is no namespace currently registered to use that prefix
-     * @throws IllegalArgumentException if the prefix is null
-     */
-    String getNamespaceForPrefix( String prefix );
+	/**
+	 * Get the namespace URI for the supplied prefix.
+	 *
+	 * @param prefix the namespace prefix
+	 * @return the namespace URI for the supplied prefix, or null if there is no namespace currently registered to use that prefix
+	 * @throws IllegalArgumentException if the prefix is null
+	 */
+	String getNamespaceForPrefix( String prefix );
 
-    /**
-     * Return the prefix used for the supplied namespace URI.
-     * @param namespaceUri the namespace URI
-     * @param generateIfMissing true if the namespace URI has not already been registered and the method should auto-register the
-     * namespace with a generated prefix, or false if the method should never auto-register the namespace
-     * @return the prefix currently being used for the namespace; never null but possibly empty for the default namespace
-     * @throws IllegalArgumentException if the namespace URI is null
-     * @see #isRegisteredNamespaceUri(String)
-     */
-    String getPrefixForNamespaceUri( String namespaceUri, boolean generateIfMissing );
+	/**
+	 * Return the prefix used for the supplied namespace URI.
+	 *
+	 * @param namespaceUri the namespace URI
+	 * @param generateIfMissing true if the namespace URI has not already been registered and the method should auto-register the
+	 *        namespace with a generated prefix, or false if the method should never auto-register the namespace
+	 * @return the prefix currently being used for the namespace, or <code>null</code> if the namespace has not been registered
+	 *         and <code>generateIfMissing</code> is <code>false</code>
+	 * @throws IllegalArgumentException if the namespace URI is null
+	 * @see #isRegisteredNamespaceUri(String)
+	 */
+	String getPrefixForNamespaceUri( String namespaceUri,
+	                                 boolean generateIfMissing );
 
-    /**
-     * Return whether there is a registered prefix for the supplied namespace URI.
-     * @param namespaceUri the namespace URI
-     * @return true if the supplied namespace has been registered with a prefix, or false otherwise
-     * @throws IllegalArgumentException if the namespace URI is null
-     */
-    boolean isRegisteredNamespaceUri( String namespaceUri );
+	/**
+	 * Return whether there is a registered prefix for the supplied namespace URI.
+	 *
+	 * @param namespaceUri the namespace URI
+	 * @return true if the supplied namespace has been registered with a prefix, or false otherwise
+	 * @throws IllegalArgumentException if the namespace URI is null
+	 */
+	boolean isRegisteredNamespaceUri( String namespaceUri );
 
-    /**
-     * Register a new namespace using the supplied prefix, returning the namespace URI previously registered under that prefix.
-     * @param prefix the prefix for the namespace, or null if a namesapce prefix should be generated automatically
-     * @param namespaceUri the namespace URI
-     * @return the namespace URI that was previously registered with the supplied prefix, or null if the prefix was not previously
-     * bound to a namespace URI
-     * @throws IllegalArgumentException if the namespace URI is null
-     */
-    String register( String prefix, String namespaceUri );
+	/**
+	 * Register a new namespace using the supplied prefix, returning the namespace URI previously registered under that prefix.
+	 *
+	 * @param prefix the prefix for the namespace, or null if a namesapce prefix should be generated automatically
+	 * @param namespaceUri the namespace URI
+	 * @return the namespace URI that was previously registered with the supplied prefix, or null if the prefix was not previously
+	 *         bound to a namespace URI
+	 * @throws IllegalArgumentException if the namespace URI is null
+	 */
+	String register( String prefix,
+	                 String namespaceUri );
 
-    /**
-     * Obtain the set of namespaces that are registered.
-     * @return the set of
-     */
-    Set<String> getRegisteredNamespaceUris();
+	/**
+	 * Obtain the set of namespaces that are registered.
+	 *
+	 * @return the set of
+	 */
+	Set<String> getRegisteredNamespaceUris();
 
 }