In addition to the XML instance documents that store the actual data, data binding uses two other types of documents:
Mapping files control which data is exchanged between system, and which data is omitted
XML Schemas describe the structure of the data, and can be used to validate XML instance documents
Mapping Files
When you exchange data between the Oracle ATG Web Commerce platform and a remote system, you will typically want to exclude certain data. For example, the Oracle ATG Web Commerce platform profile usually includes Dynamo-specific information about scenarios.
When you create an XML instance document from data in a repository, Dynamo includes and excludes certain properties by default:
If a property is readable and does not point to another item descriptor, it is included
If a property is readable, points to another item descriptor, and its
cascadeattribute is set to"delete", it is includedAll other properties are excluded
For more information about the default inclusion rules, see the isIncludeProperty() method of the atg.repository.xml.RepositoryXMLTools class in the ATG Platform API Reference. RepositoryXMLTools is a utilities class with various methods for encoding and decoding item descriptors, property names, and mapping files to and from XML-compatible namespaces and identifiers.
If you want more explicit control over the properties that are written out, you can use a mapping file. A mapping file specifies what properties to include or exclude when moving data between a repository and an XML instance document, and provides a way to map the names of Dynamo properties to their equivalents in a remote system. For example, a Dynamo profile might have an email property that stores the same information as the Email_Address attribute on another system.
The following is the Document Type Definition (DTD) for mapping files:
<!-- This is the XML DTD for ItemDescriptorMapping --> <!-- Specifies what properties in an item-descriptor should be included in another datamodel. A given mapping file gives the ability to control what properties are included/excluded from the datamodel control how names in one model relate to names in another model --> <!-- Defines the mapping for a given item-descriptor. The name and repository property are required properties. The name property corresponds to the name of a given item-descriptor. The repository should be the Nucleus path to a particular repository. For example, if an item-descriptor mapping was going to point to the the ProfileAdapterRepository located at /atg/userprofiling/ProfileAdapterRepository Nucleus path, then the repository property should be the string "/atg/userprofiling/ProfileAdapterRepository". The default-include exists to indicate whether or not properties that are associated with this item-descriptor should be included by default or not. This property defaults to true. So, if a property is does not explicitly appear as a child property element, it is assumed to be included in the data model to be exported. --> <!ELEMENT item-descriptor (property*)> <!ATTLIST item-descriptor repository-path CDATA #IMPLIED name CDATA #IMPLIED default-include (true | false) #IMPLIED> <!-- A property element controls two aspects of including a property in a given mapping; whether the property should be included or not and what the targetName for the target datamodel should be. The name attribute corresponds to the name of a property defined for a given item-descriptor. The include attribute is optional. If it is not specified, the value is obtained from the default-include value of the enclosing item-descriptor. --> <!ELEMENT property (item-descriptor*)> <!ATTLIST property name CDATA #REQUIRED include (true | false) #IMPLIED targetName CDATA #IMPLIED>
The following is a sample mapping file for the Dynamo profile repository:
<!DOCTYPE item-descriptor SYSTEM "http://www.atg.com/dtds/databinding/itemDescriptorMapping_1.0.dtd"> <item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="user" default-include="true"> <property name="homeAddress" include="true"> <item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="contactInfo" default-include="false"> </item-descriptor> </property> <property name="slotInstances" include="false"/> <property name="scenarioInstances" include="false"/> <property name="mailings" include="false"/> <property name="scenarioValues" include="false"/> <property name="firstName" targetName="first_name"/> </item-descriptor>
The data binding services all work with a single item descriptor and its properties (including any other item descriptors that are properties of the main item descriptor). The mapping file uses the item-descriptor tag to specify the repository and item descriptor that the mapping file is associated with:
<item-descriptor
repository-path="/atg/userprofiling/ProfileAdapterRepository"
name="user"
default-include="true">The default-include attribute specifies whether the item’s properties should be included or excluded by default. This value can be overridden for individual properties. In this mapping file, various scenario-related properties are excluded:
<property name="slotInstances" include="false"/>
<property name="scenarioInstances" include="false"/>
<property name="mailings" include="false"/>
<property name="scenarioValues" include="false"/>If a property is an item descriptor, there must be an item-descriptor tag inside the property tag. For example, the homeAddress property points to a contactInfo item descriptor:
<property name="homeAddress" include="true">
<item-descriptor
repository-path="/atg/userprofiling/ProfileAdapterRepository"
name="contactInfo"
default-include="false">
</item-descriptor>
</property>Note that the item-descriptor tag for contactInfo can have property tags within it. The nesting of property tags and item-descriptor tags must reflect the hierarchy of the item descriptors in the repository. If you do not include a property tag for a property that points to an item descriptor (such as the homeAddress property shown above), the Oracle ATG Web Commerce platform uses the default inclusion rules for determining which properties of that item descriptor to include.
Finally, the property tag has an optional targetName attribute for mapping the property name to its corresponding name in the remote system:
<property name="firstName" targetName="first_name"/>Managing Mapping Files for Repository Item Descriptors
The Oracle ATG Web Commerce platform includes two classes that help identify the appropriate mapping file for each item descriptor that you want to use with the repository2xml data binding facility. These classes are used by Web Service clients:
atg.repository.xml.ItemDescriptorMapping
atg.repository.xml.ItemDescriptorMappingManagerItemDescriptorMapping
An ItemDescriptorMapping is a simple bean that holds information about relationships between repository item descriptors and mapping files. The mapping files describe what properties are to be exposed when an item from that item descriptor is to be transformed into XML. Each ItemDescriptorMapping pertains to exactly one repository: for example, you would have a UserProfileItemDescriptorMapping, or a PromotionItemDescriptorMapping component, each of which would provide a list of item descriptor names from the corresponding repository and their corresponding mapping files.
An ItemDescriptorMapping contains only three properties:
Property Name | Type | Description |
|---|---|---|
|
| The path to the repository supported by this |
|
| The path to the repository supported by this |
|
| A map where the keys are item descriptor names and the values are locations of mapping files, relative to the configuration path, which provide rules for how an item of the keyed item descriptor name appears in XML format |
Here is an example properties file for an ItemDescriptorMapping that supports the profile repository:
$class=atg.repository.xml.ItemDescriptorMapping repository=/atg/userprofiling/ProfileAdapterRepository itemDescriptorMapping=\ user=/atg/userprofiling/userMapping.xml,\ contactInfo=/atg/userprofiling/contactInfoMapping.xml
Here we see the there are two entries in the itemDescriptorMapping property, one for the user item descriptor, and one for the contactInfo item descriptor.
Whenever an entry is added to the itemDescriptorMapping property, whether through a properties file, or directly in code, the ItemDescriptorMapping checks to make sure that the key of the entry, the item descriptor name, resolves to an actual item descriptor of the repository this service is configured to support. If any item descriptor name does not resolve, a RepositoryException is thrown.
By themselves, ItemDescriptorMappings do no work. They simply hold state. In order to put them to work, you must add them to the ItemDescriptorMappingManager, described below.
ItemDescriptorMappingManager
Class |
|
Component |
|
Module |
|
The ItemDescriptorMappingManager serves as a registry of ItemDescriptorMappings. It is through this service that you obtain mapping files for all repository and item descriptor combinations. The mapping files are registered in the itemDescriptorMappings property of the ItemDescriptorMappingManager component:
Property Name | Type | Description |
|---|---|---|
|
| An array of |
Here is an example properties file:
$class=atg.repository.xml.ItemDescriptorMappingManager itemDescriptorMappings=\ /atg/userprofiling/UserProfileItemMapping,\ /atg/userprofiling/ContactInfoItemMapping
The following ItemDescriptorMappingManager methods can be used to retrieve mapping files:
getMappingFileName(String pRepositoryPath, String pItemDescriptorName)
Using the given repository path and item descriptor name, returns the mapping file for that given path:name combination, or null if none exists.
getMappingFileName(Repository pRepository, String pItemDescriptorName)Using the given repository and item descriptor name, returns the mapping file for that given repository:name combination, or null if none exists.
When you use the atg.repository.xml.GetService to get repository items in XML form, you can pass along a mapping file name using these ItemDescriptorMappingManager methods. Using the ItemDescriptorMappingManager, you can centralize all mapping files in one component for all item descriptors, and just call that to determine which mapping file to use for a given item descriptor.
XML Schemas
The Oracle ATG Web Commerce platform provides tools for creating and working with XML Schemas for the XML documents written and read by the various data binding services. XML Schema is a schema language for XML that describes and restricts what a particular XML instance document might look like. An XML document can be validated against an XML Schema to check that it conforms to that Schema. Additionally, many developer tools make use of XML Schemas. For example, some tools provide a visual representation of XML Schemas to allow mapping from one XML Schema to another. See Generating XML Schemas.
Generating XML Schemas
The Oracle ATG Web Commerce platform provides a command-line tool that generates an XML Schema for a given item descriptor. The XML generated by the Get data binding service conforms to this Schema. Similarly, the XML Schema describes an instance document that is capable of being processed by the Add, Update, or Remove service.
The command-line tool is named generateXMLSchema.sh (on Unix) or generateXMLSchema.bat (on Windows) and is found in the <ATG10dir>/home/bin directory. The following table lists the arguments that can be supplied to this command:
Argument | Description |
|---|---|
| Nucleus path to the repository containing the item descriptor that the XML Schema is being generated for. Required. |
| Name of the item-descriptor that the XML Schema is being generated for. Required. |
| Specifies a directory to save the XML Schema to. This directory is in addition to the directory specified by the |
| If set to |
| Specifies the mapping file to use. Not required. |
| Nucleus path to the Schema Generator component. If omitted, defaults to |
| Specifies the set of modules to use in the repository definition. Required. |
| Prints out a usage message. Not required. |
The following command generates an XML Schema for the user item descriptor of the default Dynamo profile repository, using the properties defined in the repository definition file for the DSSJ2EEDemo application module (and the modules required by the DSSJ2EEDemo module):
generateXMLSchema -m DSSJ2EEDemo –repository
/atg/userprofiling/ProfileAdapterRepository -itemDescriptor userThe generated XML Schema is saved by the Schema Manager specified by the schemaManager property of the Schema Generator component. The default Schema Generator is the /atg/repository/xml/SchemaGenerator component, and its schemaManager property points by default to the /atg/repository/xml/SchemaManager component. Note that if the user item descriptor contains other item descriptors as properties, the generated Schema will reflect these other item descriptors as well.
To save the Schema to the current working directory in addition to the directory determined by the XMLSchemaFileDirectory property of the Schema Manager:
generateXMLSchema -m DSSJ2EEDemo –repository
/atg/userprofiling/ProfileAdapterRepository -itemDescriptor user
-outputDirectory .Managing Schemas and Mapping Files
As mentioned above, the default Schema Generator has a schemaManager property that points to the /atg/repository/xml/SchemaManager component. In addition, each of the data binding service components (described below) has an XMLSchemaManager property that points to this SchemaManager component. This component is of class atg.repository.xml.XMLSchemaManager. This class, which extends atg.repository.databinding.MappingManager, manages XML Schemas and mapping files. For example, this class has mappingFileDirectories and XMLSchemaFileDirectory properties that specify the directories where mapping files and Schemas are stored. Note that Schemas must have the extension .xsd and mapping files must have the extension .xml.
For example, suppose you want to generate an XML Schema and specify a mapping file to use. The command would look something like this:
generateXMLSchema -m DSSJ2EEDemo –repository
/atg/userprofiling/ProfileAdapterRepository -itemDescriptor user
-mappingFile profileMapping.xml
Notice that only the name of the mapping file is specified, not the entire pathname. The Schema Manager’s mappingFileDirectories property points to the directories where the mapping file should be stored.
PropertyElementNameSeparator
The repository2xml feature specifies a separator character, which functions to separate a property name from the name of its item descriptor. By default, this separator character is . (dot). The default separator character may not work for you if, for example, you use composite repository IDs that also use the . (dot) character to separate elements of the repository ID. You can specify a different separator character in the propertyElementNameSeparator property of the /atg/repository/xml/RepositoryXMLTools component.
Item References
In a repository schema, a map, set, list, or array property can point to a single other item using the itemRef attribute. The value assigned to the itemRef attribute concatenates the item descriptor name, the property element separator, and the repository ID. In the following example, the item descriptor name is role, the property element separator is . (dot) and the repository ID is 2900004:
<user:itemRef itemRef="role.2900004"/>The following is a more extended example, showing the context for the itemRef attribute:
<user:user xmlns:user=http://www.atg.com/ns/profileMapping/UserProfiles/user xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:schemaLocation="http://www.atg.com/ns/profileMapping/UserProfiles/user profileMapping+UserProfiles+user.xsd " ID="user747"> <user:homeAddress itemRef="contactInfo.1040001"/> <user:roles> <user:itemRef itemRef="role.2900004"/> <user:itemRef itemRef="role.3000008"/> </user:roles> </user:user>
