method documentation

fcrepo · May 10, 2013 · 7258a21 · 7258a21
1 parent a7991ba
commit 7258a21
Show file tree

Hide file tree

Showing 4 changed files with 89 additions and 13 deletions.
diff --git a/fcrepo-kernel/src/main/java/org/fcrepo/utils/FedoraTypesUtils.java b/fcrepo-kernel/src/main/java/org/fcrepo/utils/FedoraTypesUtils.java
@@ -6,6 +6,7 @@
 import static com.google.common.collect.ImmutableSet.copyOf;
 import static org.fcrepo.utils.FedoraJcrTypes.FEDORA_DATASTREAM;
 import static org.fcrepo.utils.FedoraJcrTypes.FEDORA_OBJECT;
+import static org.fcrepo.utils.FedoraJcrTypes.FEDORA_RESOURCE;
 import static org.fcrepo.utils.JcrRdfTools.getRDFNamespaceForJcrNamespace;
 
 import java.io.InputStream;
@@ -155,6 +156,9 @@ public org.modeshape.jcr.api.NamespaceRegistry apply(final Node n) {
 
             };
 
+    /**
+     * Map a JCR property to an RDF property with the right namespace URI and local name
+     */
     public static Function<Property, com.hp.hpl.jena.rdf.model.Property> getPredicateForProperty = new Function<Property,com.hp.hpl.jena.rdf.model.Property>() {
         @Override
         public com.hp.hpl.jena.rdf.model.Property apply(final Property property) {
@@ -211,12 +215,13 @@ public static Binary getBinary(final Node n, final InputStream i, final Strategy
 
     /**
      * Get the property definition information (containing type and multi-value information)
-     * @param propertyName
-     * @return
+     * @param node the node to use for inferring the property definition
+     * @param propertyName the property name to retrieve a definition for
+     * @return a JCR PropertyDefinition, if available, or null
      * @throws javax.jcr.RepositoryException
      */
     public static PropertyDefinition getDefinitionForPropertyName(final Node node, final String propertyName) throws RepositoryException {
-        final PropertyDefinition[] propertyDefinitions = node.getSession().getWorkspace().getNodeTypeManager().getNodeType("fedora:resource").getPropertyDefinitions();
+        final PropertyDefinition[] propertyDefinitions = node.getSession().getWorkspace().getNodeTypeManager().getNodeType(FEDORA_RESOURCE).getPropertyDefinitions();
 
         for (PropertyDefinition p : propertyDefinitions) {
             if (p.getName().equals(propertyName)) {

diff --git a/fcrepo-kernel/src/main/java/org/fcrepo/utils/JcrPropertyStatementListener.java b/fcrepo-kernel/src/main/java/org/fcrepo/utils/JcrPropertyStatementListener.java
@@ -96,6 +96,10 @@ private boolean validateModificationsForPropertyName(String propertyName) {
         return true;
     }
 
+    /**
+     * Get a list of any problems from trying to apply the statement changes to the node's properties
+     * @return
+     */
 	public Problems getProblems() {
 		return problems;
 	}

diff --git a/fcrepo-kernel/src/main/java/org/fcrepo/utils/JcrRdfTools.java b/fcrepo-kernel/src/main/java/org/fcrepo/utils/JcrRdfTools.java
@@ -31,6 +31,11 @@ public abstract class JcrRdfTools {
 
     public static BiMap<String, String> rdfNamespacesToJcrNamespaces = jcrNamespacesToRDFNamespaces.inverse();
 
+    /**
+     * Convert a Fedora RDF Namespace into its JCR equivalent
+     * @param rdfNamespaceUri a namespace from an RDF document
+     * @return the JCR namespace, or the RDF namespace if no matching JCR namespace is found
+     */
     public static String getJcrNamespaceForRDFNamespace(final String rdfNamespaceUri) {
         if (rdfNamespacesToJcrNamespaces.containsKey(rdfNamespaceUri)) {
             return rdfNamespacesToJcrNamespaces.get(rdfNamespaceUri);
@@ -39,6 +44,11 @@ public static String getJcrNamespaceForRDFNamespace(final String rdfNamespaceUri
         }
     }
 
+    /**
+     * Convert a JCR namespace into an RDF namespace fit for downstream consumption
+     * @param jcrNamespaceUri a namespace from the JCR NamespaceRegistry
+     * @return an RDF namespace for downstream consumption.
+     */
     public static String getRDFNamespaceForJcrNamespace(final String jcrNamespaceUri) {
         if (jcrNamespacesToRDFNamespaces.containsKey(jcrNamespaceUri)) {
             return jcrNamespacesToRDFNamespaces.get(jcrNamespaceUri);
@@ -48,12 +58,13 @@ public static String getRDFNamespaceForJcrNamespace(final String jcrNamespaceUri
     }
 
     /**
-     * Create a JCR value from our object data. Presumably we could infer type information from the RDFNode?
+     * Create a JCR value from an RDFNode, either by using the given JCR PropertyType or
+     * by looking at the RDFNode Datatype
      *
-     * @param data
-     * @param type
+     * @param data an RDF Node (possibly with a DataType)
+     * @param type a JCR PropertyType value
      *
-     * @return
+     * @return a JCR Value
      *
      * @throws javax.jcr.RepositoryException
      */
@@ -99,6 +110,14 @@ public static Value createValue(final Node node, final RDFNode data, final int t
         }
     }
 
+    /**
+     * Add a JCR property to the given RDF Model (with the given subject)
+     * @param subject the RDF subject to use in the assertions
+     * @param model the RDF graph to insert the triple into
+     * @param property the JCR property (multivalued or not) to convert to triples
+     *
+     * @throws RepositoryException
+     */
     public static void addPropertyToModel(final Resource subject, final Model model, final Property property) throws RepositoryException {
         if (property.isMultiple()) {
             final Value[] values = property.getValues();
@@ -113,6 +132,15 @@ public static void addPropertyToModel(final Resource subject, final Model model,
     }
 
 
+    /**
+     * Add a JCR property to the given RDF Model (with the given subject)
+     *
+     * @param subject the RDF subject to use in the assertions
+     * @param model the RDF graph to insert the triple into
+     * @param property the JCR property (multivalued or not) to convert to triples
+     * @param v the actual JCR Value to insert into the graph
+     * @throws RepositoryException
+     */
     public static void addPropertyToModel(final Resource subject, final Model model, final Property property, Value v) throws RepositoryException {
 
         final com.hp.hpl.jena.rdf.model.Property predicate = FedoraTypesUtils.getPredicateForProperty.apply(property);
@@ -160,8 +188,10 @@ public static void addPropertyToModel(final Resource subject, final Model model,
 
     /**
      * Given an RDF predicate value (namespace URI + local name), figure out what JCR property to use
-     * @param predicate
-     * @return
+     * @param node the JCR node we want a property for
+     * @param predicate the predicate to map to a property name
+     *
+     * @return the JCR property name
      * @throws RepositoryException
      */
     public static String getPropertyNameFromPredicate(final Node node, final com.hp.hpl.jena.rdf.model.Property predicate) throws RepositoryException {
@@ -172,6 +202,8 @@ public static String getPropertyNameFromPredicate(final Node node, final com.hp.
 
         final NamespaceRegistry namespaceRegistry = FedoraTypesUtils.getNamespaceRegistry.apply(node);
 
+        assert(namespaceRegistry != null);
+
         if (namespaceRegistry.isRegisteredUri(namespace)) {
             prefix = namespaceRegistry.getPrefix(namespace);
         } else {
@@ -190,12 +222,12 @@ public static String getPropertyNameFromPredicate(final Node node, final com.hp.
 
     /**
      * Strip our silly "namespace" stuff from the object
-     * @param node
-     * @param path
-     * @return
+     * @param node an existing JCR node
+     * @param path the RDF URI to look up
+     * @return the JCR node at the given RDF path
      * @throws RepositoryException
      */
-    public static Node getNodeFromObjectPath(final Node node, final String path) throws RepositoryException {
+    private static Node getNodeFromObjectPath(final Node node, final String path) throws RepositoryException {
         return node.getSession().getNode(path.substring("info:fedora".length()));
     }
 }
diff --git a/fcrepo-kernel/src/main/java/org/fcrepo/utils/NodePropertiesTools.java b/fcrepo-kernel/src/main/java/org/fcrepo/utils/NodePropertiesTools.java
@@ -18,6 +18,15 @@ public abstract class NodePropertiesTools {
 
     private static final Logger logger = getLogger(NodePropertiesTools.class);
 
+    /**
+     * Given a JCR node, property and value, either:
+     *  - if the property is single-valued, replace the existing property with the new value
+     *  - if the property is multivalued, append the new value to the property
+     * @param node the JCR node
+     * @param propertyName a name of a JCR property (either pre-existing or otherwise)
+     * @param newValue the JCR value to insert
+     * @throws RepositoryException
+     */
     public static void appendOrReplaceNodeProperty(final Node node, final String propertyName, final Value newValue) throws RepositoryException {
 
         // if it already exists, we can take some shortcuts
@@ -51,6 +60,15 @@ public static void appendOrReplaceNodeProperty(final Node node, final String pro
 
     }
 
+    /**
+     * Given a JCR node, property and value, remove the value (if it exists) from the property, and remove the
+     * property if no values remove
+     *
+     * @param node the JCR node
+     * @param propertyName a name of a JCR property (either pre-existing or otherwise)
+     * @param valueToRemove the JCR value to remove
+     * @throws RepositoryException
+     */
     public static void removeNodeProperty(final Node node, final String propertyName, final Value valueToRemove) throws RepositoryException {
         // if the property doesn't exist, we don't need to worry about it.
         if (node.hasProperty(propertyName)) {
@@ -84,6 +102,14 @@ public static void removeNodeProperty(final Node node, final String propertyName
         }
     }
 
+    /**
+     * Get the JCR property type ID for a given property name. If unsure, mark it as UNDEFINED.
+     *
+     * @param node the JCR node to add the property on
+     * @param propertyName the property name
+     * @return a PropertyType value
+     * @throws RepositoryException
+     */
     public static int getPropertyType(final Node node, final String propertyName) throws RepositoryException {
         final PropertyDefinition def = getDefinitionForPropertyName(node, propertyName);
 
@@ -94,6 +120,15 @@ public static int getPropertyType(final Node node, final String propertyName) th
         return def.getRequiredType();
     }
 
+    /**
+     * Determine if a given JCR property name is single- or multi- valued. If unsure, choose the least restrictive
+     * option (multivalued)
+     *
+     * @param node the JCR node to check
+     * @param propertyName the property name (which may or may not already exist)
+     * @return true if the property is (or could be) multivalued
+     * @throws RepositoryException
+     */
     public static boolean isMultivaluedProperty(final Node node, final String propertyName) throws RepositoryException {
         final PropertyDefinition def = getDefinitionForPropertyName(node, propertyName);