org.gvsig.tools.persistence
Interface PersistenceManager

All Known Subinterfaces:

PersistenceManagerServices

All Known Implementing Classes:

AbstractPersistenceManager, XMLPersistenceManager, ZipXMLPersistenceManager

public interface PersistenceManager

This interface contains the necessary methods to get a persistent representation of an object, suitable for storage or transmission, and to create a an object from its persistent representation.

Author:

The gvSIG project , Cesar Martinez Izquierdo , IVER T.I.

Nested Class Summary

static interface

PersistenceManager.Factories

Field Summary

static String	DEFAULT_DOMAIN_NAME
static String	DEFAULT_DOMAIN_URL
static int	DISABLED Validation Mode - DISABLED: No validation is performed at all.
static int	MANDATORY Validation Mode -- MANDATORY: Validation is active, so create(org.gvsig.tools.persistence.PersistentState) and getState(Object) will throw validation exceptions if validation errors are found.
static int	MANDATORY_IF_DECLARED Validation Mode -- MANDATORY_IF_DECLARED: Validation is active, but it will be only applied to Persistent objects which have been registered.
static String	PERSISTENCE_DYNOBJECT_NAMESPACE
static String	PERSISTENCE_NAMESPACE The namespace used on the definition of DynClasses used by the persistence manager.

Method Summary

void	addAlias(String alias, Class theClass) Associates an alias with a class.
DynStruct	addDefinition(Class theClass, String name, InputStream definitions, ClassLoader loader, String domainName, String domainUrl) Add a new definition to the class in the persistent manager.
DynStruct	addDefinition(Class theClass, String name, Map definitions, String domainName, String domainUrl) Add a new definition to the class in the persistent manager.
DynStruct	addDefinition(Class persistentClass, String name, String description, String domainName, String domainURL) Add a new definition to the class in the persistent manager.
DynStruct	addDefinition(DynStruct definition, String domainName, String domainUrl) Add a new definition to the class in the persistent manager.
Object	create(PersistentState state) Instantiates an object from a persistent state.
int	getAutoValidation() Gets the validation which will be applied in getState(Object), create(PersistentState) methods.
DynStruct	getDefinition(Class persistentClass) If the provided persistent class has registered an attribute definition in this manager, then this method returns that definition.
DynStruct	getDefinition(String name) Return the associated definition to the java class name passed as parameter.
DynStruct	getDynObjectDefinition(String className) Return the associated definition to the dynClass name passed as parameter.
PersistenceManager.Factories	getFactories()
Object	getObject(InputStream is) De-serializes an state from the data read from the provided is.
PersistentState	getState(Object obj) Creates a persistent state from an Persistent object.
PersistentState	getState(Object obj, boolean collectAllErrors) Creates a persistent state from an Persistent object.
PersistentState	loadState(InputStream in) De-serializes an state from the data read from the provided reader.
void	putObject(OutputStream os, Object obj) Serializes the object "obj" and writes the serialized data in the provided OutputStream.
void	registerFactory(PersistenceFactory factory) Register an instance of PersistenceFactory that can manage some objects that requires an especial construction or persistence.
void	saveState(PersistentState state, OutputStream out) Serializes the PersistentState and writes the serialized data in the provided OutputStream.
void	setAutoValidation(int validationMode) Sets the validation which will be applied in getState(Object), create(PersistentState) methods.
void	unregisterClass(Class theClass) Unregister a registered class from the manager.
void	unregisterClass(String className) Unregister a registered java class from the manager.
void	unregisterFactory(PersistenceFactory factory)
void	validate(PersistentState state, int mode) Validates persistent state by using the corresponding registered attribute definition.
void	validateAll(PersistentState state, int mode) Validates all persistent state related to the state by using the corresponding registered attribute definition.

Field Detail

PERSISTENCE_NAMESPACE

static final String PERSISTENCE_NAMESPACE

The namespace used on the definition of DynClasses used by the persistence manager.

See Also:

Constant Field Values

PERSISTENCE_DYNOBJECT_NAMESPACE

static final String PERSISTENCE_DYNOBJECT_NAMESPACE

See Also:

Constant Field Values

DEFAULT_DOMAIN_URL

static final String DEFAULT_DOMAIN_URL

See Also:

Constant Field Values

DEFAULT_DOMAIN_NAME

static final String DEFAULT_DOMAIN_NAME

See Also:

Constant Field Values

MANDATORY

static final int MANDATORY

Validation Mode -- MANDATORY: Validation is active, so create(org.gvsig.tools.persistence.PersistentState) and getState(Object) will throw validation exceptions if validation errors are found.

If an undeclared attribute or class is found, this will be considered a validation error.

See Also:

Constant Field Values

MANDATORY_IF_DECLARED

static final int MANDATORY_IF_DECLARED

Validation Mode -- MANDATORY_IF_DECLARED: Validation is active, but it will be only applied to Persistent objects which have been registered. create(org.gvsig.tools.persistence.PersistentState) and getState(Object) methods will throw validation exceptions if validation errors are found.

See Also:

Constant Field Values

DISABLED

static final int DISABLED

Validation Mode - DISABLED: No validation is performed at all. In this mode, PersistenceManager#ge

See Also:

Constant Field Values

Method Detail

getState

PersistentState getState(Object obj)
                         throws PersistenceException

Creates a persistent state from an Persistent object.

Parameters:

obj - The Persistent object to be persisted

Returns:

A PersistentState object, which stores the state of the provided Persistent Object.

Throws:

PersistenceException

getState

PersistentState getState(Object obj,
                         boolean collectAllErrors)
                         throws PersistenceException

Creates a persistent state from an Persistent object. When collectAllErrors is true, try to continue when an error is detected, and raise all errors when finish the process.

Parameters:

obj -

collectAllErrors -

Returns:

Throws:

PersistenceException

create

Object create(PersistentState state)
              throws PersistenceException,
                     PersistenceCreateException

Instantiates an object from a persistent state. The PersistentState object knows the class of the persisted object, and instantiates it by using introspection. The object must implement the Persistent interface so that it can understand the PersistentState.

Parameters:

state - The state of the object to be instantiated

Returns:

A new object whose state is the same as the provided state object.

Throws:

PersistenceException

PersistenceCreateException

addAlias

void addAlias(String alias,
              Class theClass)
              throws PersistenceClassNotRegistered

Associates an alias with a class. This is similar to a symbolic link, which allows to access the class by means of its alias.

When an alias is defined, it replaces any class whose qualified name is equal to the alias. Therefore, this class will never be instantiated, and instead the class pointed by the the alias will be instantiated.

For example, if the following alias is defined:

 Class aClass = org.gvsig.fmap.mapcontext.rendering.symbols.SimpleMarkerSymbol.class;
 manager.addAlias(
                "org.gvsig.fmap.mapcontext.rendering.symbols.ArrowMarkerSymbol", aClass);
 

then, SimpleMarkerSymbol will be instantiated instead of ArrowMarkerSymbol from any PersistentState which references ArrowMarkerSymbol.

Aliases are useful to provided backward-compatibility paths (as old no existing classes may be aliased to substitution classes), but are also useful to avoid limitations on ClassLoaders. As a Class object is provided, it will be possible to instantiate it even if the current ClassLoader has no direct visibility of the class to instantiate.

Parameters:

alias - The alias to reference a class

aClass - The class to be referenced by the alias

Throws:

PersistenceClassNotRegistered - if aClass is not registered

addDefinition

DynStruct addDefinition(Class persistentClass,
                        String name,
                        String description,
                        String domainName,
                        String domainURL)
                        throws AddDefinitionException

Add a new definition to the class in the persistent manager. The new definition is defined in the namespace by default for DynClasses used in persistence. if domainName or domainURL are null, values by default arent supplied by the manager. Note: A domainName can by in only one domainURL. If you try to register the same domainName with two URL an exception will be raised.

Parameters:

persistentClass -

name - of the new definition

description - of the new definition, can be null.

domainName - , can be null.

domainURL - , can be null.

Returns:

the new definition

Throws:

AddDefinitionException

addDefinition

DynStruct addDefinition(Class theClass,
                        String name,
                        InputStream definitions,
                        ClassLoader loader,
                        String domainName,
                        String domainUrl)
                        throws AddDefinitionException

Add a new definition to the class in the persistent manager.

Parameters:

theClass - to be persistent

name - of the class definition to associate to theClass

definitions - input stream from load the definitions of classes

loader - , loader to resolve references to classes

domainName - (can be null)

domainUrl - (can be null)

Returns:

Throws:

AddDefinitionException

See Also:

addDefinition(Class, String, String, String, String)

addDefinition

DynStruct addDefinition(Class theClass,
                        String name,
                        Map definitions,
                        String domainName,
                        String domainUrl)
                        throws AddDefinitionException

Add a new definition to the class in the persistent manager.

Parameters:

theClass - to be persistent

name - of the class definition to associate to theClass

definitions - , map from get the definition of the class

domainName - (can be null)

domainUrl - (can be null)

Returns:

Throws:

AddDefinitionException

See Also:

addDefinition(Class, String, String, String, String)

addDefinition

DynStruct addDefinition(DynStruct definition,
                        String domainName,
                        String domainUrl)
                        throws AddDefinitionException

Add a new definition to the class in the persistent manager.

Parameters:

definition - , TODO

domainName - (can be null)

domainUrl - (can be null)

Returns:

Throws:

AddDefinitionException

See Also:

addDefinition(Class, String, String, String, String)

registerFactory

void registerFactory(PersistenceFactory factory)

Register an instance of PersistenceFactory that can manage some objects that requires an especial construction or persistence. This factory will use the default domain name and URL.

Parameters:

factory -

unregisterFactory

void unregisterFactory(PersistenceFactory factory)

unregisterClass

void unregisterClass(Class theClass)
                     throws PersistenceClassNotRegistered

Unregister a registered class from the manager.

Parameters:

persistentClass -

Throws:

PersistenceClassNotRegistered - if persistentClass is not registered

See Also:

#registerClass(Class, DynStruct, String)

unregisterClass

void unregisterClass(String className)
                     throws PersistenceClassNotRegistered

Unregister a registered java class from the manager.

Parameters:

className - the java class name to unregister

Throws:

PersistenceClassNotRegistered - if className is not registered

See Also:

#registerClass(Class)

validate

void validate(PersistentState state,
              int mode)
              throws PersistenceValidateExceptions

Validates persistent state by using the corresponding registered attribute definition. mode specifies what to do when a definition of a state class is not registered.

Parameters:

state -

mode -

Throws:

PersistenceValidateExceptions

validateAll

void validateAll(PersistentState state,
                 int mode)
                 throws PersistenceValidateExceptions

Validates all persistent state related to the state by using the corresponding registered attribute definition. mode specifies what to do when a definition of a state class is not registered.

Parameters:

state -

mode -

Throws:

PersistenceValidateExceptions

See Also:

#setAutoValidation(int)}

getDefinition

DynStruct getDefinition(Class persistentClass)

If the provided persistent class has registered an attribute definition in this manager, then this method returns that definition. Otherwise, it returns null.

Parameters:

persistentClass - The class whose corresponding attribute definition is to be retrieved.

Returns:

The attribute definition corresponding to the provided persistent class, or null otherwise.

getDefinition

DynStruct getDefinition(String name)

Return the associated definition to the java class name passed as parameter.

Parameters:

name - of the java class to retrieve definition

Returns:

The attribute definition corresponding to the provided java class, or null otherwise.

getDynObjectDefinition

DynStruct getDynObjectDefinition(String className)

Return the associated definition to the dynClass name passed as parameter.

Parameters:

name - of the dynClass to retrieve definition

Returns:

The attribute definition corresponding to the provided dynClass, or null otherwise.

loadState

PersistentState loadState(InputStream in)
                          throws PersistenceException

De-serializes an state from the data read from the provided reader. Depending on the implementation the serialized data may have different formats, such as XML or binary data.

Note that a particular implementation will only be able to de-serialize data which has been serialized by the same implementation.

Parameters:

reader -

Returns:

Throws:

PersistenceException

saveState

void saveState(PersistentState state,
               OutputStream out)
               throws PersistenceException,
                      PersistenceValidateExceptions

Serializes the PersistentState and writes the serialized data in the provided OutputStream. Depending on the implementation the serialized data may have different formats, such as XML or binary data.

Note that a particular implementation will only be able to de-serialize data which has been serialized by the same implementation.

Parameters:

out -

Throws:

PersistenceValidateExceptions

PersistenceException

getObject

Object getObject(InputStream is)

De-serializes an state from the data read from the provided is. Depending on the implementation the serialized data may have different formats, such as XML or binary data.

Note that a particular implementation will only be able to de-serialize data which has been serialized by the same implementation.

Parameters:

reader -

is -

Returns:

putObject

void putObject(OutputStream os,
               Object obj)

Serializes the object "obj" and writes the serialized data in the provided OutputStream. Depending on the implementation the serialized data may have different formats, such as XML or binary data.

Note that a particular implementation will only be able to de-serialize data which has been serialized by the same implementation.

Parameters:

os -

obj -

setAutoValidation

void setAutoValidation(int validationMode)
                       throws PersistenceException

Sets the validation which will be applied in getState(Object), create(PersistentState) methods. Validation ensures that persisted or de-persisted objects match the declared definition (which must have been previously registered by using #registerClass(Class, DynStruct)).

When automatic validation is enabled (MANDATORY or MANDATORY_IF_DECLARED), a ValidationException will be thrown by getState(Object), create(PersistentState) if a validation error is found.

Parameters:

validationMode - On of the following values: DISABLED, MANDATORY or MANDATORY_IF_DECLARED

Throws:

PersistenceException - If the mode is not supported by this manager

See Also:

#validateAll(PersistentState), #registerClass(Class, DynStruct)

getAutoValidation

int getAutoValidation()

Gets the validation which will be applied in getState(Object), create(PersistentState) methods.

Returns:

The current mode for automatic validation: DISABLED, MANDATORY or MANDATORY_IF_DECLARED

See Also:

#validateAll(PersistentState), #registerClass(Class, DynStruct)

getFactories

PersistenceManager.Factories getFactories()