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