io.permazen.core.util.XMLObjectSerializer Maven / Gradle / Ivy

Go to download

/*
 * Copyright (C) 2015 Archie L. Cobbs. All rights reserved.
 */

package io.permazen.core.util;

import com.google.common.base.Preconditions;
import com.google.common.collect.Iterables;

import io.permazen.core.CollectionField;
import io.permazen.core.CounterField;
import io.permazen.core.DeletedObjectException;
import io.permazen.core.Field;
import io.permazen.core.FieldType;
import io.permazen.core.ListField;
import io.permazen.core.MapField;
import io.permazen.core.ObjId;
import io.permazen.core.ObjType;
import io.permazen.core.ReferenceField;
import io.permazen.core.Schema;
import io.permazen.core.SetField;
import io.permazen.core.SimpleField;
import io.permazen.core.SnapshotTransaction;
import io.permazen.core.Transaction;
import io.permazen.core.UnknownTypeException;
import io.permazen.schema.NameIndex;
import io.permazen.schema.SchemaField;
import io.permazen.schema.SchemaModel;
import io.permazen.schema.SchemaObjectType;
import io.permazen.util.AbstractXMLStreaming;

import java.io.InputStream;
import java.io.OutputStream;
import java.io.Writer;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.Comparator;
import java.util.HashMap;
import java.util.Map;
import java.util.NavigableSet;
import java.util.TreeSet;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;

import javax.xml.XMLConstants;
import javax.xml.namespace.QName;
import javax.xml.stream.XMLInputFactory;
import javax.xml.stream.XMLOutputFactory;
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamReader;
import javax.xml.stream.XMLStreamWriter;

import org.dellroad.stuff.xml.IndentXMLStreamWriter;

/**
 * Utility methods for serializing and deserializing objects in a {@link Transaction} to/from XML.
 *
 * 
 * There are two supported formats. The "Storage ID Format" specifies objects and fields using their storage IDs
 * and supports all possible database contents.
 *  
 *  <objects>
 *      <object storageId="100" id="64a971e1aef01cc8" version="1">
 *          <field storageId="101">George Washington</field>
 *          <field storageId="102">true</field>
 *          <field storageId="103">
 *              <entry>
 *                  <key>teeth</key>
 *                  <value>wooden</value>
 *              </entry>
 *          </field>
 *          <field storageId="104">c8b84a08e5c2b1a2</field>
 *      </object>
 *      ...
 *  </objects>
 *  
 *
 * 
 * "Name Format" differs from "Storage ID Format" in that object types and fields are specified by name instead of storage ID.
 * However, it does not support schemas that use names that are not valid XML tags.
 * 
 *  <objects>
 *      <Person id="64a971e1aef01cc8" version="1">
 *          <name>George Washington</name>
 *          <wasPresident>true</wasPresident>
 *          <attributes>
 *              <entry>
 *                  <key>teeth</key>
 *                  <value>wooden</value>
 *              </entry>
 *          </attributes>
 *          <spouse>c8b84a08e5c2b1a2</spouse>
 *      </Person>
 *      ...
 *  </objects>
 *  
 *
 * 
 * Some details on the input logic:
 * 

 *  Simple fields that are equal to their default values, and complex fields that are empty, may be omitted
 *  The {@code "version"} attribute may be omitted, in which case the default schema version associated with
 *      the {@link Transaction} being written to is assumed.
 *  The {@code "id"} attribute may be omitted, in which case a random unassigned ID is generated
 *  Any object ID (including the {@code "id"} attribute) may have the special form
 *      generated:TYPE:SUFFIX, where TYPE is the object type
 *      name or storage ID and SUFFIX is an arbitrary string.
 *      In this case, a random, unassigned object ID for type TYPE is generated
 *      on first occurrence, and on subsequent occurences the previously generated ID is recalled. This facilitates
 *      input generated via XSL and the {@code generate-id()} function.
 *      The {@linkplain #getGeneratedIdCache configured} {@link GeneratedIdCache} keeps track of generated IDs.
 *  XML elements and annotations are expected to be in the null namespace; elements and annotations in other
 *      namespaces are ignored
 * 
 */
public class XMLObjectSerializer extends AbstractXMLStreaming {

    /**
     * The supported XML namespace URI.
     *
     * 
     * Currently this is {@link XMLConstants#NULL_NS_URI}, i.e., the null/default namespace.
     *
     * 

     * XML tags and attributes whose names are in other namespaces are ignored.
     */
    public static final String NS_URI = XMLConstants.NULL_NS_URI;

    public static final QName ELEMENT_TAG = new QName("element");
    public static final QName ENTRY_TAG = new QName("entry");
    public static final QName FIELD_TAG = new QName("field");
    public static final QName KEY_TAG = new QName("key");
    public static final QName OBJECTS_TAG = new QName("objects");
    public static final QName OBJECT_TAG = new QName("object");
    public static final QName VALUE_TAG = new QName("value");

    public static final QName ID_ATTR = new QName("id");
    public static final QName STORAGE_ID_ATTR = new QName("storageId");
    public static final QName VERSION_ATTR = new QName("version");
    public static final QName NULL_ATTR = new QName("null");

    private static final Pattern GENERATED_ID_PATTERN = Pattern.compile("generated:([^:]+):(.*)");

    private final Transaction tx;
    private final HashMap nameIndexMap = new HashMap<>();

    private GeneratedIdCache generatedIdCache = new GeneratedIdCache();
    private final ObjIdMap unresolvedReferences = new ObjIdMap<>();
    private boolean omitDefaultValueFields = true;
    private int fieldTruncationLength = -1;

    /**
     * Constructor.
     *
     * @param tx {@link Transaction} on which to operate
     * @throws IllegalArgumentException if {@code tx} is null
     */
    public XMLObjectSerializer(Transaction tx) {
        Preconditions.checkArgument(tx != null, "null tx");
        this.tx = tx;

        // Build name index for each schema version
        for (Schema schema : this.tx.getSchemas().getVersions().values())
            nameIndexMap.put(schema.getVersionNumber(), new NameIndex(schema.getSchemaModel()));
    }

    /**
     * Get the maximum length (number of characters) of any written simple field.
     *
     * 

     * By default, this value is set to {@code -1}, i.e., truncation is disabled.
     *
     * @return maximum simple field length, or zero for empty simple fields, or {@code -1} if truncation is disabled
     * @see #setFieldTruncationLength setFieldTruncationLength()
     */
    public int getFieldTruncationLength() {
        return this.fieldTruncationLength;
    }

    /**
     * Set the maximum length (number of characters) of any written simple field.
     *
     * 

     * Simple field values longer than this will be truncated. If set to zero, all simple field values are written as empty tags.
     * If set to {@code -1}, truncation is disabled.
     *
     * 

     * Truncation is mainly useful for generating human-readable output without very long lines.
     * Obviously, when truncation is enabled, the resulting output, although still valid XML, will
     * be missing some information and therefore cannot successfully be read back in by this class.
     *
     * @param length maximum simple field length, or zero for empty simple fields, or {@code -1} to disable truncation
     * @throws IllegalArgumentException if {@code length < -1}
     */
    public void setFieldTruncationLength(int length) {
        Preconditions.checkArgument(length >= -1, "length < -1");
        this.fieldTruncationLength = length;
    }

    /**
     * Get whether to omit fields whose value equals the default value for the field's type.
     *
     * 

     * Default true.
     *
     * @return whether to omit fields with default values
     */
    public boolean isOmitDefaultValueFields() {
        return this.omitDefaultValueFields;
    }

    /**
     * Set whether to omit fields whose value equals the default value for the field's type.
     *
     * 

     * Default true.
     *
     * @param omitDefaultValueFields true to omit fields with default values
     */
    public void setOmitDefaultValueFields(final boolean omitDefaultValueFields) {
        this.omitDefaultValueFields = omitDefaultValueFields;
    }

    /**
     * Get all unresolved forward object references.
     *
     * 

     * When {@link #read(InputStream, boolean) read()} is invoked with {@code allowUnresolvedReferences = true},
     * unresolved forward object references do not trigger an exception; this allows forward references to span
     * multiple invocations. Instead, these references are collected and made available to the caller in the returned map.
     * Callers may also modify the returned map as desired between invocations.
     *
     * @return mapping from unresolved forward object reference to some referring field
     */
    public ObjIdMap getUnresolvedReferences() {
        return this.unresolvedReferences;
    }

    /**
     * Get the {@link GeneratedIdCache} associated with this instance.
     *
     * @return the associated {@link GeneratedIdCache}
     */
    public GeneratedIdCache getGeneratedIdCache() {
        return this.generatedIdCache;
    }

    /**
     * Set the {@link GeneratedIdCache} associated with this instance.
     *
     * @param generatedIdCache the {@link GeneratedIdCache} for this instance to use
     * @throws IllegalArgumentException if {@code generatedIdCache} is null
     */
    public void setGeneratedIdCache(GeneratedIdCache generatedIdCache) {
        Preconditions.checkArgument(generatedIdCache != null, "null generatedIdCache");
        this.generatedIdCache = generatedIdCache;
    }

    /**
     * Import objects pairs into the {@link Transaction} associated with this instance from the given XML input.
     *
     * 

     * This is a convenience method, equivalent to:
     * 
     * read(input, false)
     * 
     *
     * @param input XML input
     * @return the number of objects read
     * @throws XMLStreamException if an error occurs
     * @throws IllegalArgumentException if {@code input} is null
     */
    public int read(InputStream input) throws XMLStreamException {
        return this.read(input, false);
    }

    /**
     * Import objects pairs into the {@link Transaction} associated with this instance from the given XML input.
     *
     * 
     * The input format is auto-detected for each {@code