atg.repository.databinding
Class MappingManager

java.lang.Object
  atg.nucleus.logging.VariableArgumentApplicationLoggingImpl
      atg.nucleus.GenericService
          atg.repository.databinding.MappingManager

All Implemented Interfaces:

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

  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

  MappingManager()
  

  Method Summary

  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

  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, toString, 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