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 }