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 }