PersistenceConf


1   /*
2     Copyright (C) 2001-2003 Laurent Martelli <laurent@aopsys.com>
3                             Renaud Pawlak <renaud@aopsys.com>
4   
5     This program is free software; you can redistribute it and/or modify
6     it under the terms of the GNU Lesser General Public License as
7     published by the Free Software Foundation; either version 2 of the
8     License, or (at your option) any later version.
9   
10    This program is distributed in the hope that it will be useful,
11    but WITHOUT ANY WARRANTY; without even the implied warranty of
12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13    GNU Lesser General Public License for more details.
14  
15    You should have received a copy of the GNU Lesser General Public License
16    along with this program; if not, write to the Free Software
17    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */
18  
19  package org.objectweb.jac.aspects.persistence;
20  
21  import org.objectweb.jac.core.rtti.ClassItem;
22  import org.objectweb.jac.core.rtti.CollectionItem;
23  import org.objectweb.jac.core.rtti.FieldItem;
24  
25  /**
26   * This is the configuration interface of the persistence aspect.<p>
27   *
28   * @see PersistenceAC
29   */
30  
31  public interface PersistenceConf {   
32  
33      /**
34       * Associate a String-Object converter with a class
35       *
36       * <p>In order to stock objects in database, those objects must be
37       * converted in a String format. Basic classes are already
38       * implemented, but for new classes (such as java.awt.Dimension)
39       * new converters must be used. New converters can be used with
40       * fhis function.
41       *
42       * @param cl the class to convert
43       * @param converter the converter used. The class must implement
44       * <code>org.objectweb.jac.aspects.persistenceconf.StringConverter</code>.
45       * @see StringConverter 
46       */
47      void setValueConverter(ClassItem cl, ClassItem converter);
48  
49      /**
50       * Specify which the default storage class to use and the
51       * parameters to use to instanciate it. The choice of the
52       * storage's constructor is based on the number of arguments, so
53       * there should not be several constructors with the same number
54       * of arguments.
55       *
56       * Available storage are <code>FSStorage</code> and
57       * <code>PostgresStorage</code>
58       *
59       * @param storageClass the storage class. Constructors of this
60       * class must have PersistenceAC as first parameter.
61       * @param storageParameters the parameters 
62       *
63       * @see #configureStorage(String,ClassItem,String[])
64       * @see FSStorage
65       * @see PostgresStorage 
66       */
67      void configureStorage(ClassItem storageClass, String  [] storageParameters);
68  
69      /**
70       * Specify which storage class to use and the parameters to use to
71       * instanciate it. The choice of the storage's constructor is based
72       * on the number of arguments, so there should not be several
73       * constructors with the same number of arguments.
74       *
75       * Available storage are <code>FSStorage</code> and
76       * <code>PostgresStorage</code>
77       *
78       * @param id identifier for the storage. <b>It must not contain the character ':'</b>
79       * @param storageClass the storage class. Constructors of this
80       * class must have PersistenceAC as first parameter.
81       * @param storageParameters the parameters 
82       *
83       * @see #configureStorage(ClassItem,String[])
84       * @see FSStorage
85       * @see PostgresStorage 
86       */
87      void configureStorage(String   id,
88                            ClassItem storageClass, String  [] storageParameters);
89  
90      /**
91       * Sets the storage to use for some classes.
92       *
93       * @param classExpr the classes to configure
94       * @param storageId the storage ID to use for those classes. It
95       * must have been declared with {@link #configureStorage(String,ClassItem,String[])}
96       *
97       * @see #configureStorage(String,ClassItem,String[]) 
98       */
99      void setStorage(String   classExpr, String   storageId);
100 
101     /**
102      * Configure persistence for one class.
103      *
104      * <p>The persistence type must be PersistenceAC.ROOT (a named object
105      * that is an entry point in the storage) or
106      * PersistenceAC.PERSISTENT for a regular persistent class.
107      *
108      * <p>ROOT objects are always wrapped, PERSISTENT are only wrapped
109      * when they become persistent, that is when they are linked to an
110      * already persistent object.
111      * 
112      * @param classExpr class expression of static objects
113      * @param nameExpr name expression of static objects
114      */
115     void makePersistent(String   classExpr,String   nameExpr);
116 
117     /**
118      * Registers a static name, that is a name that will not be changed
119      * by the persistence AC.
120      *
121      * <p>Note that the root objects, as defined by the rtti aspect are
122      * automatically considered as static objects by the persistence
123      * aspect. Thus, it is useless to define a root object static.
124      *
125      * @param classExpr class expression of static objects
126      * @param nameExpr name expression of static objects
127      */
128     void registerStatics(String   classExpr,String   nameExpr);
129 
130     /**
131      * Sets a field or collection to be preloaded
132      *
133      * <p>By default, persistent fields are loaded when
134      * accessed. Preloading a field force it to be loaded when the
135      * object is created : in the constructor.
136      *
137      * @param field the field to preload 
138      */
139     void preloadField(FieldItem field);
140 
141     /**
142      * Set all fields of a class to be preloaded
143      *
144      * <p>Same as preloadField, but for all fields of the class
145      *
146      * @param cl the class
147      * 
148      * @see #preloadField(FieldItem) 
149      */
150     void preloadAllFields(ClassItem cl);
151 
152     /**
153      * Set a max idle time for a collection.
154      *
155      * <p>The idle time corresponds to the time the collection is
156      * loaded in memory without having been accessed. By default, a
157      * collection stays in memory when it is loaded. For big
158      * collections, it might be interested to define a max idle
159      * time. When the max idle time is reached, the persistence aspect
160      * unloads this collection from the memory. The collection will be
161      * reloaded on the next access.
162      *
163      * <p>The frequency the max idle time has be reached is global to
164      * all collection and can be defined by
165      * <code>defineMaxIdleCheckPeriod</code>
166      *
167      * @param collection the collection that has a max idle
168      * @param maxIdle the max idle time in ms
169      * @see #defineMaxIdleCheckPeriod(long) 
170      */
171     void maxIdle(CollectionItem collection,long maxIdle);
172 
173     /**
174      * Defines the period that is used to check that the collection max
175      * idle time has not been reached.
176      *
177      * <p>If a collection max idle time is defined and that it has not
178      * been used for this time, then the collection is unloaded from
179      * the memory by the peristence.
180      *
181      * <p>This method is not mandatory, by default, a check period of
182      * 200.000 ms is defined.
183      *
184      * @param period the period time check in ms
185      * @see #maxIdle(CollectionItem,long) 
186      */
187     void defineMaxIdleCheckPeriod(long period);
188 
189     /**
190      * This configuration method allows to disable the cache for a
191      * given collection.
192      *
193      * <p>Then, the collection will never be loaded in the memory but
194      * the objects will be accessed directly in the storage. 
195      */
196     void disableCache(CollectionItem collection);
197 
198 }
199
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags