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