de.topicmapslab.majortom.io
Class CXTMTopicMapWriter

java.lang.Object
  extended by de.topicmapslab.majortom.io.CXTMTopicMapWriter

public final class CXTMTopicMapWriter
extends java.lang.Object

Provides serialization of topic maps into Canonical XTM (CXTM).

CXTM is a format that guarantees that two equivalent Topic Maps Data Model instances [ISO/IEC 13250-2] will always produce byte-by-byte identical serializations, and that non-equivalent instances will always produce different serializations.

See http://www.isotopicmaps.org/cxtm / for details.

This class was copied from the tinyTiM project and adapted for MaJorToM.

Author:
Lars Heuer (heuer[at]semagia.com) Semagia, Hannes Niederhausen

Nested Class Summary
private  class CXTMTopicMapWriter.AbstractComparator<T>
          Abstract comparator that provides some utility methods which handle common comparisons.
private  class CXTMTopicMapWriter.AbstractDatatypeAwareComparator<T>
          Enhances the CXTMTopicMapWriter.AbstractComparator with a method to compare the value and datatype of an occurrence or variant.
private  class CXTMTopicMapWriter.AbstractSetComparator<T>
          Comparator which compares the size of the provided set.
private  class CXTMTopicMapWriter.AssociationComparator
          Canonical sort order: 1.
private  class CXTMTopicMapWriter.LocatorComparator
          Compares Locators.
private  class CXTMTopicMapWriter.LocatorSetComparator
          Comparator for sets of Locators.
private  class CXTMTopicMapWriter.NameComparator
          Canonical sort order: 1.
private  class CXTMTopicMapWriter.OccurrenceComparator
          Canonical sort order: 1.
private  class CXTMTopicMapWriter.RoleComparator
          Canonical sort order: 1.
private  class CXTMTopicMapWriter.RoleIgnoreParentComparator
          Role comparator which ignores the parent association.
private  class CXTMTopicMapWriter.RoleSetComparator
          Compares role sets.
private  class CXTMTopicMapWriter.ScopeComparator
          Compares the scope of two scoped Topic Maps constructs.
private  class CXTMTopicMapWriter.TopicComparator
           
private  class CXTMTopicMapWriter.TypeInstanceAssociation
          Used to represent type-instance relationships which are modelled as [type] property of topics.
private  class CXTMTopicMapWriter.TypeInstanceRole
          Immutable association role.
private static class CXTMTopicMapWriter.TypeInstanceRoleSet
          Immutable 'set' of two roles.
private  class CXTMTopicMapWriter.TypeInstanceTopic
           
private  class CXTMTopicMapWriter.VariantComparator
          Canonical sort order: 1.
 
Field Summary
private  java.util.Map<org.tmapi.core.Association,org.tmapi.core.Role[]> _assoc2Roles
           
private  java.util.Comparator<org.tmapi.core.Association> _assocComparator
           
private  org.xml.sax.helpers.AttributesImpl _attrs
           
private  java.util.Map<org.tmapi.core.Construct,java.lang.Integer> _construct2Id
           
private static org.tmapi.core.Role[] _EMPTY_ROLES
           
private  org.tmapi.core.Topic _instance
           
private  java.util.Map<org.tmapi.core.Locator,java.lang.String> _locator2Norm
           
private  java.util.Comparator<org.tmapi.core.Locator> _locComparator
           
private  java.util.Comparator<java.util.Set<org.tmapi.core.Locator>> _locSetComparator
           
private  java.util.Comparator<org.tmapi.core.Name> _nameComparator
           
private  java.lang.String _normBase
           
private  java.util.Comparator<org.tmapi.core.Occurrence> _occComparator
           
private  XMLC14NWriter _out
           
private  java.util.Comparator<org.tmapi.core.Role> _roleComparator
           
private  java.util.Comparator<java.util.Set<org.tmapi.core.Topic>> _scopeComparator
           
private  java.util.Map<org.tmapi.core.Topic,java.util.List<org.tmapi.core.Role>> _topic2Roles
           
private  java.util.Comparator<org.tmapi.core.Topic> _topicComparator
           
private  org.tmapi.core.Topic _type
           
private  org.tmapi.core.Topic _typeInstance
           
private  java.util.Comparator<org.tmapi.core.Variant> _variantComparator
           
private static java.util.logging.Logger LOG
           
 
Constructor Summary
CXTMTopicMapWriter(java.io.OutputStream out, java.lang.String baseLocator)
          Creates a canonicalizer.
 
Method Summary
private  void _addReifier(org.xml.sax.helpers.AttributesImpl attrs, org.tmapi.core.Reifiable reifiable)
          Adds a reference to the reifier of the Topic Maps construct to the provided attributes.
private  org.xml.sax.Attributes _attributes(org.tmapi.core.Reifiable reifiable, int pos)
          Returns attributes which contain the reifier (if any) and the number of the provided Topic Maps construct (not a topic).
private  void _createIndex(org.tmapi.core.Topic[] topics, org.tmapi.core.Association[] assocs)
          Creates the index on which the canonicalizer operates.
private  org.tmapi.core.Association[] _fetchAssociations(org.tmapi.core.TopicMap tm, org.tmapi.index.TypeInstanceIndex idx)
          Returns an unsorted array of associations which should be serialized.
private  org.tmapi.core.Topic[] _fetchTopics(org.tmapi.core.TopicMap topicMap, org.tmapi.index.TypeInstanceIndex idx)
          Returns an unsorted array of topics which should be included into the output.
private  org.tmapi.core.Name[] _getNames(org.tmapi.core.Topic topic)
          Returns a sorted array of names of the provided topic.
private  org.tmapi.core.Occurrence[] _getOccurrences(org.tmapi.core.Topic topic)
          Returns a sorted array of occurrences of the provided topic.
private  org.tmapi.core.Role[] _getRoles(org.tmapi.core.Association assoc)
          Returns a sorted array of roles of the provided association.
private  org.tmapi.core.Topic _getTopicBySubjectIdentifier(org.tmapi.core.TopicMap tm, java.util.Collection<org.tmapi.core.Topic> topics, java.lang.String sid)
          Returns a topic by its subject identifier.
private  org.tmapi.core.Variant[] _getVariants(org.tmapi.core.Name name)
          Returs a sorted array of variants of the provided name.
private  int _indexOf(org.tmapi.core.Construct tmo)
          Returns the index of the provided Topic Maps construct.
private static java.lang.String _normalizeBaseLocator(java.lang.String baseLocator)
          Normalizes the base locator according to the following procedure (CXTM 3.19 - 1.): [...] the base locator with any fragment identifier and query removed and any trailing "/" character removed.[...]
private  java.lang.String _normalizeLocator(org.tmapi.core.Locator locator)
          Normalizes the locator according to CXTM 3.19.
private static void _reportInvalid(java.lang.String msg)
          Writes a warning msg to the log.
private  org.xml.sax.Attributes _topicRef(org.tmapi.core.Topic topic)
          Returns attributes which contains a reference to the provided topic.
private  void _writeAssociation(org.tmapi.core.Association assoc)
          Serializes an association.
private  void _writeDatatyped(org.tmapi.core.DatatypeAware obj)
          Writes the value/datatype pair of an occurrence or variant.
private  void _writeItemIdentifiers(org.tmapi.core.Construct tmo)
          Serializes the item identifiers of the specified Topic Maps construct.
private  void _writeLocator(org.tmapi.core.Locator loc)
          Serializes a locator.
private  void _writeLocatorSet(java.lang.String localName, java.util.Set<org.tmapi.core.Locator> locators)
          Serializes the locators using the localName as element name.
private  void _writeName(org.tmapi.core.Name name, int pos)
          Serializes a topic name.
private  void _writeOccurrence(org.tmapi.core.Occurrence occ, int pos)
          Serializes an occurrence.
private  void _writeScope(org.tmapi.core.Scoped scoped)
          Serializes the scope of a scoped Topic Maps construct.
private  void _writeTopic(org.tmapi.core.Topic topic)
          Serializes the topic.
private  void _writeType(org.tmapi.core.Typed typed)
          Serializes the type of a typed Topic Maps construct.
private  void removeDuplicates(org.tmapi.core.TopicMap topicMap)
          Removes the duplicates from the topic map
 void write(org.tmapi.core.TopicMap topicMap)
          Serializes the specified topicMap into the CXTM format.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

LOG

private static final java.util.logging.Logger LOG

_EMPTY_ROLES

private static final org.tmapi.core.Role[] _EMPTY_ROLES

_attrs

private final org.xml.sax.helpers.AttributesImpl _attrs

_type

private org.tmapi.core.Topic _type

_instance

private org.tmapi.core.Topic _instance

_typeInstance

private org.tmapi.core.Topic _typeInstance

_out

private final XMLC14NWriter _out

_normBase

private final java.lang.String _normBase

_construct2Id

private final java.util.Map<org.tmapi.core.Construct,java.lang.Integer> _construct2Id

_topic2Roles

private final java.util.Map<org.tmapi.core.Topic,java.util.List<org.tmapi.core.Role>> _topic2Roles

_locator2Norm

private final java.util.Map<org.tmapi.core.Locator,java.lang.String> _locator2Norm

_assoc2Roles

private final java.util.Map<org.tmapi.core.Association,org.tmapi.core.Role[]> _assoc2Roles

_topicComparator

private final java.util.Comparator<org.tmapi.core.Topic> _topicComparator

_assocComparator

private final java.util.Comparator<org.tmapi.core.Association> _assocComparator

_roleComparator

private final java.util.Comparator<org.tmapi.core.Role> _roleComparator

_occComparator

private final java.util.Comparator<org.tmapi.core.Occurrence> _occComparator

_nameComparator

private final java.util.Comparator<org.tmapi.core.Name> _nameComparator

_variantComparator

private final java.util.Comparator<org.tmapi.core.Variant> _variantComparator

_locSetComparator

private final java.util.Comparator<java.util.Set<org.tmapi.core.Locator>> _locSetComparator

_locComparator

private final java.util.Comparator<org.tmapi.core.Locator> _locComparator

_scopeComparator

private final java.util.Comparator<java.util.Set<org.tmapi.core.Topic>> _scopeComparator
Constructor Detail

CXTMTopicMapWriter

public CXTMTopicMapWriter(java.io.OutputStream out,
                          java.lang.String baseLocator)
                   throws java.io.IOException
Creates a canonicalizer.

Parameters:
out - The stream the CXTM is written onto.
baseLocator - The base locator which is used to resolve IRIs against.
Throws:
java.io.IOException - If an error occurs.
Method Detail

write

public void write(org.tmapi.core.TopicMap topicMap)
           throws java.lang.Exception
Serializes the specified topicMap into the CXTM format.

CAUTION: This method MAY modify the topic map since duplicate Topic Maps constructs (if any) are removed in advance.

Parameters:
topicMap - The topic map to serialize.
Throws:
java.lang.Exception - If an error occurs.

removeDuplicates

private void removeDuplicates(org.tmapi.core.TopicMap topicMap)
Removes the duplicates from the topic map

Parameters:
topicMap -

_fetchTopics

private org.tmapi.core.Topic[] _fetchTopics(org.tmapi.core.TopicMap topicMap,
                                            org.tmapi.index.TypeInstanceIndex idx)
                                     throws org.tmapi.core.FeatureNotRecognizedException
Returns an unsorted array of topics which should be included into the output.

This method may return more topics than TopicMap.getTopics() since this method creates virtual topics to model type-instance relationships properly.

Parameters:
topicMap - The topic map from which the topic should be serialized.
idx - A (upto date) type instance index.
Returns:
All topics which must be included into the output.
Throws:
org.tmapi.core.FeatureNotRecognizedException

_getTopicBySubjectIdentifier

private org.tmapi.core.Topic _getTopicBySubjectIdentifier(org.tmapi.core.TopicMap tm,
                                                          java.util.Collection<org.tmapi.core.Topic> topics,
                                                          java.lang.String sid)
Returns a topic by its subject identifier. If the topic is null, a CXTMTopicMapWriter.TypeInstanceTopic is created, added to the topics and returned.

Parameters:
tm - The topic map to fetch the topic from.
topics - A modifiable collection of topics.
sid - The subject identifier.
Returns:
A topic with the specified subject identifier.

_fetchAssociations

private org.tmapi.core.Association[] _fetchAssociations(org.tmapi.core.TopicMap tm,
                                                        org.tmapi.index.TypeInstanceIndex idx)
                                                 throws org.tmapi.core.FeatureNotRecognizedException
Returns an unsorted array of associations which should be serialized. This method may return more association than TopicMap.getAssociations() since this method may create virtual associations which are used to model type-instance relationships properly.

Parameters:
tm - The topic map from which the associations should be serialized.
idx - A (upto date) type instance index.
Returns:
An unsorted array of associations which must be included into the output.
Throws:
org.tmapi.core.FeatureNotRecognizedException

_createIndex

private void _createIndex(org.tmapi.core.Topic[] topics,
                          org.tmapi.core.Association[] assocs)
Creates the index on which the canonicalizer operates. As sideeffect, the provided topic and association arrays get sorted.

Parameters:
topics - An array of topics.
assocs - An array of associations.

_getRoles

private org.tmapi.core.Role[] _getRoles(org.tmapi.core.Association assoc)
Returns a sorted array of roles of the provided association.

Parameters:
assoc - The association to retrieve the roles from.
Returns:
A (maybe empty) sorted array of roles.

_getNames

private org.tmapi.core.Name[] _getNames(org.tmapi.core.Topic topic)
Returns a sorted array of names of the provided topic.

Parameters:
topic - The topic to retrieve the names from.
Returns:
A (maybe empty) sorted array of names.

_getVariants

private org.tmapi.core.Variant[] _getVariants(org.tmapi.core.Name name)
Returs a sorted array of variants of the provided name.

Parameters:
name - The name to retrieve the variants from.
Returns:
A (maybe empty) sorted array of variants.

_getOccurrences

private org.tmapi.core.Occurrence[] _getOccurrences(org.tmapi.core.Topic topic)
Returns a sorted array of occurrences of the provided topic.

Parameters:
topic - The topic to retrieve the occurrences from.
Returns:
A (maybe emtpy) sorted array of occurrences.

_indexOf

private int _indexOf(org.tmapi.core.Construct tmo)
Returns the index of the provided Topic Maps construct. The "index" is "[...] the string encoding of the position of this information item in the canonically ordered list of the values from that set". (CXTM 3.20 Constructing the number attribute).

Parameters:
tmo - The Topic Maps construct to return the index of.
Returns:
The index of the Topic Maps construct.

_writeTopic

private void _writeTopic(org.tmapi.core.Topic topic)
                  throws java.io.IOException
Serializes the topic.

Parameters:
topic - The topic to serialize.
Throws:
java.io.IOException - If an error occurs.

_writeAssociation

private void _writeAssociation(org.tmapi.core.Association assoc)
                        throws java.io.IOException
Serializes an association.

Parameters:
assoc - The association to serialize.
Throws:
java.io.IOException - If an error occurs.

_writeOccurrence

private void _writeOccurrence(org.tmapi.core.Occurrence occ,
                              int pos)
                       throws java.io.IOException
Serializes an occurrence.

Parameters:
occ - The occurrence to serialize.
pos - The position of the occurrence within the parent container.
Throws:
java.io.IOException - If an error occurs.

_writeDatatyped

private void _writeDatatyped(org.tmapi.core.DatatypeAware obj)
                      throws java.io.IOException
Writes the value/datatype pair of an occurrence or variant.

Parameters:
obj - The construct to serialize.
Throws:
java.io.IOException - If an error occurs.

_writeName

private void _writeName(org.tmapi.core.Name name,
                        int pos)
                 throws java.io.IOException
Serializes a topic name.

Parameters:
name - The name to serialize.
pos - The position of the name within the parent container.
Throws:
java.io.IOException - If an error occurs.

_writeType

private void _writeType(org.tmapi.core.Typed typed)
                 throws java.io.IOException
Serializes the type of a typed Topic Maps construct.

Parameters:
typed - The typed Topic Maps construct from which the type should be serialized.
Throws:
java.io.IOException - If an error occurs.

_writeScope

private void _writeScope(org.tmapi.core.Scoped scoped)
                  throws java.io.IOException
Serializes the scope of a scoped Topic Maps construct. If the scope is unconstrained, this method does nothing.

Parameters:
scoped - The scoped Topic Maps construct.
Throws:
java.io.IOException - If an error occurs.

_writeLocator

private void _writeLocator(org.tmapi.core.Locator loc)
                    throws java.io.IOException
Serializes a locator. A normalized locator value is created which is serialized.

Parameters:
loc - The locator to serialize.
Throws:
java.io.IOException - If an error occurs.

_writeItemIdentifiers

private void _writeItemIdentifiers(org.tmapi.core.Construct tmo)
                            throws java.io.IOException
Serializes the item identifiers of the specified Topic Maps construct.

Parameters:
tmo - The Topic Maps construct to take the item identifiers from.
Throws:
java.io.IOException - If an error occurs.

_writeLocatorSet

private void _writeLocatorSet(java.lang.String localName,
                              java.util.Set<org.tmapi.core.Locator> locators)
                       throws java.io.IOException
Serializes the locators using the localName as element name.

If the set of locators is empty, this method does nothing.

Parameters:
localName - The element's name.
locators - The locators to serialize.
Throws:
java.io.IOException - If an error occurs.

_topicRef

private org.xml.sax.Attributes _topicRef(org.tmapi.core.Topic topic)
Returns attributes which contains a reference to the provided topic.

Parameters:
topic - The topic to which the reference should point to.
Returns:
Attributes with a topic reference.

_attributes

private org.xml.sax.Attributes _attributes(org.tmapi.core.Reifiable reifiable,
                                           int pos)
Returns attributes which contain the reifier (if any) and the number of the provided Topic Maps construct (not a topic).

Parameters:
reifiable - The Topic Maps construct.
pos - The position of the reifiable within the parent container.
Returns:
Attributes which contain a reference to the reifier (if any) and the number of the provided Topic Maps construct.

_addReifier

private void _addReifier(org.xml.sax.helpers.AttributesImpl attrs,
                         org.tmapi.core.Reifiable reifiable)
Adds a reference to the reifier of the Topic Maps construct to the provided attributes. If the Topic Maps construct has no reifier, the provided attributes are not modified.

Parameters:
attrs - The attributes.
reifiable - The reifiable Topic Maps construct.

_normalizeLocator

private java.lang.String _normalizeLocator(org.tmapi.core.Locator locator)
Normalizes the locator according to CXTM 3.19.

Parameters:
locator - The locator to normalize.
Returns:
A normalized representation of the locator.

_normalizeBaseLocator

private static java.lang.String _normalizeBaseLocator(java.lang.String baseLocator)
Normalizes the base locator according to the following procedure (CXTM 3.19 - 1.): [...] the base locator with any fragment identifier and query removed and any trailing "/" character removed.[...]

Parameters:
baseLocator -
Returns:

_reportInvalid

private static void _reportInvalid(java.lang.String msg)
Writes a warning msg to the log. This method is used to inform the user that the serialized topic map is not valid acc. to CXTM.

Parameters:
msg - The warning message.