Author: stefan
Date: Fri Jul 21 09:17:18 2006
New Revision: 424370
URL: http://svn.apache.org/viewvc?rev=424370&view=rev
Log:
improved javadoc and naming of private methods
Modified:
jackrabbit/trunk/jackrabbit/src/main/java/org/apache/jackrabbit/name/NameFormat.java
Modified:
jackrabbit/trunk/jackrabbit/src/main/java/org/apache/jackrabbit/name/NameFormat.java
URL:
http://svn.apache.org/viewvc/jackrabbit/trunk/jackrabbit/src/main/java/org/apache/jackrabbit/name/NameFormat.java?rev=424370&r1=424369&r2=424370&view=diff
==============================================================================
---
jackrabbit/trunk/jackrabbit/src/main/java/org/apache/jackrabbit/name/NameFormat.java
(original)
+++
jackrabbit/trunk/jackrabbit/src/main/java/org/apache/jackrabbit/name/NameFormat.java
Fri Jul 21 09:17:18 2006
@@ -23,15 +23,14 @@
import java.util.regex.Pattern;
/**
- * <code>NameFormat</code> formats a [EMAIL PROTECTED] QName} using a
- * [EMAIL PROTECTED] NamespaceResolver}.
+ * <code>NameFormat</code> provides methods for formatting and parsing names.
*/
public class NameFormat {
/**
- * The reqular expression pattern used to validate and parse
+ * The reqular expression pattern used to validate and doParse
* qualified names.
- * <p>
+ * <p/>
* The pattern contains the following groups:
* <ul>
* <li>group 1 is namespace prefix incl. delimiter (colon)
@@ -39,8 +38,7 @@
* <li>group 3 is localName
* </ul>
*/
- private static final Pattern NAME_PATTERN = Pattern.compile(
- "(([^ /:\\[\\]*'\"|](?:[^/:\\[\\]*'\"|]*[^ /:\\[\\]*'\"|])?):)?"
+ private static final Pattern NAME_PATTERN = Pattern.compile("(([^
/:\\[\\]*'\"|](?:[^/:\\[\\]*'\"|]*[^ /:\\[\\]*'\"|])?):)?"
+ "([^ /:\\[\\]*'\"|](?:[^/:\\[\\]*'\"|]*[^ /:\\[\\]*'\"|])?)");
/**
@@ -53,16 +51,19 @@
};
/**
- * Parses the <code>jcrName</code> and returns a new <code>QName</code>. If
- * the passed <code>resolver</code> also an instance of [EMAIL PROTECTED]
NameCache}
- * then the parsing is first read from the cache.
+ * Converts the <code>jcrName</code> to its corresponding
<code>QName</code>.
+ * If the <code>resolver</code> passed is also an instance of
+ * [EMAIL PROTECTED] NameCache} then this method first attempts to find the
+ * corresponding <code>QName</code> in the cache. If it cannot be found
then
+ * the <code>jcrName</code> is parsed and the corresponding
+ * <code>QName</code> constructed.
*
- * @param jcrName the name to be parsed
- * @param resolver <code>NamespaceResolver</code> use to retrieve the
- * namespace URI from the prefix contained in the given JCR name.
- * @return qName the new <code>QName</code>
+ * @param jcrName the JCR-style name to be parsed
+ * @param resolver <code>NamespaceResolver</code> used for resolving
+ * prefixes into namespace URIs
+ * @return the resulting <code>QName</code>
* @throws IllegalNameException If <code>jcrName</code> is not a valid
- * JCR-style name.
+ * JCR-style name.
*/
public static QName parse(String jcrName, NamespaceResolver resolver)
throws IllegalNameException, UnknownPrefixException {
@@ -70,143 +71,75 @@
if (resolver instanceof NameCache) {
QName name = ((NameCache) resolver).retrieveName(jcrName);
if (name == null) {
- name = parseNoCache(jcrName, resolver);
+ name = parseIgnoreCache(jcrName, resolver);
((NameCache) resolver).cacheName(jcrName, name);
}
return name;
} else {
- return parseNoCache(jcrName, resolver);
+ return parseIgnoreCache(jcrName, resolver);
}
}
/**
- * Parses an array of <code>jcrName</code> and returns the respective
- * array of <code>QName</code>. If the passed <code>resolver</code> also an
- * instance of [EMAIL PROTECTED] NameCache} then the parsing is first read
from the cache.
+ * Converts each JCR-style name in the passed array to its corresponding
+ * <code>QName</code> and returns the resulting <code>QName</code> array.
+ * If the <code>resolver</code> passed is also an instance of
+ * [EMAIL PROTECTED] NameCache} then this method first attempts to find the
+ * corresponding <code>QName</code> in the cache. If it cannot be found
then
+ * the <code>jcrName</code> is parsed and the corresponding
+ * <code>QName</code> constructed.
*
- * @param jcrNames the array of names to be parsed
- * @param resolver <code>NamespaceResolver</code> use to retrieve the
- * namespace URI from the prefix contained in the given JCR name.
- * @return the new array of <code>QName</code>
- * @throws IllegalNameException If <code>jcrName</code> is not a valid
- * JCR-style name.
+ * @param jcrNames the array of JCR-style names to be parsed
+ * @param resolver <code>NamespaceResolver</code> used for resolving
+ * prefixes into namespace URIs
+ * @return the resulting <code>QName</code> array
+ * @throws IllegalNameException If any of the passed names is not a valid
+ * JCR-style name.
*/
public static QName[] parse(String jcrNames[], NamespaceResolver resolver)
throws IllegalNameException, UnknownPrefixException {
QName[] ret = new QName[jcrNames.length];
if (resolver instanceof NameCache) {
- for (int i=0; i<ret.length; i++) {
+ for (int i = 0; i < ret.length; i++) {
QName name = ((NameCache) resolver).retrieveName(jcrNames[i]);
if (name == null) {
- name = parseNoCache(jcrNames[i], resolver);
+ name = parseIgnoreCache(jcrNames[i], resolver);
((NameCache) resolver).cacheName(jcrNames[i], name);
}
ret[i] = name;
}
} else {
- for (int i=0; i<ret.length; i++) {
- ret[i] = parseNoCache(jcrNames[i], resolver);
+ for (int i = 0; i < ret.length; i++) {
+ ret[i] = parseIgnoreCache(jcrNames[i], resolver);
}
}
return ret;
}
/**
- * Parses the <code>jcrName</code> and returns a new <code>QName</code>,
- * but does not respect possible caches.
- *
- * @param jcrName the name to be parsed
- * @param resolver <code>NamespaceResolver</code> use to retrieve the
- * namespace URI from the prefix contained in the given JCR name.
- * @return qName the new <code>QName</code>
- * @throws IllegalNameException If <code>jcrName</code> is not a valid
- * JCR-style name.
- */
- private static QName parseNoCache(String jcrName, NamespaceResolver
resolver)
- throws IllegalNameException, UnknownPrefixException {
- String[] parts = parse(jcrName);
- String uri;
- try {
- uri = resolver.getURI(parts[0]);
- } catch (NamespaceException nse) {
- throw new UnknownPrefixException(parts[0]);
- }
- return new QName(uri, parts[1]);
- }
-
- /**
- * Parses the <code>jcrName</code> and returns an array of two strings:
- * the first array element contains the prefix (or empty string),
- * the second the local name.
- *
- * @param jcrName the name to be parsed
- * @return An array holding two strings: the first array element contains
- * the prefix (or empty string), the second the local name.
- * @throws IllegalNameException If <code>jcrName</code> is not a valid
- * JCR-style name.
- */
- public static String[] parse(String jcrName) throws IllegalNameException {
- if (jcrName == null || jcrName.length() == 0) {
- throw new IllegalNameException("empty name");
- }
-
- if (".".equals(jcrName) || "..".equals(jcrName)) {
- // illegal syntax for name
- throw new IllegalNameException("'" + jcrName + "' is not a valid
name");
- }
-
- String prefix;
- String localName;
-
- Matcher matcher = (Matcher) NAME_MATCHER.get();
- matcher.reset(jcrName);
- if (matcher.matches()) {
- // check for prefix (group 1)
- if (matcher.group(1) != null) {
- // prefix specified
- // group 2 is namespace prefix excl. delimiter (colon)
- prefix = matcher.group(2);
- // check if the prefix is a valid XML prefix
- if (!XMLChar.isValidNCName(prefix)) {
- // illegal syntax for prefix
- throw new IllegalNameException("'" + jcrName
- + "' is not a valid name: illegal prefix");
- }
- } else {
- // no prefix specified
- prefix = "";
- }
-
- // group 3 is localName
- localName = matcher.group(3);
- } else {
- // illegal syntax for name
- throw new IllegalNameException("'" + jcrName + "' is not a valid
name");
- }
-
- return new String[] {prefix, localName};
-
- }
- /**
* Checks if <code>jcrName</code> is a valid JCR-style name.
*
* @param jcrName the name to be checked
* @throws IllegalNameException If <code>jcrName</code> is not a valid
- * JCR-style name.
+ * JCR-style name.
*/
public static void checkFormat(String jcrName) throws IllegalNameException
{
- parse(jcrName);
+ doParse(jcrName);
}
/**
- * Returns a string representation of the qualified <code>name</code> in
the
- * JCR name format. If the passed <code>resolver</code> also an instance of
- * [EMAIL PROTECTED] NameCache} then the formatting is first read from the
cache.
+ * Formats the given <code>QName</code> to produce a string representation,
+ * i.e. JCR-style name. If the <code>resolver</code> passed is also an
+ * instance of [EMAIL PROTECTED] NameCache} then this method first
attempts to find the
+ * corresponding JCR-style name in the cache. If it cannot be found then
+ * a new string representation is constructed.
*
- * @param qName the qualified name to resolve.
- * @param resolver the namespace resolver.
- * @return JCR the formatted path.
+ * @param qName the <code>QName</code> to format
+ * @param resolver <code>NamespaceResolver</code> used for resolving
+ * namespace URIs into prefixes
+ * @return the string representation (JCR-style name) of the given
+ * <code>QName</code>
* @throws NoPrefixDeclaredException if a namespace can not be resolved
* @see #format(QName, NamespaceResolver, StringBuffer)
*/
@@ -217,7 +150,7 @@
String jcrName = ((NameCache) resolver).retrieveName(qName);
if (jcrName == null) {
StringBuffer buf = new StringBuffer();
- formatNoCache(qName, resolver, buf);
+ formatIgnoreCache(qName, resolver, buf);
jcrName = buf.toString();
((NameCache) resolver).cacheName(jcrName, qName);
}
@@ -225,41 +158,41 @@
} else {
StringBuffer buf = new StringBuffer();
- formatNoCache(qName, resolver, buf);
+ formatIgnoreCache(qName, resolver, buf);
return buf.toString();
}
}
/**
- * Optimized convenience method that returns an array of string
- * representations of the given qualified <code>name</code> in the JCR name
- * format. If the passed <code>resolver</code> also an instance of
- * [EMAIL PROTECTED] NameCache} then the formatting is first read from the
cache.
+ * Same as [EMAIL PROTECTED] #format(QName, NamespaceResolver)} except
that this
+ * method takes an array of <code>QName</code>s and returns an array of
+ * corresponding string representations.
*
- * @param qNames the array of qualified name to resolve.
- * @param resolver the namespace resolver.
- * @return the array of jcr names
+ * @param qNames the array <code>QName</code>s to format
+ * @param resolver <code>NamespaceResolver</code> used for resolving
+ * namespace URIs into prefixes
+ * @return the array of corresponding string representations
* @throws NoPrefixDeclaredException if a namespace can not be resolved
- * @see #format(QName, NamespaceResolver, StringBuffer)
+ * @see #format(QName, NamespaceResolver)
*/
public static String[] format(QName[] qNames, NamespaceResolver resolver)
throws NoPrefixDeclaredException {
String[] ret = new String[qNames.length];
if (resolver instanceof NameCache) {
- for (int i=0; i<ret.length; i++) {
+ for (int i = 0; i < ret.length; i++) {
String jcrName = ((NameCache)
resolver).retrieveName(qNames[i]);
if (jcrName == null) {
StringBuffer buf = new StringBuffer();
- formatNoCache(qNames[i], resolver, buf);
+ formatIgnoreCache(qNames[i], resolver, buf);
jcrName = buf.toString();
((NameCache) resolver).cacheName(jcrName, qNames[i]);
}
ret[i] = jcrName;
}
} else {
- for (int i=0; i<ret.length; i++) {
+ for (int i = 0; i < ret.length; i++) {
StringBuffer buf = new StringBuffer();
- formatNoCache(qNames[i], resolver, buf);
+ formatIgnoreCache(qNames[i], resolver, buf);
ret[i] = buf.toString();
}
}
@@ -267,45 +200,136 @@
}
/**
- * Returns a string representation of the qualified <code>name</code> in
the
- * JCR name format. If the passed <code>resolver</code> also an instance of
- * [EMAIL PROTECTED] NameCache} then the formatting is first read from the
cache.
+ * Same as [EMAIL PROTECTED] #format(QName, NamespaceResolver)} except
that this
+ * method appends the JCR-style name to the given <code>buffer</code>
rather
+ * than returning it directly.
*
- * @param qName the qualified name to resolve.
- * @param resolver the namespace resolver.
- * @param buffer StringBuffer where the prefixed JCR name should be
appended to.
+ * @param qName the <code>QName</code> to format
+ * @param resolver <code>NamespaceResolver</code> used for resolving
+ * namespace URIs into prefixes
+ * @param buffer StringBuffer where the string representation should be
+ * appended to
* @throws NoPrefixDeclaredException if a namespace can not be resolved
- * @see #format(QName, NamespaceResolver)
*/
- public static void format(QName qName, NamespaceResolver resolver,
StringBuffer buffer)
+ public static void format(QName qName, NamespaceResolver resolver,
+ StringBuffer buffer)
throws NoPrefixDeclaredException {
if (resolver instanceof NameCache) {
String jcrName = ((NameCache) resolver).retrieveName(qName);
if (jcrName == null) {
int l = buffer.length();
- formatNoCache(qName, resolver, buffer);
+ formatIgnoreCache(qName, resolver, buffer);
((NameCache) resolver).cacheName(buffer.substring(l), qName);
} else {
buffer.append(jcrName);
}
} else {
- formatNoCache(qName, resolver, buffer);
+ formatIgnoreCache(qName, resolver, buffer);
}
}
+ //-------------------------------------------------------< implementation >
/**
- * Returns a string representation of the qualified <code>name</code> in
the
- * JCR name format, but does not respect possible caches.
+ * Converts the <code>jcrName</code> to its corresponding
<code>QName</code>.
+ * <p/>
+ * Note that unlike [EMAIL PROTECTED] #parse(String, NamespaceResolver)}
this method
+ * always constructs a new <code>QName</code>, ignoring potential caching
+ * capabilities of the passed <code>resolver</code>.
*
- * @param qName the qualified name to resolve.
- * @param resolver the namespace resolver.
- * @param buffer StringBuffer where the prefixed JCR name should be
appended to.
- * @throws NoPrefixDeclaredException if a namespace can not be resolved
+ * @param jcrName the JCR-style name to be parsed
+ * @param resolver <code>NamespaceResolver</code> used for resolving
+ * prefixes into namespace URIs
+ * @return the resulting <code>QName</code>
+ * @throws IllegalNameException If <code>jcrName</code> is not a valid
+ * JCR-style name.
+ * @see #parse(String, NamespaceResolver)
+ */
+ private static QName parseIgnoreCache(String jcrName,
+ NamespaceResolver resolver)
+ throws IllegalNameException, UnknownPrefixException {
+ String[] parts = doParse(jcrName);
+ String uri;
+ try {
+ uri = resolver.getURI(parts[0]);
+ } catch (NamespaceException nse) {
+ throw new UnknownPrefixException(parts[0]);
+ }
+ return new QName(uri, parts[1]);
+ }
+
+ /**
+ * Parses the <code>jcrName</code> and returns an array of two strings:
+ * the first array element contains the prefix (or empty string),
+ * the second the local name.
+ *
+ * @param jcrName the name to be parsed
+ * @return An array holding two strings: the first array element contains
+ * the prefix (or empty string), the second the local name.
+ * @throws IllegalNameException If <code>jcrName</code> is not a valid
+ * JCR-style name.
+ */
+ private static String[] doParse(String jcrName) throws
IllegalNameException {
+ if (jcrName == null || jcrName.length() == 0) {
+ throw new IllegalNameException("empty name");
+ }
+
+ if (".".equals(jcrName) || "..".equals(jcrName)) {
+ // illegal syntax for name
+ throw new IllegalNameException("'" + jcrName + "' is not a valid
name");
+ }
+
+ String prefix;
+ String localName;
+
+ Matcher matcher = (Matcher) NAME_MATCHER.get();
+ matcher.reset(jcrName);
+ if (matcher.matches()) {
+ // check for prefix (group 1)
+ if (matcher.group(1) != null) {
+ // prefix specified
+ // group 2 is namespace prefix excl. delimiter (colon)
+ prefix = matcher.group(2);
+ // check if the prefix is a valid XML prefix
+ if (!XMLChar.isValidNCName(prefix)) {
+ // illegal syntax for prefix
+ throw new IllegalNameException("'" + jcrName
+ + "' is not a valid name: illegal prefix");
+ }
+ } else {
+ // no prefix specified
+ prefix = "";
+ }
+
+ // group 3 is localName
+ localName = matcher.group(3);
+ } else {
+ // illegal syntax for name
+ throw new IllegalNameException("'" + jcrName + "' is not a valid
name");
+ }
+
+ return new String[]{prefix, localName};
+ }
+
+ /**
+ * Formats the given <code>QName</code> to produce a string representation,
+ * i.e. JCR-style name.
+ * <p/>
+ * Note that unlike [EMAIL PROTECTED] #format(QName, NamespaceResolver)}
this method
+ * always constructs a new <code>String</code>, ignoring potential caching
+ * capabilities of the passed <code>resolver</code>.
*
+ * @param qName the <code>QName</code> to format
+ * @param resolver <code>NamespaceResolver</code> used for resolving
+ * namespace URIs into prefixes
+ * @param buffer StringBuffer where the prefixed JCR name should be
+ * appended to
+ * @throws NoPrefixDeclaredException if a namespace can not be resolved
* @see #format(QName, NamespaceResolver)
*/
- private static void formatNoCache(QName qName, NamespaceResolver resolver,
StringBuffer buffer)
+ private static void formatIgnoreCache(QName qName,
+ NamespaceResolver resolver,
+ StringBuffer buffer)
throws NoPrefixDeclaredException {
// prefix
String prefix;
@@ -313,7 +337,7 @@
prefix = resolver.getPrefix(qName.getNamespaceURI());
} catch (NamespaceException nse) {
throw new NoPrefixDeclaredException("no prefix declared for URI: "
- + qName.getNamespaceURI());
+ + qName.getNamespaceURI());
}
if (prefix.length() == 0) {
// default prefix (empty string)
