src/main/java/org/onap/aai/champ/ChampGraph.java

   1 /**
   2  * ============LICENSE_START==========================================
   3  * org.onap.aai
   4  * ===================================================================
   5  * Copyright © 2017 AT&T Intellectual Property. All rights reserved.
   6  * Copyright © 2017 Amdocs
   7  * ===================================================================
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  *        http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  * ============LICENSE_END============================================
  20  * ECOMP is a trademark and service mark of AT&T Intellectual Property.
  21  */
  22 package org.onap.aai.champ;
  23
  24 import java.util.Map;
  25 import java.util.Optional;
  26 import java.util.stream.Stream;
  27
  28 import org.onap.aai.champ.exceptions.ChampIndexNotExistsException;
  29 import org.onap.aai.champ.exceptions.ChampMarshallingException;
  30 import org.onap.aai.champ.exceptions.ChampObjectNotExistsException;
  31 import org.onap.aai.champ.exceptions.ChampRelationshipNotExistsException;
  32 import org.onap.aai.champ.exceptions.ChampSchemaViolationException;
  33 import org.onap.aai.champ.exceptions.ChampUnmarshallingException;
  34 import org.onap.aai.champ.graph.impl.InMemoryChampGraphImpl;
  35 import org.onap.aai.champ.graph.impl.TitanChampGraphImpl;
  36 import org.onap.aai.champ.model.ChampObject;
  37 import org.onap.aai.champ.model.ChampObjectConstraint;
  38 import org.onap.aai.champ.model.ChampObjectIndex;
  39 import org.onap.aai.champ.model.ChampPartition;
  40 import org.onap.aai.champ.model.ChampRelationship;
  41 import org.onap.aai.champ.model.ChampRelationshipConstraint;
  42 import org.onap.aai.champ.model.ChampRelationshipIndex;
  43 import org.onap.aai.champ.model.ChampSchema;
  44
  45 public interface ChampGraph {
  46
  47         /**
  48          * Types that the Factory is capable of constructing
  49          */
  50         public enum Type {
  51                 IN_MEMORY,
  52                 TITAN/*,
  53                 DSE //DSE is still in beta, so leave it out for now
  54                 */
  55         }
  56
  57         /**
  58          * A factory for constructing basic ChampAPI implementations (minimal).
  59          * If finer control is needed, you should consider accessing an implementation's
  60          * constructors/builders.
  61          */
  62         public static final class Factory {
  63                 private Factory(){
  64                         //not called
  65                 }
  66                 public static ChampGraph newInstance(ChampGraph.Type type, String graphName) {
  67                         switch (type) {
  68                         case IN_MEMORY:
  69                                 return new InMemoryChampGraphImpl.Builder().build();
  70                         case TITAN:
  71                                 return new TitanChampGraphImpl.Builder(graphName)
  72                                                                                         .property("storage.backend", "inmemory")
  73                                                                                         .build();
  74                         /*
  75                         case DSE: //See above, DSE still in beta
  76                         */
  77                         default:
  78                                 throw new RuntimeException("Unknown type of ChampAPI implementation");
  79                         }
  80                 }
  81         }
  82
  83         /**
  84          * Create/Update an object.  If the ChampObject key is present, an update will be attempted,
  85          * otherwise a create will be attempted.  Each implementation has different guarantees on
  86          * validation - see the specific implementation for more details on this.
  87          * @param object - The ChampObject that you wish to store in the graph
  88          * @return The ChampObject as it was stored
  89          * @throws ChampMarshallingException If the {@code object} is not able to be marshalled into the backend representation
  90          * @throws ChampSchemaViolationException If the {@code object} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
  91          * @throws ChampObjectNotExistsException If {@link org.onap.aai.champ.model.ChampObject#getKey}.isPresent() but the object cannot be found in the graph
  92          */
  93         public ChampObject storeObject(ChampObject object) throws ChampMarshallingException, ChampSchemaViolationException, ChampObjectNotExistsException;
  94
  95         /**
  96          * Replace an object.  ChampObject key is mandatory
  97          * Each implementation has different guarantees on
  98          * validation - see the specific implementation for more details on this.
  99          * @param object - The ChampObject that you wish to replace in the graph
 100          * @return The ChampObject as it was stored
 101          * @throws ChampMarshallingException If the {@code object} is not able to be marshalled into the backend representation
 102          * @throws ChampSchemaViolationException If the {@code object} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
 103          * @throws ChampObjectNotExistsException If {@link org.onap.aai.champ.model.ChampObject#getKey} is not present or object not found in the graph
 104          */
 105         public ChampObject replaceObject(ChampObject object) throws ChampMarshallingException, ChampSchemaViolationException, ChampObjectNotExistsException;
 106
 107         /**
 108          * Retrieve an object by its key.
 109          * @param key The key of the ChampObject in the graph {@link org.onap.aai.champ.model.ChampObject#getKey()}
 110          * @return The {@link org.onap.aai.champ.model.ChampObject} if it was present, otherwise {@link Optional#empty()}
 111          * @throws ChampUnmarshallingException If the object was found, but could not be unmarshalled
 112          */
 113         public Optional<ChampObject> retrieveObject(Object key) throws ChampUnmarshallingException;
 114
 115         /**
 116          * Delete an object by its key.
 117          * @param key The key of the ChampObject in the graph {@link ChampObject#getKey}
 118          * @throws ChampObjectNotExistsException If the object did not exist in the graph
 119          */
 120         public void deleteObject(Object key) throws ChampObjectNotExistsException;
 121
 122         /**
 123          * Retrieve all the objects whose properties match the given {@code queryParams}
 124          * @param queryParams The key/value pairs which are found in {@link ChampObject#getProperties}
 125          * @return A {@link Stream} where each {@link ChampObject#getProperties} contains the {@code queryParams}
 126          */
 127         public Stream<ChampObject> queryObjects(Map<String, Object> queryParams);
 128
 129          /**
 130          * Create/Update a relationship.  If the ChampRelationship key is present, an update will be attempted,
 131          * otherwise a create will be attempted.  Each implementation has different guarantees on
 132          * validation - see the specific implementation for more details on this.
 133          * @param relationship - The ChampRelationship that you wish to store in the graph
 134          * @return The ChampRelationship as it was stored
 135          * @throws ChampMarshallingException If the {@code relationship} is not able to be marshalled into the backend representation
 136          * @throws ChampSchemaViolationException If the {@code relationship} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
 137          * @throws ChampObjectNotExistsException If either the source or target object referenced by this relationship does not exist in the graph
 138          * @throws ChampRelationshipNotExistsException If {@link org.onap.aai.champ.model.ChampRelationship#getKey}.isPresent() but the object cannot be found in the graph
 139          * @throws ChampUnmarshallingException If the edge which was created could not be unmarshalled into a ChampRelationship
 140          */
 141         public ChampRelationship storeRelationship(ChampRelationship relationship) throws ChampMarshallingException, ChampObjectNotExistsException, ChampSchemaViolationException, ChampRelationshipNotExistsException, ChampUnmarshallingException;
 142
 143          /**
 144          * Replace a relationship. ChampRelationship key is mandatory .The main purpose of this method is to replace the entire properties of an existing relationship .Source/Target can't be updated with this method
 145          * Each implementation has different guarantees on
 146          * validation - see the specific implementation for more details on this.
 147          * @param relationship - The ChampRelationship that you wish to replace in the graph
 148          * @return The ChampRelationship as it was stored
 149          * @throws ChampMarshallingException If the {@code relationship} is not able to be marshalled into the backend representation
 150          * @throws ChampSchemaViolationException If the {@code relationship} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
 151          * @throws ChampRelationshipNotExistsException If {@link org.onap.aai.champ.model.ChampRelationship#getKey} is not present or object not found in the graph
 152          * @throws ChampUnmarshallingException If the edge which was created could not be unmarshalled into a ChampRelationship
 153          */
 154         public ChampRelationship replaceRelationship(ChampRelationship relationship) throws ChampMarshallingException, ChampSchemaViolationException, ChampRelationshipNotExistsException, ChampUnmarshallingException;
 155
 156
 157         /**
 158          * Retrieve a relationship by its key.
 159          * @param key The key of the ChampRelationship in the graph {@link org.onap.aai.champ.model.ChampRelationship#getKey()}
 160          * @return The {@link org.onap.aai.champ.model.ChampRelationship} if it was present, otherwise {@link Optional#empty()}
 161          * @throws ChampUnmarshallingException If the relationship was found, but could not be unmarshalled
 162          */
 163         public Optional<ChampRelationship> retrieveRelationship(Object key) throws ChampUnmarshallingException;
 164
 165          /**
 166          * Delete a relationship by its key.
 167          * @param relationship The ChampRelationship in the graph ({@link ChampRelationship#getKey must be present})
 168          * @throws ChampRelationshipNotExistsException If the object did not exist in the graph
 169          */
 170         public void deleteRelationship(ChampRelationship relationship) throws ChampRelationshipNotExistsException;
 171
 172         /**
 173          * Retrieve the relationships which are incident to the {@code object}
 174          * @param object The object you wish to find incident relationships for
 175          * @return A {@link Stream} where each {@link ChampRelationship} has this {@code object} as either a source or target object
 176          * @throws ChampUnmarshallingException If any of the ChampRelationship objects could not be unmarshalled
 177          * @throws ChampObjectNotExistsException If the {@code object} does not exist in this graph
 178          */
 179         public Stream<ChampRelationship> retrieveRelationships(ChampObject object) throws ChampUnmarshallingException, ChampObjectNotExistsException;
 180
 181         /**
 182          * Retrieve the relationships whose properties match the given {@code queryParams}
 183          * @param queryParams The key/value pairs to search for in the {@link ChampRelationship#getProperties}
 184          * @return A {@link Stream} where each {@link ChampRelationship#getProperties} contains the {@code queryParams}
 185          */
 186         public Stream<ChampRelationship> queryRelationships(Map<String, Object> queryParams);
 187
 188         /**
 189          * Create/Update a {@link ChampPartition}.  If any of the ChampObjects or ChampRelationships
 190          * present in this ChampPartition already exist, an update will be attempted, otherwise a create
 191          * will be attempted.  Each implementation has different guarantees on validation -
 192          * see the specific implementation details for more information on this.
 193          * @param partition The ChampPartition you wish to store in this graph
 194          * @throws ChampMarshallingException If any of the objects or relationships contained in this
 195          *                                                                              partition could not be marshalled into its backed representation
 196          * @throws ChampObjectNotExistsException If any of the objects being updated do not exist, or if a relationship
 197          *                                                                                      contain objects which do not exist in the graph.
 198          * @throws ChampSchemaViolationException If any of the objects or relationships violate the schema provided by {@link retrieveSchema}
 199          * @throws ChampRelationshipNotExistsException If any of the relationships which are being updated do not exist
 200          * @return The ChampPartition as is was stored in the graph (contains keys for each newly created object)
 201          */
 202         public ChampPartition storePartition(ChampPartition partition) throws ChampMarshallingException, ChampObjectNotExistsException, ChampSchemaViolationException, ChampRelationshipNotExistsException;
 203
 204         /**
 205          * Delete the {@code partition} from the graph
 206          * @param partition The partition to delete from the graph
 207          */
 208         public void deletePartition(ChampPartition partition);
 209
 210         /**
 211          * Create/Update an object index on the graph
 212          * @param index The index to create on this {@code graph}
 213          */
 214         public void storeObjectIndex(ChampObjectIndex index);
 215
 216         /**
 217          * Retrieve an object index on the graph by its {@code indexName}
 218          * @param indexName The name of the index to retrieve from the graph
 219          * @return The {@link ChampObjectIndex} which matches the given @{code indexName} in the graph
 220          */
 221         public Optional<ChampObjectIndex> retrieveObjectIndex(String indexName);
 222
 223         /**
 224          * Retrieve the object indices on the graph
 225          * @return A {@link Stream} where each {@link ChampObjectIndex} exists in the graph
 226          */
 227         public Stream<ChampObjectIndex> retrieveObjectIndices();
 228
 229         /**
 230          * Delete the object index on the graph by its {@code indexName}
 231          * @param indexName The name of the index to delete from the graph
 232          * @throws ChampIndexNotExistsException If an index does not exist with the given {@code indexName} in the graph
 233          */
 234         public void deleteObjectIndex(String indexName) throws ChampIndexNotExistsException;
 235
 236         /**
 237          * Create/Update a relationship index on the graph
 238          * @param index The relationship index to create on the graph
 239          */
 240         public void storeRelationshipIndex(ChampRelationshipIndex index);
 241
 242         /**
 243          * Retrieve a relationship index from the graph
 244          * @param indexName The name of the relationship index to retrieve from the graph
 245          * @return The {@link ChampRelationshipIndex} which matches the given {@code indexName} in the graph
 246          *                      or {@link Optional#empty} if no such relationship index exists
 247          */
 248         public Optional<ChampRelationshipIndex> retrieveRelationshipIndex(String indexName);
 249
 250         /**
 251          * Retrieve the relationship indices from the graph
 252          * @return A {@link Stream} where each {@link ChampRelationshipIndex} exists in the graph
 253          */
 254         public Stream<ChampRelationshipIndex> retrieveRelationshipIndices();
 255
 256         /**
 257          * Delete a relationship index from the graph
 258          * @param indexName THe name of the index to delete from the graph
 259          * @throws ChampIndexNotExistsException If an index does not exist with the give {@code indexName} in the graph
 260          */
 261         public void deleteRelationshipIndex(String indexName) throws ChampIndexNotExistsException;
 262
 263         /**
 264          * Create/Update the schema for a graph
 265          * @param schema The {@link ChampSchema} to create or update on the graph
 266          * @throws ChampSchemaViolationException If this schema update would violate the current schema
 267          */
 268         public void storeSchema(ChampSchema schema) throws ChampSchemaViolationException;
 269
 270         /**
 271          * Retrieve the schema for a graph
 272          * @return The {@link ChampSchema} for the graph
 273          */
 274         public ChampSchema retrieveSchema();
 275
 276         /**
 277          * Create/Update an object constraint on a schema
 278          * @param objectConstraint The object constraint you wish to create/update for the graph
 279          * @throws ChampSchemaViolationException If this schema update would violate the current schema
 280          */
 281         public void updateSchema(ChampObjectConstraint objectConstraint) throws ChampSchemaViolationException;
 282
 283         /**
 284          * Create/Update a relationship constraint on a schema
 285          * @param schema The relationship constraint you wish to create/update for the graph
 286          * @throws ChampSchemaViolationException If this schema update would violate the current schema
 287          */
 288         public void updateSchema(ChampRelationshipConstraint schema) throws ChampSchemaViolationException;
 289
 290         /**
 291          * Delete the schema for a graph
 292          */
 293         public void deleteSchema();
 294
 295         /**
 296          * Shutdown the ChampAPI. It is up to the caller to synchronize access to the ChampAPI
 297          * so that shutting it down does not interfere with concurrent operations.
 298          */
 299         public void shutdown();
 300
 301         /**
 302          * Used to determine what the outcome of certain ChampGraph operations will be.  For example,
 303          * if this graph is not capable of deleting object indices, you can expect those calls to fail.
 304          * @see ChampCapabilities
 305          * @return What this graph is capable of performing
 306          */
 307          public ChampCapabilities capabilities();
 308 }