org.mmbase.storage
Class StorageManagerFactory<SM extends StorageManager>

java.lang.Object
  org.mmbase.storage.StorageManagerFactory<SM>

Direct Known Subclasses:

DatabaseStorageManagerFactory

public abstract class StorageManagerFactory<SM extends StorageManager>
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 42909 2010-07-15 14:55:42Z michiel $

Author:

Pierre van Rooden

Field Summary

protected Map<String,Object>	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 Map<String,String>	collationMappings
protected SortedMap<String,String>	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<Class<?>>	queryHandlerClasses The query handler classes.
protected CharTransformer	setSurrogator
protected Class<SM>	storageManagerClass The class used to instantiate storage managers.
protected List<String>	storeBinaryAsFileObjects The list with objects of which binary data should not be stored in database
protected List<TypeMapping>	typeMappings The list with type mappings

Constructor Summary

StorageManagerFactory()

Method Summary

void	beginTransaction() Puts the current thread in a database transaction
void	commit() Commits the current thread's database transaction
protected SM	createStorageManager()
Object	getAttribute(String key) Obtain an attribute from this factory.
Map<String,Object>	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<String,String>	getDisallowedFields() Returns a map of disallowed field names and their possible alternate values.
StorageReader<SM>	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.
String	getMappedCollation(Collator s) Given a Collator return a String such as the storage implemetnation may use to identify a collation.
MMBase	getMMBase() Return the MMBase module for which the factory was instantiated
Scheme	getScheme(String key) Obtain a scheme from this factory.
Scheme	getScheme(String 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.
SM	getStorageManager() Obtains a StorageManager from the factory.
List<String>	getStoreBinaryAsFileObjects() Returns a list of objects of which binary data should be stored in a file.
int	getTimeZoneOffset(long time) Returns the offset which must be used in the database.
List<TypeMapping>	getTypeMappings() Returns a sorted list of type mappings for this storage.
abstract double	getVersion() Returns the version of this factory implementation.
boolean	hasOption(String 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.
boolean	rollback() Rolls back the current thread's database transaction
void	setAttribute(String key, Object value) Set an attribute of this factory.
void	setAttributes(Map<String,Object> attributes) Add a map of attributes for this factory.
protected void	setDisallowedFields(Map disallowedFields) Sets the map of disallowed Fields.
void	setOption(String key, boolean value) Set an option to true or false.
void	setScheme(String 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<SM extends StorageManager> storageManagerClass

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

attributes

protected Map<String,Object> attributes

The map with configuration data

typeMappings

protected List<TypeMapping> typeMappings

The list with type mappings

collationMappings

protected Map<String,String> collationMappings

storeBinaryAsFileObjects

protected List<String> storeBinaryAsFileObjects

The list with objects of which binary data should not be stored in database

changeManager

protected ChangeManager changeManager

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

disallowedFields

protected final SortedMap<String,String> 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<Class<?>> 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

createStorageManager

protected SM createStorageManager()
                                                  throws StorageException

Throws:

StorageException

Since:

MMBase-1.9.1

getStorageManager

public SM 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<SM> 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<String,Object> 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<String,Object> 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(String 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(String 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(String 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(String 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(String 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(String 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(String 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<TypeMapping> getTypeMappings()

Returns a sorted list of type mappings for this storage.

Returns:

the list of TypeMapping objects

getMappedCollation

public String getMappedCollation(Collator s)

Given a Collator return a String such as the storage implemetnation may use to identify a collation. E.g. MySql would like something like 'utf8_danish_ci'. Internally, MMBase uses strings as defined by LocaleCollator to identify collators.

Since:

MMBase-1.9.2

getStoreBinaryAsFileObjects

public List<String> getStoreBinaryAsFileObjects()

Returns a list of objects of which binary data should be stored in a file.

Returns:

the list of objects of which BLOB fields should not be stored in database.

Since:

MMBase-1.8.5

getDisallowedFields

public Map<String,String> 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

beginTransaction

public void beginTransaction()
                      throws StorageException

Puts the current thread in a database transaction

Throws:

IllegalStateException - if the current thread already in transaction

StorageException

Since:

MMBase-1.9.1

commit

public void commit()
            throws StorageException

Commits the current thread's database transaction

Throws:

IllegalStateException - if the current thread not in a transaction

StorageException

Since:

MMBase-1.9.1

rollback

public boolean rollback()
                 throws StorageException

Rolls back the current thread's database transaction

Throws:

IllegalStateException - if the current thread not in a transaction

StorageException

Since:

MMBase-1.9.1