org.apache.cayenne.conf
Class Configuration

java.lang.Object
  org.apache.cayenne.conf.Configuration

Direct Known Subclasses:

DefaultConfiguration

public abstract class Configuration
extends java.lang.Object

This class is an entry point to Cayenne. It loads all configuration files and instantiates main Cayenne objects. Used as a singleton via the getSharedConfiguration()method.

To use a custom subclass of Configuration, Java applications must call initializeSharedConfiguration()with the subclass as argument. This will create and initialize a Configuration singleton instance of the specified class. By default DefaultConfigurationis instantiated.

Author:

Andrei Adamchik, Holger Hoffstaette

Field Summary

static org.apache.commons.collections.Predicate	ACCEPT_ALL_DATAVIEWS
protected org.apache.cayenne.conf.Configuration.ConfigurationShutdownHook	configurationShutdownHook
protected CayenneMap	dataDomains Lookup map that stores DataDomains with names as keys.
protected java.util.Map	dataViewLocations
static java.lang.Class	DEFAULT_CONFIGURATION_CLASS
static java.lang.String	DEFAULT_DOMAIN_FILE
static java.lang.String	DEFAULT_LOGGING_PROPS_FILE
protected java.lang.String	domainConfigurationName
protected EventManager	eventManager
protected boolean	ignoringLoadFailures
protected ConfigLoaderDelegate	loaderDelegate
protected ConfigStatus	loadStatus
protected DataSourceFactory	overrideFactory
protected java.lang.String	projectVersion
protected ConfigSaverDelegate	saverDelegate
protected static Configuration	sharedConfiguration

Constructor Summary

protected	Configuration() Default constructor for new Configuration instances.
protected	Configuration(java.lang.String domainConfigurationName) Default constructor for new Configuration instances using the given resource name as the main domain file.

Method Summary

void	addDomain(DataDomain domain) Adds new DataDomain to the list of registered domains.
static void	bootstrapSharedConfiguration(java.lang.Class cl) Deprecated. since 1.2. Use Thread.currentThread().setContextClassLoader() instead.
abstract boolean	canInitialize() Indicates whether initialize()can be called.
static void	configureCommonLogging() Configures Cayenne logging properties.
static void	configureCommonLogging(java.net.URL propsFile) Configures Cayenne logging properties using properties found at the specified URL.
protected void	configureLogging() Configures log4J.
abstract void	didInitialize() Called after successful completion of initialize().
DataSourceFactory	getDataSourceFactory() Returns an internal property for the DataSource factory that will override any settings configured in XML.
java.util.Map	getDataViewLocations()
DataDomain	getDomain() Returns default domain of this configuration.
DataDomain	getDomain(java.lang.String name) Returns registered domain matching name or null if no such domain is found.
protected abstract java.io.InputStream	getDomainConfiguration() Returns a DataDomain as a stream or null if it cannot be found.
java.lang.String	getDomainConfigurationName() Returns the name of the main domain configuration resource.
java.util.Collection	getDomains() Returns an unmodifiable collection of registered DataDomainobjects.
EventManager	getEventManager() Returns EventManager used by this configuration.
ConfigLoaderDelegate	getLoaderDelegate() Returns a delegate used for controlling the loading of configuration elements.
ConfigStatus	getLoadStatus() Returns the load status.
static org.apache.log4j.Level	getLoggingLevel() Deprecated. since 1.2 unused
protected abstract java.io.InputStream	getMapConfiguration(java.lang.String name) Returns a DataMap with the given name or null if it cannot be found.
java.lang.String	getProjectVersion()
static java.lang.ClassLoader	getResourceLoader() Deprecated. since 1.2 use Thread.currentThread().getContextClassLoader(). This is what Cayenne uses internally.
protected abstract ResourceLocator	getResourceLocator() Returns the resource locator used for finding and loading resources.
ConfigSaverDelegate	getSaverDelegate()
static Configuration	getSharedConfiguration() Use this method as an entry point to all Cayenne access objects.
protected abstract java.io.InputStream	getViewConfiguration(java.lang.String location)
abstract void	initialize() Initializes the new instance.
static void	initializeSharedConfiguration() Creates and initializes shared Configuration object.
static void	initializeSharedConfiguration(java.lang.Class configurationClass) Creates and initializes a shared Configuration object of a custom Configuration subclass.
static void	initializeSharedConfiguration(Configuration conf) Sets the shared Configuration object to a new Configuration object.
void	installConfigurationShutdownHook()
boolean	isIgnoringLoadFailures() Returns whether to ignore any failures during map loading or not.
static boolean	isLoggingConfigured() Indicates whether Log4j has been initialized, either by cayenne or otherwise.
boolean	loadDataView(DataView dataView)
boolean	loadDataView(DataView dataView, org.apache.commons.collections.Predicate dataViewNameFilter)
void	removeDomain(java.lang.String name) Unregisters DataDomain matching name from this Configuration object.
void	setDataSourceFactory(DataSourceFactory overrideFactory)
void	setDataViewLocations(java.util.Map dataViewLocations) Initializes configuration with the location of data views.
protected void	setDomainConfigurationName(java.lang.String domainConfigurationName) Sets the name of the main domain configuration resource.
void	setEventManager(EventManager eventManager) Sets EventManager used by this configuration.
protected void	setIgnoringLoadFailures(boolean ignoringLoadFailures) Sets whether to ignore any failures during map loading or not.
void	setLoaderDelegate(ConfigLoaderDelegate loaderDelegate)
protected void	setLoadStatus(ConfigStatus status) Sets the load status.
static void	setLoggingConfigured(boolean state) Indicate whether Log4j has been initialized.
static void	setLoggingLevel(org.apache.log4j.Level logLevel) Deprecated. since 1.2 unused.
void	setProjectVersion(java.lang.String projectVersion)
void	setSaverDelegate(ConfigSaverDelegate saverDelegate)
void	shutdown() Shutdowns all owned domains.
void	uninstallConfigurationShutdownHook()

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_LOGGING_PROPS_FILE

public static final java.lang.String DEFAULT_LOGGING_PROPS_FILE

See Also:

Constant Field Values

DEFAULT_DOMAIN_FILE

public static final java.lang.String DEFAULT_DOMAIN_FILE

See Also:

Constant Field Values

DEFAULT_CONFIGURATION_CLASS

public static final java.lang.Class DEFAULT_CONFIGURATION_CLASS

sharedConfiguration

protected static Configuration sharedConfiguration

ACCEPT_ALL_DATAVIEWS

public static final org.apache.commons.collections.Predicate ACCEPT_ALL_DATAVIEWS

dataDomains

protected CayenneMap dataDomains

Lookup map that stores DataDomains with names as keys.

overrideFactory

protected DataSourceFactory overrideFactory

loadStatus

protected ConfigStatus loadStatus

domainConfigurationName

protected java.lang.String domainConfigurationName

ignoringLoadFailures

protected boolean ignoringLoadFailures

loaderDelegate

protected ConfigLoaderDelegate loaderDelegate

saverDelegate

protected ConfigSaverDelegate saverDelegate

configurationShutdownHook

protected org.apache.cayenne.conf.Configuration.ConfigurationShutdownHook configurationShutdownHook

dataViewLocations

protected java.util.Map dataViewLocations

projectVersion

protected java.lang.String projectVersion

eventManager

protected EventManager eventManager

Since:

1.2

Constructor Detail

Configuration

protected Configuration()

Default constructor for new Configuration instances. Simply calls Configuration(String).

See Also:

Configuration(String)

Configuration

protected Configuration(java.lang.String domainConfigurationName)

Default constructor for new Configuration instances using the given resource name as the main domain file. First calls configureLogging(), then setDomainConfigurationName(java.lang.String)with the given domain configuration resource name.

Method Detail

bootstrapSharedConfiguration

public static void bootstrapSharedConfiguration(java.lang.Class cl)

Deprecated. since 1.2. Use Thread.currentThread().setContextClassLoader() instead.

configureCommonLogging

public static void configureCommonLogging()

Configures Cayenne logging properties. Search for the properties file called cayenne-log.properties is first done in $HOME/.cayenne, then in CLASSPATH.

configureCommonLogging

public static void configureCommonLogging(java.net.URL propsFile)

Configures Cayenne logging properties using properties found at the specified URL.

isLoggingConfigured

public static boolean isLoggingConfigured()

Indicates whether Log4j has been initialized, either by cayenne or otherwise. If an external setup has been detected, setLoggingConfigured(boolean)will be called to remember this.

setLoggingConfigured

public static void setLoggingConfigured(boolean state)

Indicate whether Log4j has been initialized. Can be used when subclasses customize the initialization process, or to configure Log4J outside of Cayenne.

getSharedConfiguration

public static Configuration getSharedConfiguration()

Use this method as an entry point to all Cayenne access objects.

Note that if you want to provide a custom Configuration, make sure you call one of the initializeSharedConfiguration()methods before your application code has a chance to call this method.

getResourceLoader

public static java.lang.ClassLoader getResourceLoader()

Deprecated. since 1.2 use Thread.currentThread().getContextClassLoader(). This is what Cayenne uses internally.

getLoggingLevel

public static org.apache.log4j.Level getLoggingLevel()

Deprecated. since 1.2 unused

Returns default log level for loading configuration. Log level is made static so that applications can set it before shared Configuration object is instantiated.

setLoggingLevel

public static void setLoggingLevel(org.apache.log4j.Level logLevel)

Deprecated. since 1.2 unused.

Sets the default log level for loading a configuration.

getEventManager

public EventManager getEventManager()

Returns EventManager used by this configuration.

Since:

1.2

setEventManager

public void setEventManager(EventManager eventManager)

Sets EventManager used by this configuration.

Since:

1.2

initializeSharedConfiguration

public static void initializeSharedConfiguration()

Creates and initializes shared Configuration object. By default DefaultConfigurationwill be instantiated and assigned to a singleton instance of Configuration.

initializeSharedConfiguration

public static void initializeSharedConfiguration(java.lang.Class configurationClass)

Creates and initializes a shared Configuration object of a custom Configuration subclass.

initializeSharedConfiguration

public static void initializeSharedConfiguration(Configuration conf)

Sets the shared Configuration object to a new Configuration object. First calls canInitialize()and - if permitted -initialize()followed by didInitialize().

canInitialize

public abstract boolean canInitialize()

Indicates whether initialize()can be called. Returning false allows new instances to delay or refuse the initialization process.

initialize

public abstract void initialize()
                         throws java.lang.Exception

Initializes the new instance.

Throws:

java.lang.Exception

didInitialize

public abstract void didInitialize()

Called after successful completion of initialize().

getResourceLocator

protected abstract ResourceLocator getResourceLocator()

Returns the resource locator used for finding and loading resources.

getDomainConfiguration

protected abstract java.io.InputStream getDomainConfiguration()

Returns a DataDomain as a stream or null if it cannot be found.

getMapConfiguration

protected abstract java.io.InputStream getMapConfiguration(java.lang.String name)

Returns a DataMap with the given name or null if it cannot be found.

getViewConfiguration

protected abstract java.io.InputStream getViewConfiguration(java.lang.String location)

configureLogging

protected void configureLogging()

Configures log4J. This implementation calls configureCommonLogging().

getDomainConfigurationName

public java.lang.String getDomainConfigurationName()

Returns the name of the main domain configuration resource. Defaults to DEFAULT_DOMAIN_FILE.

setDomainConfigurationName

protected void setDomainConfigurationName(java.lang.String domainConfigurationName)

Sets the name of the main domain configuration resource.

Parameters:

domainConfigurationName - the name of the resource that contains this Configuration's domain(s).

getProjectVersion

public java.lang.String getProjectVersion()

Since:

1.1

setProjectVersion

public void setProjectVersion(java.lang.String projectVersion)

Since:

1.1

getDataSourceFactory

public DataSourceFactory getDataSourceFactory()

Returns an internal property for the DataSource factory that will override any settings configured in XML. Subclasses may override this method to provide a special factory for DataSource creation that will take precedence over any factories configured in a cayenne project.

setDataSourceFactory

public void setDataSourceFactory(DataSourceFactory overrideFactory)

addDomain

public void addDomain(DataDomain domain)

Adds new DataDomain to the list of registered domains. Injects EventManager used by this configuration into the domain.

getDomain

public DataDomain getDomain(java.lang.String name)

Returns registered domain matching name or null if no such domain is found.

getDomain

public DataDomain getDomain()

Returns default domain of this configuration. If no domains are configured, null is returned. If more than one domain exists in this configuration, a CayenneRuntimeException is thrown, indicating that the domain name must be explicitly specified. In such cases getDomain(String name)must be used instead.

removeDomain

public void removeDomain(java.lang.String name)

Unregisters DataDomain matching name from this Configuration object. Note that any domain database connections remain open, and it is a responsibility of a caller to clean it up.

getDomains

public java.util.Collection getDomains()

Returns an unmodifiable collection of registered DataDomainobjects.

isIgnoringLoadFailures

public boolean isIgnoringLoadFailures()

Returns whether to ignore any failures during map loading or not.

Returns:

boolean

setIgnoringLoadFailures

protected void setIgnoringLoadFailures(boolean ignoringLoadFailures)

Sets whether to ignore any failures during map loading or not.

Parameters:

ignoringLoadFailures - true or false

getLoadStatus

public ConfigStatus getLoadStatus()

Returns the load status.

Returns:

ConfigStatus

setLoadStatus

protected void setLoadStatus(ConfigStatus status)

Sets the load status.

getLoaderDelegate

public ConfigLoaderDelegate getLoaderDelegate()

Returns a delegate used for controlling the loading of configuration elements.

setLoaderDelegate

public void setLoaderDelegate(ConfigLoaderDelegate loaderDelegate)

Since:

1.1

getSaverDelegate

public ConfigSaverDelegate getSaverDelegate()

Since:

1.2

setSaverDelegate

public void setSaverDelegate(ConfigSaverDelegate saverDelegate)

Since:

1.2

setDataViewLocations

public void setDataViewLocations(java.util.Map dataViewLocations)

Initializes configuration with the location of data views.

Parameters:

dataViewLocations - Map of DataView locations.

Since:

1.1

getDataViewLocations

public java.util.Map getDataViewLocations()

Since:

1.1

loadDataView

public boolean loadDataView(DataView dataView)
                     throws java.io.IOException

Throws:

java.io.IOException

Since:

1.1

loadDataView

public boolean loadDataView(DataView dataView,
                            org.apache.commons.collections.Predicate dataViewNameFilter)
                     throws java.io.IOException

Throws:

java.io.IOException

Since:

1.1

shutdown

public void shutdown()

Shutdowns all owned domains. Invokes DataDomain.shutdown().

installConfigurationShutdownHook

public void installConfigurationShutdownHook()

uninstallConfigurationShutdownHook

public void uninstallConfigurationShutdownHook()