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