champ-lib/champ-core/src/main/java/org/onap/aai/champcore/ChampGraph.java

   1 /**
   2  * ============LICENSE_START==========================================
   3  * org.onap.aai
   4  * ===================================================================
   5  * Copyright © 2017-2018 AT&T Intellectual Property. All rights reserved.
   6  * Copyright © 2017-2018 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  */
  21 package org.onap.aai.champcore;
  22
  23 import java.util.List;
  24 import java.util.Map;
  25 import java.util.Optional;
  26 import java.util.stream.Stream;
  27
  28 import org.onap.aai.champcore.exceptions.ChampIndexNotExistsException;
  29 import org.onap.aai.champcore.exceptions.ChampMarshallingException;
  30 import org.onap.aai.champcore.exceptions.ChampObjectNotExistsException;
  31 import org.onap.aai.champcore.exceptions.ChampRelationshipNotExistsException;
  32 import org.onap.aai.champcore.exceptions.ChampSchemaViolationException;
  33 import org.onap.aai.champcore.exceptions.ChampTransactionException;
  34 import org.onap.aai.champcore.exceptions.ChampUnmarshallingException;
  35 import org.onap.aai.champcore.model.ChampObject;
  36 import org.onap.aai.champcore.model.ChampObjectConstraint;
  37 import org.onap.aai.champcore.model.ChampObjectIndex;
  38 import org.onap.aai.champcore.model.ChampPartition;
  39 import org.onap.aai.champcore.model.ChampRelationship;
  40 import org.onap.aai.champcore.model.ChampRelationshipConstraint;
  41 import org.onap.aai.champcore.model.ChampRelationshipIndex;
  42 import org.onap.aai.champcore.model.ChampSchema;
  43
  44 public interface ChampGraph {
  45
  46   /**
  47    * Opens a transaction within the graph data store.
  48    *
  49    * @return - A transaction object.
  50    */
  51   public ChampTransaction openTransaction();
  52
  53   /**
  54    * Attempts to commit the supplied open transaction.
  55    *
  56    * @param transaction - The transaction to be committed.
  57    *
  58    * @throws ChampTransactionException - If an attempt to commit or rollback the transaction failed.
  59    */
  60   public void commitTransaction(ChampTransaction transaction) throws ChampTransactionException;
  61
  62   /**
  63    * Attempts to roll back the supplied open transaction.
  64    *
  65    * @param transaction - The transaction to be committed.
  66    *
  67    * @throws ChampTransactionException - If an attempt to commit or rollback the transaction failed.
  68    */
  69   public void rollbackTransaction(ChampTransaction transaction) throws ChampTransactionException;
  70
  71   /**
  72    * Create/Update an object.
  73    * <p>
  74    * If the ChampObject key is present, an update will be attempted,
  75    * otherwise a create will be attempted.  Each implementation has different guarantees on
  76    * validation - see the specific implementation for more details on this.
  77    *
  78    * @param object      - The ChampObject that you wish to store in the graph
  79    *
  80    * @return The ChampObject as it was stored
  81    *
  82    * @throws ChampMarshallingException If the {@code object} is not able to be marshalled into the backend representation
  83    * @throws ChampSchemaViolationException If the {@code object} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
  84    * @throws ChampObjectNotExistsException If {@link org.onap.aai.champcore.model.ChampObject#getKey}.isPresent() but the object cannot be found in the graph
  85    * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
  86    */
  87   public ChampObject storeObject(ChampObject object) throws ChampMarshallingException, ChampSchemaViolationException, ChampObjectNotExistsException, ChampTransactionException;
  88
  89   /**
  90     * Create/Update an object.
  91     * <p>
  92     * If the ChampObject key is present, an update will be attempted,
  93     * otherwise a create will be attempted.  Each implementation has different guarantees on
  94     * validation - see the specific implementation for more details on this.
  95     * <p>
  96     * If a transaction context is not provided, then a transaction will be automatically
  97     * created and committed for this operation only, otherwise, the supplied transaction
  98     * will be used and it will be up to the caller to commit the transaction at its
  99     * discretion.
 100     *
 101     * @param object      - The ChampObject that you wish to store in the graph
 102     * @param transaction - Optional transaction context to perform the operation in.
 103     *
 104     * @return The ChampObject as it was stored
 105     *
 106     * @throws ChampMarshallingException If the {@code object} is not able to be marshalled into the backend representation
 107     * @throws ChampSchemaViolationException If the {@code object} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
 108     * @throws ChampObjectNotExistsException If {@link org.onap.aai.champcore.model.ChampObject#getKey}.isPresent() but the object cannot be found in the graph
 109     * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 110     */
 111   public ChampObject storeObject(ChampObject object, Optional<ChampTransaction> transaction) throws ChampMarshallingException, ChampSchemaViolationException, ChampObjectNotExistsException, ChampTransactionException;
 112
 113   /**
 114    * Replace an object.  ChampObject key is mandatory
 115    * <p>
 116    * Each implementation has different guarantees on validation - see the specific implementation
 117    * for more details on this.
 118    *
 119    * @param object - The ChampObject that you wish to replace in the graph
 120    *
 121    * @return The ChampObject as it was stored
 122    *
 123    * @throws ChampMarshallingException If the {@code object} is not able to be marshalled into the backend representation
 124    * @throws ChampSchemaViolationException If the {@code object} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
 125    * @throws ChampObjectNotExistsException If {@link org.onap.aai.champcore.model.ChampObject#getKey} is not present or object not found in the graph
 126    * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 127    */
 128   public ChampObject replaceObject(ChampObject object) throws ChampMarshallingException, ChampSchemaViolationException, ChampObjectNotExistsException, ChampTransactionException;
 129
 130   /**
 131     * Replace an object.  ChampObject key is mandatory
 132     * <p>
 133     * Each implementation has different guarantees on validation - see the specific implementation
 134     * for more details on this.
 135     * <p>
 136     * If a transaction context is not provided, then a transaction will be automatically
 137     * created and committed for this operation only, otherwise, the supplied transaction
 138     * will be used and it will be up to the caller to commit the transaction at its
 139     * discretion.
 140     *
 141         * @param object - The ChampObject that you wish to replace in the graph
 142         * @param transaction - Optional transaction context to perform the operation in.
 143     *
 144         * @return The ChampObject as it was stored
 145         *
 146     * @throws ChampMarshallingException If the {@code object} is not able to be marshalled into the backend representation
 147     * @throws ChampSchemaViolationException If the {@code object} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
 148     * @throws ChampObjectNotExistsException If {@link org.onap.aai.champcore.model.ChampObject#getKey} is not present or object not found in the graph
 149     * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 150     */
 151   public ChampObject replaceObject(ChampObject object, Optional<ChampTransaction> transaction) throws ChampMarshallingException, ChampSchemaViolationException, ChampObjectNotExistsException, ChampTransactionException;
 152
 153   /**
 154    * Retrieve an object by its key.
 155    *
 156    * @param key         - The key of the ChampObject in the graph {@link org.onap.aai.champcore.model.ChampObject#getKey()}
 157    *
 158    * @return The {@link org.onap.aai.champcore.model.ChampObject} if it was present, otherwise {@link Optional#empty()}
 159    *
 160    * @throws ChampUnmarshallingException If the object was found, but could not be unmarshalled
 161    * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 162    */
 163   public Optional<ChampObject> retrieveObject(Object key) throws ChampUnmarshallingException, ChampTransactionException;
 164
 165
 166   /**
 167     * Retrieve an object by its key.
 168     * <p>
 169     * If a transaction context is not provided, then a transaction will be automatically
 170     * created and committed for this operation only, otherwise, the supplied transaction
 171     * will be used and it will be up to the caller to commit the transaction at its
 172     * discretion.
 173     *
 174     * @param key         - The key of the ChampObject in the graph {@link org.onap.aai.champcore.model.ChampObject#getKey()}
 175     * @param transaction - Optional transaction context to perform the operation in.
 176     *
 177     * @return The {@link org.onap.aai.champcore.model.ChampObject} if it was present, otherwise {@link Optional#empty()}
 178     *
 179     * @throws ChampUnmarshallingException If the object was found, but could not be unmarshalled
 180     * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 181     */
 182   public Optional<ChampObject> retrieveObject(Object key, Optional<ChampTransaction> transaction) throws ChampUnmarshallingException, ChampTransactionException;
 183
 184   /**
 185    * Delete an object by its key.
 186    *
 187    * @param key         - The key of the ChampObject in the graph {@link ChampObject#getKey}
 188    *
 189    * @throws ChampObjectNotExistsException If the object did not exist in the graph
 190    * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 191    */
 192   public void deleteObject(Object key) throws ChampObjectNotExistsException, ChampTransactionException;
 193
 194   /**
 195     * Delete an object by its key.
 196     * <p>
 197     * If a transaction context is not provided, then a transaction will be automatically
 198     * created and committed for this operation only, otherwise, the supplied transaction
 199     * will be used and it will be up to the caller to commit the transaction at its
 200     * discretion.
 201     *
 202     * @param key         - The key of the ChampObject in the graph {@link ChampObject#getKey}
 203     * @param transaction - Optional transaction context to perform the operation in.
 204     *
 205     * @throws ChampObjectNotExistsException If the object did not exist in the graph
 206     * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 207     */
 208   public void deleteObject(Object key, Optional<ChampTransaction> transaction) throws ChampObjectNotExistsException, ChampTransactionException;
 209
 210   /**
 211    * Retrieve all the objects whose properties match the given {@code queryParams}
 212    *
 213    * @param queryParams - The key/value pairs which are found in {@link ChampObject#getProperties}
 214    *
 215    * @return - A {@link Stream} where each {@link ChampObject#getProperties} contains the {@code queryParams}
 216    *
 217    * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 218    */
 219   public Stream<ChampObject> queryObjects(Map<String, Object> queryParams) throws ChampTransactionException;
 220
 221
 222   /**
 223     * Retrieve all the objects whose properties match the given {@code queryParams}
 224     * <p>
 225     * If a transaction context is not provided, then a transaction will be automatically
 226     * created and committed for this operation only, otherwise, the supplied transaction
 227     * will be used and it will be up to the caller to commit the transaction at its
 228     * discretion.
 229     *
 230     * @param queryParams - The key/value pairs which are found in {@link ChampObject#getProperties}
 231     * @param transaction - Optional transaction context to perform the operation in.
 232     *
 233     * @return - A {@link Stream} where each {@link ChampObject#getProperties} contains the {@code queryParams}
 234     *
 235     * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 236     */
 237   public Stream<ChampObject> queryObjects(Map<String, Object> queryParams, Optional<ChampTransaction> transaction) throws ChampTransactionException;
 238
 239   /**
 240    * Create/Update a relationship.
 241    * <p>
 242    * If the ChampRelationship key is present, an update will be attempted,
 243    * otherwise a create will be attempted.  Each implementation has different guarantees on
 244    * validation - see the specific implementation for more details on this.
 245    *
 246    * @param relationship - The ChampRelationship that you wish to store in the graph
 247    *
 248    * @return The ChampRelationship as it was stored
 249    *
 250    * @throws ChampMarshallingException If the {@code relationship} is not able to be marshalled into the backend representation
 251    * @throws ChampSchemaViolationException If the {@code relationship} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
 252    * @throws ChampObjectNotExistsException If either the source or target object referenced by this relationship does not exist in the graph
 253    * @throws ChampRelationshipNotExistsException If {@link org.onap.aai.champcore.model.ChampRelationship#getKey}.isPresent() but the object cannot be found in the graph
 254    * @throws ChampUnmarshallingException If the edge which was created could not be unmarshalled into a ChampRelationship
 255    * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 256    */
 257   public ChampRelationship storeRelationship(ChampRelationship relationship) throws ChampMarshallingException, ChampObjectNotExistsException, ChampSchemaViolationException, ChampRelationshipNotExistsException, ChampUnmarshallingException, ChampTransactionException;
 258
 259
 260   /**
 261     * Create/Update a relationship.
 262     * <p>
 263     * If the ChampRelationship key is present, an update will be attempted,
 264     * otherwise a create will be attempted.  Each implementation has different guarantees on
 265     * validation - see the specific implementation for more details on this.
 266     * <p>
 267     * If a transaction context is not provided, then a transaction will be automatically
 268     * created and committed for this operation only, otherwise, the supplied transaction
 269     * will be used and it will be up to the caller to commit the transaction at its
 270     * discretion.
 271     *
 272     * @param relationship - The ChampRelationship that you wish to store in the graph
 273     * @param transaction  - Optional transaction context to perform the operation in.
 274     *
 275     * @return The ChampRelationship as it was stored
 276     *
 277     * @throws ChampMarshallingException If the {@code relationship} is not able to be marshalled into the backend representation
 278     * @throws ChampSchemaViolationException If the {@code relationship} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
 279     * @throws ChampObjectNotExistsException If either the source or target object referenced by this relationship does not exist in the graph
 280     * @throws ChampRelationshipNotExistsException If {@link org.onap.aai.champcore.model.ChampRelationship#getKey}.isPresent() but the object cannot be found in the graph
 281     * @throws ChampUnmarshallingException If the edge which was created could not be unmarshalled into a ChampRelationship
 282     * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 283     */
 284   public ChampRelationship storeRelationship(ChampRelationship relationship, Optional<ChampTransaction> transaction) throws ChampMarshallingException, ChampObjectNotExistsException, ChampSchemaViolationException, ChampRelationshipNotExistsException, ChampUnmarshallingException, ChampTransactionException;
 285
 286   /**
 287    * Replace a relationship.
 288    * <p>
 289    * ChampRelationship key is mandatory.  The main purpose of this method is to replace the
 290    * entire properties of an existing relationship.  Source/Target can't be updated with this method.
 291    * <p>
 292    * Each implementation has different guarantees on validation - see the specific implementation
 293    * for more details on this.
 294    *
 295    * @param relationship - The ChampRelationship that you wish to replace in the graph
 296    *
 297    * @return The ChampRelationship as it was stored
 298    *
 299    * @throws ChampMarshallingException If the {@code relationship} is not able to be marshalled into the backend representation
 300    * @throws ChampSchemaViolationException If the {@code relationship} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
 301    * @throws ChampRelationshipNotExistsException If {@link org.onap.aai.champcore.model.ChampRelationship#getKey} is not present or object not found in the graph
 302    * @throws ChampUnmarshallingException If the edge which was created could not be unmarshalled into a ChampRelationship
 303    * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 304    */
 305   public ChampRelationship replaceRelationship(ChampRelationship relationship) throws ChampMarshallingException, ChampSchemaViolationException, ChampRelationshipNotExistsException, ChampUnmarshallingException, ChampTransactionException;
 306
 307   /**
 308     * Replace a relationship.
 309     * <p>
 310     * ChampRelationship key is mandatory.  The main purpose of this method is to replace the
 311     * entire properties of an existing relationship.  Source/Target can't be updated with this method.
 312     * <p>
 313     * Each implementation has different guarantees on validation - see the specific implementation
 314     * for more details on this.
 315     * <p>
 316     * If a transaction context is not provided, then a transaction will be automatically
 317     * created and committed for this operation only, otherwise, the supplied transaction
 318     * will be used and it will be up to the caller to commit the transaction at its
 319     * discretion.
 320     *
 321     * @param relationship - The ChampRelationship that you wish to replace in the graph
 322     * @param transaction  - Optional transaction context to perform the operation in.
 323     *
 324     * @return The ChampRelationship as it was stored
 325     *
 326     * @throws ChampMarshallingException If the {@code relationship} is not able to be marshalled into the backend representation
 327     * @throws ChampSchemaViolationException If the {@code relationship} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
 328     * @throws ChampRelationshipNotExistsException If {@link org.onap.aai.champcore.model.ChampRelationship#getKey} is not present or object not found in the graph
 329     * @throws ChampUnmarshallingException If the edge which was created could not be unmarshalled into a ChampRelationship
 330     * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 331     */
 332   public ChampRelationship replaceRelationship(ChampRelationship relationship, Optional<ChampTransaction> transaction) throws ChampMarshallingException, ChampSchemaViolationException, ChampRelationshipNotExistsException, ChampUnmarshallingException, ChampTransactionException;
 333
 334   /**
 335    * Retrieve a relationship by its key.
 336    *
 337    * @param key          - The key of the ChampRelationship in the graph
 338    *                       {@link org.onap.aai.champcore.model.ChampRelationship#getKey()}
 339    *
 340    * @return The {@link org.onap.aai.champcore.model.ChampRelationship} if it was present, otherwise {@link Optional#empty()}
 341    *
 342    * @throws ChampUnmarshallingException If the relationship was found, but could not be unmarshalled
 343    * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 344    */
 345   public Optional<ChampRelationship> retrieveRelationship(Object key) throws ChampUnmarshallingException, ChampTransactionException;
 346
 347
 348   /**
 349     * Retrieve a relationship by its key.
 350     * <p>
 351     * If a transaction context is not provided, then a transaction will be automatically
 352     * created and committed for this operation only, otherwise, the supplied transaction
 353     * will be used and it will be up to the caller to commit the transaction at its
 354     * discretion.
 355     *
 356     * @param key          - The key of the ChampRelationship in the graph
 357     *                       {@link org.onap.aai.champcore.model.ChampRelationship#getKey()}
 358     * @param transaction  - Optional transaction context to perform the operation in.
 359     *
 360     * @return The {@link org.onap.aai.champcore.model.ChampRelationship} if it was present, otherwise {@link Optional#empty()}
 361     *
 362     * @throws ChampUnmarshallingException If the relationship was found, but could not be unmarshalled
 363     * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 364     */
 365   public Optional<ChampRelationship> retrieveRelationship(Object key, Optional<ChampTransaction> transaction) throws ChampUnmarshallingException, ChampTransactionException;
 366
 367   /**
 368    * Delete a relationship by its key.
 369    *
 370    * @param relationship - The ChampRelationship in the graph ({@link ChampRelationship#getKey must be present})
 371    *
 372    * @throws ChampRelationshipNotExistsException If the object did not exist in the graph
 373    * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 374    */
 375   public void deleteRelationship(ChampRelationship relationship) throws ChampRelationshipNotExistsException, ChampTransactionException;
 376
 377   /**
 378     * Delete a relationship by its key.
 379     * <p>
 380     * If a transaction context is not provided, then a transaction will be automatically
 381     * created and committed for this operation only, otherwise, the supplied transaction
 382     * will be used and it will be up to the caller to commit the transaction at its
 383     * discretion.
 384     *
 385     * @param relationship - The ChampRelationship in the graph ({@link ChampRelationship#getKey must be present})
 386     * @param transaction  - Optional transaction context to perform the operation in.
 387     *
 388     * @throws ChampRelationshipNotExistsException If the object did not exist in the graph
 389     * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 390     */
 391   public void deleteRelationship(ChampRelationship relationship, Optional<ChampTransaction> transaction) throws ChampRelationshipNotExistsException, ChampTransactionException;
 392
 393   /**
 394    * Retrieve the relationships which are incident to the {@code object}
 395    *
 396    * @param object       - The object you wish to find incident relationships for
 397    *
 398    * @return A {@link Stream} where each {@link ChampRelationship} has this {@code object} as either a source or target object
 399    *
 400    * @throws ChampUnmarshallingException If any of the ChampRelationship objects could not be unmarshalled
 401    * @throws ChampObjectNotExistsException If the {@code object} does not exist in this graph
 402    * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 403    */
 404   public Stream<ChampRelationship> retrieveRelationships(ChampObject object) throws ChampUnmarshallingException, ChampObjectNotExistsException, ChampTransactionException;
 405
 406
 407   /**
 408     * Retrieve the relationships which are incident to the {@code object}
 409     * <p>
 410     * If a transaction context is not provided, then a transaction will be automatically
 411     * created and committed for this operation only, otherwise, the supplied transaction
 412     * will be used and it will be up to the caller to commit the transaction at its
 413     * discretion.
 414     *
 415     * @param object       - The object you wish to find incident relationships for
 416     * @param transaction  - Optional transaction context to perform the operation in.
 417     *
 418     * @return A {@link Stream} where each {@link ChampRelationship} has this {@code object} as either a source or target object
 419     *
 420     * @throws ChampUnmarshallingException If any of the ChampRelationship objects could not be unmarshalled
 421     * @throws ChampObjectNotExistsException If the {@code object} does not exist in this graph
 422     * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 423     */
 424   public Stream<ChampRelationship> retrieveRelationships(ChampObject object, Optional<ChampTransaction> transaction) throws ChampUnmarshallingException, ChampObjectNotExistsException, ChampTransactionException;
 425
 426   /**
 427    * Retrieve the relationships whose properties match the given {@code queryParams}
 428    *
 429    * @param queryParams - The key/value pairs to search for in the {@link ChampRelationship#getProperties}
 430    *
 431    * @return A {@link Stream} where each {@link ChampRelationship#getProperties} contains the {@code queryParams}
 432    *
 433    * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 434    */
 435   public Stream<ChampRelationship> queryRelationships(Map<String, Object> queryParams) throws ChampTransactionException;
 436
 437   /**
 438     * Retrieve the relationships whose properties match the given {@code queryParams}
 439     * <p>
 440     * If a transaction context is not provided, then a transaction will be automatically
 441     * created and committed for this operation only, otherwise, the supplied transaction
 442     * will be used and it will be up to the caller to commit the transaction at its
 443     * discretion.
 444     *
 445     * @param queryParams - The key/value pairs to search for in the {@link ChampRelationship#getProperties}
 446     * @param transaction - Optional transaction context to perform the operation in.
 447     *
 448     * @return A {@link Stream} where each {@link ChampRelationship#getProperties} contains the {@code queryParams}
 449     *
 450     * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 451     */
 452   public Stream<ChampRelationship> queryRelationships(Map<String, Object> queryParams, Optional<ChampTransaction> transaction) throws ChampTransactionException;
 453
 454   /**
 455    * Create/Update a {@link ChampPartition}.  If any of the ChampObjects or ChampRelationships
 456    * present in this ChampPartition already exist, an update will be attempted, otherwise a create
 457    * will be attempted.
 458    * <p>
 459    * Each implementation has different guarantees on validation -
 460    * see the specific implementation details for more information on this.
 461    *
 462    * @param partition   - The ChampPartition you wish to store in this graph
 463    *
 464    * @throws ChampMarshallingException If any of the objects or relationships contained in this
 465    *                                       partition could not be marshalled into its backed representation
 466    * @throws ChampObjectNotExistsException If any of the objects being updated do not exist, or if a relationship
 467    *                                           contain objects which do not exist in the graph.
 468    * @throws ChampSchemaViolationException If any of the objects or relationships violate the schema provided by {@link retrieveSchema}
 469    * @throws ChampRelationshipNotExistsException If any of the relationships which are being updated do not exist
 470    * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 471    *
 472    * @return The ChampPartition as is was stored in the graph (contains keys for each newly created object)
 473    */
 474   public ChampPartition storePartition(ChampPartition partition) throws ChampMarshallingException, ChampObjectNotExistsException, ChampSchemaViolationException, ChampRelationshipNotExistsException, ChampTransactionException;
 475
 476   /**
 477     * Create/Update a {@link ChampPartition}.  If any of the ChampObjects or ChampRelationships
 478     * present in this ChampPartition already exist, an update will be attempted, otherwise a create
 479     * will be attempted.
 480     * <p>
 481     * Each implementation has different guarantees on validation -
 482     * see the specific implementation details for more information on this.
 483     * <p>
 484     * If a transaction context is not provided, then a transaction will be automatically
 485     * created and committed for this operation only, otherwise, the supplied transaction
 486     * will be used and it will be up to the caller to commit the transaction at its
 487     * discretion.
 488     *
 489     * @param partition   - The ChampPartition you wish to store in this graph
 490     * @param transaction - Optional transaction context to perform the operation in.
 491     *
 492     * @throws ChampMarshallingException If any of the objects or relationships contained in this
 493     *                                                                           partition could not be marshalled into its backed representation
 494     * @throws ChampObjectNotExistsException If any of the objects being updated do not exist, or if a relationship
 495     *                                                                                   contain objects which do not exist in the graph.
 496     * @throws ChampSchemaViolationException If any of the objects or relationships violate the schema provided by {@link retrieveSchema}
 497     * @throws ChampRelationshipNotExistsException If any of the relationships which are being updated do not exist
 498     * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 499     *
 500     * @return The ChampPartition as is was stored in the graph (contains keys for each newly created object)
 501     */
 502   public ChampPartition storePartition(ChampPartition partition, Optional<ChampTransaction> transaction) throws ChampMarshallingException, ChampObjectNotExistsException, ChampSchemaViolationException, ChampRelationshipNotExistsException, ChampTransactionException;
 503
 504   /**
 505    * Delete the {@code partition} from the graph.
 506    *
 507    * @param partition   - The partition to delete from the graph
 508    *
 509    * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 510    */
 511   public void deletePartition(ChampPartition partition) throws ChampTransactionException;
 512
 513   /**
 514     * Delete the {@code partition} from the graph.
 515     * <p>
 516     * If a transaction context is not provided, then a transaction will be automatically
 517     * created and committed for this operation only, otherwise, the supplied transaction
 518     * will be used and it will be up to the caller to commit the transaction at its
 519     * discretion.
 520     *
 521     * @param partition   - The partition to delete from the graph
 522     * @param transaction - Optional transaction context to perform the operation in.
 523     *
 524     * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
 525     */
 526   public void deletePartition(ChampPartition partition, Optional<ChampTransaction> transaction) throws ChampTransactionException;
 527
 528   /**
 529     * Create/Update an object index on the graph
 530     * @param index - The index to create on this {@code graph}
 531     */
 532   public void storeObjectIndex(ChampObjectIndex index);
 533
 534         /**
 535          * Retrieve an object index on the graph by its {@code indexName}
 536          * @param indexName The name of the index to retrieve from the graph
 537          * @return The {@link ChampObjectIndex} which matches the given @{code indexName} in the graph
 538          */
 539         public Optional<ChampObjectIndex> retrieveObjectIndex(String indexName);
 540
 541         /**
 542          * Retrieve the object indices on the graph
 543          * @return A {@link Stream} where each {@link ChampObjectIndex} exists in the graph
 544          */
 545         public Stream<ChampObjectIndex> retrieveObjectIndices();
 546
 547         /**
 548          * Delete the object index on the graph by its {@code indexName}
 549          * @param indexName The name of the index to delete from the graph
 550          * @throws ChampIndexNotExistsException If an index does not exist with the given {@code indexName} in the graph
 551          */
 552         public void deleteObjectIndex(String indexName) throws ChampIndexNotExistsException;
 553
 554         /**
 555          * Create/Update a relationship index on the graph
 556          * @param index The relationship index to create on the graph
 557          */
 558         public void storeRelationshipIndex(ChampRelationshipIndex index);
 559
 560         /**
 561          * Retrieve a relationship index from the graph
 562          * @param indexName The name of the relationship index to retrieve from the graph
 563          * @return The {@link ChampRelationshipIndex} which matches the given {@code indexName} in the graph
 564          *                      or {@link Optional#empty} if no such relationship index exists
 565          */
 566         public Optional<ChampRelationshipIndex> retrieveRelationshipIndex(String indexName);
 567
 568         /**
 569          * Retrieve the relationship indices from the graph
 570          * @return A {@link Stream} where each {@link ChampRelationshipIndex} exists in the graph
 571          */
 572         public Stream<ChampRelationshipIndex> retrieveRelationshipIndices();
 573
 574         /**
 575          * Delete a relationship index from the graph
 576          * @param indexName THe name of the index to delete from the graph
 577          * @throws ChampIndexNotExistsException If an index does not exist with the give {@code indexName} in the graph
 578          */
 579         public void deleteRelationshipIndex(String indexName) throws ChampIndexNotExistsException;
 580
 581         /**
 582          * Create/Update the schema for a graph
 583          * @param schema The {@link ChampSchema} to create or update on the graph
 584          * @throws ChampSchemaViolationException If this schema update would violate the current schema
 585          */
 586         public void storeSchema(ChampSchema schema) throws ChampSchemaViolationException;
 587
 588         /**
 589          * Retrieve the schema for a graph
 590          * @return The {@link ChampSchema} for the graph
 591          */
 592         public ChampSchema retrieveSchema();
 593
 594         /**
 595          * Create/Update an object constraint on a schema
 596          * @param objectConstraint The object constraint you wish to create/update for the graph
 597          * @throws ChampSchemaViolationException If this schema update would violate the current schema
 598          */
 599         public void updateSchema(ChampObjectConstraint objectConstraint) throws ChampSchemaViolationException;
 600
 601         /**
 602          * Create/Update a relationship constraint on a schema
 603          * @param schema The relationship constraint you wish to create/update for the graph
 604          * @throws ChampSchemaViolationException If this schema update would violate the current schema
 605          */
 606         public void updateSchema(ChampRelationshipConstraint schema) throws ChampSchemaViolationException;
 607
 608         /**
 609          * Delete the schema for a graph
 610          */
 611         public void deleteSchema();
 612
 613         /**
 614          * Shutdown the ChampAPI. It is up to the caller to synchronize access to the ChampAPI
 615          * so that shutting it down does not interfere with concurrent operations.
 616          */
 617         public void shutdown();
 618
 619         /**
 620          * Used to determine what the outcome of certain ChampGraph operations will be.  For example,
 621          * if this graph is not capable of deleting object indices, you can expect those calls to fail.
 622          * @see ChampCapabilities
 623          * @return What this graph is capable of performing
 624          */
 625          public ChampCapabilities capabilities();
 626 }