atg.repository.databinding

Class MappingManager

java.lang.Object

atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

atg.nucleus.GenericService

atg.repository.databinding.MappingManager

All Implemented Interfaces:

atg.core.logging.Logging, atg.core.logging.TraceLogging, atg.naming.AbsoluteNameable, NameContextBindingListener, NameContextElement, atg.naming.NameContextParentable, NameResolver, AdminableService, atg.nucleus.Configured, ApplicationLogging, atg.nucleus.logging.ApplicationLoggingSender, atg.nucleus.logging.TraceApplicationLogging, VariableArgumentApplicationLogging, ComponentNameResolver, Service, ServiceListener, java.util.EventListener, org.xml.sax.ErrorHandler

public class MappingManager
extends GenericService
implements org.xml.sax.ErrorHandler

This class maintains a pointer to a directory that contains mapping files that live on a virtual file system. Users can request access to one of these mapping files by logical name. This logical name corresponds to the name of the mapping file itself. The contents of the file will be returned to the user as a parsed tree that contains ItemMappingElementItemMappingElements and PropertyMappingElementPropertyMappingElements.

The mapping files are expected to conform to the itemDescriptorMapping DTD.

As an example, if a user wanted to specify a mapping file for the Profile item-descriptor that lives in the /atg/userprofiling/ProfileAdapterRepository and declare that the "scenarios" property should not be included in the datamodel to be exported then the following would be done.

• Define the mapping file. The mapping file would look like
  <item-descriptor repository="/atg/userprofiling/ProfileAdapterRepository" name="profile">
  <property name="scenarios" include="false"/>
  
  The file could be named ProfileMapping
• Place the mapping file into the directory pointed to by this Mapping Manager component. For example, this could be {atg.dynamo.root}/mappingFiles
• Applications that want access to this mapping file would invoke the #getMapping(String)getMapping() method on this class, passing in the name of the mapping file as the argument, i.e. ProfileMapping. This component would then return the contents of the file parsed as set of Java objects. The top level object returned would be an instance of the ItemMappingElement class.

See Also:

ItemMappingElement, PropertyMappingElement

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CLASS_VERSION
static java.lang.String	DEFAULT_INCLUDE_ATTR Whether or not properties should be included in the exported data model by default.
static java.lang.String	INCLUDE_ATTR Name of the property that controls whether or not a property should be included in a particular data model.
static java.lang.String	ITEM_DESC_NAME Name of the attribute property that indicates the name of the item-desc
static java.lang.String	ITEM_DESC_TAG_NAME Identifier for the item-descriptor tag that appears in a mapping file
static java.lang.String	NAME_ATTR The attribute property that indicates the property for the item-descriptor
static java.lang.String	PROPERTY_TAG_NAME Identifier for the property tag that appears in a mapping file
static java.lang.String	REPOSITORY_PATH Name of the attribute property that points to the path of a repository
static java.lang.String	TARGET_NAME_ATTR The attribute property that indicates the property for the remote data model.

Fields inherited from class atg.nucleus.GenericService

SERVICE_INFO_KEY

Fields inherited from interface atg.nucleus.logging.TraceApplicationLogging

DEFAULT_LOG_TRACE_STATUS

Fields inherited from interface atg.nucleus.logging.ApplicationLogging

DEFAULT_LOG_DEBUG_STATUS, DEFAULT_LOG_ERROR_STATUS, DEFAULT_LOG_INFO_STATUS, DEFAULT_LOG_WARNING_STATUS

Constructor Summary

Constructors

Constructor and Description
MappingManager()

Method Summary

Modifier and Type	Method and Description
atg.repository.databinding.ItemMappingElement	buildItemMappingElement(org.w3c.dom.Element pItemElement, RepositoryItemDescriptor pDescriptor) This method will build a single node in the mapping configuration tree.
atg.repository.databinding.PropertyMappingElement	buildPropertyMappingElement(org.w3c.dom.Element pPropertyElement, RepositoryItemDescriptor pDescriptor) This method will build a single PropertyMappingElement object which reflects all of the information contained within the pPropertyElement parameter.
void	clearCache() This method can be used to clear the cache that is maintained internally by this class.
void	doStartService() This method will determine if the mapping files pointed to by this component should be parsed on start-up.
void	error(org.xml.sax.SAXParseException pException) Register this class to handle parse exceptions during a mapping file.
void	fatalError(org.xml.sax.SAXParseException pException) Register this class to handle parse exceptions during a mapping file.
protected org.w3c.dom.Document	getDocumentObject(java.io.InputStream pInputStream) Utility method which will return the inputstream as a Document object to us.
protected RepositoryItemDescriptor	getItemDescriptor(org.w3c.dom.Element pElement) This method returns the item-descriptor that is referred to by the top-level item-descriptor mapping element.
RepositoryItemDescriptor	getItemDescriptor(Repository pRepository, org.w3c.dom.Element pElement) This method will retrieve the item-descriptor that is specified on the element passed to this method that is defined in the repository passed to this method.
atg.repository.databinding.ItemMappingElement	getMapping(java.lang.String pMappingFileName) This method will retrieve a parsed tree of mapping file information for a given mapping file.
java.io.File[]	getMappingFileDirectories() A set of directories can be specified that mapping files will be obtained from.
java.io.File	getMappingFileDirectory() Deprecated. This property has been deprecated, the mappingFileDirectories property should be used instead since it allows the user to specify multiple directories.
java.lang.String	getMappingFileExtension() The extension that is expected to be on mapping files.
java.lang.String[]	getMappingFileNames() Rturns a list of the mapping files that this component points to.
protected java.io.InputStream	getMappingInputStream(java.lang.String pMappingFileName) This method returns the input stream that is associated with the specified mapping file.
Repository	getRepository(org.w3c.dom.Element pElement) Given an element, try to extract the path to a Nucleus repository component.
boolean	isItemDescriptorValidForProperty(RepositoryItemDescriptor pItemDescriptor, java.lang.String pPropertyName, RepositoryItemDescriptor pMapElementItemDescriptor) This method determines if the item-descriptor which was specified in the mapping file refers to an item-descriptor type that is valid for the target property on the item-descriptor defined in the repository.
boolean	isParseMappingsOnStartup() Whether or not the mapping files that this component points to should be parsed on start-up.
atg.repository.databinding.ItemMappingElement	newItemMappingElement() Creates a new ItemMappingElement object.
atg.repository.databinding.PropertyMappingElement	newPropertyMappingElement() This method creates a new PropertyMappingElement.
void	parseAllFiles() Parse all the mapping files that are pointed to by this component.
void	populateItemMappingProperties(atg.repository.databinding.ItemMappingElement pItemMapping, org.w3c.dom.Element pItemElement, RepositoryItemDescriptor pDescriptor) This method populates the ItemMappingElement object passed to it with two properties the repository defined on the pElement the item-descriptor defined on the pElement If the repository or item-descriptor is not defined on the pElement passed to this method then the values will be set to null.
void	populatePropertyMappingProperties(atg.repository.databinding.PropertyMappingElement pPropertyMapping, org.w3c.dom.Element pElement) This method populates the PropertyMappingElement object passed to it with three properties the include information from the pElement That is, whether or not the property associated with this object should be included in the externalized data-model the property name as it should appear in the item-descriptor (name) the property name as it should appear in the target datamodel Any values not specified in the xml mapping file will be set to null.
void	setMappingFileDirectories(java.io.File[] pMappingFileDirectories) Sets property MappingFileDirectories
void	setMappingFileDirectory(java.io.File pMappingFileDirectory) Set the mappingFileDirectory property.
void	setMappingFileExtension(java.lang.String mappingFileExtension) Sets the mappingFileExtension.
void	setParseMappingsOnStartup(boolean pParseMappingsOnStartup) Set the parseMappingsOnStartup property.
void	warning(org.xml.sax.SAXParseException pException) Register this class to handle parse exceptions during a mapping file.

Methods inherited from class atg.nucleus.GenericService

addLogListener, createAdminServlet, doStopService, getAbsoluteName, getAdminServlet, getAdminServletOutputStreamEncoding, getLoggingForVlogging, getLogListenerCount, getLogListeners, getName, getNameContext, getNucleus, getRoot, getServiceConfiguration, getServiceInfo, isAdminServletUseServletOutputStream, isLoggingDebug, isLoggingError, isLoggingInfo, isLoggingTrace, isLoggingWarning, isRunning, logDebug, logDebug, logDebug, logError, logError, logError, logInfo, logInfo, logInfo, logTrace, logTrace, logTrace, logWarning, logWarning, logWarning, nameContextElementBound, nameContextElementUnbound, removeLogListener, reResolveThis, resolveName, resolveName, resolveName, resolveName, sendLogEvent, setAdminServletOutputStreamEncoding, setAdminServletUseServletOutputStream, setLoggingDebug, setLoggingError, setLoggingInfo, setLoggingTrace, setLoggingWarning, setNucleus, setServiceInfo, startService, stopService, toString

Methods inherited from class atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

vlogDebug, vlogDebug, vlogDebug, vlogDebug, vlogDebugTrace, vlogError, vlogError, vlogError, vlogError, vlogInfo, vlogInfo, vlogInfo, vlogInfo, vlogTrace, vlogTrace, vlogTrace, vlogTrace, vlogWarning, vlogWarning, vlogWarning, vlogWarning

Methods inherited from class java.lang.Object

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

Field Detail

CLASS_VERSION

public static java.lang.String CLASS_VERSION

ITEM_DESC_TAG_NAME

public static final java.lang.String ITEM_DESC_TAG_NAME

Identifier for the item-descriptor tag that appears in a mapping file

See Also:

Constant Field Values

PROPERTY_TAG_NAME

public static final java.lang.String PROPERTY_TAG_NAME

Identifier for the property tag that appears in a mapping file

See Also:

Constant Field Values

REPOSITORY_PATH

public static final java.lang.String REPOSITORY_PATH

Name of the attribute property that points to the path of a repository

See Also:

Constant Field Values

ITEM_DESC_NAME

public static final java.lang.String ITEM_DESC_NAME

Name of the attribute property that indicates the name of the item-desc

See Also:

Constant Field Values

NAME_ATTR

public static final java.lang.String NAME_ATTR

The attribute property that indicates the property for the item-descriptor

See Also:

Constant Field Values

TARGET_NAME_ATTR

public static final java.lang.String TARGET_NAME_ATTR

The attribute property that indicates the property for the remote data model.

See Also:

Constant Field Values

INCLUDE_ATTR

public static final java.lang.String INCLUDE_ATTR

Name of the property that controls whether or not a property should be included in a particular data model.

See Also:

Constant Field Values

DEFAULT_INCLUDE_ATTR

public static final java.lang.String DEFAULT_INCLUDE_ATTR

Whether or not properties should be included in the exported data model by default.

See Also:

Constant Field Values

Constructor Detail

MappingManager

public MappingManager()

Method Detail

getMappingFileExtension

public java.lang.String getMappingFileExtension()

The extension that is expected to be on mapping files. Defaults to ".xml"

Returns:

String the extension for mapping files

setMappingFileExtension

public void setMappingFileExtension(java.lang.String mappingFileExtension)

Sets the mappingFileExtension.

Parameters:

mappingFileExtension - The mappingFileExtension to set

isParseMappingsOnStartup

public boolean isParseMappingsOnStartup()

Whether or not the mapping files that this component points to should be parsed on start-up. In a production site, the mapping files should be parsed on start-up so as to avoid the performance hit the first time that a mapping file is parsed. For a development situation, it might be desirable to not have the files parsed on start-up, thus enabling faster start-up times.

This property defaults to false.

Returns:

true if mapping files should be parsed on start-up.

setParseMappingsOnStartup

public void setParseMappingsOnStartup(boolean pParseMappingsOnStartup)

Set the parseMappingsOnStartup property.

Parameters:

pParseMappingsOnStartup -

getMappingFileDirectories

public java.io.File[] getMappingFileDirectories()

A set of directories can be specified that mapping files will be obtained from. If there are mapping files with the same name that appear in multiple directories, those mapping files will use XML Combination and be combined into a single mapping file.

This property should be used as opposed to the mappingFileDirectory because of the ability to specify multiple directories.

If values for this property are specified in addition to the mappingFileDirectory, then files will be obtained from both the directories associated with the mappingFileDirectories as well as the mappingFileDirectory property.

Returns:

File[] the set of directories that will be searched for mapping files.

setMappingFileDirectories

public void setMappingFileDirectories(java.io.File[] pMappingFileDirectories)

Sets property MappingFileDirectories

Parameters:

pMappingFileDirectories -

getMappingFileDirectory

public java.io.File getMappingFileDirectory()

Deprecated.

This property has been deprecated, the mappingFileDirectories property should be used instead since it allows the user to specify multiple directories.

The directory in which mapping files will be stored. When this component is asked to obtain a parsed mapping file, it will resolve the logical name for the mapping file relative to this directory.

Returns:

the mapping file directory

setMappingFileDirectory

public void setMappingFileDirectory(java.io.File pMappingFileDirectory)

Set the mappingFileDirectory property.

Parameters:

pMappingFileDirectory -

doStartService

public void doStartService()
                    throws ServiceException

This method will determine if the mapping files pointed to by this component should be parsed on start-up. If they should be parsed on start-up, then it will get a list of all files pointed to by this component and call getMapping() method with the file name thus placing them in the cache.

The list of files that are pointed to by this component is determined by invoking the getMappingFileNames() method.

Overrides:

doStartService in class GenericService

Throws:

ServiceException - if an error occurs

getMapping

public atg.repository.databinding.ItemMappingElement getMapping(java.lang.String pMappingFileName)
                                                         throws MappingException

This method will retrieve a parsed tree of mapping file information for a given mapping file. The parameter to this method should be the name of the file that the mapping file lives in. This filename is resolved relative to the mappingFileDirectory property on this class.

This method will check for a mapping file that lives in the cache keyed by pMappingFileName parameter. If no entry is found in the cache then this method will resolve the file and parse it into a configuration tree.

Parameters:

pMappingFileName - the name of the mapping file to parse relative to the mappingFileDirectory parameter.

Returns:

the top-leve ItemMappingElement that appears in the mapping file

Throws:

java.io.IOException - if an error occurs

MappingException - if an error occurs during the processing of a mapping file.

buildItemMappingElement

public atg.repository.databinding.ItemMappingElement buildItemMappingElement(org.w3c.dom.Element pItemElement,
                                                                             RepositoryItemDescriptor pDescriptor)
                                                                      throws MappingException,
                                                                             RepositoryException

This method will build a single node in the mapping configuration tree. First, it creates a new ItemMappingElement and then it parses the XML element passed in as the pItemElement parameter. It will call the populateItemMappingProperties() method to populate all of the properties from the pItemElement to the ItemMappingElement.

Finally, it will iterator over all the child element tags of pItemElement. For each child element which is a property tag it will ensure that property referred to by this child element is a legal property on the item-descriptor that the pItemElement referred to. If a legal property element is found, the buildPropertyMappingElement() method is called. The buildPropertyMappingElement() can recursively call the buildItemMappingElement() method thus allowing the creation of the entire mapping configuration tree.

When this method completes, a tree of objects that will be generated which reflects all of the mapping information from the mapping elements and the properties pointed to by each item-descriptor element will be verified to exist on the actual item-descriptor in the repository.

Parameters:

pItemElement - XML element from mapping configuration file

pDescriptor - item-descriptor referred to by the pItemElement

Returns:

created ItemMappingElement that reflects all information from the pItemElement.

Throws:

MappingException - if an error occurs

RepositoryException

buildPropertyMappingElement

public atg.repository.databinding.PropertyMappingElement buildPropertyMappingElement(org.w3c.dom.Element pPropertyElement,
                                                                                     RepositoryItemDescriptor pDescriptor)
                                                                              throws MappingException,
                                                                                     RepositoryException

This method will build a single PropertyMappingElement object which reflects all of the information contained within the pPropertyElement parameter.

This method will create a new PropertyMappingElement and then call the populatePropertyMappingProperties() method to copy properties from the pPropertyElement to the create PropertyMappingElement.

It will then walk all children element tags defined from the pPropertyElement. For each child tag, it will first ensure that the item-descriptor type mentioned in the element tag is assignable to the property. If it is, then the buildItemMappingElement method will be called.

Parameters:

pPropertyElement - the property element from the mapping config file

pDescriptor - the item-descriptor that the property referred to by the pPropertyElement refers to

Returns:

newly created PropertyMappingElement containing information copied from the pPropertyElement

Throws:

MappingException

RepositoryException

getMappingInputStream

protected java.io.InputStream getMappingInputStream(java.lang.String pMappingFileName)
                                             throws MappingException,
                                                    java.io.IOException

This method returns the input stream that is associated with the specified mapping file.

Parameters:

pMappingFileName - the name of the mapping file to return the InputStream to. This filename is resolved relative to the mappingFileDirectory.

Throws:

MappingException - if an error occured while trying to access the mappingInputStream.

java.io.IOException

clearCache

public void clearCache()

This method can be used to clear the cache that is maintained internally by this class. After this class parses a file the first time, it will cache the parsed contents in memory so that future requests do not require a parse operation.

If this cache needs to be cleared (because a file changed on the system for example) this method can be invoked and the cache will be reset.

getDocumentObject

protected org.w3c.dom.Document getDocumentObject(java.io.InputStream pInputStream)
                                          throws javax.xml.parsers.ParserConfigurationException,
                                                 org.xml.sax.SAXException,
                                                 java.io.IOException

Utility method which will return the inputstream as a Document object to us. It performs validation on the parsing of the document.

Parameters:

pInputStream - input stream that contains a mapping instance document

Returns:

the Document which is the parsed instance document

Throws:

javax.xml.parsers.ParserConfigurationException

org.xml.sax.SAXException

java.io.IOException

getItemDescriptor

protected RepositoryItemDescriptor getItemDescriptor(org.w3c.dom.Element pElement)
                                              throws MappingException,
                                                     RepositoryException

This method returns the item-descriptor that is referred to by the top-level item-descriptor mapping element.

Parameters:

pElement - the element which is an item-descriptor element from a mapping file

Throws:

MappingException

RepositoryException

newItemMappingElement

public atg.repository.databinding.ItemMappingElement newItemMappingElement()

Creates a new ItemMappingElement object. It defaults to creating an instance of atg.repository.databinding.ItemMappingElement.

Returns:

newly constructed ItemMappingElement.

See Also:

ItemMappingElement

newPropertyMappingElement

public atg.repository.databinding.PropertyMappingElement newPropertyMappingElement()

This method creates a new PropertyMappingElement. It defaults to creating an instance of atg.repository.databinding.PropertyMappingElement.

Returns:

newly constructed PropertyMappingElement

See Also:

PropertyMappingElement

populateItemMappingProperties

public void populateItemMappingProperties(atg.repository.databinding.ItemMappingElement pItemMapping,
                                          org.w3c.dom.Element pItemElement,
                                          RepositoryItemDescriptor pDescriptor)
                                   throws MappingException,
                                          RepositoryException

This method populates the ItemMappingElement object passed to it with two properties

• the repository defined on the pElement
• the item-descriptor defined on the pElement

If the repository or item-descriptor is not defined on the pElement passed to this method then the values will be set to null.

Parameters:

pItemMapping - an ItemMappingElement value

pElement - an Element value

pDescriptor - the RepositoryItemDescriptor that the ItemMappingElement backs.

Throws:

MappingException

RepositoryException

populatePropertyMappingProperties

public void populatePropertyMappingProperties(atg.repository.databinding.PropertyMappingElement pPropertyMapping,
                                              org.w3c.dom.Element pElement)

This method populates the PropertyMappingElement object passed to it with three properties

• the include information from the pElement That is, whether or not the property associated with this object should be included in the externalized data-model
• the property name as it should appear in the item-descriptor (name)
• the property name as it should appear in the target datamodel

Any values not specified in the xml mapping file will be set to null.

Parameters:

pItemMapping - an ItemMappingElement value

pElement - an Element value

getRepository

public Repository getRepository(org.w3c.dom.Element pElement)
                         throws MappingException

Given an element, try to extract the path to a Nucleus repository component. From this path, look-up the component in Nucleus and return this to the caller.

The pElement parameter passed to this method is expected to have an attribute on it whose name matches the repository path constant defined on this class.

Parameters:

pElement - the element that a repository path will be extracted from

Returns:

the resolved Repository, null if no repository defined on item

Throws:

MappingException - if an error occurs

getItemDescriptor

public RepositoryItemDescriptor getItemDescriptor(Repository pRepository,
                                                  org.w3c.dom.Element pElement)
                                           throws MappingException,
                                                  RepositoryException

This method will retrieve the item-descriptor that is specified on the element passed to this method that is defined in the repository passed to this method.

The pElement parameter passed to this method is expected to have an attribute on it whose name matches the item-descriptor name constant defined on this class.

Parameters:

pRepository - the repository that the item-descriptor is defined in

pElement - the element that contains the item-descriptor name

Returns:

the RepositoryItemDescriptor that was found in the repository

Throws:

MappingException - if an error occurs

RepositoryException

isItemDescriptorValidForProperty

public boolean isItemDescriptorValidForProperty(RepositoryItemDescriptor pItemDescriptor,
                                                java.lang.String pPropertyName,
                                                RepositoryItemDescriptor pMapElementItemDescriptor)
                                         throws RepositoryException

This method determines if the item-descriptor which was specified in the mapping file refers to an item-descriptor type that is valid for the target property on the item-descriptor defined in the repository.

It will check to make sure that the target property does not point to a property which is a simple type. It then will check the target property and all of its possible subtype item-descriptors to see if there is a match against the item-desc passed.

Parameters:

pItemDescriptor - the item-descriptor defined in a repository whose property is currently being operated on

pPropertyName - the property that is being modified in some way

pMapElementItemDescriptor - the item-descriptor that comes from the mapping file

Returns:

true if the item-descriptor type defined in the mapping file is assignable to the property being modified by the mapping file

Throws:

RepositoryException

getMappingFileNames

public java.lang.String[] getMappingFileNames()
                                       throws MappingException

Rturns a list of the mapping files that this component points to.

Returns:

array of filenames pointed to by this component

Throws:

MappingException

error

public void error(org.xml.sax.SAXParseException pException)

Register this class to handle parse exceptions during a mapping file.

Specified by:

error in interface org.xml.sax.ErrorHandler

Parameters:

pException - the exception

warning

public void warning(org.xml.sax.SAXParseException pException)

Register this class to handle parse exceptions during a mapping file.

Specified by:

warning in interface org.xml.sax.ErrorHandler

Parameters:

pException - the exception

fatalError

public void fatalError(org.xml.sax.SAXParseException pException)

Register this class to handle parse exceptions during a mapping file.

Specified by:

fatalError in interface org.xml.sax.ErrorHandler

Parameters:

pException - the exception

parseAllFiles

public void parseAllFiles()
                   throws RepositoryException,
                          MappingException,
                          java.io.IOException,
                          javax.xml.parsers.ParserConfigurationException,
                          org.xml.sax.SAXException

Parse all the mapping files that are pointed to by this component. Every file will be parsed again and added to the cache.

This method does not clear the cache before parsing files. So, if a change has been made to mapping file and those changes should be detected, the clearCache() method should be invoked.

Throws:

RepositoryException - if an error occurs

MappingException - if an error occurs

java.io.IOException - if an error occurs

javax.xml.parsers.ParserConfigurationException - if an error occurs

org.xml.sax.SAXException - if an error occurs