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/05/08 23:50:58 UTC
svn commit: r169173 - in
/incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name:
Name.java Path.java PathBuilder.java PathElement.java PathParser.java
Author: jukka
Date: Sun May 8 14:50:56 2005
New Revision: 169173
URL: http://svn.apache.org/viewcvs?rev=169173&view=rev
Log:
JCR-EXT: Added javadocs.
Modified:
incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Name.java
incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Path.java
incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathBuilder.java
incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathElement.java
incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathParser.java
Modified: incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Name.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Name.java?rev=169173&r1=169172&r2=169173&view=diff
==============================================================================
--- incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Name.java (original)
+++ incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Name.java Sun May 8 14:50:56 2005
@@ -106,7 +106,17 @@
return "{" + namespaceURI + "}" + localPart;
}
- public static Name parseJCRName(Session session, String name)
+ /**
+ * Parses the given prefixed JCR name into a qualified name instance.
+ * The namespace prefix is resolved using the current session.
+ *
+ * @param session current session
+ * @param name prefixed JCR name
+ * @return qualified name
+ * @throws NamespaceException if the namespace prefix is not registered
+ * @throws RepositoryException if another error occurs
+ */
+ public static Name fromJCRName(Session session, String name)
throws NamespaceException, RepositoryException {
int p = name.indexOf(':');
if (p != -1) {
@@ -118,6 +128,15 @@
}
}
+ /**
+ * Returns the prefixed JCR name representation of the qualified name.
+ * The namespace prefix is retrieved from the current session.
+ *
+ * @param session current session
+ * @return prefixed JCR name
+ * @throws NamespaceException if the namespace URI is not registered
+ * @throws RepositoryException if another error occurs
+ */
public String toJCRName(Session session)
throws NamespaceException, RepositoryException {
String prefix = session.getNamespacePrefix(namespaceURI);
Modified: incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Path.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Path.java?rev=169173&r1=169172&r2=169173&view=diff
==============================================================================
--- incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Path.java (original)
+++ incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/Path.java Sun May 8 14:50:56 2005
@@ -21,14 +21,43 @@
import javax.jcr.RepositoryException;
import javax.jcr.Session;
+/**
+ * Content path. Instances of this class are used to represent item paths
+ * within a JCR content repository.
+ * <p>
+ * A path instance consists of a sequence of path elements, that are
+ * resolved one by one in the specified order to reach the target item from
+ * a given context item.
+ * <p>
+ * Once created, a path instance is immutable.
+ *
+ * @see PathElement
+ * @see PathParser
+ * @see PathBuilder
+ */
public final class Path {
+ /** Path elements */
private final PathElement[] elements;
+ /**
+ * Creates a path instance that contains the given path elements.
+ *
+ * @param elements path elements
+ */
Path(PathElement[] elements) {
this.elements = elements;
}
+ /**
+ * Resolves this path starting from the given context item. Returns
+ * the result of the path resolution.
+ *
+ * @param item the context item from which to resolve this path
+ * @return the resolved target item
+ * @throws PathNotFoundException if the path can not be resolved
+ * @throws RepositoryException if another error occurs
+ */
public Item resolve(Item item)
throws PathNotFoundException, RepositoryException {
for (int i = 0; i < elements.length; i++) {
@@ -37,11 +66,34 @@
return item;
}
+ /**
+ * Parses the given JCR path string. Namespace prefixes within the path
+ * are resolved using the current session.
+ *
+ * @param session current session
+ * @param path JCR path
+ * @return path instance
+ * @throws IllegalArgumentException if the given path is invalid
+ * @throws RepositoryException if another error occurs
+ * @see PathParser
+ */
public static Path parse(Session session, String path)
throws IllegalArgumentException, RepositoryException {
return new PathParser(session).parsePath(path);
}
+ /**
+ * Resolves the given JCR path from the given context item. Returns
+ * the result of the path resolution. Namespace prefixes within the path
+ * are resolved using the session associated with the context item.
+ *
+ * @param item context item
+ * @param path JCR path
+ * @return target item
+ * @throws IllegalArgumentException if the given path is invalid
+ * @throws PathNotFoundException if the given path can not be resolved
+ * @throws RepositoryException if another error occurs
+ */
public static Item resolve(Item item, String path)
throws IllegalArgumentException, PathNotFoundException,
RepositoryException {
Modified: incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathBuilder.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathBuilder.java?rev=169173&r1=169172&r2=169173&view=diff
==============================================================================
--- incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathBuilder.java (original)
+++ incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathBuilder.java Sun May 8 14:50:56 2005
@@ -19,18 +19,39 @@
import java.util.List;
import java.util.Vector;
+/**
+ * Content path builder. This utility class uses the Builder design
+ * pattern (GoF) to provide a simple mechanism for converting a sequence
+ * of path elements into a path instance.
+ *
+ * @see PathParser
+ */
final class PathBuilder {
+ /** Path element list. Grows as more elements are added. */
private final List elements;
+ /**
+ * Creates a path builder instance.
+ */
public PathBuilder() {
elements = new Vector();
}
+ /**
+ * Adds an element to the path being built.
+ *
+ * @param element path element
+ */
public void addElement(PathElement element) {
elements.add(element);
}
+ /**
+ * Creates a path instance from the collected sequence of path elements.
+ *
+ * @return path instance
+ */
public Path getPath() {
return new Path((PathElement[])
elements.toArray(new PathElement[elements.size()]));
Modified: incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathElement.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathElement.java?rev=169173&r1=169172&r2=169173&view=diff
==============================================================================
--- incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathElement.java (original)
+++ incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathElement.java Sun May 8 14:50:56 2005
@@ -34,8 +34,8 @@
* Resolves this path element within the context of the given content
* item. Retuns the result of the path element resolution.
*
- * @param item the context from which to resolve this path element
- * @return the resolved content item
+ * @param item the context item from which to resolve this path element
+ * @return the resolved target item
* @throws PathNotFoundException if the path element could not be resolved
* @throws RepositoryException if another error occurred
*/
Modified: incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathParser.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathParser.java?rev=169173&r1=169172&r2=169173&view=diff
==============================================================================
--- incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathParser.java (original)
+++ incubator/jackrabbit/trunk/contrib/jcr-ext/src/java/org/apache/jackrabbit/name/PathParser.java Sun May 8 14:50:56 2005
@@ -23,16 +23,22 @@
import javax.jcr.RepositoryException;
import javax.jcr.Session;
-final class PathParser {
+/**
+ * JCR content path parser. Instances of this class are used to parse
+ * JCR content path strings into resolvable path instances. A path parser
+ * instance is always associated with a given session that is used to
+ * resolve namespace prefixes within the parsed paths.
+ */
+public final class PathParser {
/**
- * Pattern used to validate and parse path elements:<p>
+ * Pattern used to validate and parse path elements.
* <ul>
- * <li>group 1 is .
- * <li>group 2 is ..
- * <li>group 3 is namespace prefix excl. delimiter (colon)
- * <li>group 4 is localName
- * <li>group 5 is index excl. brackets
+ * <li>group 1 is . (matches the full string)
+ * <li>group 2 is .. (matches the full string)
+ * <li>group 3 is the optional namespace prefix (without the colon)
+ * <li>group 4 is the local part of the JCR name
+ * <li>group 5 is the optional index (without the brackets)
* </ul>
*/
private static final Pattern PATH_ELEMENT_PATTERN = Pattern.compile(
@@ -41,38 +47,60 @@
+ "([^ /:\\[\\]*'\"|](?:[^/:\\[\\]*'\"|]*[^ /:\\[\\]*'\"|])?)"
+ "(?:\\[([1-9]\\d*)\\])?");
+ /** Current session. Used to resolve namespace prefixes. */
private final Session session;
+ /**
+ * Creates a path parser for the given session.
+ *
+ * @param session current session
+ */
public PathParser(Session session) {
this.session = session;
}
+ /**
+ * Parses the given JCR content path.
+ *
+ * @param path JCR content path
+ * @return path instance
+ * @throws IllegalArgumentException if the given path is invalid
+ * @throws RepositoryException if another error occurs
+ */
public Path parsePath(String path)
throws IllegalArgumentException, RepositoryException {
PathBuilder builder = new PathBuilder();
-
int p = path.indexOf('/');
- if (p == 0) {
+
+ if (p == 0) { // Check for an absolute path with a leading slash
builder.addElement(new RootElement());
path = path.substring(1);
p = path.indexOf('/');
}
while (p != -1) {
- if (p > 0) {
+ if (p > 0) { // Ignore empty path elements
builder.addElement(parsePathElement(path.substring(0, p)));
}
path = path.substring(p + 1);
p = path.indexOf('/');
}
- if (path.length() > 0) {
+ if (path.length() > 0) { // Ignore empty trailing path elements
builder.addElement(parsePathElement(path));
}
return builder.getPath();
}
+ /**
+ * Parses the given path element.
+ *
+ * @param element path element
+ * @return path element instance
+ * @throws IllegalArgumentException if the given path element is invalid
+ * @throws RepositoryException if another error occurs
+ */
private PathElement parsePathElement(String element)
throws IllegalArgumentException, RepositoryException {
Matcher matcher = PATH_ELEMENT_PATTERN.matcher(element);