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

Class 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 Details

    • 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 Details

    • 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:

    • 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:

    • 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

      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:

    • 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:

    • 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:

    • 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

      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

      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: