/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.jackrabbit.commons.xml;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Iterator;
import java.util.LinkedList;
import java.util.Map;
import java.util.Set;
import java.util.SortedMap;
import java.util.TreeMap;
import javax.jcr.Node;
import javax.jcr.NodeIterator;
import javax.jcr.Property;
import javax.jcr.PropertyIterator;
import javax.jcr.PropertyType;
import javax.jcr.RepositoryException;
import javax.jcr.Session;
import javax.jcr.Value;
import javax.jcr.ValueFactory;
import org.apache.jackrabbit.commons.NamespaceHelper;
import org.xml.sax.ContentHandler;
import org.xml.sax.SAXException;
import org.xml.sax.helpers.AttributesImpl;
/**
* Abstract base class for document and system view exporters. This class
* takes care of all the details related to namespace mappings, shareable
* nodes, recursive exports, binary values, and so on while leaving the
* decisions about what kind of SAX events to generate to subclasses.
* <p>
* A subclass should only need to implement the abstract methods of this
* class to produce a fully functional exporter.
*
* @since Jackrabbit JCR Commons 1.5
*/
public abstract class Exporter {
/**
* Attributes of the next element. This single instance is reused for
* all elements by simply clearing it after each element has been emitted.
*/
private final AttributesImpl attributes = new AttributesImpl();
/**
* Stack of namespace mappings.
*/
private final LinkedList stack = new LinkedList();
/**
* The UUID strings of all shareable nodes already exported.
*/
private final Set shareables = new HashSet();
/**
* Whether the current node is a shareable node that has already been
* exported.
*/
private boolean share = false;
/**
* Current session.
*/
private final Session session;
/**
* Namespace helper.
*/
protected final NamespaceHelper helper;
/**
* SAX event handler to which the export events are sent.
*/
private final ContentHandler handler;
/**
* Whether to export the subtree or just the given node.
*/
private final boolean recurse;
/**
* Whether to export binary values.
*/
private final boolean binary;
/**
* Creates an exporter instance.
*
* @param session current session
* @param handler SAX event handler
* @param recurse whether the export should be recursive
* @param binary whether the export should include binary values
*/
protected Exporter(
Session session, ContentHandler handler,
boolean recurse, boolean binary) {
this.session = session;
this.helper = new NamespaceHelper(session);
this.handler = handler;
this.recurse = recurse;
this.binary = binary;
stack.add(new HashMap());
}
/**
* Exports the given node by preparing the export and calling the
* abstract {@link #exportNode(String, String, Node)} method to give
* control of the export format to a subclass.
* <p>
* This method should be called only once for an exporter instance.
*
* @param node node to be exported
* @throws SAXException if a SAX error occurs
* @throws RepositoryException if a repository error occurs
*/
public void export(Node node) throws RepositoryException, SAXException {
handler.startDocument();
String[] prefixes = session.getNamespacePrefixes();
for (int i = 0; i < prefixes.length; i++) {
if (prefixes[i].length() > 0 && !prefixes[i].equals("xml") ) {
addNamespace(prefixes[i], session.getNamespaceURI(prefixes[i]));
}
}
exportNode(node);
handler.endDocument();
}
/**
* Called to export the given node. The node name (or <code>jcr:root</code>
* if the node is the root node) is given as an explicit pair of the
* resolved namespace URI and local part of the name.
* <p>
* The implementation of this method should call the methods
* {@link #exportProperties(Node)} and {@link #exportProperties(Node)}
* to respectively export the properties and child nodes of the given node.
* Those methods will call back to the implementations of this method and
* the abstract property export methods so the subclass can decide what
* SAX events to emit for each exported item.
*
* @param uri node namespace
* @param local node name
* @param node node
* @throws RepositoryException if a repository error occurs
* @throws SAXException if a SAX error occurs
*/
protected abstract void exportNode(String uri, String local, Node node)
throws RepositoryException, SAXException;
/**
* Called by {@link #exportProperties(Node)} to process a single-valued
* property.
*
* @param uri property namespace
* @param local property name
* @param value property value
* @throws RepositoryException if a repository error occurs
* @throws SAXException if a SAX error occurs
*/
protected abstract void exportProperty(
String uri, String local, Value value)
throws RepositoryException, SAXException;
/**
* Called by {@link #exportProperties(Node)} to process a multivalued
* property.
*
* @param uri property namespace
* @param local property name
* @param type property type
* @param values property values
* @throws RepositoryException if a repository error occurs
* @throws SAXException if a SAX error occurs
*/
protected abstract void exportProperty(
String uri, String local, int type, Value[] values)
throws RepositoryException, SAXException;
/**
* Called by {@link #exportNode(String, String, Node)} to recursively
* call {@link #exportNode(String, String, Node)} for each child node.
* Does nothing if this exporter is not recursive.
*
* @param node parent node
* @throws RepositoryException if a repository error occurs
* @throws SAXException if a SAX error occurs
*/
protected void exportNodes(Node node)
throws RepositoryException, SAXException {
if (recurse && !share) {
NodeIterator iterator = node.getNodes();
while (iterator.hasNext()) {
Node child = iterator.nextNode();
exportNode(child);
}
}
}
/**
* Processes all properties of the given node by calling the abstract
* {@link #exportProperty(String, String, Value)} and
* {@link #exportProperty(String, String, int, Value[])} methods for
* each property depending on whether the property is single- or
* multivalued.
* <p>
* The first properties to be processed are <code>jcr:primaryType</code>,
* <code>jcr:mixinTypes</code>, and <code>jcr:uuid</code>, and then the
* remaining properties ordered by their names.
* <p>
* If the node is a shareable node that has already been encountered by
* this event generator, then only a <code>jcr:primaryType</code> property
* with the fixed value "nt:share" and the <code>jcr:uuid</code> property
* of the shareable node are exported.
*
* @see https://issues.apache.org/jira/browse/JCR-1084
* @param node node
* @return properties as sorted map
* @throws RepositoryException if a repository error occurs
* @throws SAXException if a SAX error occurs
*/
protected void exportProperties(Node node)
throws RepositoryException, SAXException {
// if node is shareable and has already been serialized, change its
// type to nt:share and process only the properties jcr:primaryType
// and jcr:uuid (mix:shareable is referenceable, so jcr:uuid exists)
if (share) {
ValueFactory factory = session.getValueFactory();
exportProperty(
NamespaceHelper.JCR, "primaryType",
factory.createValue(
helper.getJcrName("nt:share"), PropertyType.NAME));
exportProperty(
NamespaceHelper.JCR, "uuid",
factory.createValue(node.getUUID()));
} else {
// Standard behaviour: return all properties (sorted, see JCR-1084)
SortedMap properties = getProperties(node);
// serialize jcr:primaryType, jcr:mixinTypes & jcr:uuid first:
exportProperty(properties, helper.getJcrName("jcr:primaryType"));
exportProperty(properties, helper.getJcrName("jcr:mixinTypes"));
exportProperty(properties, helper.getJcrName("jcr:uuid"));
// serialize remaining properties
Iterator iterator = properties.entrySet().iterator();
while (iterator.hasNext()) {
Map.Entry entry = (Map.Entry) iterator.next();
String name = (String) entry.getKey();
exportProperty(name, (Property) entry.getValue());
}
}
}
/**
* Utility method for exporting the given node. Parses the node name
* (or <code>jcr:root</code> if given the root node) and calls
* {@link #exportNode(String, String, Node)} with the resolved namespace
* URI and the local part of the name.
*
* @param node node
* @throws RepositoryException if a repository error occurs
* @throws SAXException if a SAX error occurs
*/
private void exportNode(Node node)
throws RepositoryException, SAXException {
share = node.isNodeType(helper.getJcrName("mix:shareable"))
&& !shareables.add(node.getUUID());
if (node.getDepth() == 0) {
exportNode(NamespaceHelper.JCR, "root", node);
} else {
String name = node.getName();
int colon = name.indexOf(':');
if (colon == -1) {
exportNode("", name, node);
} else {
String uri = session.getNamespaceURI(name.substring(0, colon));
exportNode(uri, name.substring(colon + 1), node);
}
}
}
/**
* Returns a sorted map of the properties of the given node.
*
* @param node JCR node
* @return sorted map (keyed by name) of properties
* @throws RepositoryException if a repository error occurs
*/
private SortedMap getProperties(Node node) throws RepositoryException {
SortedMap properties = new TreeMap();
PropertyIterator iterator = node.getProperties();
while (iterator.hasNext()) {
Property property = iterator.nextProperty();
properties.put(property.getName(), property);
}
return properties;
}
/**
* Utility method for processing the named property from the given
* map of properties. If the property exists, it is removed from the
* given map and passed to {@link #exportProperty(Property)}.
* The property is ignored if it does not exist.
*
* @param properties map of properties
* @param name property name
* @throws RepositoryException if a repository error occurs
* @throws SAXException if a SAX error occurs
*/
private void exportProperty(Map properties, String name)
throws RepositoryException, SAXException {
Property property = (Property) properties.remove(name);
if (property != null) {
exportProperty(name, property);
}
}
/**
* Utility method for processing the given property. Calls either
* {@link #exportProperty(Value)} or {@link #exportProperty(int, Value[])}
* depending on whether the the property is single- or multivalued.
*
* @param name property name
* @param property property
* @throws RepositoryException if a repository error occurs
* @throws SAXException if a SAX error occurs
*/
private void exportProperty(String name, Property property)
throws RepositoryException, SAXException {
String uri = "";
String local = name;
int colon = name.indexOf(':');
if (colon != -1) {
uri = session.getNamespaceURI(name.substring(0, colon));
local = name.substring(colon + 1);
}
int type = property.getType();
if (type != PropertyType.BINARY || binary) {
if (property.isMultiple()) {
exportProperty(uri, local, type, property.getValues());
} else {
exportProperty(uri, local, property.getValue());
}
} else {
ValueFactory factory = session.getValueFactory();
Value value = factory.createValue("", PropertyType.BINARY);
if (property.isMultiple()) {
exportProperty(uri, local, type, new Value[] { value });
} else {
exportProperty(uri, local, value);
}
}
}
//---------------------------------------------< XML handling methods >--
/**
* Emits a characters event with the given character content.
*
* @param ch character array
* @param start start offset within the array
* @param length number of characters to emit
* @throws SAXException if a SAX error occurs
*/
protected void characters(char[] ch, int start, int length)
throws SAXException {
handler.characters(ch, start, length);
}
/**
* Adds the given attribute to be included in the next element.
*
* @param uri namespace URI of the attribute
* @param local local name of the attribute
* @param value attribute value
* @throws RepositoryException if a repository error occurs
*/
protected void addAttribute(String uri, String local, String value)
throws RepositoryException {
attributes.addAttribute(
uri, local, getXMLName(uri, local), "CDATA", value);
}
/**
* Emits the start element event for an element with the given name.
* All the attributes added using
* {@link #addAttribute(String, String, String)} are included in the
* element along with any new namespace mappings. The namespace stack
* is extended for potential child elements.
*
* @param uri namespace URI or the element
* @param local local name of the element
* @throws RepositoryException if a repository error occurs
* @throws SAXException if a SAX error occurs
*/
protected void startElement(String uri, String local)
throws SAXException, RepositoryException {
// Prefixed name is generated before namespace handling so that a
// potential new prefix mapping gets included as a xmlns attribute
String name = getXMLName(uri, local);
// Add namespace mappings
Map namespaces = (Map) stack.getFirst();
Iterator iterator = namespaces.entrySet().iterator();
while (iterator.hasNext()) {
Map.Entry entry = (Map.Entry) iterator.next();
String namespace = (String) entry.getKey();
String prefix = (String) entry.getValue();
handler.startPrefixMapping(prefix, namespace);
attributes.addAttribute(
"http://www.w3.org/2000/xmlns/", prefix, "xmlns:" + prefix,
"CDATA", namespace);
}
// Emit the start element event, and clear things for the next element
handler.startElement(uri, local, name, attributes);
attributes.clear();
stack.addFirst(new HashMap());
}
/**
* Emits the end element event for an element with the given name.
* The namespace stack and mappings are automatically updated.
*
* @param uri namespace URI or the element
* @param local local name of the element
* @throws RepositoryException if a repository error occurs
* @throws SAXException if a SAX error occurs
*/
protected void endElement(String uri, String local)
throws SAXException, RepositoryException {
stack.removeFirst();
handler.endElement(uri, local, getXMLName(uri, local));
Map namespaces = (Map) stack.getFirst();
Iterator iterator = namespaces.values().iterator();
while (iterator.hasNext()) {
handler.endPrefixMapping((String) iterator.next());
}
namespaces.clear();
}
/**
* Returns a prefixed XML name for the given namespace URI and local
* name. If a prefix mapping for the namespace URI is not yet available,
* it is created based on the namespace mappings of the current JCR
* session.
*
* @param uri namespace URI
* @param local local name
* @return prefixed XML name
* @throws RepositoryException if a JCR namespace mapping is not available
*/
protected String getXMLName(String uri, String local)
throws RepositoryException {
if (uri.length() == 0) {
return local;
} else {
String prefix = getPrefix(uri);
if (prefix == null) {
prefix = getUniquePrefix(session.getNamespacePrefix(uri));
((Map) stack.getFirst()).put(uri, prefix);
}
return prefix + ":" + local;
}
}
/**
* Adds the given namespace to the export. A unique prefix based on
* the given prefix hint is mapped to the given namespace URI. If the
* namespace is already mapped, then the existing prefix is returned.
*
* @param hint prefix hint
* @param uri namespace URI
* @return registered prefix
*/
protected String addNamespace(String hint, String uri) {
String prefix = getPrefix(uri);
if (prefix == null) {
prefix = getUniquePrefix(hint);
((Map) stack.getFirst()).put(uri, prefix);
}
return prefix;
}
/**
* Returns the namespace prefix mapped to the given URI. Returns
* <code>null</code> if the namespace URI is not registered.
*
* @param uri namespace URI
* @return prefix mapped to the URI, or <code>null</code>
*/
private String getPrefix(String uri) {
Iterator iterator = stack.iterator();
while (iterator.hasNext()) {
String prefix = (String) ((Map) iterator.next()).get(uri);
if (prefix != null) {
return prefix;
}
}
return null;
}
/**
* Returns a unique namespace prefix based on the given hint.
* We need prefixes to be unique within the current namespace
* stack as otherwise for example a previously added attribute
* to the current element might incorrectly be using a prefix
* that is being redefined in this element.
*
* @param hint prefix hint
* @return unique prefix
*/
private String getUniquePrefix(String hint) {
String prefix = hint;
for (int i = 2; prefixExists(prefix); i++) {
prefix = hint + i;
}
return prefix;
}
/**
* Checks whether the given prefix is already mapped within the
* current namespace stack.
*
* @param prefix namespace prefix
* @return <code>true</code> if the prefix is mapped,
* <code>false</code> otherwise
*/
private boolean prefixExists(String prefix) {
Iterator iterator = stack.iterator();
while (iterator.hasNext()) {
if (((Map) iterator.next()).containsValue(prefix)) {
return true;
}
}
return false;
}
}