/** * ============LICENSE_START========================================== * org.onap.aai * =================================================================== * Copyright © 2017 AT&T Intellectual Property. All rights reserved. * Copyright © 2017 Amdocs * =================================================================== * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. * ============LICENSE_END============================================ * ECOMP is a trademark and service mark of AT&T Intellectual Property. */ package org.onap.aai.champcore; import java.util.List; import java.util.Map; import java.util.Optional; import java.util.stream.Stream; import org.onap.aai.champcore.exceptions.ChampIndexNotExistsException; import org.onap.aai.champcore.exceptions.ChampMarshallingException; import org.onap.aai.champcore.exceptions.ChampObjectNotExistsException; import org.onap.aai.champcore.exceptions.ChampRelationshipNotExistsException; import org.onap.aai.champcore.exceptions.ChampSchemaViolationException; import org.onap.aai.champcore.exceptions.ChampTransactionException; import org.onap.aai.champcore.exceptions.ChampUnmarshallingException; import org.onap.aai.champcore.model.ChampObject; import org.onap.aai.champcore.model.ChampObjectConstraint; import org.onap.aai.champcore.model.ChampObjectIndex; import org.onap.aai.champcore.model.ChampPartition; import org.onap.aai.champcore.model.ChampRelationship; import org.onap.aai.champcore.model.ChampRelationshipConstraint; import org.onap.aai.champcore.model.ChampRelationshipIndex; import org.onap.aai.champcore.model.ChampSchema; public interface ChampGraph { /** * Opens a transaction within the graph data store. * * @return - A transaction object. */ public ChampTransaction openTransaction(); /** * Attempts to commit the supplied open transaction. * * @param transaction - The transaction to be committed. * * @throws ChampTransactionException - If an attempt to commit or rollback the transaction failed. */ public void commitTransaction(ChampTransaction transaction) throws ChampTransactionException; /** * Attempts to roll back the supplied open transaction. * * @param transaction - The transaction to be committed. * * @throws ChampTransactionException - If an attempt to commit or rollback the transaction failed. */ public void rollbackTransaction(ChampTransaction transaction) throws ChampTransactionException; /** * Create/Update an object. *
* If the ChampObject key is present, an update will be attempted, * otherwise a create will be attempted. Each implementation has different guarantees on * validation - see the specific implementation for more details on this. * * @param object - The ChampObject that you wish to store in the graph * * @return The ChampObject as it was stored * * @throws ChampMarshallingException If the {@code object} is not able to be marshalled into the backend representation * @throws ChampSchemaViolationException If the {@code object} violates the constraints specifed by {@link ChampGraph#retrieveSchema} * @throws ChampObjectNotExistsException If {@link org.onap.aai.champcore.model.ChampObject#getKey}.isPresent() but the object cannot be found in the graph * @throws ChampTransactionException If an attempt to commit or rollback the transaction failed. */ public ChampObject storeObject(ChampObject object) throws ChampMarshallingException, ChampSchemaViolationException, ChampObjectNotExistsException, ChampTransactionException; /** * Create/Update an object. *
* If the ChampObject key is present, an update will be attempted, * otherwise a create will be attempted. Each implementation has different guarantees on * validation - see the specific implementation for more details on this. *
* If a transaction context is not provided, then a transaction will be automatically
* created and committed for this operation only, otherwise, the supplied transaction
* will be used and it will be up to the caller to commit the transaction at its
* discretion.
*
* @param object - The ChampObject that you wish to store in the graph
* @param transaction - Optional transaction context to perform the operation in.
*
* @return The ChampObject as it was stored
*
* @throws ChampMarshallingException If the {@code object} is not able to be marshalled into the backend representation
* @throws ChampSchemaViolationException If the {@code object} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
* @throws ChampObjectNotExistsException If {@link org.onap.aai.champcore.model.ChampObject#getKey}.isPresent() but the object cannot be found in the graph
* @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
*/
public ChampObject storeObject(ChampObject object, Optional
* Each implementation has different guarantees on validation - see the specific implementation
* for more details on this.
*
* @param object - The ChampObject that you wish to replace in the graph
*
* @return The ChampObject as it was stored
*
* @throws ChampMarshallingException If the {@code object} is not able to be marshalled into the backend representation
* @throws ChampSchemaViolationException If the {@code object} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
* @throws ChampObjectNotExistsException If {@link org.onap.aai.champcore.model.ChampObject#getKey} is not present or object not found in the graph
* @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
*/
public ChampObject replaceObject(ChampObject object) throws ChampMarshallingException, ChampSchemaViolationException, ChampObjectNotExistsException, ChampTransactionException;
/**
* Replace an object. ChampObject key is mandatory
*
* Each implementation has different guarantees on validation - see the specific implementation
* for more details on this.
*
* If a transaction context is not provided, then a transaction will be automatically
* created and committed for this operation only, otherwise, the supplied transaction
* will be used and it will be up to the caller to commit the transaction at its
* discretion.
*
* @param object - The ChampObject that you wish to replace in the graph
* @param transaction - Optional transaction context to perform the operation in.
*
* @return The ChampObject as it was stored
*
* @throws ChampMarshallingException If the {@code object} is not able to be marshalled into the backend representation
* @throws ChampSchemaViolationException If the {@code object} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
* @throws ChampObjectNotExistsException If {@link org.onap.aai.champcore.model.ChampObject#getKey} is not present or object not found in the graph
* @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
*/
public ChampObject replaceObject(ChampObject object, Optional
* If a transaction context is not provided, then a transaction will be automatically
* created and committed for this operation only, otherwise, the supplied transaction
* will be used and it will be up to the caller to commit the transaction at its
* discretion.
*
* @param key - The key of the ChampObject in the graph {@link org.onap.aai.champcore.model.ChampObject#getKey()}
* @param transaction - Optional transaction context to perform the operation in.
*
* @return The {@link org.onap.aai.champcore.model.ChampObject} if it was present, otherwise {@link Optional#empty()}
*
* @throws ChampUnmarshallingException If the object was found, but could not be unmarshalled
* @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
*/
public Optional
* If a transaction context is not provided, then a transaction will be automatically
* created and committed for this operation only, otherwise, the supplied transaction
* will be used and it will be up to the caller to commit the transaction at its
* discretion.
*
* @param key - The key of the ChampObject in the graph {@link ChampObject#getKey}
* @param transaction - Optional transaction context to perform the operation in.
*
* @throws ChampObjectNotExistsException If the object did not exist in the graph
* @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
*/
public void deleteObject(Object key, Optional
* If a transaction context is not provided, then a transaction will be automatically
* created and committed for this operation only, otherwise, the supplied transaction
* will be used and it will be up to the caller to commit the transaction at its
* discretion.
*
* @param queryParams - The key/value pairs which are found in {@link ChampObject#getProperties}
* @param transaction - Optional transaction context to perform the operation in.
*
* @return - A {@link Stream} where each {@link ChampObject#getProperties} contains the {@code queryParams}
*
* @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
*/
public Stream
* If the ChampRelationship key is present, an update will be attempted,
* otherwise a create will be attempted. Each implementation has different guarantees on
* validation - see the specific implementation for more details on this.
*
* @param relationship - The ChampRelationship that you wish to store in the graph
*
* @return The ChampRelationship as it was stored
*
* @throws ChampMarshallingException If the {@code relationship} is not able to be marshalled into the backend representation
* @throws ChampSchemaViolationException If the {@code relationship} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
* @throws ChampObjectNotExistsException If either the source or target object referenced by this relationship does not exist in the graph
* @throws ChampRelationshipNotExistsException If {@link org.onap.aai.champcore.model.ChampRelationship#getKey}.isPresent() but the object cannot be found in the graph
* @throws ChampUnmarshallingException If the edge which was created could not be unmarshalled into a ChampRelationship
* @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
*/
public ChampRelationship storeRelationship(ChampRelationship relationship) throws ChampMarshallingException, ChampObjectNotExistsException, ChampSchemaViolationException, ChampRelationshipNotExistsException, ChampUnmarshallingException, ChampTransactionException;
/**
* Create/Update a relationship.
*
* If the ChampRelationship key is present, an update will be attempted,
* otherwise a create will be attempted. Each implementation has different guarantees on
* validation - see the specific implementation for more details on this.
*
* If a transaction context is not provided, then a transaction will be automatically
* created and committed for this operation only, otherwise, the supplied transaction
* will be used and it will be up to the caller to commit the transaction at its
* discretion.
*
* @param relationship - The ChampRelationship that you wish to store in the graph
* @param transaction - Optional transaction context to perform the operation in.
*
* @return The ChampRelationship as it was stored
*
* @throws ChampMarshallingException If the {@code relationship} is not able to be marshalled into the backend representation
* @throws ChampSchemaViolationException If the {@code relationship} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
* @throws ChampObjectNotExistsException If either the source or target object referenced by this relationship does not exist in the graph
* @throws ChampRelationshipNotExistsException If {@link org.onap.aai.champcore.model.ChampRelationship#getKey}.isPresent() but the object cannot be found in the graph
* @throws ChampUnmarshallingException If the edge which was created could not be unmarshalled into a ChampRelationship
* @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
*/
public ChampRelationship storeRelationship(ChampRelationship relationship, Optional
* 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.
*
* Each implementation has different guarantees on validation - see the specific implementation
* for more details on this.
*
* @param relationship - The ChampRelationship that you wish to replace in the graph
*
* @return The ChampRelationship as it was stored
*
* @throws ChampMarshallingException If the {@code relationship} is not able to be marshalled into the backend representation
* @throws ChampSchemaViolationException If the {@code relationship} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
* @throws ChampRelationshipNotExistsException If {@link org.onap.aai.champcore.model.ChampRelationship#getKey} is not present or object not found in the graph
* @throws ChampUnmarshallingException If the edge which was created could not be unmarshalled into a ChampRelationship
* @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
*/
public ChampRelationship replaceRelationship(ChampRelationship relationship) throws ChampMarshallingException, ChampSchemaViolationException, ChampRelationshipNotExistsException, ChampUnmarshallingException, ChampTransactionException;
/**
* 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.
*
* Each implementation has different guarantees on validation - see the specific implementation
* for more details on this.
*
* If a transaction context is not provided, then a transaction will be automatically
* created and committed for this operation only, otherwise, the supplied transaction
* will be used and it will be up to the caller to commit the transaction at its
* discretion.
*
* @param relationship - The ChampRelationship that you wish to replace in the graph
* @param transaction - Optional transaction context to perform the operation in.
*
* @return The ChampRelationship as it was stored
*
* @throws ChampMarshallingException If the {@code relationship} is not able to be marshalled into the backend representation
* @throws ChampSchemaViolationException If the {@code relationship} violates the constraints specifed by {@link ChampGraph#retrieveSchema}
* @throws ChampRelationshipNotExistsException If {@link org.onap.aai.champcore.model.ChampRelationship#getKey} is not present or object not found in the graph
* @throws ChampUnmarshallingException If the edge which was created could not be unmarshalled into a ChampRelationship
* @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
*/
public ChampRelationship replaceRelationship(ChampRelationship relationship, Optional
* If a transaction context is not provided, then a transaction will be automatically
* created and committed for this operation only, otherwise, the supplied transaction
* will be used and it will be up to the caller to commit the transaction at its
* discretion.
*
* @param key - The key of the ChampRelationship in the graph
* {@link org.onap.aai.champcore.model.ChampRelationship#getKey()}
* @param transaction - Optional transaction context to perform the operation in.
*
* @return The {@link org.onap.aai.champcore.model.ChampRelationship} if it was present, otherwise {@link Optional#empty()}
*
* @throws ChampUnmarshallingException If the relationship was found, but could not be unmarshalled
* @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
*/
public Optional
* If a transaction context is not provided, then a transaction will be automatically
* created and committed for this operation only, otherwise, the supplied transaction
* will be used and it will be up to the caller to commit the transaction at its
* discretion.
*
* @param relationship - The ChampRelationship in the graph ({@link ChampRelationship#getKey must be present})
* @param transaction - Optional transaction context to perform the operation in.
*
* @throws ChampRelationshipNotExistsException If the object did not exist in the graph
* @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
*/
public void deleteRelationship(ChampRelationship relationship, Optional
* If a transaction context is not provided, then a transaction will be automatically
* created and committed for this operation only, otherwise, the supplied transaction
* will be used and it will be up to the caller to commit the transaction at its
* discretion.
*
* @param object - The object you wish to find incident relationships for
* @param transaction - Optional transaction context to perform the operation in.
*
* @return A {@link Stream} where each {@link ChampRelationship} has this {@code object} as either a source or target object
*
* @throws ChampUnmarshallingException If any of the ChampRelationship objects could not be unmarshalled
* @throws ChampObjectNotExistsException If the {@code object} does not exist in this graph
* @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
*/
public Stream
* If a transaction context is not provided, then a transaction will be automatically
* created and committed for this operation only, otherwise, the supplied transaction
* will be used and it will be up to the caller to commit the transaction at its
* discretion.
*
* @param queryParams - The key/value pairs to search for in the {@link ChampRelationship#getProperties}
* @param transaction - Optional transaction context to perform the operation in.
*
* @return A {@link Stream} where each {@link ChampRelationship#getProperties} contains the {@code queryParams}
*
* @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
*/
public Stream
* Each implementation has different guarantees on validation -
* see the specific implementation details for more information on this.
*
* @param partition - The ChampPartition you wish to store in this graph
*
* @throws ChampMarshallingException If any of the objects or relationships contained in this
* partition could not be marshalled into its backed representation
* @throws ChampObjectNotExistsException If any of the objects being updated do not exist, or if a relationship
* contain objects which do not exist in the graph.
* @throws ChampSchemaViolationException If any of the objects or relationships violate the schema provided by {@link retrieveSchema}
* @throws ChampRelationshipNotExistsException If any of the relationships which are being updated do not exist
* @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
*
* @return The ChampPartition as is was stored in the graph (contains keys for each newly created object)
*/
public ChampPartition storePartition(ChampPartition partition) throws ChampMarshallingException, ChampObjectNotExistsException, ChampSchemaViolationException, ChampRelationshipNotExistsException, ChampTransactionException;
/**
* Create/Update a {@link ChampPartition}. If any of the ChampObjects or ChampRelationships
* present in this ChampPartition already exist, an update will be attempted, otherwise a create
* will be attempted.
*
* Each implementation has different guarantees on validation -
* see the specific implementation details for more information on this.
*
* If a transaction context is not provided, then a transaction will be automatically
* created and committed for this operation only, otherwise, the supplied transaction
* will be used and it will be up to the caller to commit the transaction at its
* discretion.
*
* @param partition - The ChampPartition you wish to store in this graph
* @param transaction - Optional transaction context to perform the operation in.
*
* @throws ChampMarshallingException If any of the objects or relationships contained in this
* partition could not be marshalled into its backed representation
* @throws ChampObjectNotExistsException If any of the objects being updated do not exist, or if a relationship
* contain objects which do not exist in the graph.
* @throws ChampSchemaViolationException If any of the objects or relationships violate the schema provided by {@link retrieveSchema}
* @throws ChampRelationshipNotExistsException If any of the relationships which are being updated do not exist
* @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
*
* @return The ChampPartition as is was stored in the graph (contains keys for each newly created object)
*/
public ChampPartition storePartition(ChampPartition partition, Optional
* If a transaction context is not provided, then a transaction will be automatically
* created and committed for this operation only, otherwise, the supplied transaction
* will be used and it will be up to the caller to commit the transaction at its
* discretion.
*
* @param partition - The partition to delete from the graph
* @param transaction - Optional transaction context to perform the operation in.
*
* @throws ChampTransactionException If an attempt to commit or rollback the transaction failed.
*/
public void deletePartition(ChampPartition partition, Optional