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 }