View Javadoc

1   /*
2    * Copyright 2006 - 2012 Christina Bohk and Roland Ewald
3    *  
4    * Licensed under the Apache License, Version 2.0 (the "License"); 
5    * you may not use this file except in compliance with the License. 
6    * You may obtain a copy of the License at 
7    *  
8    *  http://www.apache.org/licenses/LICENSE-2.0
9    *  
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
13   * See the License for the specific language governing permissions and 
14   * limitations under the License. 
15   */
16  package p3j.database;
17  
18  import james.core.data.DBConnectionData;
19  
20  import java.util.List;
21  
22  import p3j.experiment.results.ResultsOfTrial;
23  import p3j.gui.misc.P3JConfigFile;
24  import p3j.misc.IProgressObserver;
25  import p3j.misc.MatrixDimension;
26  import p3j.misc.math.Matrix;
27  import p3j.misc.math.Matrix2D;
28  import p3j.pppm.ProjectionModel;
29  import p3j.pppm.parameters.Parameter;
30  import p3j.pppm.parameters.ParameterAssignment;
31  import p3j.pppm.parameters.ParameterInstance;
32  import p3j.pppm.parameters.Population;
33  import p3j.pppm.sets.Set;
34  import p3j.pppm.sets.SetType;
35  
36  /**
37   * Database interface for P3J. It provides loading, saving, and look-up means
38   * for all parts of the PPPM that ought to be persistent (e.g.,
39   * {@link Parameter}, {@link ParameterInstance}, {@link Set}, {@link SetType}).
40   * 
41   * Created on January 11, 2007
42   * 
43   * @author Christina Bohk
44   * @author Roland Ewald
45   * 
46   */
47  public interface IP3MDatabase {
48  
49    /**
50     * Initialize database connection.
51     * 
52     * @param dbConn
53     *          the connection details
54     * @param configFile
55     *          the config file with additional information
56     */
57    void init(DBConnectionData dbConn, P3JConfigFile configFile);
58  
59    /**
60     * Establishes database connection.
61     */
62    void open();
63  
64    /**
65     * Clears the database. I.e., it removes *all* entries and re-initializes the
66     * (potentially changed) table structure.
67     */
68    void clear();
69  
70    /**
71     * Closes the database connection.
72     */
73    void close();
74  
75    // Parameter
76  
77    /**
78     * Creates a new parameter (if not already existent) and returns it.
79     * 
80     * @param name
81     *          name of the parameter
82     * @param genDep
83     *          flag to determine generation dependency
84     * @param height
85     *          height of parameter values
86     * @param width
87     *          width of parameter values
88     * @param population
89     *          the population to which this parameter refers
90     * @return newly created parameter (or retrieved from DB)
91     */
92    Parameter newParameter(String name, boolean genDep, MatrixDimension height,
93        MatrixDimension width, Population population);
94  
95    /**
96     * Retrieves a parameter with the given name from the database.
97     * 
98     * @param name
99     *          the name of the parameter to be retrieved
100    * @return the parameter, or null if not exists
101    */
102   Parameter getParameter(String name);
103 
104   /**
105    * Retrieves list with all parameters.
106    * 
107    * @return list of all {@link Parameter} instances stored in the database
108    */
109   List<Parameter> getAllParameters();
110 
111   /**
112    * Deletes given parameter from database.
113    * 
114    * @param parameter
115    *          the parameter to be deleted
116    * @return true if deletion was successful, otherwise false
117    */
118   boolean deleteParameter(Parameter parameter);
119 
120   // ParameterInstance
121 
122   /**
123    * Creates new parameter instance.
124    * 
125    * @param comparisonIndex
126    *          comparison index of the instance
127    * @param param
128    *          the associated parameter
129    * @param generation
130    *          the generation of the instance
131    * @return a newly created instance, or instance with the same generation and
132    *         parameter from the database
133    */
134   ParameterInstance newParameterInstance(int comparisonIndex, Parameter param,
135       int generation);
136 
137   /**
138    * Retrieves a parameter instance from the database.
139    * 
140    * @param param
141    *          the associated parameter
142    * @param generation
143    *          the generation for which the parameter shall be instantiated
144    * @return existing parameter from database, or null
145    */
146   ParameterInstance getParameterInstance(Parameter param, int generation);
147 
148   /**
149    * Retrieves list with all parameter instances.
150    * 
151    * @return list of all parameter instances that are stored in the database
152    */
153   List<ParameterInstance> getAllParameterInstances();
154 
155   /**
156    * Deletes given parameter instances from the data base.
157    * 
158    * @param instance
159    *          the instance to be deleted
160    * @return true, if deletion was successful
161    */
162   boolean deleteParameterInstance(ParameterInstance instance);
163 
164   // Matrix
165 
166   /**
167    * Creates a new matrix if a matrix with the same values is not already
168    * existing in the system.
169    * 
170    * @param value
171    *          the value of the matrix
172    * @return the newly created (or retrieved) matrix
173    */
174   Matrix newMatrix(Matrix2D value);
175 
176   /**
177    * Get matrix with a certain value from database.
178    * 
179    * @param value
180    *          the value of the matrix
181    * @return the matrix, if could be found - otherwise null
182    */
183   Matrix getMatrix(Matrix2D value);
184 
185   /**
186    * Retrieves all input matrices from the database.
187    * 
188    * @return list of all matrices
189    */
190   List<Matrix> getAllMatrices();
191 
192   /**
193    * Deletes given matrix from the database.
194    * 
195    * @param matrix
196    *          the matrix to be deleted
197    * @return true if deletion was successful
198    */
199   boolean deleteMatrix(Matrix matrix);
200 
201   // ParameterAssignment
202 
203   /**
204    * Creates a new parameter assignment.
205    * 
206    * @param paramInstance
207    *          the associated parameter instance
208    * @param name
209    *          the name of the assignment
210    * @param description
211    *          the description of the assignment
212    * @param probability
213    *          the probability of the assignment
214    * @param deviation
215    *          the assumption-inherent deviation, i.e. the noise
216    * @param value
217    *          the assigned value
218    * @return the instantiated assignment
219    */
220   ParameterAssignment newParameterAssignment(ParameterInstance paramInstance,
221       String name, String description, double probability, double deviation,
222       Matrix2D value);
223 
224   /**
225    * Retrieves all {@link ParameterAssignment} entities for a certain
226    * {@link ParameterInstance}.
227    * 
228    * @param paramInstance
229    *          the parameter instance
230    * @return list containing all parameter assignments from database
231    */
232   List<ParameterAssignment> getAllParameterAssignments(
233       ParameterInstance paramInstance);
234 
235   /**
236    * Deletes given parameter assignment.
237    * 
238    * @param assignment
239    *          the assignment to be deleted
240    * @return true, if deletion was successful
241    */
242   boolean deleteParameterAssignment(ParameterAssignment assignment);
243 
244   /**
245    * Saves given parameter assignment.
246    * 
247    * @param assignment
248    *          the parameter assignment
249    */
250   void saveParameterAssignment(ParameterAssignment assignment);
251 
252   // Sets
253 
254   /**
255    * Creates a new set.
256    * 
257    * @param params
258    *          parameter instance for which assignments can be defined
259    * @param name
260    *          name of the set
261    * @param desc
262    *          description of the set
263    * @param prob
264    *          probability of the set
265    * @return newly created set
266    */
267   Set newSet(List<ParameterInstance> params, String name, String desc,
268       double prob);
269 
270   /**
271    * Updates the set. This stores all changed/added/removed
272    * {@link p3j.pppm.parameters.ParameterAssignmentSet} instances as well.
273    * 
274    * @param set
275    *          the set to be updated
276    */
277   void saveSet(Set set);
278 
279   /**
280    * Deletes given set from database.
281    * 
282    * @param set
283    *          the set to be deleted
284    * @return true, if deletion was successful
285    */
286   boolean deleteSet(Set set);
287 
288   /**
289    * Retrieves all sets from database.
290    * 
291    * @return list of all sets
292    */
293   List<Set> getAllSets();
294 
295   // Settype
296 
297   /**
298    * Create new Settype.
299    * 
300    * @param name
301    *          name of the Settype to be created
302    * @param description
303    *          description of the Settype to be created
304    * @return newly created Settype
305    */
306   SetType newSetType(String name, String description);
307 
308   /**
309    * Updates the Settype. This stores all changed/added/removed {@link Set}
310    * instances as well.
311    * 
312    * @param setType
313    *          the Settype to be updated
314    */
315   void saveSetType(SetType setType);
316 
317   /**
318    * Retrieve all Settypes from data base.
319    * 
320    * @return list with all Settypes in the database
321    */
322   List<SetType> getAllSetTypes();
323 
324   /**
325    * Delete {@link SetType} from database.
326    * 
327    * @param setType
328    *          the Settype to be deleted
329    * @return true, if deletion was successful
330    */
331   boolean deleteSeType(SetType setType);
332 
333   // Scenario
334 
335   /**
336    * Adds new projection to database, automatically adds any {@link Parameter}
337    * or {@link ParameterInstance} entities that have not yet been created.
338    * 
339    * @param projection
340    *          the new projection
341    */
342   void newProjection(ProjectionModel projection);
343 
344   /**
345    * Retrieves list of all projections from the database.
346    * 
347    * @return list of all projections from the database
348    * @throws Exception
349    *           if lookup fails
350    */
351   List<ProjectionModel> getAllProjections();
352 
353   /**
354    * Retrieves projection by id.
355    * 
356    * @param id
357    *          the id of the projection
358    * @return the projection, null if none was found
359    */
360   ProjectionModel getProjectionByID(int id);
361 
362   /**
363    * Delete projection from database.
364    * 
365    * @param projection
366    *          the projection to be deleted
367    * @param observer
368    *          the progress observer (may be null)
369    * @return true, if deletion was successful
370    */
371   boolean deleteProjection(ProjectionModel projection,
372       IProgressObserver observer);
373 
374   /**
375    * Saves projection.
376    * 
377    * @param projection
378    *          the projection to be saved/updated
379    */
380   void saveProjection(ProjectionModel projection);
381 
382   // Results
383 
384   /**
385    * Saves results of a single trial. They are reproducible, as they include the
386    * specific parameter assignments that were used.
387    * 
388    * @param resultOfTrial
389    *          the result of the trial
390    */
391   void saveTrialResults(ResultsOfTrial resultOfTrial);
392 
393   /**
394    * Retrieves all results for the given projection. Take care:
395    * 
396    * @param projection
397    *          the projection
398    * 
399    * @return the all results
400    */
401   List<ResultsOfTrial> getAllResults(ProjectionModel projection);
402 
403   /**
404    * Deletes a result.
405    * 
406    * @param resultOfTrial
407    *          the result of trial
408    */
409   void deleteResult(ResultsOfTrial resultOfTrial);
410 
411   /**
412    * Delete all results of the projection.
413    * 
414    * @param projection
415    *          the projection
416    * @param observer
417    *          the progress observer (may be null)
418    */
419   void deleteAllResults(ProjectionModel projection, IProgressObserver observer);
420 
421   /**
422    * Gets the result iterator.
423    * 
424    * @param projection
425    *          the projection for which the results shall be gathered
426    * 
427    * @return the result iterator
428    */
429   IProjectionResultsIterator getResultIterator(ProjectionModel projection);
430 
431   /**
432    * Clears the given object from cache. Use only if you know this object is not
433    * going to be needed again (e.g., during a result export).
434    * 
435    * @param o
436    *          the object to be cleared from cache
437    */
438   void clearCache(Object o);
439 
440 }