org.exolab.castor.mapping
Class Mapping

java.lang.Object
  extended by org.exolab.castor.mapping.Mapping

public class Mapping
extends java.lang.Object

Utility class for loading mapping files and providing them to the XML marshaller, JDO engine etc. The mapping file can be loaded from a URL, input stream or SAX InputSource.

Multiple mapping files can be loaded with the same Mapping object. When loading master mapping files that include other mapping files it might be convenient to use setBaseURL(java.lang.String) or setEntityResolver(org.xml.sax.EntityResolver).

If the desired class loader is different than the one used by Castor (e.g. if Castor is installed as a Java extension), the Mapping object can be constructed with the proper class loader.

The following example loads two mapping files:

 Mapping mapping;

 mapping = new Mapping( getClass().getClassLoader() );
 mapping.loadMapping( "mapping.xml" );
 mapping.loadMapping( url );
 

Version:
$Revision: 1.10 $ $Date: 2005/03/07 08:34:49 $
Author:
Assaf Arkin

Nested Class Summary
(package private)  class Mapping.ClassMappingResolver
          An IDResolver to allow us to resolve ClassMappings from included Mapping files
(package private) static class Mapping.EngineMapping
          Associates engine name (XML, JDO, etc) with the class of its mapping loader.
(package private)  class Mapping.IncludeListener
          An UnmarshalListener to handle mapping includes
(package private)  class Mapping.MappingState
          A class to keep track of the loaded mapping.
 
Field Summary
static Mapping.EngineMapping DAX
          Use this object to obtain the mapping resolver for DAX from getResolver(EngineMapping).
static Mapping.EngineMapping JDO
          Use this object to obtain the mapping resolver for JDO from getResolver(EngineMapping).
static Mapping.EngineMapping XML
          Use this object to obtain the mapping resolver for XML from getResolver(EngineMapping).
 
Constructor Summary
Mapping()
          Constructs a new mapping.
Mapping(java.lang.ClassLoader loader)
          Constructs a new mapping.
 
Method Summary
 java.lang.ClassLoader getClassLoader()
          Returns the class loader used by this mapping object.
 MappingResolver getResolver(Mapping.EngineMapping engine)
          Returns a mapping resolver for the suitable engine.
 MappingResolver getResolver(Mapping.EngineMapping engine, java.lang.Object param)
          Returns a mapping resolver for the suitable engine.
 MappingRoot getRoot()
          Returns a MappingRoot which contains all loaded mapping classes and key generators definition.
 void loadMapping(org.xml.sax.InputSource source)
          Loads the mapping from the specified input source.
 void loadMapping(java.lang.String url)
          Loads the mapping from the specified URL.
 void loadMapping(java.net.URL url)
          Loads the mapping from the specified URL.
 void setAllowRedefinitions(boolean allow)
          Enables or disables the ability to allow the redefinition of class mappings.
 void setBaseURL(java.lang.String url)
          Sets the base URL for the mapping and related files.
 void setEntityResolver(org.xml.sax.EntityResolver resolver)
          Sets the entity resolver.
 void setLogWriter(java.io.PrintWriter logWriter)
          Sets the log writer.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

JDO

public static final Mapping.EngineMapping JDO
Use this object to obtain the mapping resolver for JDO from getResolver(EngineMapping).


DAX

public static final Mapping.EngineMapping DAX
Use this object to obtain the mapping resolver for DAX from getResolver(EngineMapping).


XML

public static final Mapping.EngineMapping XML
Use this object to obtain the mapping resolver for XML from getResolver(EngineMapping).

Constructor Detail

Mapping

public Mapping(java.lang.ClassLoader loader)
Constructs a new mapping.

Parameters:
loader - The class loader to use, null for the default

Mapping

public Mapping()
Constructs a new mapping.

Method Detail

getResolver

public MappingResolver getResolver(Mapping.EngineMapping engine)
                            throws MappingException
Returns a mapping resolver for the suitable engine. The engine's specific mapping loader is created and used to create engine specific descriptors, returning a suitable mapping resolver. The mapping resolver is cached in memory and returned in subsequent method calls.

Parameters:
engine - The mapping engine
Returns:
A mapping resolver
Throws:
MappingException - A mapping error occured preventing descriptors from being generated from the loaded mapping
See Also:
JDO, XML, DAX

getResolver

public MappingResolver getResolver(Mapping.EngineMapping engine,
                                   java.lang.Object param)
                            throws MappingException
Returns a mapping resolver for the suitable engine. The engine's specific mapping loader is created and used to create engine specific descriptors, returning a suitable mapping resolver. The mapping resolver is cached in memory and returned in subsequent method calls.

Parameters:
engine - The mapping engine
param - Arbitrary parameter that is to be passed to resolver.loadMapping()
Returns:
A mapping resolver
Throws:
MappingException - A mapping error occured preventing descriptors from being generated from the loaded mapping
See Also:
JDO, XML, DAX

getRoot

public MappingRoot getRoot()
Returns a MappingRoot which contains all loaded mapping classes and key generators definition.


setAllowRedefinitions

public void setAllowRedefinitions(boolean allow)
Enables or disables the ability to allow the redefinition of class mappings.

Parameters:
allow - a boolean that when true enables redefinitions.

setLogWriter

public void setLogWriter(java.io.PrintWriter logWriter)
Sets the log writer. If not null, errors and other messages will be directed to that log writer.

Parameters:
logWriter - The log writer to use

setEntityResolver

public void setEntityResolver(org.xml.sax.EntityResolver resolver)
Sets the entity resolver. The entity resolver can be used to resolve external entities and cached documents that are used from within mapping files.

Parameters:
resolver - The entity resolver to use

setBaseURL

public void setBaseURL(java.lang.String url)
Sets the base URL for the mapping and related files. If the base URL is known, files can be included using relative names. Any URL can be passed, if the URL can serve as a base URL it will be used. If url is an absolute path, it is converted to a file URL.

Parameters:
url - The base URL

getClassLoader

public java.lang.ClassLoader getClassLoader()
Returns the class loader used by this mapping object. The returned class loaded may be the one passed in the constructor, the one used to load Castor, or in some 1.1 JVMs null.

Returns:
The class loader used by this mapping object (may be null)

loadMapping

public void loadMapping(java.lang.String url)
                 throws java.io.IOException,
                        MappingException
Loads the mapping from the specified URL. If an entity resolver was specified, will use the entity resolver to resolve the URL. This method is also used to load mappings referenced from another mapping or configuration file.

Parameters:
url - The URL of the mapping file
Throws:
java.io.IOException - An error occured when reading the mapping file
MappingException - The mapping file is invalid

loadMapping

public void loadMapping(java.net.URL url)
                 throws java.io.IOException,
                        MappingException
Loads the mapping from the specified URL.

Parameters:
url - The URL of the mapping file
Throws:
java.io.IOException - An error occured when reading the mapping file
MappingException - The mapping file is invalid

loadMapping

public void loadMapping(org.xml.sax.InputSource source)
                 throws java.io.IOException,
                        MappingException
Loads the mapping from the specified input source.

Parameters:
source - The input source
Throws:
java.io.IOException - An error occured when reading the mapping file
MappingException - The mapping file is invalid


Intalio Inc. (C) 1999-2004. All rights reserved http://www.intalio.com