com.luciad.format.xml.bind.schema.dataobject

LuciadFusionClass TLcdXMLDataModelBuilder

java.lang.Object

com.luciad.format.xml.bind.schema.dataobject.TLcdXMLDataModelBuilder

public class TLcdXMLDataModelBuilder
extends Object

Class that builds TLcdDataModels based on XML schemas. The main responsibility of this class is to create a data model that maps on the types of an XML schema. Data models created by this builder are annotated with TLcdXMLSchemaMappingAnnotation and TLcdXMLSchemaTypeMappingAnnotation.

The following example shows a typical usage of creating a data model from an XML schema, with some customizations:

   TLcdXMLDataModelBuilder xmlBuilder = new TLcdXMLDataModelBuilder();
   TLcdDataModelBuilder dataModelBuilder = new TLcdDataModelBuilder( "sample" );
   xmlBuilder.buildDataModel( dataModelBuilder, "http://www.luciad.com/samples.xml.customdomainclasses",
     Main.class.getResource( "/samples/xml/customdomainclasses/samples.xml.customdomainclasses.xsd" ).toString() );
   dataModelBuilder.typeBuilder( "_Model" ).instanceClass( Model.class );
   dataModelBuilder.typeBuilder( "AddressType" ).instanceClass( Address.class );
   TLcdDataModel dataModel = dataModelBuilder.createDataModel();
 

Note that this XML builder may override any settings that were already configured on the data model builder before it is passed to the XML builder. It is strongly advised to perform all customizations of the data model (e.g. configuration instance classes of types, as in the above example) after it has been configured by the XML builder.

An XML schema is mapped on a data model according to the following rules.

• For each type defined in the schema, a type is created in the data model. This type will have the same name as the XML schema type.
• Complex types are mapped on data object types (see TLcdDataType.isDataObjectType()), simple types on primitive types (see TLcdDataType.isPrimitive()).
• The following information of a complex type will be mapped on a corresponding property:
  • attributes (typically one property per attribute)
  • elements (typically one property per element declaration)
  • character content (one property)
  The order in which properties are defined is specified as follows: first the attributes, then the elements (in the order in which they are defined in the schema type) and finally character content. Because XML schema does not dictate an order for attributes, we need to provide one to have a well-defined property order. Therefore we sort attributes, first on namespaceURI, then on their local name. The convention is that attributes without a namespaceURI come first.
• Multi-valued elements (elements which have a maxOccurence larger than 1) are modeled as list properties (see TLcdDataProperty.CollectionType.LIST).
• Type inheritance in XML schema is directly mapped as type inheritance of data types. Two types that inherit from each other in XML schema will be mapped as two types that inherit from each other.
• All types will inherit the instance class from their parent type. The instance class for xsd:anyType is ILcdDataObject, for xsd:anySimpleType String.class.

Next to these basic rules, there are a number of additional rules to handle special cases.

• A choice of particles is mapped as a single property. The type of this property is the common super type of all choice elements. In case some particles are single-valued and other multi-valued, the type of the property will be TLcdCoreDataTypes.OBJECT_TYPE.
• In case the type is of mixed content, all elements and text content will be mapped onto a single list property of type Object.class.
• In XML schema, a restriction can be used to reduce to simplify the structure of a type, thereby even removing elements. Because of the substitution principle, this is not supported by the LuciadLightspeed meta model. Therefore, a restricted type is always mapped as type that declares no properties. All its properties are inherited from its parent.
• In case multiple global elements exist for a single type and all these elements are in the same substitution group, it is not possible to determine the name of an object given its type. Therefore an additional property with name "type" is added to carry this information. The type of this property is TLcdXMLBuiltInDataTypes.QName.
• Union types are mapped on the common super type of all their member types.
• The XLink::simpleLink attribute group is represented by two properties. The first (called 'linkInfo') is of type Object.class. It typically contains TLcdXLinkSimpleLink instances. The second property (called 'linkedObject') is also of type Object.class. This property will be populated during XLink resolution with the object to which the XLink points.

Instances of this class are not thread safe.

Since:

10.0

Constructor Summary

Constructors

Constructor and Description
TLcdXMLDataModelBuilder(ILcdXMLSchemaTypeMapping aSchemaTypeMapping) Creates a new XML data model builder.
TLcdXMLDataModelBuilder(TLcdDataModel... aDataModels) Creates a new XML data model builder.

Method Summary

Modifier and Type	Method and Description
void	buildDataModel(TLcdDataModelBuilder aModelBuilder, String aSystemId) Builds all types for the given model builder based on the schema located at the given system id.
void	buildDataModel(TLcdDataModelBuilder aModelBuilder, String aPublicId, String aSystemId) Builds all types for the given model builder based on the schema located at the given system id.
protected void	buildType(TLcdDataTypeBuilder aTypeBuilder, TLcdXMLSchemaTypeIdentifier aTypeId) Builds the type for the given XML type identifier.
TLcdDataModel	createDataModel(String aPublicId, String aSystemId) Creates a data model that maps on the schema with the given public id and system id.
TLcdDataModel	createDataModel(String aName, String aPublicId, String aSystemId) Creates data model for the schema with the given public id and system id.
static TLcdDataTypeBuilder	createDataObjectTypeForPrimitiveType(TLcdDataModelBuilder aBuilder, TLcdDataTypeBuilder aPrimitiveType) Builds a data object type for the given primitive type.
static TLcdDataType	getDataObjectTypeForPrimitiveType(TLcdDataType aPrimitiveType) In some cases, certain simple XML schema types have to be represented by two types: one primitive type and one data object type.
EntityResolver2	getEntityResolver() Returns the entity resolved that is used to resolve the schemas.
ILcdXMLSchemaTypeMapping	getSchemaTypeMapping() Returns the schema type mapping associated with this data model builder.
protected TLcdDataTypeBuilder	getTypeBuilder(TLcdDataModelBuilder aBuilder, TLcdXMLSchemaTypeIdentifier aTypeId) Returns the type builder for a given XML schema type.
void	setEntityResolver(EntityResolver2 aEntityResolver) Sets the entity resolver that is used to resolve the schemas.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TLcdXMLDataModelBuilder

public TLcdXMLDataModelBuilder(TLcdDataModel... aDataModels)

Creates a new XML data model builder. The given data models are used in case newly built types reference types from other data models.

Parameters:

aDataModels - a list of referenced data models

TLcdXMLDataModelBuilder

public TLcdXMLDataModelBuilder(ILcdXMLSchemaTypeMapping aSchemaTypeMapping)

Creates a new XML data model builder. The given type mapping is used to resolve XML schema types which are already mapped. This is for instance the case when a data model for a certain schema is built and that schema refers to other schemata for which data models have already been built.

Parameters:

aSchemaTypeMapping - the type mapping that is used to resolve XML schema types with

Method Detail

createDataModel

public TLcdDataModel createDataModel(String aPublicId,
                                     String aSystemId)

Creates a data model that maps on the schema with the given public id and system id. Note that creation of the data model may trigger creation of dependent data models. This occurs when for a certain dependent data model no mapping was given when this object was constructed. The name of the returned data model will be equal to the given public id.

The public identifier, also known as namespace URI, is the globally unique name to identify the schema, and should be a valid URI (e.g. 'http://www.opengis.net/gml/3.2' for the GML schema). The system id points to a resource, usually in the classpath, on the local system, or on the Internet, where the schema can be found (e.g. 'net/opengis/gml/3.2.1/gml.xsd' for a GML schema in the classpath).

Note that the given public id can be null. In that case, the name of the returned data model will be equal to the target name space of the schema with the given system id.

The EntityResolver2 instance of this builder is used to map the schema (public id / system id) to an InputSource that can be decoded and interpreted by this builder.

Parameters:

aPublicId - the public id (namespaceURI) of the schema for which a data model is to be built

aSystemId - the system id (location) of the schema for which a data model is to be built

Returns:

a data model for the given schema

See Also:

setEntityResolver(org.xml.sax.ext.EntityResolver2)

createDataModel

public TLcdDataModel createDataModel(String aName,
                                     String aPublicId,
                                     String aSystemId)

Creates data model for the schema with the given public id and system id. Note that creation of the data model may trigger creation of dependent data models. This occurs when for a certain dependent data model no mapping was given when this object was constructed.

The public identifier, also known as namespace URI, is the globally unique name to identify the schema, and should be a valid URI (e.g. 'http://www.opengis.net/gml/3.2' for the GML schema). The system id points to a resource, usually in the classpath, on the local system, or on the Internet, where the schema can be found (e.g. 'net/opengis/gml/3.2.1/gml.xsd' for a GML schema in the classpath).

Note that the given public id can be null. In that case, the name of the returned data model will be equal to the target name space of the schema with the given system id.

The EntityResolver2 instance of this builder is used to map the schema (public id / system id) to an InputSource that can be decoded and interpreted by this builder.

Parameters:

aName - the name of the data model that is to be built

aPublicId - the public id (namespaceURI) of the schema for which a data model is to be built.

aSystemId - the system id (location) of the schema for which a data model is to be built

Returns:

a data model for the given schema

See Also:

setEntityResolver(org.xml.sax.ext.EntityResolver2)

getEntityResolver

public EntityResolver2 getEntityResolver()

Returns the entity resolved that is used to resolve the schemas.

Returns:

the entity resolver that is used to resolve the XML schemas

See Also:

setEntityResolver(EntityResolver2)

setEntityResolver

public void setEntityResolver(EntityResolver2 aEntityResolver)

Sets the entity resolver that is used to resolve the schemas.

The EntityResolver2 is responsible for mapping the schema identifier, either public or system id, to an InputSource that can be decoded and interpreted by this builder.

Parameters:

aEntityResolver - the entity resolver that is to be used to resolve the XML schemas

See Also:

getEntityResolver()

buildDataModel

public void buildDataModel(TLcdDataModelBuilder aModelBuilder,
                           String aSystemId)

Builds all types for the given model builder based on the schema located at the given system id. This never triggers the creation of dependent data models. This method is especially useful in case mutually dependent models need to be built of which some are automatically defined based on a schema and others are manually constructed.

This builder may override any settings that were already configured on aModelBuilder. It's strongly advised to perform all customizations of the data model (e.g. configuring instance classes of types) after this method has been called.

The EntityResolver2 instance of this builder is used to map the schema (public id / system id) to an InputSource that can be decoded and interpreted by this builder.

Parameters:

aModelBuilder - the model builder for which to create all the types

aSystemId - the system id (location) of the schema to build

See Also:

setEntityResolver(org.xml.sax.ext.EntityResolver2)

buildDataModel

public void buildDataModel(TLcdDataModelBuilder aModelBuilder,
                           String aPublicId,
                           String aSystemId)

Builds all types for the given model builder based on the schema located at the given system id. This never triggers the creation of dependent data models. This method is especially useful in case mutually dependent models need to be built of which some are automatically defined based on a schema and others are manually constructed.

This builder may override any settings that were already configured on aModelBuilder. It's strongly advised to perform all customizations of the data model (e.g. configuring instance classes of types) after this method has been called.

The public identifier, also known as namespace URI, is the globally unique name to identify the schema, and should be a valid URI (e.g. 'http://www.opengis.net/gml/3.2' for the GML schema). The system id points to a resource, usually in the classpath, on the local system, or on the Internet, where the schema can be found (e.g. 'net/opengis/gml/3.2.1/gml.xsd' for a GML schema in the classpath).

The EntityResolver2 instance of this builder is used to map the schema (public id / system id) to an InputSource that can be decoded and interpreted by this builder.

Parameters:

aModelBuilder - the model builder for which to create all the types

aPublicId - the public id (namespace) of the schema to build

aSystemId - the system id (location) of the schema to build

See Also:

setEntityResolver(org.xml.sax.ext.EntityResolver2)

getTypeBuilder

protected TLcdDataTypeBuilder getTypeBuilder(TLcdDataModelBuilder aBuilder,
                                             TLcdXMLSchemaTypeIdentifier aTypeId)

Returns the type builder for a given XML schema type. Override this method to customize the mapping from XML schema type to data type. Note that this method does not build the type. It merely returns a TLcdDataTypeBuilder.

Parameters:

aBuilder - the data model builder that can be used to create the type builder

aTypeId - the identifier of the XML schema type for which the type builder is to be returned

Returns:

a type builder for the given XML schema type

See Also:

buildType(TLcdDataTypeBuilder, TLcdXMLSchemaTypeIdentifier)

buildType

protected void buildType(TLcdDataTypeBuilder aTypeBuilder,
                         TLcdXMLSchemaTypeIdentifier aTypeId)

Builds the type for the given XML type identifier. Override this method to customize the type mapping for a type.

Parameters:

aTypeBuilder - the type builder for the type that is to be built

aTypeId - the XML type identifier of the type that is to be built

getSchemaTypeMapping

public ILcdXMLSchemaTypeMapping getSchemaTypeMapping()

Returns the schema type mapping associated with this data model builder.

Returns:

the schema type mapping associated with this instance

getDataObjectTypeForPrimitiveType

public static TLcdDataType getDataObjectTypeForPrimitiveType(TLcdDataType aPrimitiveType)

In some cases, certain simple XML schema types have to be represented by two types: one primitive type and one data object type. This is for instance the case when a complex schema type extends from a simple XML schema type. In the LuciadLightspeed meta model it is not possible to directly represent this. Data object types can't extend from primitive types. To cope with this, such schema types are represented by two different types: one that is a primitive type and another one that is a data object type. The latter type has a single property of the former type. This method returns the data object type given the primitive type.

Parameters:

aPrimitiveType - a primitive type representing a simple schema type for which to return the corresponding data object type

Returns:

the data object type that corresponds to the given type

See Also:

createDataObjectTypeForPrimitiveType(TLcdDataModelBuilder, TLcdDataTypeBuilder)

createDataObjectTypeForPrimitiveType

public static TLcdDataTypeBuilder createDataObjectTypeForPrimitiveType(TLcdDataModelBuilder aBuilder,
                                                                       TLcdDataTypeBuilder aPrimitiveType)

Builds a data object type for the given primitive type.

Parameters:

aBuilder - the data model builder for the data model

aPrimitiveType - a builder for the primitive type for which a data object type is to be created

Returns:

a data object type with a single property of the given type

See Also:

getDataObjectTypeForPrimitiveType(TLcdDataType)