models-dao/src/main/java/org/onap/policy/models/dao/PfDao.java

   1 /*-
   2  * ============LICENSE_START=======================================================
   3  *  Copyright (C) 2019-2021 Nordix Foundation.
   4  *  Modifications Copyright (C) 2021 AT&T Intellectual Property. All rights reserved.
   5  * ================================================================================
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  *      http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  * SPDX-License-Identifier: Apache-2.0
  19  * ============LICENSE_END=========================================================
  20  */
  21
  22 package org.onap.policy.models.dao;
  23
  24 import java.time.Instant;
  25 import java.util.Collection;
  26 import java.util.List;
  27 import java.util.Map;
  28 import org.onap.policy.models.base.PfConcept;
  29 import org.onap.policy.models.base.PfConceptKey;
  30 import org.onap.policy.models.base.PfGeneratedIdKey;
  31 import org.onap.policy.models.base.PfModelException;
  32 import org.onap.policy.models.base.PfReferenceKey;
  33 import org.onap.policy.models.base.PfReferenceTimestampKey;
  34 import org.onap.policy.models.base.PfTimestampKey;
  35
  36 /**
  37  * The Interface PfDao describes the DAO interface for reading and writing Policy Framework {@link PfConcept} concepts
  38  * to and from databases using JDBC.
  39  */
  40 public interface PfDao {
  41
  42     /**
  43      * Initialize the Policy Framework DAO with the given parameters.
  44      *
  45      * @param daoParameters parameters to use to access the database
  46      * @throws PfModelException on initialization errors
  47      */
  48     void init(DaoParameters daoParameters) throws PfModelException;
  49
  50     /**
  51      * Close the Policy Framework DAO.
  52      */
  53     void close();
  54
  55     /**
  56      * Creates an Policy Framework concept on the database.
  57      *
  58      * @param <T> the type of the object to create, a subclass of {@link PfConcept}
  59      * @param obj the object to create
  60      */
  61     <T extends PfConcept> void create(T obj);
  62
  63     /**
  64      * Delete an Policy Framework concept on the database.
  65      *
  66      * @param <T> the type of the object to delete, a subclass of {@link PfConcept}
  67      * @param obj the object to delete
  68      */
  69     <T extends PfConcept> void delete(T obj);
  70
  71     /**
  72      * Delete an Policy Framework concept on the database.
  73      *
  74      * @param <T> the type of the object to delete, a subclass of {@link PfConcept}
  75      * @param someClass the class of the object to delete, a subclass of {@link PfConcept}
  76      * @param key the key of the object to delete
  77      */
  78     <T extends PfConcept> void delete(Class<T> someClass, PfConceptKey key);
  79
  80     /**
  81      * Delete an Policy Framework concept on the database.
  82      *
  83      * @param <T> the type of the object to delete, a subclass of {@link PfConcept}
  84      * @param someClass the class of the object to delete, a subclass of {@link PfConcept}
  85      * @param key the key of the object to delete
  86      */
  87     <T extends PfConcept> void delete(Class<T> someClass, PfReferenceKey key);
  88
  89     /**
  90      * Delete an Policy Framework concept on the database.
  91      *
  92      * @param <T> the type of the object to delete, a subclass of {@link PfConcept}
  93      * @param someClass the class of the object to delete, a subclass of {@link PfConcept}
  94      * @param timeStampKey the PfTimestampKey of the object to delete
  95      */
  96     <T extends PfConcept> void delete(Class<T> someClass, PfTimestampKey timeStampKey);
  97
  98     /**
  99      * Delete an Policy Framework concept on the database.
 100      *
 101      * @param <T> the type of the object to delete, a subclass of {@link PfConcept}
 102      * @param someClass the class of the object to delete, a subclass of {@link PfConcept}
 103      * @param idKey the PfConceptIdKey of the object to delete
 104      */
 105     <T extends PfConcept> void delete(Class<T> someClass, PfGeneratedIdKey idKey);
 106
 107     /**
 108      * Create a collection of objects in the database.
 109      *
 110      * @param <T> the type of the object to create, a subclass of {@link PfConcept}
 111      * @param objs the objects to create
 112      */
 113     <T extends PfConcept> void createCollection(Collection<T> objs);
 114
 115     /**
 116      * Delete a collection of objects in the database.
 117      *
 118      * @param <T> the type of the objects to delete, a subclass of {@link PfConcept}
 119      * @param objs the objects to delete
 120      */
 121     <T extends PfConcept> void deleteCollection(Collection<T> objs);
 122
 123     /**
 124      * Delete a collection of objects in the database referred to by concept key.
 125      *
 126      * @param <T> the type of the objects to delete, a subclass of {@link PfConcept}
 127      * @param someClass the class of the objects to delete, a subclass of {@link PfConcept}
 128      * @param keys the keys of the objects to delete
 129      * @return the number of objects deleted
 130      */
 131     <T extends PfConcept> int deleteByConceptKey(Class<T> someClass, Collection<PfConceptKey> keys);
 132
 133     /**
 134      * Delete a collection of objects in the database referred to by reference key.
 135      *
 136      * @param <T> the type of the objects to delete, a subclass of {@link PfConcept}
 137      * @param someClass the class of the objects to delete, a subclass of {@link PfConcept}
 138      * @param keys the keys of the objects to delete
 139      * @return the number of objects deleted
 140      */
 141     <T extends PfConcept> int deleteByReferenceKey(Class<T> someClass, Collection<PfReferenceKey> keys);
 142
 143     /**
 144      * Delete all objects of a given class in the database.
 145      *
 146      * @param <T> the type of the objects to delete, a subclass of {@link PfConcept}
 147      * @param someClass the class of the objects to delete, a subclass of {@link PfConcept}
 148      */
 149     <T extends PfConcept> void deleteAll(Class<T> someClass);
 150
 151     /**
 152      * Get an object from the database, referred to by concept key.
 153      *
 154      * @param <T> the type of the object to get, a subclass of {@link PfConcept}
 155      * @param someClass the class of the object to get, a subclass of {@link PfConcept}, if name is null, all concepts
 156      *        of type T are returned, if name is not null and version is null, all versions of that concept matching the
 157      *        name are returned.
 158      * @param name the name of the object to get, null returns all objects
 159      * @param version the version the object to get, null returns all objects for a specified name
 160      * @return the objects that was retrieved from the database
 161      */
 162     <T extends PfConcept> List<T> getFiltered(Class<T> someClass, String name, String version);
 163
 164     /**
 165      * Get an object from the database, referred to by concept key.
 166      *
 167      * @param <T> the type of the object to get, a subclass of {@link PfConcept}
 168      * @param someClass the class of the object to get, a subclass of {@link PfConcept}, if name is null, all concepts
 169      *        of type T are returned, if name is not null and version is null, all versions of that concept matching the
 170      *        name are returned.
 171      * @param name the name of the object to get, null returns all objects
 172      * @param version the version the object to get, null returns all objects for a specified name
 173      * @param startTime the start timeStamp to filter from database, filter rule: startTime <= filteredRecord timeStamp
 174      *        <= endTime. null for ignore start time.
 175      * @param endTime the end timeStamp to filter from database, filter rule: startTime <= filteredRecord timeStamp <=
 176      *        endTime. null for ignore end time
 177      * @param filterMap Map store extra key/value used to filter from database, can be null.
 178      * @param sortOrder sortOrder to query database
 179      * @param getRecordNum Total query count from database
 180      * @return the objects that was retrieved from the database
 181      */
 182     <T extends PfConcept> List<T> getFiltered(Class<T> someClass, String name, String version, Instant startTime,
 183             Instant endTime, Map<String, Object> filterMap, String sortOrder, int getRecordNum);
 184
 185     /**
 186      * Get an object from the database, referred to by concept key.
 187      *
 188      * @param <T> the type of the object to get, a subclass of {@link PfConcept}
 189      * @param someClass the class of the object to get, a subclass of {@link PfConcept}
 190      * @param key the PfConceptKey of the object to get
 191      * @return the object that was retrieved from the database
 192      */
 193     <T extends PfConcept> T get(Class<T> someClass, PfConceptKey key);
 194
 195     /**
 196      * Get an object from the database, referred to by reference key.
 197      *
 198      * @param <T> the type of the object to get, a subclass of {@link PfConcept}
 199      * @param someClass the class of the object to get, a subclass of {@link PfConcept}
 200      * @param key the PfReferenceKey of the object to get
 201      * @return the object that was retrieved from the database or null if the object was not retrieved
 202      */
 203     <T extends PfConcept> T get(Class<T> someClass, PfReferenceKey key);
 204
 205     /**
 206      * Get an object from the database, referred to by reference key.
 207      *
 208      * @param <T> the type of the object to get, a subclass of {@link PfConcept}
 209      * @param someClass the class of the object to get, a subclass of {@link PfConcept}
 210      * @param timestampKey the PfTimestampKey of the object to get
 211      * @return the object that was retrieved from the database or null if the object was not retrieved
 212      */
 213     <T extends PfConcept> T get(Class<T> someClass, PfTimestampKey timestampKey);
 214
 215     /**
 216      * Get an object from the database, referred to by reference key.
 217      *
 218      * @param <T> the type of the object to get, a subclass of {@link PfConcept}
 219      * @param someClass the class of the object to get, a subclass of {@link PfConcept}
 220      * @param idKey the PfConceptIdKey of the object to get
 221      * @return the object that was retrieved from the database or null if the object was not retrieved
 222      */
 223     <T extends PfConcept> T get(Class<T> someClass, PfGeneratedIdKey idKey);
 224
 225     /**
 226      * Get an object from the database, referred to by reference timestamp key.
 227      *
 228      * @param <T> the type of the object to get, a subclass of {@link PfConcept}
 229      * @param someClass the class of the object to get, a subclass of {@link PfConcept}
 230      * @param key the PfReferenceTimestampKey of the object to get
 231      * @return the object that was retrieved from the database or null if the object was not retrieved
 232      */
 233     <T extends PfConcept> T get(Class<T> someClass, PfReferenceTimestampKey key);
 234
 235     /**
 236      * Get all the objects in the database of a given type.
 237      *
 238      * @param <T> the type of the objects to get, a subclass of {@link PfConcept}
 239      * @param someClass the class of the objects to get, a subclass of {@link PfConcept}
 240      * @return the objects or null if no objects were retrieved
 241      */
 242     <T extends PfConcept> List<T> getAll(Class<T> someClass);
 243
 244     /**
 245      * Get all the objects in the database of the given type with the given parent concept key.
 246      *
 247      * @param <T> the type of the objects to get, a subclass of {@link PfConcept}
 248      * @param someClass the class of the objects to get, a subclass of {@link PfConcept}
 249      * @param parentKey the parent key of the concepts to get
 250      * @return the all
 251      */
 252     <T extends PfConcept> List<T> getAll(Class<T> someClass, PfConceptKey parentKey);
 253
 254     /**
 255      * Get all the objects in the database of a given type.
 256      *
 257      * @param <T> the type of the objects to get, a subclass of {@link PfConcept}
 258      * @param someClass the class of the objects to get, a subclass of {@link PfConcept}
 259      * @param orderBy field from class to order results by
 260      * @param numRecords number of records to be retrieved
 261      * @return the objects or null if no objects were retrieved
 262      */
 263     <T extends PfConcept> List<T> getAll(Class<T> someClass, String orderBy, Integer numRecords);
 264
 265     /**
 266      * Get all the objects in the database of a given type.
 267      *
 268      * @param <T> the type of the objects to get, a subclass of {@link PfConcept}
 269      * @param someClass the class of the objects to get, a subclass of {@link PfConcept}
 270      * @param name the name of the concepts for which to get all versions
 271      * @return the objects or null if no objects were retrieved
 272      */
 273     <T extends PfConcept> List<T> getAllVersions(Class<T> someClass, final String name);
 274
 275     /**
 276      * Get all the objects in the database of a given type.
 277      *
 278      * @param <T> the type of the objects to get, a subclass of {@link PfConcept}
 279      * @param someClass the class of the objects to get, a subclass of {@link PfConcept}
 280      * @param parentKeyName the name of the concepts for which to get all versions
 281      * @return the objects or null if no objects were retrieved
 282      */
 283     <T extends PfConcept> List<T> getAllVersionsByParent(Class<T> someClass, final String parentKeyName);
 284
 285     /**
 286      * Get all the objects in the database of a given type.
 287      *
 288      * @param <T> the type of the objects to get, a subclass of {@link PfConcept}
 289      * @param someClass the class of the objects to get, a subclass of {@link PfConcept}
 290      * @param key the key of the PfGeneratedIdKey to get
 291      * @param timeStamp the timeStamp of the concepts to get
 292      * @return the objects or null if no objects were retrieved
 293      */
 294     <T extends PfConcept> List<T> getByTimestamp(final Class<T> someClass,
 295                                                  final PfGeneratedIdKey key, final Instant timeStamp);
 296
 297     /**
 298      * Get a concept from the database with the given concept key.
 299      *
 300      * @param <T> the type of the object to get, a subclass of {@link PfConcept}
 301      * @param someClass the class of the object to get, a subclass of {@link PfConcept}
 302      * @param conceptId the concept key of the concept to get
 303      * @return the concept that matches the key or null if the concept is not retrieved
 304      */
 305     <T extends PfConcept> T getConcept(Class<T> someClass, PfConceptKey conceptId);
 306
 307     /**
 308      * Get a concept from the database with the given reference key.
 309      *
 310      * @param <T> the type of the object to get, a subclass of {@link PfConcept}
 311      * @param someClass the class of the object to get, a subclass of {@link PfConcept}
 312      * @param conceptId the concept key of the concept to get
 313      * @return the concept that matches the key or null if the concept is not retrieved
 314      */
 315     <T extends PfConcept> T getConcept(Class<T> someClass, PfReferenceKey conceptId);
 316
 317     /**
 318      * Get the number of instances of a concept that exist in the database.
 319      *
 320      * @param <T> the type of the object to get, a subclass of {@link PfConcept}
 321      * @param someClass the class of the object to get, a subclass of {@link PfConcept}
 322      * @return the number of instances of the concept in the database
 323      */
 324     <T extends PfConcept> long size(Class<T> someClass);
 325
 326     /**
 327      * Update a concept in the database.
 328      *
 329      * @param <T> the type of the object to update, a subclass of {@link PfConcept}
 330      * @param obj the object to update
 331      * @return the updated object
 332      */
 333     <T extends PfConcept> T update(T obj);
 334 }