You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jackrabbit.apache.org by ju...@apache.org on 2005/04/01 18:36:48 UTC
svn commit: r159705 -
incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/QName.java
Author: jukka
Date: Fri Apr 1 08:36:47 2005
New Revision: 159705
URL: http://svn.apache.org/viewcvs?view=rev&rev=159705
Log:
JCR-73: Improved QName javadocs
Modified:
incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/QName.java
Modified: incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/QName.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/QName.java?view=diff&r1=159704&r2=159705
==============================================================================
--- incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/QName.java (original)
+++ incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/QName.java Fri Apr 1 08:36:47 2005
@@ -24,11 +24,19 @@
import java.util.regex.Pattern;
/**
- * <code>QName</code> represents the qualified name of a repository item
- * (i.e. <code>Node</code> or <code>Property</code>) or a node type.
- * <p/>
- * The external string representation is specified as follows:
- * <xmp>
+ * 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>
+ * 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.
+ *
+ * <h2>String representations</h2>
+ * <p>
+ * The prefixed JCR name format of a qualified name is specified by
+ * JSR 170 as follows:
+ * <pre>
* name ::= [prefix ':'] simplename
* prefix ::= << Any valid XML Name >>
* simplename ::= nonspacestring [[string] nonspacestring]
@@ -41,36 +49,49 @@
* '''(the single quote),
* '"'(the double quote),
* any whitespace character >>
- * </xmp>
+ * </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 {
+ /** Serialization UID of this class. */
static final long serialVersionUID = -2712313010017755368L;
/**
- * Pattern used to validate and parse name:<p>
+ * The reqular expression pattern used to validate and parse
+ * qualified names.
+ * <p>
+ * The pattern contains the following groups:
* <ul>
* <li>group 1 is namespace prefix incl. delimiter (colon)
* <li>group 2 is namespace prefix excl. delimiter (colon)
* <li>group 3 is localName
* </ul>
*/
- private static final Pattern NAME_PATTERN =
- Pattern.compile("(([^ /:\\[\\]*'\"|](?:[^/:\\[\\]*'\"|]*[^ /:\\[\\]*'\"|])?):)?([^ /:\\[\\]*'\"|](?:[^/:\\[\\]*'\"|]*[^ /:\\[\\]*'\"|])?)");
+ private static final Pattern NAME_PATTERN = Pattern.compile(
+ "(([^ /:\\[\\]*'\"|](?:[^/:\\[\\]*'\"|]*[^ /:\\[\\]*'\"|])?):)?"
+ + "([^ /:\\[\\]*'\"|](?:[^/:\\[\\]*'\"|]*[^ /:\\[\\]*'\"|])?)");
+ /** The memorized hash code of this qualified name. */
private transient int hash;
+
+ /** The memorized string representation of this qualified name. */
private transient String string;
+ /** The namespace URI of this qualified name. */
protected final String namespaceURI;
- protected final String localName;
+ /** The local part of this qualified name. */
+ protected final String localName;
/**
- * Creates a new <code>QName</code> instance with the given <code>namespaceURI</code>
- * and <code>localName</code>.
+ * Creates a new qualified name with the given namespace URI and
+ * local part.
*
- * @param namespaceURI
- * @param localName
+ * @param namespaceURI namespace uri
+ * @param localName local part
*/
public QName(String namespaceURI, String localName) {
if (namespaceURI == null) {
@@ -86,12 +107,16 @@
}
//------------------------------------------------------< factory methods >
+
/**
- * @param rawName
- * @param resolver
- * @return
- * @throws IllegalNameException
- * @throws UnknownPrefixException
+ * Parses the given prefixed JCR name into a qualified name using the
+ * given namespace resolver.
+ *
+ * @param rawName prefixed JCR name
+ * @param resolver namespace resolver
+ * @return qualified name
+ * @throws IllegalNameException if the given name is not a valid JCR name
+ * @throws UnknownPrefixException if the JCR name prefix does not resolve
*/
public static QName fromJCRName(String rawName, NamespaceResolver resolver)
throws IllegalNameException, UnknownPrefixException {
@@ -131,7 +156,7 @@
* as a <code>QName</code>.
* @see #toString()
*/
- public static QName valueOf(String s) {
+ public static QName valueOf(String s) throws IllegalArgumentException {
if ("".equals(s) || s == null) {
throw new IllegalArgumentException("invalid QName literal");
}
@@ -218,23 +243,31 @@
//-------------------------------------------------------< public methods >
/**
- * @return
+ * Returns the local part of the qualified name.
+ *
+ * @return local name
*/
public String getLocalName() {
return localName;
}
/**
- * @return
+ * Returns the namespace URI of the qualified name.
+ *
+ * @return namespace URI
*/
public String getNamespaceURI() {
return namespaceURI;
}
/**
- * @param resolver
- * @return
- * @throws NoPrefixDeclaredException
+ * Returns the qualified name in the prefixed JCR name format.
+ * The namespace URI is mapped to a prefix using the given
+ * namespace resolver.
+ *
+ * @param resolver namespace resolver
+ * @return prefixed name
+ * @throws NoPrefixDeclaredException if the namespace fails to resolve
*/
public String toJCRName(NamespaceResolver resolver) throws NoPrefixDeclaredException {
StringBuffer sb = new StringBuffer();
@@ -273,6 +306,16 @@
return string;
}
+ /**
+ * Compares two qualified names for equality. Returns <code>true</code>
+ * if the given object is a qualified name and has the same namespace URI
+ * and local part as this qualified name.
+ *
+ * @param obj the object to compare this qualified name with
+ * @return <code>true</code> if the object is equal to this qualified name,
+ * <code>false</code> otherwise
+ * @see Object#equals(Object)
+ */
public boolean equals(Object obj) {
if (this == obj) {
return true;
@@ -285,6 +328,14 @@
return false;
}
+ /**
+ * Returns the hash code of this qualified name. The hash code is
+ * computed from the namespace URI and local part of the qualified
+ * name and memorized for better performance.
+ *
+ * @return hash code
+ * @see Object#hashCode()
+ */
public int hashCode() {
// QName is immutable, we can store the computed hash code value
int h = hash;
@@ -298,18 +349,27 @@
}
/**
- * Creates a clone of this <code>QName</code>.
+ * Creates a clone of this qualified name.
* Overriden in order to make <code>clone()</code> public.
*
* @return a clone of this instance
- * @throws CloneNotSupportedException
+ * @throws CloneNotSupportedException never thrown
+ * @see Object#clone()
*/
public Object clone() throws CloneNotSupportedException {
// QName is immutable, no special handling required
return super.clone();
}
- public int compareTo(Object o) {
+ /**
+ * Compares two qualified names.
+ *
+ * @param o the object to compare this qualified name with
+ * @return comparison result
+ * @throws ClassCastException if the given object is not a qualified name
+ * @see Comparable#compareTo(Object)
+ */
+ public int compareTo(Object o) throws ClassCastException {
return toString().compareTo(((QName) o).toString());
}