org.apache.cayenne.conf
Class Configuration

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

Direct Known Subclasses:

DefaultConfiguration, MultiProjectConfiguration

public abstract class Configuration
extends 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.

Field Summary

protected org.apache.cayenne.conf.Configuration.ConfigurationShutdownHook	configurationShutdownHook
protected SortedMap<String,DataDomain>	dataDomains Lookup map that stores DataDomains with names as keys.
protected Map<String,String>	dataViewLocations
static Class<DefaultConfiguration>	DEFAULT_CONFIGURATION_CLASS
static String	DEFAULT_DOMAIN_FILE
protected String	domainConfigurationName
protected EventManager	eventManager
protected boolean	ignoringLoadFailures
protected ConfigLoaderDelegate	loaderDelegate
protected ConfigStatus	loadStatus
protected DataSourceFactory	overrideFactory
protected SchemaUpdateStrategy	overrideStrategy
protected String	projectVersion
protected ConfigSaverDelegate	saverDelegate
protected static Configuration	sharedConfiguration

Constructor Summary

protected	Configuration() Default constructor for new Configuration instances.
protected	Configuration(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.
boolean	canInitialize() Deprecated. since 3.0 - this method is redundant, as subclasses can prevent initialization by overriding initialize() and throwing an exception.
void	didInitialize() Deprecated. since 3.0 subclasses are recommended to override initialize().
DataSourceFactory	getDataSourceFactory() Deprecated. since 3.0 this method is no longer called when configuration is loaded. Instead getDataSourceFactory(String) is invoked, and this is the method that should be overriden.
DataSourceFactory	getDataSourceFactory(String userFactoryName) Returns a DataSourceFactory that should override a given factory specified by caller.
Map<String,String>	getDataViewLocations() See 'https://svn.apache.org/repos/asf/cayenne/dataviews/trunk' for DataViews code, which is not a part of Cayenne since 3.0.
DataDomain	getDomain() Returns default domain of this configuration.
DataDomain	getDomain(String name) Returns registered domain matching name or null if no such domain is found.
protected InputStream	getDomainConfiguration() Deprecated. since 3.0 This method is specific to subclass, so it should not be in the superclass.
String	getDomainConfigurationName() Returns the name of the main domain configuration resource.
Collection<DataDomain>	getDomains() Returns an unmodifiable collection of registered DataDomains sorted by domain name.
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.
protected InputStream	getMapConfiguration(String name) Returns a DataMap with the given name or null if it cannot be found.
String	getProjectVersion()
protected abstract ResourceFinder	getResourceFinder() Returns ResourceFinder associated with this Configuration that is to be used for config files lookup.
protected ResourceLocator	getResourceLocator() Deprecated. since 3.0 use/override getResourceFinder().
ConfigSaverDelegate	getSaverDelegate()
SchemaUpdateStrategy	getSchemaUpdateStrategy()
static Configuration	getSharedConfiguration() Use this method as an entry point to all Cayenne access objects.
protected InputStream	getViewConfiguration(String location) Deprecated. since 3.0 as Cayenne no longer cares to read view config files.
abstract void	initialize() Initializes the new instance.
static void	initializeSharedConfiguration() Creates and initializes shared Configuration object.
static void	initializeSharedConfiguration(Class<? extends Configuration> 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.
void	removeDomain(String name) Unregisters DataDomain matching name from this Configuration object.
void	setDataSourceFactory(DataSourceFactory overrideFactory)
void	setDataViewLocations(Map<String,String> dataViewLocations) Initializes configuration with the location of data views.
protected void	setDomainConfigurationName(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.
void	setProjectVersion(String projectVersion)
void	setSaverDelegate(ConfigSaverDelegate saverDelegate)
void	setSchemaUpdateStrategy(SchemaUpdateStrategy overrideStrategy)
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_DOMAIN_FILE

public static final String DEFAULT_DOMAIN_FILE

See Also:

Constant Field Values

DEFAULT_CONFIGURATION_CLASS

public static final Class<DefaultConfiguration> DEFAULT_CONFIGURATION_CLASS

sharedConfiguration

protected static Configuration sharedConfiguration

dataDomains

protected SortedMap<String,DataDomain> dataDomains

Lookup map that stores DataDomains with names as keys.

overrideFactory

protected DataSourceFactory overrideFactory

overrideStrategy

protected SchemaUpdateStrategy overrideStrategy

loadStatus

protected ConfigStatus loadStatus

domainConfigurationName

protected 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 Map<String,String> dataViewLocations

projectVersion

protected 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(String domainConfigurationName)

Default constructor for new Configuration instances using the given resource name as the main domain file.

Method Detail

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.

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(Class<? extends Configuration> 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 boolean canInitialize()

Deprecated. since 3.0 - this method is redundant, as subclasses can prevent initialization by overriding initialize() and throwing an exception.

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

initialize

public abstract void initialize()
                         throws Exception

Initializes the new instance.

Throws:

Exception

didInitialize

public void didInitialize()

Deprecated. since 3.0 subclasses are recommended to override initialize().

Called after successful completion of initialize(). This implementation is a noop.

getResourceLocator

protected ResourceLocator getResourceLocator()

Deprecated. since 3.0 use/override getResourceFinder().

Returns the resource locator used for finding and loading resources.

getResourceFinder

protected abstract ResourceFinder getResourceFinder()

Returns ResourceFinder associated with this Configuration that is to be used for config files lookup.

Since:

3.0

getDomainConfiguration

protected InputStream getDomainConfiguration()

Deprecated. since 3.0 This method is specific to subclass, so it should not be in the superclass.

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

getMapConfiguration

protected InputStream getMapConfiguration(String name)

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

getViewConfiguration

protected InputStream getViewConfiguration(String location)

Deprecated. since 3.0 as Cayenne no longer cares to read view config files.

See 'https://svn.apache.org/repos/asf/cayenne/dataviews/trunk' for DataViews code, which is not a part of Cayenne since 3.0.

getDomainConfigurationName

public String getDomainConfigurationName()

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

setDomainConfigurationName

protected void setDomainConfigurationName(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 String getProjectVersion()

Since:

1.1

setProjectVersion

public void setProjectVersion(String projectVersion)

Since:

1.1

getDataSourceFactory

public DataSourceFactory getDataSourceFactory(String userFactoryName)

Returns a DataSourceFactory that should override a given factory specified by caller. Returns null if the user factory should not be overriden.

Since:

3.0

getSchemaUpdateStrategy

public SchemaUpdateStrategy getSchemaUpdateStrategy()

setSchemaUpdateStrategy

public void setSchemaUpdateStrategy(SchemaUpdateStrategy overrideStrategy)

getDataSourceFactory

public DataSourceFactory getDataSourceFactory()

Deprecated. since 3.0 this method is no longer called when configuration is loaded. Instead getDataSourceFactory(String) is invoked, and this is the method that should be overriden.

Returns an internal DataSourceFactory 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(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(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 Collection<DataDomain> getDomains()

Returns an unmodifiable collection of registered DataDomains sorted by domain name.

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(Map<String,String> dataViewLocations)

Initializes configuration with the location of data views.

Parameters:

dataViewLocations - Map of DataView locations.

Since:

1.1

getDataViewLocations

public Map<String,String> getDataViewLocations()

See 'https://svn.apache.org/repos/asf/cayenne/dataviews/trunk' for DataViews code, which is not a part of Cayenne since 3.0.

Since:

1.1

shutdown

public void shutdown()

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

installConfigurationShutdownHook

public void installConfigurationShutdownHook()

uninstallConfigurationShutdownHook

public void uninstallConfigurationShutdownHook()