001    /*
002      Copyright (C) 2001-2003 Laurent Martelli <laurent@aopsys.com>
003                              Renaud Pawlak <renaud@aopsys.com>
004    
005      This program is free software; you can redistribute it and/or modify
006      it under the terms of the GNU Lesser General Public License as
007      published by the Free Software Foundation; either version 2 of the
008      License, or (at your option) any later version.
009    
010      This program is distributed in the hope that it will be useful,
011      but WITHOUT ANY WARRANTY; without even the implied warranty of
012      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
013      GNU Lesser General Public License for more details.
014    
015      You should have received a copy of the GNU Lesser General Public License
016      along with this program; if not, write to the Free Software
017      Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */
018    
019    package org.objectweb.jac.aspects.persistence;
020    
021    import org.objectweb.jac.core.rtti.ClassItem;
022    import org.objectweb.jac.core.rtti.CollectionItem;
023    import org.objectweb.jac.core.rtti.FieldItem;
024    
025    /**
026     * This is the configuration interface of the persistence aspect.<p>
027     *
028     * @see PersistenceAC
029     */
030    
031    public interface PersistenceConf {   
032    
033        /**
034         * Associate a String-Object converter with a class
035         *
036         * <p>In order to stock objects in database, those objects must be
037         * converted in a String format. Basic classes are already
038         * implemented, but for new classes (such as java.awt.Dimension)
039         * new converters must be used. New converters can be used with
040         * fhis function.
041         *
042         * @param cl the class to convert
043         * @param converter the converter used. The class must implement
044         * <code>org.objectweb.jac.aspects.persistenceconf.StringConverter</code>.
045         * @see StringConverter 
046         */
047        void setValueConverter(ClassItem cl, ClassItem converter);
048    
049        /**
050         * Specify which the default storage class to use and the
051         * parameters to use to instanciate it. The choice of the
052         * storage's constructor is based on the number of arguments, so
053         * there should not be several constructors with the same number
054         * of arguments.
055         *
056         * Available storage are <code>FSStorage</code> and
057         * <code>PostgresStorage</code>
058         *
059         * @param storageClass the storage class. Constructors of this
060         * class must have PersistenceAC as first parameter.
061         * @param storageParameters the parameters 
062         *
063         * @see #configureStorage(String,ClassItem,String[])
064         * @see FSStorage
065         * @see PostgresStorage 
066         */
067        void configureStorage(ClassItem storageClass, String[] storageParameters);
068    
069        /**
070         * Specify which storage class to use and the parameters to use to
071         * instanciate it. The choice of the storage's constructor is based
072         * on the number of arguments, so there should not be several
073         * constructors with the same number of arguments.
074         *
075         * Available storage are <code>FSStorage</code> and
076         * <code>PostgresStorage</code>
077         *
078         * @param id identifier for the storage. <b>It must not contain the character ':'</b>
079         * @param storageClass the storage class. Constructors of this
080         * class must have PersistenceAC as first parameter.
081         * @param storageParameters the parameters 
082         *
083         * @see #configureStorage(ClassItem,String[])
084         * @see FSStorage
085         * @see PostgresStorage 
086         */
087        void configureStorage(String id,
088                              ClassItem storageClass, String[] storageParameters);
089    
090        /**
091         * Sets the storage to use for some classes.
092         *
093         * @param classExpr the classes to configure
094         * @param storageId the storage ID to use for those classes. It
095         * must have been declared with {@link #configureStorage(String,ClassItem,String[])}
096         *
097         * @see #configureStorage(String,ClassItem,String[]) 
098         */
099        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    }