JCR API

Magnolia relies on the Apache Jackrabbit JCR API to manage its data, with security handled by JCR.

Important Util classes

  • NodeUtil. Utility methods to collect data from JCR repository.

  • NodeTypes. Magnolia-defined node types and their properties and convenience methods.

  • PropertyUtil. Property-related utility methods.

  • SessionUtil. Session-related utility methods.

  • JcrFunctions. Functions for working with JCR items without catching repository exceptions.

  • NodeBuilder. Entry point for using the node builder API. Also see the NodeBuilderTask and ModuleNodeBuilderTask classes for usage of the node builder API in ModuleVersionHandler.

  • ContentDecorator. Applies custom behavior in a graph of JCR objects by wrapping objects. Allows for expressing the logic in a single place.

    • Created

      • getCreated(javax.jcr.Node node) Returns the creation date of a node or null if creation date isn’t set.

Session

  • Session

    • getNode(java.lang.String absPath). Returns the node at the specified absolute path in the workspace.

    • getNodeByIdentifier(java.lang.String id) Returns the node specified by the given identifier.

    • save(). Validates all pending changes currently recorded in this Session.

Node

  • Node. Represents a node in the repository.

    • getNode(java.lang.String relPath). Returns the node at relPath relative to this node.

    • getNodes() Returns all child nodes of this node accessible through the current Session.

    • getNodes(java.lang.String namePattern) Gets all child nodes of this node accessible through the current Session that match namePattern.

    • getProperty(java.lang.String relPath) Returns the property at relPath relative to this node.

    • setProperty(java.lang.String name, Value value) Sets the single-value property of this node called name to the specified value.

  • Property. A Property object represents the smallest granularity of content storage.

    • getLong()

    • getString()

    • getBinary()

Node2Bean

  • Node2BeanProcessor. Transforms nodes to beans or maps. The transformer is use to resolve classes or to instantiate beans.

  • Node2BeanTransformer. Contract for transformation from node to java beans.

Examples

Accessing a workspace

  • Access a workspace with javax.jcr.Session:

    Session session = MgnlContext.getJCRSession("workspaceName");

Session session = someNode.getSession();

Getting javax.jcr.Node or javax.jcr.Property

  • Access a specific node or property with the JCR session:

    Node foundNode = session.getNodeByIdentifier("identifier");
Node foundNode = session.getNode("absolutePath");
Property foundProperty = session.getProperty("absolutePath");

Node foundNode = NodeUtil.getNodeByIdentifier("workspaceName", "identifier");

Operations on javax.jcr.Node

  • Get a node’s name:

    String name = someNode.getName();

String name = NodeUtil.getName(someNode);

  • Get all child nodes together:

    NodeIterator childrenIterator = someNode.getNodes();
Iterable<Node> childrenIterable = NodeUtil.asIterable(childrenIterator);
List<Node> childrenList = NodeUtil.asList(childrenIterable);

Iterable<Node> childrenIterable = NodeUtil.collectAllChildren(someNode);
List<Node> childrenList = NodeUtil.asList(childrenIterable);

  • Get a specific child node by name:

    Node childNode = someNode.getNode("relativePath");

  • Get a node property by name:

    Property nodeProperty = someNode.getProperty("relativePath");

Property foundProperty = PropertyUtil.getProperty(someNode, "relativePath");

  • Get a node’s path:

    String pathToNode = someNode.getPath();

String pathToNode = NodeUtil.getNodePathIfPossible(someNode);

  • Create a property and set its value for a specific node:

    someNode.setProperty("propertyName", "propertyValue");

PropertyUtil.setProperty(someNode, "propertyName", "propertyValue");

  • Create a subnode:

    someNode.addNode("relativePath", primaryNodeTypeName);

NodeUtil.createPath(parent, "relativePath", primaryNodeTypeName)

  • Get a session from a node and save changes:

    //Get a session from a node and save changes
someNode.getSession().save();

//If you already have the session
session.save()

Content node metadata

  • Examples of content node metadata with NodeTypes:

    NodeTypes.Activatable.getActivationStatus(node);
NodeTypes.Activatable.update(node, "username", isActivated);

NodeTypes.Renderable.getTemplate(node);
NodeTypes.Renderable.set(node, "template id");

NodeTypes.LastModified.getLastModified(node);
NodeTypes.LastModified.update(node);
NodeTypes.LastModified.update(node, "username", date);

Operations on javax.jcr.Property

  • Get a property’s name:

    String name = nodeProperty.getName();

  • Get a property’s path:

    String pathToProperty = nodeProperty.getPath();

  • Get a property’s parent node:

    Node parentNode = nodeProperty.getParent();

  • Get a value from a property:

    String stringValue = nodeProperty.getString()
Calendar dateValue = nodeProperty.getDate();
Double doubleValue = nodeProperty.getDouble();
Long longValue = nodeProperty.getLong();
Binary forBinaryNodeData = nodeProperty.getBinary();

PropertyUtil.getString(someNode, propertyName);
PropertyUtil.getDate(someNode, propertyName);
PropertyUtil.getBoolean(someNode, propertyName, defaultValue)

  • Set the value of a property:

    nodeProperty.setValue(booleanValue);
nodeProperty.setValue(calendarObject);
nodeProperty.setValue(longValue);
nodeProperty.setValue(doubleValue);
nodeProperty.setValue(intValueWillBeStoredAsLong);
nodeProperty.setValue(booleanValue);
nodeProperty.setValue(inputStreamForBinary);

Exception-free JCR operations

Use JcrFunctions to work with JCR items without catching repository exceptions.

Set<Node> parents = getValueContext().get()
                .map(JcrFunctions::getParent)
                .collect(Collectors.toSet());

Providing a node as ContentMap to scripts

It is not recommended that you operate in template scripts directly on a JCR Node. cmsfn provides all scripts with any node transformed into ContentMap. That way, it is much easier to access a node’s data. ContentMap provides the following special attributes that are not properties:

  • @name

  • @path

  • @id

  • @depth

  • @nodeType

    In Java:

    ContentMap nodeAsContentMap = new ContentMap(someNode);
Node backToNode = nodeAsContentMap.getJCRNode();

    In Freemarker:

    ${cmsfn.asJCRNode(aContentMap)}
${cmsfn.asContentMap(aJCRNode)}

    See cmsfn for more templating functions operating on the JCR API.

Related topics
Feedback