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

   1 /*-
   2  * ============LICENSE_START=======================================================
   3  *  Copyright (C) 2019-2021, 2024 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     String NAME = "name";
  40     String VERSION = "version";
  41     String TIMESTAMP = "timeStamp";
  42     String PARENT_NAME = "parentname";
  43     String PARENT_VERSION = "parentversion";
  44     String LOCAL_NAME = "localname";
  45
  46     String TABLE_TOKEN = "__TABLE__";
  47
  48     String DELETE_FROM_TABLE = "DELETE FROM __TABLE__ c";
  49
  50     String SELECT_FROM_TABLE = "SELECT c FROM __TABLE__ c";
  51
  52     String WHERE = " WHERE ";
  53     String AND = " AND ";
  54     String ORDER_BY = " ORDER BY c.";
  55
  56     String NAME_FILTER = "c.key.name = :name";
  57     String VERSION_FILTER = "c.key.version = :version";
  58     String TIMESTAMP_FILTER = "c.key.timeStamp = :timeStamp";
  59     String PARENT_NAME_FILTER = "c.key.parentKeyName = :parentname";
  60     String PARENT_VERSION_FILTER = "c.key.parentKeyVersion = :parentversion";
  61     String LOCAL_NAME_FILTER = "c.key.localName = :localname";
  62
  63     String CLONE_ERR_MSG = "Could not clone object of class \"{}\"";
  64
  65     String DELETE_BY_CONCEPT_KEY =
  66         DELETE_FROM_TABLE + WHERE + NAME_FILTER + AND + VERSION_FILTER;
  67
  68     String DELETE_BY_TIMESTAMP_KEY =
  69         DELETE_FROM_TABLE + WHERE + NAME_FILTER + AND + VERSION_FILTER + AND + TIMESTAMP_FILTER;
  70
  71     String DELETE_BY_REFERENCE_KEY =
  72         DELETE_FROM_TABLE + WHERE + PARENT_NAME_FILTER + AND + PARENT_VERSION_FILTER + AND + LOCAL_NAME_FILTER;
  73
  74     String SELECT_ALL_FOR_PARENT =
  75         SELECT_FROM_TABLE + WHERE + PARENT_NAME_FILTER + AND + PARENT_VERSION_FILTER;
  76
  77     String SELECT_ALL_VERSIONS_FOR_PARENT =
  78         SELECT_FROM_TABLE + WHERE + PARENT_NAME_FILTER;
  79
  80     String SELECT_ALL_VERSIONS = SELECT_FROM_TABLE + WHERE + NAME_FILTER;
  81
  82     String SELECT_BY_CONCEPT_KEY =
  83         SELECT_FROM_TABLE + WHERE + NAME_FILTER + AND + VERSION_FILTER;
  84
  85     String SELECT_BY_REFERENCE_KEY =
  86         SELECT_FROM_TABLE + WHERE + PARENT_NAME_FILTER + AND + PARENT_VERSION_FILTER + AND + LOCAL_NAME_FILTER;
  87
  88     /**
  89      * Initialize the Policy Framework DAO with the given parameters.
  90      *
  91      * @param daoParameters parameters to use to access the database
  92      * @throws PfModelException on initialization errors
  93      */
  94     void init(DaoParameters daoParameters) throws PfModelException;
  95
  96     /**
  97      * Close the Policy Framework DAO.
  98      */
  99     void close();
 100
 101     /**
 102      * Creates a Policy Framework concept on the database.
 103      *
 104      * @param <T> the type of the object to create, a subclass of {@link PfConcept}
 105      * @param obj the object to create
 106      */
 107     <T extends PfConcept> void create(T obj);
 108
 109     /**
 110      * Delete a Policy Framework concept on the database.
 111      *
 112      * @param <T> the type of the object to delete, a subclass of {@link PfConcept}
 113      * @param obj the object to delete
 114      */
 115     <T extends PfConcept> void delete(T obj);
 116
 117     /**
 118      * Delete a Policy Framework concept on the database.
 119      *
 120      * @param <T>       the type of the object to delete, a subclass of {@link PfConcept}
 121      * @param someClass the class of the object to delete, a subclass of {@link PfConcept}
 122      * @param key       the key of the object to delete
 123      */
 124     <T extends PfConcept> void delete(Class<T> someClass, PfConceptKey key);
 125
 126     /**
 127      * Delete a Policy Framework concept on the database.
 128      *
 129      * @param <T>       the type of the object to delete, a subclass of {@link PfConcept}
 130      * @param someClass the class of the object to delete, a subclass of {@link PfConcept}
 131      * @param key       the key of the object to delete
 132      */
 133     <T extends PfConcept> void delete(Class<T> someClass, PfReferenceKey key);
 134
 135     /**
 136      * Delete a Policy Framework concept on the database.
 137      *
 138      * @param <T>          the type of the object to delete, a subclass of {@link PfConcept}
 139      * @param someClass    the class of the object to delete, a subclass of {@link PfConcept}
 140      * @param timeStampKey the PfTimestampKey of the object to delete
 141      */
 142     <T extends PfConcept> void delete(Class<T> someClass, PfTimestampKey timeStampKey);
 143
 144     /**
 145      * Create a collection of objects in the database.
 146      *
 147      * @param <T>  the type of the object to create, a subclass of {@link PfConcept}
 148      * @param objs the objects to create
 149      */
 150     <T extends PfConcept> void createCollection(Collection<T> objs);
 151
 152     /**
 153      * Delete a collection of objects in the database.
 154      *
 155      * @param <T>  the type of the objects to delete, a subclass of {@link PfConcept}
 156      * @param objs the objects to delete
 157      */
 158     <T extends PfConcept> void deleteCollection(Collection<T> objs);
 159
 160     /**
 161      * Delete a collection of objects in the database referred to by concept key.
 162      *
 163      * @param <T>       the type of the objects to delete, a subclass of {@link PfConcept}
 164      * @param someClass the class of the objects to delete, a subclass of {@link PfConcept}
 165      * @param keys      the keys of the objects to delete
 166      * @return the number of objects deleted
 167      */
 168     <T extends PfConcept> int deleteByConceptKey(Class<T> someClass, Collection<PfConceptKey> keys);
 169
 170     /**
 171      * Delete a collection of objects in the database referred to by reference key.
 172      *
 173      * @param <T>       the type of the objects to delete, a subclass of {@link PfConcept}
 174      * @param someClass the class of the objects to delete, a subclass of {@link PfConcept}
 175      * @param keys      the keys of the objects to delete
 176      * @return the number of objects deleted
 177      */
 178     <T extends PfConcept> int deleteByReferenceKey(Class<T> someClass, Collection<PfReferenceKey> keys);
 179
 180     /**
 181      * Delete all objects of a given class in the database.
 182      *
 183      * @param <T>       the type of the objects to delete, a subclass of {@link PfConcept}
 184      * @param someClass the class of the objects to delete, a subclass of {@link PfConcept}
 185      */
 186     <T extends PfConcept> void deleteAll(Class<T> someClass);
 187
 188     /**
 189      * Get an object from the database, referred to by concept key.
 190      *
 191      * @param <T>       the type of the object to get, a subclass of {@link PfConcept}
 192      * @param someClass the class of the object to get, a subclass of {@link PfConcept}, if name is null, all concepts
 193      *                  of type T are returned, if name is not null and version is null, all versions of that concept
 194      *                  matching the name are returned.
 195      * @param name      the name of the object to get, null returns all objects
 196      * @param version   the version the object to get, null returns all objects for a specified name
 197      * @return the objects that was retrieved from the database
 198      */
 199     <T extends PfConcept> List<T> getFiltered(Class<T> someClass, String name, String version);
 200
 201     /**
 202      * Get an object from the database, referred to by concept key.
 203      *
 204      * @param <T>          the type of the object to get, a subclass of {@link PfConcept}
 205      * @param someClass    the class of the object to get, a subclass of {@link PfConcept}, if name is null, all
 206      *                     concepts of type T are returned, if name is not null and version is null, all versions of
 207      *                     that concept matching the name are returned.
 208      * @param filterParams filter parameters
 209      * @return the objects that was retrieved from the database
 210      */
 211     <T extends PfConcept> List<T> getFiltered(Class<T> someClass, PfFilterParametersIntfc filterParams);
 212
 213     /**
 214      * Get an object from the database, referred to by concept key.
 215      *
 216      * @param <T>       the type of the object to get, a subclass of {@link PfConcept}
 217      * @param someClass the class of the object to get, a subclass of {@link PfConcept}
 218      * @param key       the PfConceptKey of the object to get
 219      * @return the object that was retrieved from the database
 220      */
 221     <T extends PfConcept> T get(Class<T> someClass, PfConceptKey key);
 222
 223     /**
 224      * Get an object from the database, referred to by reference key.
 225      *
 226      * @param <T>       the type of the object to get, a subclass of {@link PfConcept}
 227      * @param someClass the class of the object to get, a subclass of {@link PfConcept}
 228      * @param key       the PfReferenceKey of the object to get
 229      * @return the object that was retrieved from the database or null if the object was not retrieved
 230      */
 231     <T extends PfConcept> T get(Class<T> someClass, PfReferenceKey key);
 232
 233     /**
 234      * Get an object from the database, referred to by reference key.
 235      *
 236      * @param <T>          the type of the object to get, a subclass of {@link PfConcept}
 237      * @param someClass    the class of the object to get, a subclass of {@link PfConcept}
 238      * @param timestampKey the PfTimestampKey of the object to get
 239      * @return the object that was retrieved from the database or null if the object was not retrieved
 240      */
 241     <T extends PfConcept> T get(Class<T> someClass, PfTimestampKey timestampKey);
 242
 243     /**
 244      * Get an object from the database, referred to by reference timestamp key.
 245      *
 246      * @param <T>       the type of the object to get, a subclass of {@link PfConcept}
 247      * @param someClass the class of the object to get, a subclass of {@link PfConcept}
 248      * @param key       the PfReferenceTimestampKey of the object to get
 249      * @return the object that was retrieved from the database or null if the object was not retrieved
 250      */
 251     <T extends PfConcept> T get(Class<T> someClass, PfReferenceTimestampKey key);
 252
 253     /**
 254      * Get all the objects in the database of a given type.
 255      *
 256      * @param <T>       the type of the objects to get, a subclass of {@link PfConcept}
 257      * @param someClass the class of the objects to get, a subclass of {@link PfConcept}
 258      * @return the objects or null if no objects were retrieved
 259      */
 260     <T extends PfConcept> List<T> getAll(Class<T> someClass);
 261
 262     /**
 263      * Get all the objects in the database of the given type with the given parent concept key.
 264      *
 265      * @param <T>       the type of the objects to get, a subclass of {@link PfConcept}
 266      * @param someClass the class of the objects to get, a subclass of {@link PfConcept}
 267      * @param parentKey the parent key of the concepts to get
 268      * @return the all
 269      */
 270     <T extends PfConcept> List<T> getAll(Class<T> someClass, PfConceptKey parentKey);
 271
 272     /**
 273      * Get all the objects in the database of a given type.
 274      *
 275      * @param <T>        the type of the objects to get, a subclass of {@link PfConcept}
 276      * @param someClass  the class of the objects to get, a subclass of {@link PfConcept}
 277      * @param orderBy    field from class to order results by
 278      * @param numRecords number of records to be retrieved
 279      * @return the objects or null if no objects were retrieved
 280      */
 281     <T extends PfConcept> List<T> getAll(Class<T> someClass, String orderBy, Integer numRecords);
 282
 283     /**
 284      * Get all the objects in the database of a given type.
 285      *
 286      * @param <T>       the type of the objects to get, a subclass of {@link PfConcept}
 287      * @param someClass the class of the objects to get, a subclass of {@link PfConcept}
 288      * @param name      the name of the concepts for which to get all versions
 289      * @return the objects or null if no objects were retrieved
 290      */
 291     <T extends PfConcept> List<T> getAllVersions(Class<T> someClass, final String name);
 292
 293     /**
 294      * Get all the objects in the database of a given type.
 295      *
 296      * @param <T>           the type of the objects to get, a subclass of {@link PfConcept}
 297      * @param someClass     the class of the objects to get, a subclass of {@link PfConcept}
 298      * @param parentKeyName the name of the concepts for which to get all versions
 299      * @return the objects or null if no objects were retrieved
 300      */
 301     <T extends PfConcept> List<T> getAllVersionsByParent(Class<T> someClass, final String parentKeyName);
 302
 303     /**
 304      * Get a concept from the database with the given concept key.
 305      *
 306      * @param <T>       the type of the object to get, a subclass of {@link PfConcept}
 307      * @param someClass the class of the object to get, a subclass of {@link PfConcept}
 308      * @param conceptId the concept key of the concept to get
 309      * @return the concept that matches the key or null if the concept is not retrieved
 310      */
 311     <T extends PfConcept> T getConcept(Class<T> someClass, PfConceptKey conceptId);
 312
 313     /**
 314      * Get a concept from the database with the given reference key.
 315      *
 316      * @param <T>       the type of the object to get, a subclass of {@link PfConcept}
 317      * @param someClass the class of the object to get, a subclass of {@link PfConcept}
 318      * @param conceptId the concept key of the concept to get
 319      * @return the concept that matches the key or null if the concept is not retrieved
 320      */
 321     <T extends PfConcept> T getConcept(Class<T> someClass, PfReferenceKey conceptId);
 322
 323     /**
 324      * Get the number of instances of a concept that exist in the database.
 325      *
 326      * @param <T>       the type of the object to get, a subclass of {@link PfConcept}
 327      * @param someClass the class of the object to get, a subclass of {@link PfConcept}
 328      * @return the number of instances of the concept in the database
 329      */
 330     <T extends PfConcept> long size(Class<T> someClass);
 331
 332     /**
 333      * Update a concept in the database.
 334      *
 335      * @param <T> the type of the object to update, a subclass of {@link PfConcept}
 336      * @param obj the object to update
 337      * @return the updated object
 338      */
 339     <T extends PfConcept> T update(T obj);
 340 }