org.mmbase.storage
Class StorageManagerFactory

java.lang.Object
  org.mmbase.storage.StorageManagerFactory

Direct Known Subclasses:

DatabaseStorageManagerFactory

public abstract class StorageManagerFactory

extends Object

This class contains functionality for retrieving StorageManager instances, which give access to the storage device. It also provides functionality for setting and retrieving configuration data. This is an abstract class. You cannot instantiate it. Use the static newInstance() or newInstance(MMBase) methods to obtain a factory class.

Since:

MMBase-1.7

Version:

$Id: StorageManagerFactory.java,v 1.27 2006/07/15 10:58:36 michiel Exp $

Author:

Pierre van Rooden

Field Summary

protected Map	attributes The map with configuration data
protected ChangeManager	changeManager The ChangeManager object, used to register/broadcast changes to a node or set of nodes.
protected SortedMap	disallowedFields The map with disallowed fieldnames and (if given) alternates
protected CharTransformer	getSurrogator
protected MMBase	mmbase A reference to the MMBase module
protected SearchQueryHandler	queryHandler The query handler to use with this factory.
protected List	queryHandlerClasses The query handler classes.
protected CharTransformer	setSurrogator
protected Class	storageManagerClass The class used to instantiate storage managers.
protected List	typeMappings The list with type mappings

Constructor Summary

StorageManagerFactory()

Method Summary

Object	getAttribute(Object key) Obtain an attribute from this factory.
Map	getAttributes() Retrieve a map of attributes for this factory.
String	getCatalog() Returns the name of the catalog used by this storage (null if no catalog is used).
ChangeManager	getChangeManager() Returns the ChangeManager utility instance, used to register and broadcast changes to nodes in the storage layer.
Map	getDisallowedFields() Returns a map of disallowed field names and their possible alternate values.
StorageReader	getDocumentReader() Locates and opens the storage configuration document, if available.
CharTransformer	getGetSurrogator() Returns a filter which can be used to filter strings taken from storage or null if none defined.
MMBase	getMMBase() Return the MMBase module for which the factory was instantiated
Scheme	getScheme(Object key) Obtain a scheme from this factory.
Scheme	getScheme(Object key, String defaultPattern) Obtain a scheme from this factory.
SearchQueryHandler	getSearchQueryHandler() Obtains a SearchQueryHandler from the factory.
CharTransformer	getSetSurrogator() Returns a filter which can be used to filter strings which are to be set into storage or null if none defined.
Object	getStorageIdentifier() Obtains the identifier for the basic storage element.
Object	getStorageIdentifier(Object mmobject) Obtains a identifier for an MMBase object.
StorageManager	getStorageManager() Obtains a StorageManager from the factory.
int	getTimeZoneOffset(long time) Returns the offset which must be used in the database.
List	getTypeMappings() Returns a sorted list of type mappings for this storage.
abstract double	getVersion() Returns the version of this factory implementation.
boolean	hasOption(Object key) Check whether an option was set.
protected void	init(MMBase mmbase) Initialize the StorageManagerFactory.
protected abstract Object	instantiateBasicHandler(Class handlerClass) Instantiate a basic handler object using the specified class.
protected abstract Object	instantiateChainedHandler(Class handlerClass, Object previousHandler) Instantiate a chained handler object using the specified class.
protected abstract SearchQueryHandler	instantiateQueryHandler(Object data) Instantiate a SearchQueryHandler object using the specified object.
protected void	load() Opens and reads the storage configuration document.
static StorageManagerFactory	newInstance() Obtain the storage manager factory belonging to the default MMBase module.
static StorageManagerFactory	newInstance(MMBase mmbase) Obtain the StorageManagerFactory belonging to the indicated MMBase module.
void	setAttribute(Object key, Object value) Set an attribute of this factory.
void	setAttributes(Map attributes) Add a map of attributes for this factory.
protected void	setDisallowedFields(Map disallowedFields) Sets the map of disallowed Fields.
void	setOption(Object key, boolean value) Set an option to true or false.
void	setScheme(Object key, String pattern) Set a scheme of this factory, using a string pattern to base the Scheme on.
abstract boolean	supportsTransactions() Returns whether transactions, and specifically rollback, is supported in the storage layer.

Methods inherited from class java.lang.Object

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

Field Detail

mmbase

protected MMBase mmbase

A reference to the MMBase module

storageManagerClass

protected Class storageManagerClass

The class used to instantiate storage managers. The classname is retrieved from the storage configuration file

attributes

protected Map attributes

The map with configuration data

typeMappings

protected List typeMappings

The list with type mappings

changeManager

protected ChangeManager changeManager

The ChangeManager object, used to register/broadcast changes to a node or set of nodes.

disallowedFields

protected final SortedMap disallowedFields

The map with disallowed fieldnames and (if given) alternates

queryHandler

protected SearchQueryHandler queryHandler

The query handler to use with this factory. Note: the current handler makes use of the JDBC2NodeInterface and is not optimized for storage: using it means you call getNodeManager() TWICE. Have to look into how this should work together.

queryHandlerClasses

protected List queryHandlerClasses

The query handler classes. Assign a value to this class if you want to set a default query handler.

setSurrogator

protected CharTransformer setSurrogator

See Also:

getSetSurrogator()

getSurrogator

protected CharTransformer getSurrogator

See Also:

getGetSurrogator()

Constructor Detail

StorageManagerFactory

public StorageManagerFactory()

Method Detail

newInstance

public static StorageManagerFactory newInstance(MMBase mmbase)
                                         throws StorageException

Obtain the StorageManagerFactory belonging to the indicated MMBase module.

Parameters:

mmbase - The MMBase module for which to retrieve the storagefactory

Returns:

The StorageManagerFactory

Throws:

StorageException - if the StorageManagerFactory class cannot be located, accessed, or instantiated, or when something went wrong during configuration of the factory

newInstance

public static StorageManagerFactory newInstance()
                                         throws StorageException

Obtain the storage manager factory belonging to the default MMBase module.

Returns:

The StoragemanagerFactory

Throws:

StorageException - if the StorageManagerFactory class cannot be located, accessed, or instantiated, or when something went wrong during configuration of the factory

init

protected final void init(MMBase mmbase)
                   throws StorageError

Initialize the StorageManagerFactory. This method should be called after instantiation of the factory class. It is called automatically by newInstance() and newInstance(MMBase).

Parameters:

mmbase - the MMBase instance to which this factory belongs

Throws:

StorageError - when something went wrong during configuration of the factory, or when the storage cannot be accessed

getMMBase

public MMBase getMMBase()

Return the MMBase module for which the factory was instantiated

Returns:

the MMBase instance

instantiateBasicHandler

protected abstract Object instantiateBasicHandler(Class handlerClass)

Instantiate a basic handler object using the specified class. A basic handler can be any type of class and is dependent on the factory implementation. For instance, the database factory expects an org.mmbase.storage.search.implentation.database.SQLHandler class.

Parameters:

handlerClass - the class to instantuate teh object with

Returns:

the new handler class

instantiateChainedHandler

protected abstract Object instantiateChainedHandler(Class handlerClass,
                                                    Object previousHandler)

Instantiate a chained handler object using the specified class. A chained handler can be any type of class and is dependent on the factory implementation. For instance, the database factory expects an org.mmbase.storage.search.implentation.database.ChainedSQLHandler class.

Parameters:

handlerClass - the class to instantuate teh object with

previousHandler - a handler thatw a sinstantiated previously. this handler should be passed to the new handler class during or after constrcution, so the ne whandler can 'chain' any events it cannot handle to this class.

Returns:

the new handler class

instantiateQueryHandler

protected abstract SearchQueryHandler instantiateQueryHandler(Object data)

Instantiate a SearchQueryHandler object using the specified object. The specified parameter may be an actual SearchQueryHandler object, or it may be a utility class. For instance, the database factory expects an org.mmbase.storage.search.implentation.database.SQLHandler object, which is used as a parameter in the construction of the actual SearchQueryHandler class.

Parameters:

data - the object to instantuate a SearchQueryHandler object with

load

protected void load()
             throws StorageException

Opens and reads the storage configuration document. Override this method to add additional configuration code before or after the configuration document is read.

Throws:

StorageException - if the storage could not be accessed or necessary configuration data is missing or invalid

getStorageManager

public StorageManager getStorageManager()
                                 throws StorageException

Obtains a StorageManager from the factory. The instance represents a temporary connection to the datasource - do not store the result of this call as a static or long-term member of a class.

Returns:

a StorageManager instance

Throws:

StorageException - when the storagemanager cannot be created

getSearchQueryHandler

public SearchQueryHandler getSearchQueryHandler()
                                         throws StorageException

Obtains a SearchQueryHandler from the factory. This provides ways to query for data using the SearchQuery interface. Note that cannot run the querys on a transaction (since SearchQuery does not support them).

Returns:

a SearchQueryHandler instance

Throws:

StorageException - when the handler cannot be created

getDocumentReader

public StorageReader getDocumentReader()
                                throws StorageException

Locates and opens the storage configuration document, if available. The configuration document to open can be set in mmbasereoot (using the storage property). The property should point to a resource which is to be present in the MMBase classpath. Overriding factories may provide ways to auto-detect the location of a configuration file.

Returns:

a StorageReader instance, or null if no reader has been configured

Throws:

StorageException - if something went wrong while obtaining the document reader

getAttributes

public Map getAttributes()

Retrieve a map of attributes for this factory. The attributes are the configuration parameters for the factory. You cannot change this map, though you can change the attributes themselves.

Returns:

an unmodifiable Map

setAttributes

public void setAttributes(Map attributes)

Add a map of attributes for this factory. The attributes are the configuration parameters for the factory. The actual content the factory expects is dependent on the implementation. The attributes are added to any attributes already knwon to the factory.

Parameters:

attributes - the map of attributes to add

getAttribute

public Object getAttribute(Object key)

Obtain an attribute from this factory. Attributes are the configuration parameters for the storagefactory.

Parameters:

key - the key of the attribute

Returns:

the attribute value, or null if it is unknown

setAttribute

public void setAttribute(Object key,
                         Object value)

Set an attribute of this factory. Attributes are the configuration parameters for the factory. The actual content the factory expects is dependent on the implementation. To invalidate an attribute, you can pass the null value.

Parameters:

key - the key of the attribute

value - the value of the attribute

getScheme

public Scheme getScheme(Object key)

Obtain a scheme from this factory. Schemes are special attributes, consisting of patterned strings that can be expanded with arguments.

Parameters:

key - the key of the attribute

Returns:

the scheme value, or null if it is unknown

getScheme

public Scheme getScheme(Object key,
                        String defaultPattern)

Obtain a scheme from this factory. Schemes are special attributes, consisting of patterned strings that can be expanded with arguments. If no scheme is present, the default pattern is used to create a scheme and add it to the factory.

Parameters:

key - the key of the attribute

defaultPattern - the pattern to use for the default scheme, null if there is no default

Returns:

the scheme value, null if there is no scheme

setScheme

public void setScheme(Object key,
                      String pattern)

Set a scheme of this factory, using a string pattern to base the Scheme on. Schemes are special attributes, consisting of patterned strings that can be expanded with arguments.

Parameters:

key - the key of the scheme

pattern - the pattern to use for the scheme

hasOption

public boolean hasOption(Object key)

Check whether an option was set. Options are attributes that return a boolean value.

Parameters:

key - the key of the option

Returns:

true if the option was set

setOption

public void setOption(Object key,
                      boolean value)

Set an option to true or false.

Parameters:

key - the key of the option

value - the value of the option (true or false)

getTypeMappings

public List getTypeMappings()

Returns a sorted list of type mappings for this storage.

Returns:

the list of TypeMapping objects

getDisallowedFields

public Map getDisallowedFields()

Returns a map of disallowed field names and their possible alternate values.

Returns:

A Map of disallowed field names

setDisallowedFields

protected void setDisallowedFields(Map disallowedFields)

Sets the map of disallowed Fields. Unlike setAttributes(), this actually replaces the existing disallowed fields map.

getStorageIdentifier

public Object getStorageIdentifier()
                            throws StorageException

Obtains the identifier for the basic storage element.

Returns:

the storage-specific identifier

Throws:

StorageException - if the object cannot be given a valid identifier

getStorageIdentifier

public Object getStorageIdentifier(Object mmobject)
                            throws StorageException

Obtains a identifier for an MMBase object. The default implementation returns the following type of identifiers:

• For StorageManager: the basename
• For MMBase: the String '[basename]_object
• For MMObjectBuilder: the String '[basename]_[builder name]'
• For Indices: the String '[basename]_[builder name]_[index name]_idx'
• For MMObjectNode: the object number as a Integer
• For CoreField or String: the field name, or the replacement fieldfname (from the disallowedfields map)

Note that 'basename' is a property from the mmbase module, set in mmbaseroot.xml.
You can override this method if you intend to use different ids.

Parameters:

mmobject - the MMBase objecty

Returns:

the storage-specific identifier

Throws:

StorageException - if the object cannot be given a valid identifier

See Also:

Storable

getChangeManager

public ChangeManager getChangeManager()

Returns the ChangeManager utility instance, used to register and broadcast changes to nodes in the storage layer. This method is for use by the StorageManager

getCatalog

public String getCatalog()

Returns the name of the catalog used by this storage (null if no catalog is used).

getVersion

public abstract double getVersion()

Returns the version of this factory implementation. The factory uses this number to verify whether it can handle storage configuration files that list version requirements.

Returns:

the version as an integer

supportsTransactions

public abstract boolean supportsTransactions()

Returns whether transactions, and specifically rollback, is supported in the storage layer.

Returns:

true if trasnactions are supported

getGetSurrogator

public CharTransformer getGetSurrogator()

Returns a filter which can be used to filter strings taken from storage or null if none defined.

Since:

MMBase-1.7.4

getSetSurrogator

public CharTransformer getSetSurrogator()

Returns a filter which can be used to filter strings which are to be set into storage or null if none defined.

Since:

MMBase-1.7.4

getTimeZoneOffset

public int getTimeZoneOffset(long time)

Returns the offset which must be used in the database. Currently this is based on the system's default time zone. It is imaginable that can have configuration or database specific details later.

Parameters:

time - The time at which it is evaluated (summer time issues)

Since:

MMBase-1.8

To Do:

experimental