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 class Factory {
  63                 public static ChampGraph newInstance(ChampGraph.Type type, String graphName) {
  64                         switch (type) {
  65                         case IN_MEMORY:
  66                                 return new InMemoryChampGraphImpl.Builder().build();
  67                         case TITAN:
  68                                 return new TitanChampGraphImpl.Builder(graphName)
  69                                                                                         .property("storage.backend", "inmemory")
  70                                                                                         .build();
  71                         /*
  72                         case DSE: //See above, DSE still in beta
  73                         */
  74                         default:
  75                                 throw new RuntimeException("Unknown type of ChampAPI implementation");
  76                         }
  77                 }
  78         }
  79
  80         /**
  81          * Create/Update an object.  If the ChampObject key is present, an update will be attempted,
  82          * otherwise a create will be attempted.  Each implementation has different guarantees on
  83          * validation - see the specific implementation for more details on this.
  84          * @param object - The ChampObject that you wish to store in the graph
  85          * @return The ChampObject as it was stored
  86          * @throws ChampMarshallingException If the {@code object} is not able to be marshalled into the backend representation
  87          * @throws ChampSchemaViolationException If the {@code object} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
  88          * @throws ChampObjectNotExistsException If {@link org.onap.aai.champ.model.ChampObject#getKey}.isPresent() but the object cannot be found in the graph
  89          */
  90         public ChampObject storeObject(ChampObject object) throws ChampMarshallingException, ChampSchemaViolationException, ChampObjectNotExistsException;
  91
  92         /**
  93          * Replace an object.  ChampObject key is mandatory
  94          * Each implementation has different guarantees on
  95          * validation - see the specific implementation for more details on this.
  96          * @param object - The ChampObject that you wish to replace in the graph
  97          * @return The ChampObject as it was stored
  98          * @throws ChampMarshallingException If the {@code object} is not able to be marshalled into the backend representation
  99          * @throws ChampSchemaViolationException If the {@code object} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
 100          * @throws ChampObjectNotExistsException If {@link org.onap.aai.champ.model.ChampObject#getKey} is not present or object not found in the graph
 101          */
 102         public ChampObject replaceObject(ChampObject object) throws ChampMarshallingException, ChampSchemaViolationException, ChampObjectNotExistsException;
 103
 104         /**
 105          * Retrieve an object by its key.
 106          * @param key The key of the ChampObject in the graph {@link org.onap.aai.champ.model.ChampObject#getKey()}
 107          * @return The {@link org.onap.aai.champ.model.ChampObject} if it was present, otherwise {@link Optional#empty()}
 108          * @throws ChampUnmarshallingException If the object was found, but could not be unmarshalled
 109          */
 110         public Optional<ChampObject> retrieveObject(Object key) throws ChampUnmarshallingException;
 111
 112         /**
 113          * Delete an object by its key.
 114          * @param key The key of the ChampObject in the graph {@link ChampObject#getKey}
 115          * @throws ChampObjectNotExistsException If the object did not exist in the graph
 116          */
 117         public void deleteObject(Object key) throws ChampObjectNotExistsException;
 118
 119         /**
 120          * Retrieve all the objects whose properties match the given {@code queryParams}
 121          * @param queryParams The key/value pairs which are found in {@link ChampObject#getProperties}
 122          * @return A {@link Stream} where each {@link ChampObject#getProperties} contains the {@code queryParams}
 123          */
 124         public Stream<ChampObject> queryObjects(Map<String, Object> queryParams);
 125
 126          /**
 127          * Create/Update a relationship.  If the ChampRelationship key is present, an update will be attempted,
 128          * otherwise a create will be attempted.  Each implementation has different guarantees on
 129          * validation - see the specific implementation for more details on this.
 130          * @param relationship - The ChampRelationship that you wish to store in the graph
 131          * @return The ChampRelationship as it was stored
 132          * @throws ChampMarshallingException If the {@code relationship} is not able to be marshalled into the backend representation
 133          * @throws ChampSchemaViolationException If the {@code relationship} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
 134          * @throws ChampObjectNotExistsException If either the source or target object referenced by this relationship does not exist in the graph
 135          * @throws ChampRelationshipNotExistsException If {@link org.onap.aai.champ.model.ChampRelationship#getKey}.isPresent() but the object cannot be found in the graph
 136          * @throws ChampUnmarshallingException If the edge which was created could not be unmarshalled into a ChampRelationship
 137          */
 138         public ChampRelationship storeRelationship(ChampRelationship relationship) throws ChampMarshallingException, ChampObjectNotExistsException, ChampSchemaViolationException, ChampRelationshipNotExistsException, ChampUnmarshallingException;
 139
 140          /**
 141          * 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
 142          * Each implementation has different guarantees on
 143          * validation - see the specific implementation for more details on this.
 144          * @param relationship - The ChampRelationship that you wish to replace in the graph
 145          * @return The ChampRelationship as it was stored
 146          * @throws ChampMarshallingException If the {@code relationship} is not able to be marshalled into the backend representation
 147          * @throws ChampSchemaViolationException If the {@code relationship} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
 148          * @throws ChampRelationshipNotExistsException If {@link org.onap.aai.champ.model.ChampRelationship#getKey} is not present or object not found in the graph
 149          * @throws ChampUnmarshallingException If the edge which was created could not be unmarshalled into a ChampRelationship
 150          */
 151         public ChampRelationship replaceRelationship(ChampRelationship relationship) throws ChampMarshallingException, ChampSchemaViolationException, ChampRelationshipNotExistsException, ChampUnmarshallingException;
 152
 153
 154         /**
 155          * Retrieve a relationship by its key.
 156          * @param key The key of the ChampRelationship in the graph {@link org.onap.aai.champ.model.ChampRelationship#getKey()}
 157          * @return The {@link org.onap.aai.champ.model.ChampRelationship} if it was present, otherwise {@link Optional#empty()}
 158          * @throws ChampUnmarshallingException If the relationship was found, but could not be unmarshalled
 159          */
 160         public Optional<ChampRelationship> retrieveRelationship(Object key) throws ChampUnmarshallingException;
 161
 162          /**
 163          * Delete a relationship by its key.
 164          * @param relationship The ChampRelationship in the graph ({@link ChampRelationship#getKey must be present})
 165          * @throws ChampRelationshipNotExistsException If the object did not exist in the graph
 166          */
 167         public void deleteRelationship(ChampRelationship relationship) throws ChampRelationshipNotExistsException;
 168
 169         /**
 170          * Retrieve the relationships which are incident to the {@code object}
 171          * @param object The object you wish to find incident relationships for
 172          * @return A {@link Stream} where each {@link ChampRelationship} has this {@code object} as either a source or target object
 173          * @throws ChampUnmarshallingException If any of the ChampRelationship objects could not be unmarshalled
 174          * @throws ChampObjectNotExistsException If the {@code object} does not exist in this graph
 175          */
 176         public Stream<ChampRelationship> retrieveRelationships(ChampObject object) throws ChampUnmarshallingException, ChampObjectNotExistsException;
 177
 178         /**
 179          * Retrieve the relationships whose properties match the given {@code queryParams}
 180          * @param queryParams The key/value pairs to search for in the {@link ChampRelationship#getProperties}
 181          * @return A {@link Stream} where each {@link ChampRelationship#getProperties} contains the {@code queryParams}
 182          */
 183         public Stream<ChampRelationship> queryRelationships(Map<String, Object> queryParams);
 184
 185         /**
 186          * Create/Update a {@link ChampPartition}.  If any of the ChampObjects or ChampRelationships
 187          * present in this ChampPartition already exist, an update will be attempted, otherwise a create
 188          * will be attempted.  Each implementation has different guarantees on validation -
 189          * see the specific implementation details for more information on this.
 190          * @param partition The ChampPartition you wish to store in this graph
 191          * @throws ChampMarshallingException If any of the objects or relationships contained in this
 192          *                                                                              partition could not be marshalled into its backed representation
 193          * @throws ChampObjectNotExistsException If any of the objects being updated do not exist, or if a relationship
 194          *                                                                                      contain objects which do not exist in the graph.
 195          * @throws ChampSchemaViolationException If any of the objects or relationships violate the schema provided by {@link retrieveSchema}
 196          * @throws ChampRelationshipNotExistsException If any of the relationships which are being updated do not exist
 197          * @return The ChampPartition as is was stored in the graph (contains keys for each newly created object)
 198          */
 199         public ChampPartition storePartition(ChampPartition partition) throws ChampMarshallingException, ChampObjectNotExistsException, ChampSchemaViolationException, ChampRelationshipNotExistsException;
 200
 201         /**
 202          * Delete the {@code partition} from the graph
 203          * @param partition The partition to delete from the graph
 204          */
 205         public void deletePartition(ChampPartition partition);
 206
 207         /**
 208          * Create/Update an object index on the graph
 209          * @param index The index to create on this {@code graph}
 210          */
 211         public void storeObjectIndex(ChampObjectIndex index);
 212
 213         /**
 214          * Retrieve an object index on the graph by its {@code indexName}
 215          * @param indexName The name of the index to retrieve from the graph
 216          * @return The {@link ChampObjectIndex} which matches the given @{code indexName} in the graph
 217          */
 218         public Optional<ChampObjectIndex> retrieveObjectIndex(String indexName);
 219
 220         /**
 221          * Retrieve the object indices on the graph
 222          * @return A {@link Stream} where each {@link ChampObjectIndex} exists in the graph
 223          */
 224         public Stream<ChampObjectIndex> retrieveObjectIndices();
 225
 226         /**
 227          * Delete the object index on the graph by its {@code indexName}
 228          * @param indexName The name of the index to delete from the graph
 229          * @throws ChampIndexNotExistsException If an index does not exist with the given {@code indexName} in the graph
 230          */
 231         public void deleteObjectIndex(String indexName) throws ChampIndexNotExistsException;
 232
 233         /**
 234          * Create/Update a relationship index on the graph
 235          * @param index The relationship index to create on the graph
 236          */
 237         public void storeRelationshipIndex(ChampRelationshipIndex index);
 238
 239         /**
 240          * Retrieve a relationship index from the graph
 241          * @param indexName The name of the relationship index to retrieve from the graph
 242          * @return The {@link ChampRelationshipIndex} which matches the given {@code indexName} in the graph
 243          *                      or {@link Optional#empty} if no such relationship index exists
 244          */
 245         public Optional<ChampRelationshipIndex> retrieveRelationshipIndex(String indexName);
 246
 247         /**
 248          * Retrieve the relationship indices from the graph
 249          * @return A {@link Stream} where each {@link ChampRelationshipIndex} exists in the graph
 250          */
 251         public Stream<ChampRelationshipIndex> retrieveRelationshipIndices();
 252
 253         /**
 254          * Delete a relationship index from the graph
 255          * @param indexName THe name of the index to delete from the graph
 256          * @throws ChampIndexNotExistsException If an index does not exist with the give {@code indexName} in the graph
 257          */
 258         public void deleteRelationshipIndex(String indexName) throws ChampIndexNotExistsException;
 259
 260         /**
 261          * Create/Update the schema for a graph
 262          * @param schema The {@link ChampSchema} to create or update on the graph
 263          * @throws ChampSchemaViolationException If this schema update would violate the current schema
 264          */
 265         public void storeSchema(ChampSchema schema) throws ChampSchemaViolationException;
 266
 267         /**
 268          * Retrieve the schema for a graph
 269          * @return The {@link ChampSchema} for the graph
 270          */
 271         public ChampSchema retrieveSchema();
 272
 273         /**
 274          * Create/Update an object constraint on a schema
 275          * @param objectConstraint The object constraint you wish to create/update for the graph
 276          * @throws ChampSchemaViolationException If this schema update would violate the current schema
 277          */
 278         public void updateSchema(ChampObjectConstraint objectConstraint) throws ChampSchemaViolationException;
 279
 280         /**
 281          * Create/Update a relationship constraint on a schema
 282          * @param schema The relationship constraint you wish to create/update for the graph
 283          * @throws ChampSchemaViolationException If this schema update would violate the current schema
 284          */
 285         public void updateSchema(ChampRelationshipConstraint schema) throws ChampSchemaViolationException;
 286
 287         /**
 288          * Delete the schema for a graph
 289          */
 290         public void deleteSchema();
 291
 292         /**
 293          * Shutdown the ChampAPI. It is up to the caller to synchronize access to the ChampAPI
 294          * so that shutting it down does not interfere with concurrent operations.
 295          */
 296         public void shutdown();
 297
 298         /**
 299          * Used to determine what the outcome of certain ChampGraph operations will be.  For example,
 300          * if this graph is not capable of deleting object indices, you can expect those calls to fail.
 301          * @see ChampCapabilities
 302          * @return What this graph is capable of performing
 303          */
 304          public ChampCapabilities capabilities();
 305 }