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