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 java.util.List;
19  
20  import org.jamesii.core.data.DBConnectionData;
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 sortIndex
83     *          the sorting index
84     * @param genDep
85     *          flag to determine generation dependency
86     * @param height
87     *          height of parameter values
88     * @param width
89     *          width of parameter values
90     * @param population
91     *          the population to which this parameter refers
92     * @return newly created parameter (or retrieved from DB)
93     */
94    Parameter newParameter(String name, int sortIndex, boolean genDep,
95        MatrixDimension height, MatrixDimension width, Population population);
96  
97    /**
98     * Retrieves a parameter with the given name from the database.
99     * 
100    * @param name
101    *          the name of the parameter to be retrieved
102    * @return the parameter, or null if not exists
103    */
104   Parameter getParameter(String name);
105 
106   /**
107    * Retrieves list with all parameters.
108    * 
109    * @return list of all {@link Parameter} instances stored in the database
110    */
111   List<Parameter> getAllParameters();
112 
113   /**
114    * Deletes given parameter from database.
115    * 
116    * @param parameter
117    *          the parameter to be deleted
118    * @return true if deletion was successful, otherwise false
119    */
120   boolean deleteParameter(Parameter parameter);
121 
122   // ParameterInstance
123 
124   /**
125    * Creates new parameter instance.
126    * 
127    * @param comparisonIndex
128    *          comparison index of the instance
129    * @param param
130    *          the associated parameter
131    * @param generation
132    *          the generation of the instance
133    * @return a newly created instance, or instance with the same generation and
134    *         parameter from the database
135    */
136   ParameterInstance newParameterInstance(int comparisonIndex, Parameter param,
137       int generation);
138 
139   /**
140    * Retrieves a parameter instance from the database.
141    * 
142    * @param param
143    *          the associated parameter
144    * @param generation
145    *          the generation for which the parameter shall be instantiated
146    * @return existing parameter from database, or null
147    */
148   ParameterInstance getParameterInstance(Parameter param, int generation);
149 
150   /**
151    * Retrieves list with all parameter instances.
152    * 
153    * @return list of all parameter instances that are stored in the database
154    */
155   List<ParameterInstance> getAllParameterInstances();
156 
157   /**
158    * Deletes given parameter instances from the data base.
159    * 
160    * @param instance
161    *          the instance to be deleted
162    * @return true, if deletion was successful
163    */
164   boolean deleteParameterInstance(ParameterInstance instance);
165 
166   // Matrix
167 
168   /**
169    * Creates a new matrix if a matrix with the same values is not already
170    * existing in the system.
171    * 
172    * @param value
173    *          the value of the matrix
174    * @return the newly created (or retrieved) matrix
175    */
176   Matrix newMatrix(Matrix2D value);
177 
178   /**
179    * Deletes given matrix from the database.
180    * 
181    * @param matrix
182    *          the matrix to be deleted
183    * @return true if deletion was successful
184    */
185   boolean deleteMatrix(Matrix matrix);
186 
187   // ParameterAssignment
188 
189   /**
190    * Creates a new parameter assignment.
191    * 
192    * @param paramInstance
193    *          the associated parameter instance
194    * @param name
195    *          the name of the assignment
196    * @param description
197    *          the description of the assignment
198    * @param probability
199    *          the probability of the assignment
200    * @param deviation
201    *          the assumption-inherent deviation, i.e. the noise
202    * @param value
203    *          the assigned value
204    * @return the instantiated assignment
205    */
206   ParameterAssignment newParameterAssignment(ParameterInstance paramInstance,
207       String name, String description, double probability, double deviation,
208       Matrix2D value);
209 
210   /**
211    * Retrieves all {@link ParameterAssignment} entities for a certain
212    * {@link ParameterInstance}.
213    * 
214    * @param paramInstance
215    *          the parameter instance
216    * @return list containing all parameter assignments from database
217    */
218   List<ParameterAssignment> getAllParameterAssignments(
219       ParameterInstance paramInstance);
220 
221   /**
222    * Deletes given parameter assignment.
223    * 
224    * @param assignment
225    *          the assignment to be deleted
226    * @return true, if deletion was successful
227    */
228   boolean deleteParameterAssignment(ParameterAssignment assignment);
229 
230   /**
231    * Saves given parameter assignment.
232    * 
233    * @param assignment
234    *          the parameter assignment
235    */
236   void saveParameterAssignment(ParameterAssignment assignment);
237 
238   // Sets
239 
240   /**
241    * Creates a new set.
242    * 
243    * @param params
244    *          parameter instance for which assignments can be defined
245    * @param name
246    *          name of the set
247    * @param desc
248    *          description of the set
249    * @param prob
250    *          probability of the set
251    * @return newly created set
252    */
253   Set newSet(List<ParameterInstance> params, String name, String desc,
254       double prob);
255 
256   /**
257    * Updates the set. This stores all changed/added/removed
258    * {@link p3j.pppm.parameters.ParameterAssignmentSet} instances as well.
259    * 
260    * @param set
261    *          the set to be updated
262    */
263   void saveSet(Set set);
264 
265   /**
266    * Deletes given set from database.
267    * 
268    * @param set
269    *          the set to be deleted
270    * @return true, if deletion was successful
271    */
272   boolean deleteSet(Set set);
273 
274   /**
275    * Retrieves all sets from database.
276    * 
277    * @return list of all sets
278    */
279   List<Set> getAllSets();
280 
281   // Settype
282 
283   /**
284    * Create new Settype.
285    * 
286    * @param name
287    *          name of the Settype to be created
288    * @param description
289    *          description of the Settype to be created
290    * @return newly created Settype
291    */
292   SetType newSetType(String name, String description);
293 
294   /**
295    * Updates the Settype. This stores all changed/added/removed {@link Set}
296    * instances as well.
297    * 
298    * @param setType
299    *          the Settype to be updated
300    */
301   void saveSetType(SetType setType);
302 
303   /**
304    * Retrieve all Settypes from data base.
305    * 
306    * @return list with all Settypes in the database
307    */
308   List<SetType> getAllSetTypes();
309 
310   /**
311    * Delete {@link SetType} from database.
312    * 
313    * @param setType
314    *          the Settype to be deleted
315    * @return true, if deletion was successful
316    */
317   boolean deleteSeType(SetType setType);
318 
319   // Scenario
320 
321   /**
322    * Adds new projection to database, automatically adds any {@link Parameter}
323    * or {@link ParameterInstance} entities that have not yet been created.
324    * 
325    * @param projection
326    *          the new projection
327    */
328   void newProjection(ProjectionModel projection);
329 
330   /**
331    * Retrieves list of all projections from the database.
332    * 
333    * @return list of all projections from the database
334    * @throws Exception
335    *           if lookup fails
336    */
337   List<ProjectionModel> getAllProjections();
338 
339   /**
340    * Retrieves projection by id.
341    * 
342    * @param id
343    *          the id of the projection
344    * @return the projection, null if none was found
345    */
346   ProjectionModel getProjectionByID(int id);
347 
348   /**
349    * Delete projection from database.
350    * 
351    * @param projection
352    *          the projection to be deleted
353    * @param observer
354    *          the progress observer (may be null)
355    * @return true, if deletion was successful
356    */
357   boolean deleteProjection(ProjectionModel projection,
358       IProgressObserver observer);
359 
360   /**
361    * Saves projection.
362    * 
363    * @param projection
364    *          the projection to be saved/updated
365    */
366   void saveProjection(ProjectionModel projection);
367 
368   // Results
369 
370   /**
371    * Saves results of a single trial. They are reproducible, as they include the
372    * specific parameter assignments that were used.
373    * 
374    * @param resultOfTrial
375    *          the result of the trial
376    */
377   void saveTrialResults(ResultsOfTrial resultOfTrial);
378 
379   /**
380    * Retrieves all results for the given projection. Take care:
381    * 
382    * @param projection
383    *          the projection
384    * 
385    * @return the all results
386    */
387   List<ResultsOfTrial> getAllResults(ProjectionModel projection);
388 
389   /**
390    * Deletes a result.
391    * 
392    * @param resultOfTrial
393    *          the result of trial
394    */
395   void deleteResult(ResultsOfTrial resultOfTrial);
396 
397   /**
398    * Delete all results of the projection.
399    * 
400    * @param projection
401    *          the projection
402    * @param observer
403    *          the progress observer (may be null)
404    */
405   void deleteAllResults(ProjectionModel projection, IProgressObserver observer);
406 
407   /**
408    * Gets the result iterator.
409    * 
410    * @param projection
411    *          the projection for which the results shall be gathered
412    * 
413    * @return the result iterator
414    */
415   IProjectionResultsIterator getResultIterator(ProjectionModel projection);
416 
417   /**
418    * Clears the given object from cache. Use only if you know this object is not
419    * going to be needed again (e.g., during a result export).
420    * 
421    * @param o
422    *          the object to be cleared from cache
423    */
424   void clearCache(Object o);
425 
426 }