svn-gvsig-desktop / branches / v2_0_0_prep / libraries / libTools / src / org / gvsig / tools / persistence / PersistenceManager.java @ 28076
History | View | Annotate | Download (5.08 KB)
1 |
package org.gvsig.tools.persistence; |
---|---|
2 |
|
3 |
import java.io.Reader; |
4 |
import java.util.Iterator; |
5 |
|
6 |
import org.gvsig.tools.dynobject.DynStruct; |
7 |
import org.gvsig.tools.persistence.validation.ValidationResult; |
8 |
|
9 |
/**
|
10 |
* <p>This interface contains the necessary methods to get a persistent representation
|
11 |
* of an object, suitable for storage or transmission, and to create a an object from
|
12 |
* its persistent representation.</p>
|
13 |
*
|
14 |
* @author The gvSIG project <http://www.gvsig.org>
|
15 |
* @author Cesar Martinez Izquierdo <cesar.martinez@iver.es>
|
16 |
* @author IVER T.I. <http://www.iver.es>
|
17 |
*/
|
18 |
public interface PersistenceManager { |
19 |
|
20 |
/**
|
21 |
* <p>Creates a persistent state from an Persistent object.</p>
|
22 |
*
|
23 |
* @param obj The Persistent object to be persisted
|
24 |
*
|
25 |
* @return A PersistentState object, which stores the state of the
|
26 |
* provided Persistent Object.
|
27 |
* @throws PersistenceException
|
28 |
*/
|
29 |
public PersistentState getState(Persistent obj) throws PersistenceException; |
30 |
|
31 |
/**
|
32 |
* <p>Instantiates an object from a persistent state. The PersistentState object knows
|
33 |
* the class of the persisted object, and instantiates it by using introspection. The
|
34 |
* object must implement the Persistent interface so that it can understand the
|
35 |
* PersistentState.</p>
|
36 |
*
|
37 |
* @param state The state of the object to be instantiated
|
38 |
* @return A new object whose state is the same as the provided <code>state</code> object.
|
39 |
*
|
40 |
* @throws PersistenceException
|
41 |
*/
|
42 |
public Object create(PersistentState state) throws PersistenceException; |
43 |
|
44 |
/**
|
45 |
* <p>Associates an alias with a class. This is similar to a symbolic link, which allows
|
46 |
* to access the class by means of its alias.</p>
|
47 |
*
|
48 |
* <p>When an alias is defined, it replaces any
|
49 |
* class whose qualified name is equal to the alias. Therefore, this class will never
|
50 |
* be instantiated, and instead the class pointed by the the alias will be instantiated.</p>
|
51 |
*
|
52 |
* <p>For example, if the following alias is defined:</p>
|
53 |
*
|
54 |
* <pre>Class aClass = org.gvsig.fmap.mapcontext.rendering.symbols.SimpleMarkerSymbol.class;
|
55 |
* manager.addAlias("org.gvsig.fmap.mapcontext.rendering.symbols.ArrowMarkerSymbol", aClass);
|
56 |
* </pre>
|
57 |
* <p>then, SimpleMarkerSymbol will be instantiated instead of ArrowMarkerSymbol from any
|
58 |
* PersistentState which references ArrowMarkerSymbol.</p>
|
59 |
*
|
60 |
* <p>Aliases are useful to provided backward-compatibility paths (as old unexisting classes
|
61 |
* may be aliased to substitution classes), but are also useful to avoid limitations on
|
62 |
* ClassLoaders. As a Class object is provided, it will be possible to instantiate it even
|
63 |
* if the current ClassLoader has no direct visibility of the class to instantiate.</p>
|
64 |
*
|
65 |
* @param alias The alias to reference a class
|
66 |
* @param aClass The class to be referenced by the alias
|
67 |
*/
|
68 |
public void addAlias(String alias, Class aClass); |
69 |
|
70 |
/**
|
71 |
* <p>Registers persistentClass as Persistent, and associates an attribute definition to that
|
72 |
* class. During a persistence process, the PersistenceManager will validate that a class
|
73 |
* only persists attributes which has been defined in its DynStruct definition.</p>
|
74 |
*
|
75 |
* @param persistentClass The class to register
|
76 |
* @param definition The definition of the attributes allowed for the persistentClass
|
77 |
*/
|
78 |
public void addDefinition(Class persistentClass, DynStruct definition); |
79 |
|
80 |
/**
|
81 |
* <p>De-registers a class which has been previously registered using
|
82 |
* <code>{@link #addDefinition(Class, DynStruct)}</code></p>
|
83 |
*
|
84 |
* @param persistentClass
|
85 |
*/
|
86 |
public void removeDefinition(Class persistentClass); |
87 |
|
88 |
/**
|
89 |
* <p>Validate a persistent state by using the corresponding registered
|
90 |
* attribute definition. If there is no registered definition for the class
|
91 |
* represented by the PersistenteState, validation should fail.</p>
|
92 |
*
|
93 |
* <p>Some manager implementations may not support validation. In this case,
|
94 |
* they should always return a positive validation.</p>
|
95 |
*
|
96 |
* @param state
|
97 |
*
|
98 |
* @return The validation result
|
99 |
*/
|
100 |
public ValidationResult validate(PersistentState state);
|
101 |
|
102 |
/**
|
103 |
* <p>If the provided persistent class has registered an attribute definition in
|
104 |
* this manager, then this method returns that definition. Otherwise, it returns
|
105 |
* null.</p>
|
106 |
*
|
107 |
* @param persistentClass The class whose corresponding attribute definition is
|
108 |
* to be retrieved.
|
109 |
*
|
110 |
* @return The attribute definition corresponding to the provided persistent class,
|
111 |
* or null otherwise.
|
112 |
*/
|
113 |
public DynStruct getDefinition(Class persistentClass); |
114 |
|
115 |
/**
|
116 |
* <p>Gets a list of the registered Persistent classes.</p>
|
117 |
*
|
118 |
* @return An iterator over the registered Persistent classes.
|
119 |
*/
|
120 |
public Iterator getPersistentClasses(); |
121 |
|
122 |
/**
|
123 |
* <p>De-serializes an state from the data read from the provided
|
124 |
* <code>reader</code>. Depending on the implementation the serialized
|
125 |
* data may have different formats, such as XML or binary data.</p>
|
126 |
*
|
127 |
* <p>Note that a particular implementation will only be able to
|
128 |
* de-serialize data which has been serialized by the same
|
129 |
* implementation.</p>
|
130 |
*
|
131 |
* @param reader
|
132 |
* @return
|
133 |
*/
|
134 |
public PersistentState loadState(Reader reader) throws PersistenceException; |
135 |
|
136 |
} |