org.hawkular.inventory.base.spi

Interface InventoryBackend<E>

Type Parameters:

E - the type of the backend-specific objects representing the inventory entities and relationships. It is assumed that the backend is "untyped" and stores all different inventory entities using this single type.

All Superinterfaces:

AutoCloseable

public interface InventoryBackend<E>
extends AutoCloseable

The backend for the base inventory that does all the "low level" stuff like querying the actual inventory store, its modifications, etc.

Since:

0.1.0

Author:

Lukas Krejci

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	InventoryBackend.Transaction Represents a transaction being performed.

Method Summary

Modifier and Type	Method and Description
void	commit(InventoryBackend.Transaction transaction) Commits the transaction.
<T> T	convert(E entityRepresentation, Class<T> entityType) Converts the provided representation object to an inventory element of provided type.
void	delete(E entity) Simply deletes the entity from the storage.
void	deleteStructuredData(E dataRepresentation) Deletes the structured data represented by the provided object.
E	descendToData(E dataEntityRepresentation, RelativePath dataPath) Given the representation of the data entity, this will return the representation of a structured data element on the given path "inside" the data entity.
CanonicalPath	extractCanonicalPath(E entityRepresentation) Each element (including relationships) stores the canonical path to it.
String	extractId(E entityRepresentation) The element type is opaque from the point of the caller.
String	extractRelationshipName(E relationship)
Class<?>	extractType(E entityRepresentation) Similar to extractId(Object) but extracts the type of element from the representation.
E	find(CanonicalPath element) Tries to find an element at given canonical path.
InputStream	getGraphSON(String tenantId) See the javadoc in Inventory.getGraphSON(String)
E	getRelationship(E source, E target, String relationshipName) Get a single relationship with the provided name between the source and target.
Set<E>	getRelationships(E entity, Relationships.Direction direction, String... names) Similar to hasRelationship(Object, Relationships.Direction, String) but this method actually returns the relationship objects.
E	getRelationshipSource(E relationship)
E	getRelationshipTarget(E relationship)
<T extends Entity<?,?>> Iterator<T>	getTransitiveClosureOver(CanonicalPath startingPoint, Relationships.Direction direction, Class<T> clazz, String... relationshipNames)
Iterator<E>	getTransitiveClosureOver(E startingPoint, Relationships.Direction direction, String... relationshipNames) Going from the starting poing, this will return an iterator over all elements that are connected to the starting point using relationships with provided name and recursively down to the elements connected in the same way to them.
boolean	hasRelationship(E source, E target, String relationshipName) Checks whether there exists a relationship with given name between the provided entities.
boolean	hasRelationship(E entity, Relationships.Direction direction, String relationshipName) Checks whether there exists any relationship in given direction relative to the given entity with given name.
E	persist(CanonicalPath path, Blueprint blueprint) Persists a new entity with the provided assigned path.
E	persist(StructuredData structuredData) Persists the structured data and returns a reference to it.
Page<E>	query(Query query, Pager pager) Translates the query to the backend-specific representation and runs it, returning a correct page of results as prescribed by the provided pager object.
<T> Page<T>	query(Query query, Pager pager, Function<E,T> conversion, Function<T,Boolean> filter) A variant of the query(Query, Pager) method which in addition to querying also converts the results using the provided conversion function and, more importantly, filters the results using the provided (possibly null) filter function PRIOR TO paging is applied.
E	relate(E sourceEntity, E targetEntity, String name, Map<String,Object> properties) Creates a new relationship from source to target with given name and properties.
void	rollback(InventoryBackend.Transaction transaction) Rolls back the transaction.
InventoryBackend.Transaction	startTransaction(boolean mutating) Starts a transaction in the backend.
Page<E>	traverse(E startingPoint, Query query, Pager pager) Translates the query to the backend-specific representation and runs it, returning a correct page of results as prescribed by the provided pager object.
void	update(E entity, AbstractElement.Update update) Updates given entity with the data provided in the update object.

Methods inherited from interface java.lang.AutoCloseable

close

Method Detail

startTransaction

InventoryBackend.Transaction startTransaction(boolean mutating)

Starts a transaction in the backend.

Parameters:

mutating - whether there will be calls mutating the data or not

Returns:

the newly started transaction

find

E find(CanonicalPath element)
throws ElementNotFoundException

Tries to find an element at given canonical path.

Parameters:

element - the canonical path of the element to find

Returns:

the element

Throws:

ElementNotFoundException - if the element is not found

traverse

Page<E> traverse(E startingPoint,
                 Query query,
                 Pager pager)

Translates the query to the backend-specific representation and runs it, returning a correct page of results as prescribed by the provided pager object.

Parameters:

startingPoint - the element which should be the starting point of the traversal

query - the query to perform

pager - pager to limit the number of results with

Returns:

the page of results, possibly empty, never null

query

Page<E> query(Query query,
              Pager pager)

Translates the query to the backend-specific representation and runs it, returning a correct page of results as prescribed by the provided pager object.

The difference between this method and traverse(Object, Query, Pager) is that this method performs a graph-wide query, while traverse starts from a single element.

Parameters:

query - the query to execute

pager - the page to return

Returns:

a page of results corresponding to the parameters, possibly empty, never null.

query

<T> Page<T> query(Query query,
                  Pager pager,
                  Function<E,T> conversion,
                  Function<T,Boolean> filter)

A variant of the query(Query, Pager) method which in addition to querying also converts the results using the provided conversion function and, more importantly, filters the results using the provided (possibly null) filter function PRIOR TO paging is applied.

Because the total count and the paging is dependent on the filtering it needs to be applied during the querying process and not only after the fact be the caller.

Type Parameters:

T - the type of the returned elements

Parameters:

query - the query to perform

pager - the page to retrieve

conversion - a conversion function to apply on the elements, never null

filter - possibly null filter to filter the results with

Returns:

the page of results according to the supplied parameters

getTransitiveClosureOver

Iterator<E> getTransitiveClosureOver(E startingPoint,
                                     Relationships.Direction direction,
                                     String... relationshipNames)

Going from the starting poing, this will return an iterator over all elements that are connected to the starting point using relationships with provided name and recursively down to the elements connected in the same way to them.

Parameters:

startingPoint - the starting element

direction - any of the valid directions including Relationships.Direction#both.

relationshipNames - the names of the relationships to follow when composing the transitive closure

Returns:

an iterator over the transitive closure, may be "lazy" and evaluate the closure on demand.

hasRelationship

boolean hasRelationship(E entity,
                        Relationships.Direction direction,
                        String relationshipName)

Checks whether there exists any relationship in given direction relative to the given entity with given name.

Parameters:

entity - the entity in question

direction - the direction the relationship should have relative to the entity ( Relationships.Direction.both means "any" in this context).

relationshipName - the name of the relationship to seek

Returns:

true if there is such relationship, false otherwise

See Also:

getRelationships(Object, Relationships.Direction, String...)

hasRelationship

boolean hasRelationship(E source,
                        E target,
                        String relationshipName)

Checks whether there exists a relationship with given name between the provided entities.

Parameters:

source - the source of the relationship

target - the target of the relationship

relationshipName - the name of the relationship

Returns:

true, if such relationship exists, false otherwise

getRelationships

Set<E> getRelationships(E entity,
                        Relationships.Direction direction,
                        String... names)

Similar to hasRelationship(Object, Relationships.Direction, String) but this method actually returns the relationship objects.

Parameters:

entity - the entity in question

direction - the direction in which the relationships should be going

names - the names of the relationships to return

Returns:

the possibly empty set of the relationships, never null

See Also:

hasRelationship(Object, Relationships.Direction, String)

getRelationship

E getRelationship(E source,
                  E target,
                  String relationshipName)
           throws ElementNotFoundException

Get a single relationship with the provided name between the source and target.

Parameters:

source - the source of the relationship

target - the target of the relationship

relationshipName - the name of the relationship

Returns:

the relationship

Throws:

ElementNotFoundException - if the relationship is not found

IllegalArgumentException - if source or target are not entities or relationship name is null

getRelationshipSource

E getRelationshipSource(E relationship)

Parameters:

relationship - the relationship in question

Returns:

the source of the relationship

getRelationshipTarget

E getRelationshipTarget(E relationship)

Parameters:

relationship - the relationship in question

Returns:

the target of the relationship

extractRelationshipName

String extractRelationshipName(E relationship)

Parameters:

relationship - the relationship in question

Returns:

the name of the relationship

extractId

String extractId(E entityRepresentation)

The element type is opaque from the point of the caller. This method provides the caller with the ability to extract the ID of the entity represented by the object.

Parameters:

entityRepresentation - the object representing an element

Returns:

the ID

extractType

Class<?> extractType(E entityRepresentation)

Similar to extractId(Object) but extracts the type of element from the representation.

Parameters:

entityRepresentation - the representation object.

Returns:

the type of the object represented

extractCanonicalPath

CanonicalPath extractCanonicalPath(E entityRepresentation)

Each element (including relationships) stores the canonical path to it. This will extract that value from the entity representation.

Parameters:

entityRepresentation - the representation object

Returns:

the extracted canonical path

convert

<T> T convert(E entityRepresentation,
              Class<T> entityType)

Converts the provided representation object to an inventory element of provided type.

This must support all the concrete subclasses of AbstractElement, StructuredData and ShallowStructuredData.

Type Parameters:

T - the desired type of the element

Parameters:

entityRepresentation - the object representing the element

entityType - the desired type of the element

Returns:

the converted inventory element

Throws:

ClassCastException - if the representation object doesn't correspond to the provided type

descendToData

E descendToData(E dataEntityRepresentation,
                RelativePath dataPath)

Given the representation of the data entity, this will return the representation of a structured data element on the given path "inside" the data entity.

Parameters:

dataEntityRepresentation - the representation of the DataEntity instance

dataPath - the path in the data to descend to.

See Also:

org.hawkular.inventory.api.Datas.Single#data(RelativePath)

relate

E relate(E sourceEntity,
         E targetEntity,
         String name,
         Map<String,Object> properties)

Creates a new relationship from source to target with given name and properties.

Parameters:

sourceEntity - the source of the relationship

targetEntity - the target of the relationship

name - the name of the relationship

properties - the properties of the relationship, may be null

Returns:

the representation of the newly created relationship

Throws:

IllegalArgumentException - if source or target are relationships themselves or if name is null

persist

E persist(CanonicalPath path,
          Blueprint blueprint)

Persists a new entity with the provided assigned path.

Parameters:

path - the canonical path to the entity

blueprint - the blueprint of the entity

Returns:

the representation object of the newly created entity

persist

E persist(StructuredData structuredData)

Persists the structured data and returns a reference to it. It is the responsibility of the caller to wire it up to some other entity by some relationship.

Parameters:

structuredData - the structured data to persist

Returns:

the representation of the newly persisted structured data

update

void update(E entity,
            AbstractElement.Update update)

Updates given entity with the data provided in the update object.

Parameters:

entity - the entity to update

update - the update object

Throws:

IllegalArgumentException - if the entity is of different type than the update

delete

void delete(E entity)

Simply deletes the entity from the storage.

Parameters:

entity - the entity to delete

deleteStructuredData

void deleteStructuredData(E dataRepresentation)

Deletes the structured data represented by the provided object.

Parameters:

dataRepresentation - the backend-specific object representing the structured data to delete

commit

void commit(InventoryBackend.Transaction transaction)
     throws CommitFailureException

Commits the transaction.

Parameters:

transaction - the transaction to commit

Throws:

CommitFailureException

rollback

void rollback(InventoryBackend.Transaction transaction)

Rolls back the transaction.

Parameters:

transaction - the transaction to roll back

getGraphSON

InputStream getGraphSON(String tenantId)

See the javadoc in Inventory.getGraphSON(String)

getTransitiveClosureOver

<T extends Entity<?,?>> Iterator<T> getTransitiveClosureOver(CanonicalPath startingPoint,
                                                             Relationships.Direction direction,
                                                             Class<T> clazz,
                                                             String... relationshipNames)