org.apache.ojb.broker.metadata
Class MetadataManager

java.lang.Object
  org.apache.ojb.broker.metadata.MetadataManager

public class MetadataManager
extends Object

Central class for metadata operations/manipulations - manages OJB's metadata objects, in particular:

• DescriptorRepository contains metadata of persistent objects
• ConnectionRepository contains all connection metadata information

This class allows transparent flexible metadata loading/manipulation at runtime.

How to read/merge metadata
Per default OJB loads default DescriptorRepository and ConnectionRepository instances, by reading the specified repository file. This is done first time the MetadataManager instance was used.
To read metadata information at runtime use readDescriptorRepository and readConnectionRepository methods.
It is also possible to merge different repositories using mergeDescriptorRepository and mergeConnectionRepository

Per thread handling of metadata

Per default the manager handle one global DescriptorRepository for all calling threads, but it is ditto possible to use different metadata profiles in a per thread manner - profiles means different copies of DescriptorRepository objects.

Enable the per thread mode
To enable the 'per thread' mode for DescriptorRepository instances:

   MetadataManager mm = MetadataManager.getInstance();
   // tell the manager to use per thread mode
   mm.setEnablePerThreadChanges(true);
   ...
 

This could be done e.g. at start up.
Now it's possible to use dedicated DescriptorRepository instances per thread:

   // e.g we get a coppy of the global repository
   DescriptorRepository dr = mm.copyOfGlobalRepository();
   // now we can manipulate the persistent object metadata of the copy
   ......

   // set the changed repository for this thread
   mm.setDescriptor(dr);

   // now let this thread lookup a PersistenceBroker instance
   // with the modified metadata
   // all other threads use the global metadata
   PersistenceBroker broker = Persis......
 

Note: Change metadata before lookup the PersistenceBroker instance for current thread, because the metadata was bound to the PB at lookup.

How to use different metadata profiles
MetadataManager was shipped with a simple mechanism to add, remove and load different persistent objects metadata profiles (different DescriptorRepository instances) in a per thread manner. Use

• addProfile add different persistent object metadata profiles
• removeProfile remove a persistent object metadata profiles
• loadProfile load a profile for the current thread

Note: method loadProfile only works if the per thread mode is enabled.

Version:

$Id: MetadataManager.java,v 1.1 2007-08-24 22:17:29 ewestfal Exp $

Author:

Armin Waibel

Method Summary

void	addProfile(Object key, DescriptorRepository repository) Add a metadata profile.
void	clearProfiles() Remove all metadata profiles.
ConnectionRepository	connectionRepository() Returns the ConnectionRepository.
DescriptorRepository	copyOfGlobalRepository() Returns a copy of the current global DescriptorRepository
Object	getCurrentProfileKey() Returns the last activated profile key.
PBKey	getDefaultPBKey() Return the default PBKey used in convinience method PersistenceBrokerFactory.defaultPersistenceBroker().
DescriptorRepository	getGlobalRepository() Returns explicit the global DescriptorRepository - use with care, because it ignores the per thread mode.
static MetadataManager	getInstance() Returns an instance of this class.
DescriptorRepository	getRepository() Returns the current valid DescriptorRepository for the caller.
boolean	isEnablePerThreadChanges() If returns true if per thread runtime changes of the DescriptorRepository is enabled and the getRepository() method returns a threaded repository file if set, or the global if no threaded was found.
void	loadProfile(Object key) Load the given metadata profile for the current thread.
void	mergeConnectionRepository(ConnectionRepository repository) Merge the given ConnectionRepository with the existing one (without making a deep copy of the containing connection descriptors).
void	mergeConnectionRepository(ConnectionRepository targetRepository, ConnectionRepository sourceRepository, boolean deep) Merge the given source ConnectionRepository with the existing target.
void	mergeDescriptorRepository(DescriptorRepository repository) Merge the given DescriptorRepository (without making a deep copy of containing class-descriptor objects) with the global one, returned by method getRepository() - keep in mind if running in per thread mode merge maybe only takes effect on current thread.
void	mergeDescriptorRepository(DescriptorRepository targetRepository, DescriptorRepository sourceRepository, boolean deep) Merge the given DescriptorRepository files, the source objects will be pushed to the target repository.
ConnectionRepository	readConnectionRepository(InputStream inst) Read JdbcConnectionDescriptors from this InputStream.
ConnectionRepository	readConnectionRepository(String fileName) Read JdbcConnectionDescriptors from the given repository file.
DescriptorRepository	readDescriptorRepository(InputStream inst) Read ClassDescriptors from the given InputStream.
DescriptorRepository	readDescriptorRepository(String fileName) Read ClassDescriptors from the given repository file.
void	removeAllProfiles() Remove all profiles
DescriptorRepository	removeProfile(Object key) Remove the given metadata profile.
void	setDefaultPBKey(PBKey defaultPBKey) Set the PBKey used in convinience method PersistenceBrokerFactory.defaultPersistenceBroker().
void	setDescriptor(DescriptorRepository repository) Set DescriptorRepository for the current thread.
void	setDescriptor(DescriptorRepository repository, boolean global) Set the DescriptorRepository - if global was true, the given descriptor aquire global availability (use with care!), else the given descriptor was associated with the calling thread.
void	setEnablePerThreadChanges(boolean enablePerThreadChanges) Enable the possibility of making per thread runtime changes of the DescriptorRepository.
void	setPerThreadDescriptor(DescriptorRepository repository) Deprecated. use setDescriptor(org.apache.ojb.broker.metadata.DescriptorRepository, boolean)
void	shutdown()

Methods inherited from class java.lang.Object

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

Method Detail

shutdown

public void shutdown()

getInstance

public static MetadataManager getInstance()

Returns an instance of this class.

getRepository

public DescriptorRepository getRepository()

Returns the current valid DescriptorRepository for the caller. This is the provided way to obtain the DescriptorRepository.
When per thread descriptor handling is enabled it search for a specific DescriptorRepository for the calling thread, if none can be found the global descriptor was returned.

See Also:

getGlobalRepository(), copyOfGlobalRepository()

getGlobalRepository

public DescriptorRepository getGlobalRepository()

Returns explicit the global DescriptorRepository - use with care, because it ignores the per thread mode.

See Also:

getRepository(), copyOfGlobalRepository()

connectionRepository

public ConnectionRepository connectionRepository()

Returns the ConnectionRepository.

mergeConnectionRepository

public void mergeConnectionRepository(ConnectionRepository repository)

Merge the given ConnectionRepository with the existing one (without making a deep copy of the containing connection descriptors).

See Also:

mergeConnectionRepository(ConnectionRepository targetRepository, ConnectionRepository sourceRepository, boolean deep)

mergeConnectionRepository

public void mergeConnectionRepository(ConnectionRepository targetRepository,
                                      ConnectionRepository sourceRepository,
                                      boolean deep)

Merge the given source ConnectionRepository with the existing target. If parameter deep is set true deep copies of source objects were made.
Note: Using deep copy mode all descriptors will be serialized by using the default class loader to resolve classes. This can be problematic when classes are loaded by a context class loader.

Note: All classes within the repository structure have to implement java.io.Serializable to be able to create a cloned copy.

mergeDescriptorRepository

public void mergeDescriptorRepository(DescriptorRepository repository)

Merge the given DescriptorRepository (without making a deep copy of containing class-descriptor objects) with the global one, returned by method getRepository() - keep in mind if running in per thread mode merge maybe only takes effect on current thread.

See Also:

mergeDescriptorRepository(DescriptorRepository targetRepository, DescriptorRepository sourceRepository, boolean deep)

mergeDescriptorRepository

public void mergeDescriptorRepository(DescriptorRepository targetRepository,
                                      DescriptorRepository sourceRepository,
                                      boolean deep)

Merge the given DescriptorRepository files, the source objects will be pushed to the target repository. If parameter deep is set true deep copies of source objects were made.
Note: Using deep copy mode all descriptors will be serialized by using the default class loader to resolve classes. This can be problematic when classes are loaded by a context class loader.

Note: All classes within the repository structure have to implement java.io.Serializable to be able to create a cloned copy.

See Also:

isEnablePerThreadChanges(), setEnablePerThreadChanges(boolean)

readDescriptorRepository

public DescriptorRepository readDescriptorRepository(String fileName)

Read ClassDescriptors from the given repository file.

See Also:

mergeDescriptorRepository(org.apache.ojb.broker.metadata.DescriptorRepository)

readDescriptorRepository

public DescriptorRepository readDescriptorRepository(InputStream inst)

Read ClassDescriptors from the given InputStream.

See Also:

mergeDescriptorRepository(org.apache.ojb.broker.metadata.DescriptorRepository)

readConnectionRepository

public ConnectionRepository readConnectionRepository(String fileName)

Read JdbcConnectionDescriptors from the given repository file.

See Also:

mergeConnectionRepository(org.apache.ojb.broker.metadata.ConnectionRepository)

readConnectionRepository

public ConnectionRepository readConnectionRepository(InputStream inst)

Read JdbcConnectionDescriptors from this InputStream.

See Also:

mergeConnectionRepository(org.apache.ojb.broker.metadata.ConnectionRepository)

setDescriptor

public void setDescriptor(DescriptorRepository repository,
                          boolean global)

Set the DescriptorRepository - if global was true, the given descriptor aquire global availability (use with care!), else the given descriptor was associated with the calling thread.

See Also:

isEnablePerThreadChanges(), setEnablePerThreadChanges(boolean)

setDescriptor

public void setDescriptor(DescriptorRepository repository)

Set DescriptorRepository for the current thread. Convenience method for setDescriptor(repository, false).

setPerThreadDescriptor

public void setPerThreadDescriptor(DescriptorRepository repository)

Deprecated. use setDescriptor(org.apache.ojb.broker.metadata.DescriptorRepository, boolean)

Convenience method for setDescriptor(repository, false).

copyOfGlobalRepository

public DescriptorRepository copyOfGlobalRepository()

Returns a copy of the current global DescriptorRepository

Note: All classes within the repository structure have to implement java.io.Serializable to be able to create a cloned copy.

See Also:

getGlobalRepository(), getRepository()

isEnablePerThreadChanges

public boolean isEnablePerThreadChanges()

If returns true if per thread runtime changes of the DescriptorRepository is enabled and the getRepository() method returns a threaded repository file if set, or the global if no threaded was found.
If returns false the getRepository() method return always the global repository.

See Also:

setEnablePerThreadChanges(boolean)

setEnablePerThreadChanges

public void setEnablePerThreadChanges(boolean enablePerThreadChanges)

Enable the possibility of making per thread runtime changes of the DescriptorRepository.

See Also:

isEnablePerThreadChanges()

addProfile

public void addProfile(Object key,
                       DescriptorRepository repository)

Add a metadata profile.

See Also:

loadProfile(java.lang.Object)

loadProfile

public void loadProfile(Object key)

Load the given metadata profile for the current thread.

getCurrentProfileKey

public Object getCurrentProfileKey()
                            throws MetadataException

Returns the last activated profile key.

Returns:

the last activated profile key or null if no profile has been loaded

Throws:

MetadataException - if per-thread changes has not been activated

See Also:

loadProfile(Object)

removeProfile

public DescriptorRepository removeProfile(Object key)

Remove the given metadata profile.

clearProfiles

public void clearProfiles()

Remove all metadata profiles.

removeAllProfiles

public void removeAllProfiles()

Remove all profiles

See Also:

removeProfile(java.lang.Object), addProfile(java.lang.Object, org.apache.ojb.broker.metadata.DescriptorRepository)

getDefaultPBKey

public PBKey getDefaultPBKey()

Return the default PBKey used in convinience method PersistenceBrokerFactory.defaultPersistenceBroker().
If in JdbcConnectionDescriptor the default connection is enabled, OJB will detect the default PBKey by itself.

See Also:

setDefaultPBKey(org.apache.ojb.broker.PBKey)

setDefaultPBKey

public void setDefaultPBKey(PBKey defaultPBKey)

Set the PBKey used in convinience method PersistenceBrokerFactory.defaultPersistenceBroker().
It's only allowed to use one JdbcConnectionDescriptor with enabled default connection. In this case OJB will automatically set the default key.
Note: It's recommended to set this key only once and not to change at runtime of OJB to avoid side-effects. If set more then one time a warning will be logged.

Throws:

MetadataException - if key was set more than one time