org.apache.ojb.broker.metadata
Class MetadataManager

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

public class MetadataManager
extends java.lang.Object

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

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

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

Version:
$Id: MetadataManager.java 365232 2005-12-21 22:36:07Z tomdz $
Author:
Armin Waibel

Method Summary
 void addProfile(java.lang.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 Note: All classes within the repository structure have to implement java.io.Serializable to be able to create a cloned copy.
 java.lang.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(java.lang.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(java.io.InputStream inst)
          Read JdbcConnectionDescriptors from this InputStream.
 ConnectionRepository readConnectionRepository(java.lang.String fileName)
          Read JdbcConnectionDescriptors from the given repository file.
 DescriptorRepository readDescriptorRepository(java.io.InputStream inst)
          Read ClassDescriptors from the given InputStream.
 DescriptorRepository readDescriptorRepository(java.lang.String fileName)
          Read ClassDescriptors from the given repository file.
 void removeAllProfiles()
          Remove all profiles
 DescriptorRepository removeProfile(java.lang.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!
 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
equals, 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(java.lang.String fileName)
Read ClassDescriptors from the given repository file.

See Also:
mergeDescriptorRepository(org.apache.ojb.broker.metadata.DescriptorRepository)

readDescriptorRepository

public DescriptorRepository readDescriptorRepository(java.io.InputStream inst)
Read ClassDescriptors from the given InputStream.

See Also:
mergeDescriptorRepository(org.apache.ojb.broker.metadata.DescriptorRepository)

readConnectionRepository

public ConnectionRepository readConnectionRepository(java.lang.String fileName)
Read JdbcConnectionDescriptors from the given repository file.

See Also:
mergeConnectionRepository(org.apache.ojb.broker.metadata.ConnectionRepository)

readConnectionRepository

public ConnectionRepository readConnectionRepository(java.io.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(java.lang.Object key,
                       DescriptorRepository repository)
Add a metadata profile.

See Also:
loadProfile(java.lang.Object)

loadProfile

public void loadProfile(java.lang.Object key)
Load the given metadata profile for the current thread.


getCurrentProfileKey

public java.lang.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(java.lang.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


(C) 2002 - 2006 Apache Software Foundation
All rights reserved. Published under the Apache License 2.0.
http://db.apache.org/ojb
Version: 1.0.4, 2005-12-30