org.compass.core.config
Class CompassConfiguration

java.lang.Object
  extended by org.compass.core.config.CompassConfiguration
Direct Known Subclasses:
CompassAnnotationsConfiguration

public class CompassConfiguration
extends Object

Used to configure Compass instances.

An instance of it allows the application to specify settings and mapping files to be used when creating Compass.

There are several options to configure a Compass instance, programmatically using the CompassConfiguration class, using the xml configuration file (compass.cfg.xml), or a json configuration file, or a combination of all.

Usually the application will create a single CompassConfiguration, use it to configure and than build a Compass instance, and than instantiate CompassSessions in threads servicing client requests.

The CompassConfiguration is meant only as an initialization-time object. Compass is immutable and do not affect the CompassConfiguration that created it.

Author:
kimchy
See Also:
Compass

Field Summary
protected  ConfigurationBuilder configurationBuilder
           
protected static org.apache.commons.logging.Log log
           
protected  CompassMappingBinding mappingBinding
           
 
Constructor Summary
CompassConfiguration()
           
 
Method Summary
 CompassConfiguration addClass(Class searchableClass)
          Read a mapping from an application resource, using a convention.
 CompassConfiguration addDirectory(File dir)
          Read all mapping and meta-data documents from a directory tree.
 CompassConfiguration addFile(File file)
          Read mappings from a particular file.
 CompassConfiguration addFile(String filePath)
          Read mappings from a particular file.
 CompassConfiguration addInputStream(InputStream inputStream, String resourceName)
          Read mappings from an InputStream.
 CompassConfiguration addJar(File jar)
          Read all mappings and meta-data from a jar file.
 CompassConfiguration addMapping(ContractMapping contractMapping)
          Advance: Add mappings based on ContractMapping implementation which allows for adding pre built mapping constructs.
 CompassConfiguration addMapping(ContractMappingProvider contractMappingProvider)
          Allows to provide contract mapping through a level of indiraction.
 CompassConfiguration addMapping(ResourceMapping resourceMapping)
          Advance: Add mappings based on ResourceMapping implementation which allows for adding pre built mapping constructs.
 CompassConfiguration addMapping(ResourceMappingProvider resourceMappingProvider)
          Allows to provide resource mapping through a level of indiraction.
protected  void addMappingBindings(CompassMappingBinding mappingBinding)
           
 CompassConfiguration addMappingResolver(InputStreamMappingResolver mappingResolver)
          Uses a class that implements the InputStreamMappingResolver for auto generation of mapping definitions.
 CompassConfiguration addPackage(String packageName)
          Read annotated package definitions.
 CompassConfiguration addResource(String path)
          Read mappings from an application resource trying different classloaders.
 CompassConfiguration addResource(String path, ClassLoader classLoader)
          Read mappings from an application resource
 CompassConfiguration addScan(String basePackage)
          Scans the given base package recursivly for any applicable mappings definitions.
 CompassConfiguration addScan(String basePackage, String pattern)
          Scans the given base package recursivly for any applicable mappings definitions.
 CompassConfiguration addURL(URL url)
          Read mappings from a URL.
 Compass buildCompass()
          Build compass with the configurations set.
 CompassConfiguration configure()
          Use the mappings and properties specified in an application resource with the path /compass.cfg.xml.
 CompassConfiguration configure(File configFile)
          Use the mappings and properties specified in the given application file.
 CompassConfiguration configure(String resource)
          Use the mappings and properties specified in the given application resource.
 CompassConfiguration configure(URL url)
          Use the mappings and properties specified in the given document.
 ClassLoader getClassLoader()
          Returns the class loader that will be used to load classes and resources.
 CompassSettings getSettings()
          Returns the current set of settings associated with the configuration.
 CompassConfiguration registerConverter(String converterName, Class type, Converter converter)
          Regsiters a Converter under the given name.
 CompassConfiguration registerConverter(String converterName, Converter converter)
          Registers a Converter under the given name.
protected  void registerExtraConverters(ConverterLookup converterLookup)
           
 CompassConfiguration removeMappingByAlias(String alias)
          Removes the mapping registered under the given alias.
 CompassConfiguration removeMappingByClass(Class clazz)
          Removes all the mappings registered under the given class name.
 CompassConfiguration removeMappingByClass(String className)
          Removes all the mappings registered under the given class name.
 CompassConfiguration setClassLoader(ClassLoader classLoader)
          Sets the class loader that will be used to load classes and resources.
 CompassConfiguration setConnection(String connection)
          Sets the connection for the compass instance.
 CompassConfiguration setSetting(String setting, Object value)
          Sets a specific setting in the compass configuration settings.
 boolean tryAddClass(Class searchableClass)
          Tries to add a class and returns a boolean indicator if it was added or not.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

log

protected static final org.apache.commons.logging.Log log

mappingBinding

protected CompassMappingBinding mappingBinding

configurationBuilder

protected ConfigurationBuilder configurationBuilder
Constructor Detail

CompassConfiguration

public CompassConfiguration()
Method Detail

addMappingBindings

protected void addMappingBindings(CompassMappingBinding mappingBinding)

setClassLoader

public CompassConfiguration setClassLoader(ClassLoader classLoader)
Sets the class loader that will be used to load classes and resources.


getClassLoader

public ClassLoader getClassLoader()
Returns the class loader that will be used to load classes and resources. If directly set, will return it. If not, will return the therad local context class loader.


getSettings

public CompassSettings getSettings()
Returns the current set of settings associated with the configuration.

Returns:
The settings used by the configuration

setSetting

public CompassConfiguration setSetting(String setting,
                                       Object value)
Sets a specific setting in the compass configuration settings.

Parameters:
setting - The setting name
value - The setting value
Returns:
CompassConfiguration for method chaining

setConnection

public CompassConfiguration setConnection(String connection)
Sets the connection for the compass instance.

Parameters:
connection - The connection for compass to use
Returns:
CompassConfiguration for method chaining

registerConverter

public CompassConfiguration registerConverter(String converterName,
                                              Converter converter)
Registers a Converter under the given name. The name can then be used in the mapping definitions as a logical name to the converter.

Parameters:
converterName - the converter name the converter will be registered under
converter - The converter to use
Returns:
The configuration

registerConverter

public CompassConfiguration registerConverter(String converterName,
                                              Class type,
                                              Converter converter)
Regsiters a Converter under the given name. This converter will apply to all the given types that match the given type.

Parameters:
converterName - The name of the converter
type - The type to register the converter for
converter - The converter
Returns:
The configuration

buildCompass

public Compass buildCompass()
                     throws CompassException
Build compass with the configurations set. Creates a copy of all the current settings and mappings, configures a Compass instance and starts it.

Note that the CompassConfiguration class can be used to create more Compass objects after the method has been called.

Returns:
the Compass
Throws:
CompassException

registerExtraConverters

protected void registerExtraConverters(ConverterLookup converterLookup)

configure

public CompassConfiguration configure()
                               throws ConfigurationException
Use the mappings and properties specified in an application resource with the path /compass.cfg.xml.

Returns:
CompassConfiguration for method chaining
Throws:
ConfigurationException

configure

public CompassConfiguration configure(String resource)
                               throws ConfigurationException
Use the mappings and properties specified in the given application resource.

Parameters:
resource - The compass configuration resource path
Returns:
CompassConfiguration for method chaining
Throws:
ConfigurationException

configure

public CompassConfiguration configure(URL url)
                               throws ConfigurationException
Use the mappings and properties specified in the given document.

Parameters:
url - URL from which you wish to load the configuration
Returns:
A configuration configured via the file
Throws:
ConfigurationException

configure

public CompassConfiguration configure(File configFile)
                               throws ConfigurationException
Use the mappings and properties specified in the given application file.

Parameters:
configFile - File from which you wish to load the configuration
Returns:
A configuration configured via the file
Throws:
ConfigurationException

addMapping

public CompassConfiguration addMapping(ContractMapping contractMapping)
Advance: Add mappings based on ContractMapping implementation which allows for adding pre built mapping constructs.


addMapping

public CompassConfiguration addMapping(ContractMappingProvider contractMappingProvider)
Allows to provide contract mapping through a level of indiraction.


addMapping

public CompassConfiguration addMapping(ResourceMapping resourceMapping)
Advance: Add mappings based on ResourceMapping implementation which allows for adding pre built mapping constructs.


addMapping

public CompassConfiguration addMapping(ResourceMappingProvider resourceMappingProvider)
Allows to provide resource mapping through a level of indiraction.


removeMappingByAlias

public CompassConfiguration removeMappingByAlias(String alias)
                                          throws MappingException
Removes the mapping registered under the given alias.

Throws:
MappingException

removeMappingByClass

public CompassConfiguration removeMappingByClass(Class clazz)
                                          throws MappingException
Removes all the mappings registered under the given class name.

Throws:
MappingException

removeMappingByClass

public CompassConfiguration removeMappingByClass(String className)
                                          throws MappingException
Removes all the mappings registered under the given class name.

Throws:
MappingException

addMappingResolver

public CompassConfiguration addMappingResolver(InputStreamMappingResolver mappingResolver)
                                        throws ConfigurationException
Uses a class that implements the InputStreamMappingResolver for auto generation of mapping definitions.

Parameters:
mappingResolver - The mapping resolver
Throws:
ConfigurationException

addResource

public CompassConfiguration addResource(String path,
                                        ClassLoader classLoader)
                                 throws ConfigurationException
Read mappings from an application resource

Parameters:
path - a resource
classLoader - a ClassLoader to use
Throws:
ConfigurationException

addResource

public CompassConfiguration addResource(String path)
                                 throws ConfigurationException
Read mappings from an application resource trying different classloaders. This method will try to load the resource first from the thread context classloader and then from the classloader that loaded Compass.

Parameters:
path - The path of the resource
Throws:
ConfigurationException

addFile

public CompassConfiguration addFile(String filePath)
                             throws ConfigurationException
Read mappings from a particular file.

Parameters:
filePath - a path to a file
Throws:
ConfigurationException

addFile

public CompassConfiguration addFile(File file)
                             throws ConfigurationException
Read mappings from a particular file.

Parameters:
file - a path to a file
Throws:
ConfigurationException

addPackage

public CompassConfiguration addPackage(String packageName)
                                throws ConfigurationException
Read annotated package definitions.

Parameters:
packageName - The package name to load
Throws:
ConfigurationException

addClass

public CompassConfiguration addClass(Class searchableClass)
                              throws ConfigurationException
Read a mapping from an application resource, using a convention. The class foo.bar.Foo is mapped by the file foo/bar/Foo.cpm.xml (in the case of Xml binding).

Parameters:
searchableClass - the mapped class
Throws:
ConfigurationException

addScan

public CompassConfiguration addScan(String basePackage)
                             throws ConfigurationException
Scans the given base package recursivly for any applicable mappings definitions. This incldues xml mapping defintiions as well as annotations.

Throws:
ConfigurationException

addScan

public CompassConfiguration addScan(String basePackage,
                                    String pattern)
                             throws ConfigurationException
Scans the given base package recursivly for any applicable mappings definitions. This incldues xml mapping defintiions as well as annotations.

An optional ant style pattern can be provided to narrow down the search. For example, the base package can be com.mycompany, and the pattern can be **/model/** which will match all the everythign that has a package named model within it under the given base package.

Throws:
ConfigurationException

tryAddClass

public boolean tryAddClass(Class searchableClass)
                    throws ConfigurationException
Tries to add a class and returns a boolean indicator if it was added or not.

Parameters:
searchableClass - The searchable class to add
Returns:
true if the class was added, false otherwise
Throws:
ConfigurationException

addDirectory

public CompassConfiguration addDirectory(File dir)
                                  throws ConfigurationException
Read all mapping and meta-data documents from a directory tree. Assume that any file named *.cpm.xml or *.cmd.xml is a mapping document.

Parameters:
dir - a directory
Throws:
ConfigurationException

addJar

public CompassConfiguration addJar(File jar)
                            throws ConfigurationException
Read all mappings and meta-data from a jar file. Assume that any file named *.cpm.xml or *.cmd.xml is a mapping document.

Parameters:
jar - a jar file
Throws:
ConfigurationException

addURL

public CompassConfiguration addURL(URL url)
                            throws ConfigurationException
Read mappings from a URL.

Parameters:
url - the URL
Throws:
ConfigurationException

addInputStream

public CompassConfiguration addInputStream(InputStream inputStream,
                                           String resourceName)
                                    throws ConfigurationException
Read mappings from an InputStream.

Parameters:
inputStream - an InputStream containing
Throws:
ConfigurationException


Copyright (c) 2004-2009 The Compass Project.