org.electrocodeogram.cpc.core.api.provider.xml
Interface IMappingProvider

All Superinterfaces:

IProvider

public interface IMappingProvider
extends IProvider

A mapping provider implements means of mapping IStatefulObject data to and from a string representation. It provides "serialisation" functionality for CPC data objects.

The format of the string representation is not specified and is entirely up to the implementation.
However, each mapping provider should add some kind of special "magic" to the header which allows itself to quickly decide whether a given string is likely to be in a mapping format which it supports.

NOTE: When mapping an external string representation to CPC objects it is recommended to use the IMappingRegistry instead of directly accessing the default IMappingProvider. This ensures that "legacy" mappings can still be read, even if the default mapping provider is changed.

Author:

vw

See Also:

IMappingRegistry, MappingStore

Method Summary

java.lang.String	extractCloneObjectUuidFromString(java.lang.String data) Takes a string representation which matches the ones generated by mapToString(MappingStore, boolean) and extracts the ICloneObject.getUuid() of the main object, if it exists and is of type ICloneObject.
boolean	isSupportedMappingFormat(java.lang.String data) Does a quick check to see whether the given cpc data mapping is in a format which this mapping provider can understand.
MappingStore	mapFromString(java.lang.String data) Takes a string representation which matches the ones generated by mapToString(MappingStore, boolean) and builds a MappingStore containing the IStatefulObject which the given mapping represents.
java.lang.String	mapToString(MappingStore mappingStore, boolean addHeaders) Takes a list of IStatefulObjects and maps them into a string representation.

Methods inherited from interface org.electrocodeogram.cpc.core.api.provider.IProvider

getProviderName, toString

Method Detail

isSupportedMappingFormat

boolean isSupportedMappingFormat(java.lang.String data)

Does a quick check to see whether the given cpc data mapping is in a format which this mapping provider can understand.
Typically this method will only check some magic part of the data header and will not check the entire mapping document for integrity violations.

It is up to the implementation how to handle this method call.
However, this is a potentially very frequently called method and any implementation should try to optimise the performance of this method as far as possible.

Parameters:

data - the cpc data mapping to check, never null.

Returns:

true if this IMappingProvider is compatible with the given mapping format, false otherwise. A return value of true does not automatically indicate that the given mapping data is well formed and valid.

mapToString

java.lang.String mapToString(MappingStore mappingStore,
                             boolean addHeaders)
                             throws MappingException

Takes a list of IStatefulObjects and maps them into a string representation.
The MappingStore and the contained IStatefulObjects may not be modified in any way by this method.

Parameters:

mappingStore - a MappingStore which represents the IStatefulObjects which should be mapped to a string representation, never null.

addHeaders - whether a full set of headers should be added (true) or not (false). Some string representations may have special nesting semantics. This parameter can be used to indicate whether the result is intended to be nested within another string representation of the same type or whether it is meant to be used standalone.
I.e. for a XML mapping, this might turn the xml preamble on or off.

Returns:

string representation of the given stateful objects, never null.

Throws:

MappingException - if the data can not be mapped

mapFromString

MappingStore mapFromString(java.lang.String data)
                           throws MappingException

Takes a string representation which matches the ones generated by mapToString(MappingStore, boolean) and builds a MappingStore containing the IStatefulObject which the given mapping represents.

Parameters:

data - a valid string representation which encodes IStatefulObject data, never null.

Returns:

a MappingStore with IStatefulObjects corresponding to the given mapping data, never null.

Throws:

MappingException - if the given string representation is not valid

extractCloneObjectUuidFromString

java.lang.String extractCloneObjectUuidFromString(java.lang.String data)
                                                  throws MappingException

Takes a string representation which matches the ones generated by mapToString(MappingStore, boolean) and extracts the ICloneObject.getUuid() of the main object, if it exists and is of type ICloneObject.
The main object is the special object which was designated as parent object on creation of the string representation or the object, if there is exactly one object in the mapping.
Typically this is an ICloneFile file UUID.

Convenience method which is provided for performance reasons in situations where only the UUID of the main entry is of interest and where parsing of the entire file is therefore not needed.
It is up to the implementation to decide whether to implement this method separately or whether calls to this method should simply be mapped to mapFromString(String).
This API makes no guarantee that using this method does provide any performance gain. Use of this method should be considered as an optimisation hint for the implementation.

An implementation is not required to do a full validity check of the given data structure. Thus there may be corrupted data structures for which a call to this method succeeds but a call to mapFromString(String) fails.

Parameters:

data - a valid string representation which encodes IStatefulObject data, never null.

Returns:

the ICloneObject.getUuid() of the main object of this mapping structure or NULL if the given mapping structure contains multiple elements and no element was designated as parent element or if the main element is not of type ICloneObject.

Throws:

MappingException - if the given mapping structure is not valid