jackrabbit-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ju...@apache.org
Subject svn commit: r293146 - in /incubator/jackrabbit/trunk/src: java/org/apache/jackrabbit/name/ test/org/apache/jackrabbit/name/
Date Sun, 02 Oct 2005 18:47:45 GMT
Author: jukka
Date: Sun Oct  2 11:47:16 2005
New Revision: 293146

URL: http://svn.apache.org/viewcvs?rev=293146&view=rev
Log:
JCR-73: Improved javadocs for o.a.j.name exceptions, QName, and NamespaceRegistry.
Removed the (unused) exception constructors that did not include an explicit error message.
Made the QName class final and the QName properties private to make the class truly immutable.

Modified:
    incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/IllegalNameException.java
    incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/MalformedPathException.java
    incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/NamespaceResolver.java
    incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/NoPrefixDeclaredException.java
    incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/QName.java
    incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/UnknownPrefixException.java
    incubator/jackrabbit/trunk/src/test/org/apache/jackrabbit/name/QNameTest.java

Modified: incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/IllegalNameException.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/IllegalNameException.java?rev=293146&r1=293145&r2=293146&view=diff
==============================================================================
--- incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/IllegalNameException.java
(original)
+++ incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/IllegalNameException.java
Sun Oct  2 11:47:16 2005
@@ -19,46 +19,35 @@
 import org.apache.jackrabbit.BaseException;
 
 /**
- * <code>IllegalNameException</code> ...
+ * Thrown when an illegal JCR name string is encountered. This exception is
+ * thrown when attempting to parse a JCR name string that does not match the
+ * JCR name syntax, or is otherwise not a legal name. Note that an
+ * {@link UnknownPrefixException} is thrown if the prefix of the JCR name
+ * string is syntactically valid but not bound to any namespace. 
+ * <p>
+ * See the section 4.6 of the JCR 1.0 specification for details of the
+ * JCR name syntax.
  */
 public class IllegalNameException extends BaseException {
-    /**
-     * Constructs a new instance of this class with <code>null</code> as its
-     * detail message.
-     */
-    public IllegalNameException() {
-        super();
-    }
 
     /**
-     * Constructs a new instance of this class with the specified detail
-     * message.
+     * Creates an IllegalNameException with the given error message.
      *
-     * @param message the detail message. The detail message is saved for
-     *                later retrieval by the {@link #getMessage()} method.
+     * @param message error message
      */
     public IllegalNameException(String message) {
         super(message);
     }
 
     /**
-     * Constructs a new instance of this class with the specified detail
-     * message and root cause.
+     * Creates an IllegalNameException with the given error message and
+     * root cause exception.
      *
-     * @param message   the detail message. The detail message is saved for
-     *                  later retrieval by the {@link #getMessage()} method.
-     * @param rootCause root failure cause
+     * @param message error message
+     * @param rootCause root cause exception
      */
     public IllegalNameException(String message, Throwable rootCause) {
         super(message, rootCause);
     }
 
-    /**
-     * Constructs a new instance of this class with the specified root cause.
-     *
-     * @param rootCause root failure cause
-     */
-    public IllegalNameException(Throwable rootCause) {
-        super(rootCause);
-    }
 }

Modified: incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/MalformedPathException.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/MalformedPathException.java?rev=293146&r1=293145&r2=293146&view=diff
==============================================================================
--- incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/MalformedPathException.java
(original)
+++ incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/MalformedPathException.java
Sun Oct  2 11:47:16 2005
@@ -19,46 +19,34 @@
 import org.apache.jackrabbit.BaseException;
 
 /**
- * <code>MalformedPathException</code> ...
+ * Thrown when a malformed JCR path string is encountered. This exception is
+ * thrown when attempting to parse a JCR path string that does not match the
+ * JCR patch syntax, contains an invalid path elements, or is otherwise not
+ * well formed.
+ * <p>
+ * See the section 4.6 of the JCR 1.0 specification for details of the
+ * JCR path syntax.
  */
 public class MalformedPathException extends BaseException {
-    /**
-     * Constructs a new instance of this class with <code>null</code> as its
-     * detail message.
-     */
-    public MalformedPathException() {
-        super();
-    }
 
     /**
-     * Constructs a new instance of this class with the specified detail
-     * message.
+     * Creates a MalformedPathException with the given error message.
      *
-     * @param message the detail message. The detail message is saved for
-     *                later retrieval by the {@link #getMessage()} method.
+     * @param message error message
      */
     public MalformedPathException(String message) {
         super(message);
     }
 
     /**
-     * Constructs a new instance of this class with the specified detail
-     * message and root cause.
+     * Creates a MalformedPathException with the given error message
+     * and root cause exception.
      *
-     * @param message   the detail message. The detail message is saved for
-     *                  later retrieval by the {@link #getMessage()} method.
-     * @param rootCause root failure cause
+     * @param message error message
+     * @param rootCause root cause exception
      */
     public MalformedPathException(String message, Throwable rootCause) {
         super(message, rootCause);
     }
 
-    /**
-     * Constructs a new instance of this class with the specified root cause.
-     *
-     * @param rootCause root failure cause
-     */
-    public MalformedPathException(Throwable rootCause) {
-        super(rootCause);
-    }
 }

Modified: incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/NamespaceResolver.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/NamespaceResolver.java?rev=293146&r1=293145&r2=293146&view=diff
==============================================================================
--- incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/NamespaceResolver.java
(original)
+++ incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/NamespaceResolver.java
Sun Oct  2 11:47:16 2005
@@ -19,25 +19,31 @@
 import javax.jcr.NamespaceException;
 
 /**
- * The <code>NamespaceResolver</code> interface ...
+ * Interface for resolving namespace URIs and prefixes. Unlike the JCR
+ * {@link javax.jcr.NamespaceRegistry} interface, this interface contains
+ * no functionality other than the basic namespace URI and prefix resolution
+ * methods. This interface is therefore used internally in many places where
+ * the full namespace registry is either not available or some other mechanism
+ * is used for resolving namespaces.
  */
 public interface NamespaceResolver {
 
     /**
      * Returns the URI to which the given prefix is mapped.
      *
-     * @param prefix a string
+     * @param prefix namespace prefix
      * @return the namespace URI to which the given prefix is mapped.
-     * @throws javax.jcr.NamespaceException if the prefix is unknown.
+     * @throws NamespaceException if the prefix is unknown.
      */
     String getURI(String prefix) throws NamespaceException;
 
     /**
      * Returns the prefix which is mapped to the given URI.
      *
-     * @param uri a string
+     * @param uri namespace URI
      * @return the prefix mapped to the given URI.
-     * @throws javax.jcr.NamespaceException if the URI is unknown.
+     * @throws NamespaceException if the URI is unknown.
      */
     String getPrefix(String uri) throws NamespaceException;
+
 }

Modified: incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/NoPrefixDeclaredException.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/NoPrefixDeclaredException.java?rev=293146&r1=293145&r2=293146&view=diff
==============================================================================
--- incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/NoPrefixDeclaredException.java
(original)
+++ incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/NoPrefixDeclaredException.java
Sun Oct  2 11:47:16 2005
@@ -19,46 +19,31 @@
 import org.apache.jackrabbit.BaseException;
 
 /**
- * The <code>NoPrefixDeclaredException</code> ...
+ * Thrown when the namespace prefix of a qualified name is not found. This
+ * exception is thrown when trying to convert a qualified name whose namespace
+ * prefix is not found into a JCR name string. The JCR name string can not be
+ * created without the namespace prefix.
  */
 public class NoPrefixDeclaredException extends BaseException {
-    /**
-     * Constructs a new instance of this class with <code>null</code> as its
-     * detail message.
-     */
-    public NoPrefixDeclaredException() {
-        super();
-    }
 
     /**
-     * Constructs a new instance of this class with the specified detail
-     * message.
+     * Creates a NoPrefixDeclaredException with the given error message.
      *
-     * @param message the detail message. The detail message is saved for
-     *                later retrieval by the {@link #getMessage()} method.
+     * @param message error message
      */
     public NoPrefixDeclaredException(String message) {
         super(message);
     }
 
     /**
-     * Constructs a new instance of this class with the specified detail
-     * message and root cause.
+     * Creates a NoPrefixDeclaredException with the given error message and
+     * root cause exception.
      *
-     * @param message   the detail message. The detail message is saved for
-     *                  later retrieval by the {@link #getMessage()} method.
-     * @param rootCause root failure cause
+     * @param message error message
+     * @param rootCause root cause exception
      */
     public NoPrefixDeclaredException(String message, Throwable rootCause) {
         super(message, rootCause);
     }
 
-    /**
-     * Constructs a new instance of this class with the specified root cause.
-     *
-     * @param rootCause root failure cause
-     */
-    public NoPrefixDeclaredException(Throwable rootCause) {
-        super(rootCause);
-    }
 }

Modified: incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/QName.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/QName.java?rev=293146&r1=293145&r2=293146&view=diff
==============================================================================
--- incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/QName.java (original)
+++ incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/QName.java Sun Oct  2 11:47:16
2005
@@ -25,50 +25,52 @@
 
 /**
  * Qualified name. A qualified name is a combination of a namespace URI
- * and a local part. Instances of this class are used by Jackrabbit to
- * represent the names of JCR content items and other objects.
- * <p/>
+ * and a local part. Instances of this class are used to internally represent
+ * the names of JCR content items and other objects within a content repository.
+ * <p>
  * A qualified name is immutable once created, although the prefixed JCR
  * name representation of the qualified name can change depending on the
  * namespace mappings in effect.
+ * <p>
+ * This class also contains a number of common namespace and qualified name
+ * constants for the namespaces and names specified by the JCR specification.
  *
  * <h2>String representations</h2>
  * <p>
  * The prefixed JCR name format of a qualified name is specified by
- * JSR 170 as follows:
+ * section 4.6 of the the JCR 1.0 specification (JSR 170) as follows:
  * <pre>
- *
- *  name ::= simplename | prefixedname
- *  simplename ::= onecharsimplename |
- *                 twocharsimplename |
- *                 threeormorecharname
- *  prefixedname ::= prefix ':' localname
- *  localname ::= onecharlocalname |
- *                twocharlocalname |
- *                threeormorecharname
- *  onecharsimplename ::= (* Any Unicode character except:
- *                     '.', '/', ':', '[', ']', '*',
- *                     ''', '"', '|' or any whitespace
- *                     character *)
- *  twocharsimplename ::= '.' onecharsimplename |
- *                        onecharsimplename '.' |
- *                        onecharsimplename onecharsimplename
- *  onecharlocalname ::= nonspace
- *  twocharlocalname ::= nonspace nonspace
- *  threeormorecharname ::= nonspace string nonspace
- *  prefix ::= (* Any valid XML Name *)
- *  string ::= char | string char
- *  char ::= nonspace | ' '
- *  nonspace ::= (* Any Unicode character except:
- *                  '/', ':', '[', ']', '*',
- *                  ''', '"', '|' or any whitespace
- *                  character *)
+ * name                ::= simplename | prefixedname
+ * simplename          ::= onecharsimplename |
+ *                         twocharsimplename |
+ *                         threeormorecharname
+ * prefixedname        ::= prefix ':' localname
+ * localname           ::= onecharlocalname |
+ *                         twocharlocalname |
+ *                         threeormorecharname
+ * onecharsimplename   ::= (* Any Unicode character except:
+ *                            '.', '/', ':', '[', ']', '*',
+ *                            ''', '"', '|' or any whitespace
+ *                            character *)
+ * twocharsimplename   ::= '.' onecharsimplename |
+ *                         onecharsimplename '.' |
+ *                         onecharsimplename onecharsimplename
+ * onecharlocalname    ::= nonspace
+ * twocharlocalname    ::= nonspace nonspace
+ * threeormorecharname ::= nonspace string nonspace
+ * prefix              ::= (* Any valid XML Name *)
+ * string              ::= char | string char
+ * char                ::= nonspace | ' '
+ * nonspace            ::= (* Any Unicode character except:
+ *                            '/', ':', '[', ']', '*',
+ *                            ''', '"', '|' or any whitespace
+ *                            character *)
  * </pre>
  * <p>
  * In addition to the prefixed JCR name format, a qualified name can also
  * be represented using the format "<code>{namespaceURI}localPart</code>".
  */
-public class QName implements Cloneable, Comparable, Serializable {
+public final class QName implements Cloneable, Comparable, Serializable {
 
     //------------------------------------------< namespace related constants >
 
@@ -542,10 +544,10 @@
     private transient String string;
 
     /** The internalized namespace URI of this qualified name. */
-    protected final String namespaceURI;
+    private final String namespaceURI;
 
     /** The internalized local part of this qualified name. */
-    protected final String localName;
+    private final String localName;
 
     /**
      * Creates a new qualified name with the given namespace URI and

Modified: incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/UnknownPrefixException.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/UnknownPrefixException.java?rev=293146&r1=293145&r2=293146&view=diff
==============================================================================
--- incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/UnknownPrefixException.java
(original)
+++ incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/name/UnknownPrefixException.java
Sun Oct  2 11:47:16 2005
@@ -19,46 +19,30 @@
 import org.apache.jackrabbit.BaseException;
 
 /**
- * The <code>UnknownPrefixException</code> ...
+ * Thrown when a JCR name string with an unknown prefix is encountered.
+ * This exception is thrown when attempting to parse a JCR name string
+ * whose prefix is not bound to any namespace.
  */
 public class UnknownPrefixException extends BaseException {
-    /**
-     * Constructs a new instance of this class with <code>null</code> as its
-     * detail message.
-     */
-    public UnknownPrefixException() {
-        super();
-    }
 
     /**
-     * Constructs a new instance of this class with the specified detail
-     * message.
+     * Creates an UnknownPrefixException with the given error message.
      *
-     * @param message the detail message. The detail message is saved for
-     *                later retrieval by the {@link #getMessage()} method.
+     * @param message error message
      */
     public UnknownPrefixException(String message) {
         super(message);
     }
 
     /**
-     * Constructs a new instance of this class with the specified detail
-     * message and root cause.
+     * Creates an IllegalNameException with the given error message and
+     * root cause exception.
      *
-     * @param message   the detail message. The detail message is saved for
-     *                  later retrieval by the {@link #getMessage()} method.
-     * @param rootCause root failure cause
+     * @param message error message
+     * @param rootCause root cause exception
      */
     public UnknownPrefixException(String message, Throwable rootCause) {
         super(message, rootCause);
     }
 
-    /**
-     * Constructs a new instance of this class with the specified root cause.
-     *
-     * @param rootCause root failure cause
-     */
-    public UnknownPrefixException(Throwable rootCause) {
-        super(rootCause);
-    }
 }

Modified: incubator/jackrabbit/trunk/src/test/org/apache/jackrabbit/name/QNameTest.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/src/test/org/apache/jackrabbit/name/QNameTest.java?rev=293146&r1=293145&r2=293146&view=diff
==============================================================================
--- incubator/jackrabbit/trunk/src/test/org/apache/jackrabbit/name/QNameTest.java (original)
+++ incubator/jackrabbit/trunk/src/test/org/apache/jackrabbit/name/QNameTest.java Sun Oct
 2 11:47:16 2005
@@ -86,8 +86,8 @@
                     if (!t.isValid()) {
                         fail("Should throw IllegalNameException: " + t.jcrName);
                     }
-                    assertEquals("\"" + t.jcrName + "\".uri", t.prefix, n.namespaceURI);
-                    assertEquals("\"" + t.jcrName + "\".localName", t.name, n.localName);
+                    assertEquals("\"" + t.jcrName + "\".uri", t.prefix, n.getNamespaceURI());
+                    assertEquals("\"" + t.jcrName + "\".localName", t.name, n.getLocalName());
                 } catch (IllegalNameException e) {
                     if (t.isValid()) {
                         throw e;



Mime
View raw message