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 }