Inventory (Hawkular Inventory API 0.2.0.Alpha1 API)

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

BaseInventory, EmptyInventory
```
public interface Inventory
extends AutoCloseable
```
Inventory stores "resources" which are groupings of measurements and other data. Inventory also stores metadata about the measurements and resources to give them meaning.
The resources are organized by tenant (your company) and environments (i.e. testing, development, staging, production, ...).
Despite their name, tenants are not completely separated and one can easily create relationships between them or between entities underneath different tenants. This is because there are situations where such relationships might make sense but more importantly because at the API level, inventory does not mandate any security model. It is assumed that the true multi-tenancy in the common sense of the word is implemented by a layer on top of the inventory API that also understands some security model to separate the tenants.
Resources are hierarchical - meaning that one can be a parent of others, recursively. One can also say that a resource can contain other resources. Resources can have other kinds of relationships that are not necessarily tree-like.
Resources can have a "resource type" (but they don't have to) which prescribes what kind of data a resource contains. Most prominently a resource can have a list of metrics and a resource type can define what those metrics should be by specifying the set of "metric types".
This interface offers a fluent API to compose a "traversal" over the graph of entities stored in the inventory in a strongly typed fashion.
The inventory implementations are not required to be thread-safe. Instances should therefore be accessed only by a single thread or serially.
Note to implementers:
It is highly recommended to extend the BaseInventory and its SPI instead of this interface directly. The base is considered the "reference implementation" and any implementation is required to behave the same.
If you for any reason need to implement the full inventory interface, please consider the following:
The interfaces composing the inventory API are of 2 kinds:
1. CRUD interfaces that provide manipulation of the entities as well as the retrieval of the actual entity instances (various Read, ReadWrite or ReadRelate interfaces, e.g. Environments.ReadWrite),
2. browse interfaces that offer further navigation methods to "hop" onto other entities somehow related to the one(s) in the current position in the inventory traversal. These interfaces are further divided into 2 groups:
  - Single interfaces that provide methods for navigating from a single entity. These interfaces generally contain methods that enable modification of the entity or its relationships. See Environments.Single for an example.
  - Multiple interfaces that provide methods for navigating from multiple entities at once. These interfaces strictly offer only read-only access to the entities, because the semantics of what should be done when modifying or relating multiple entities at once is not uniformly defined on all types of entities and therefore would make the API more confusing than necessary. See Environments.Multiple for example.
Since:

0.0.1

Author:

Lukas Krejci

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`boolean`	`hasObservers(Interest<?,?> interest)` This method is mainly useful for testing.
`void`	`initialize(Configuration configuration)` Initializes the inventory from the provided configuration object.
`default <E extends AbstractElement<?,U>,U extends AbstractElement.Update,Single extends ResolvableToSingle<E,U>> Single`	`inspect(CanonicalPath path, Class<Single> accessInterface)` Another generic version of the inspect method, this time using the `CanonicalPath` to an element.
`default <E extends AbstractElement<?,U>,U extends AbstractElement.Update,Single extends ResolvableToSingle<E,U>> Single`	`inspect(E entity, Class<Single> accessInterface)` A generic version of the `inspect` methods that accepts an element and returns the access interface to it.
`default Environments.Single`	`inspect(Environment environment)` Provides an access interface for inspecting given environment.
`default Feeds.Single`	`inspect(Feed feed)` Provides an access interface for inspecting given feed.
`default Metrics.Single`	`inspect(Metric metric)` Provides an access interface for inspecting given metric.
`default MetricTypes.Single`	`inspect(MetricType metricType)` Provides an access interface for inspecting given metric type.
`default Relationships.Single`	`inspect(Relationship relationship)`
`default Resources.Single`	`inspect(Resource resource)` Provides an access interface for inspecting given resource.
`default ResourceTypes.Single`	`inspect(ResourceType resourceType)` Provides an access interface for inspecting given resource type.
`default Tenants.Single`	`inspect(Tenant tenant)` Provides an access interface for inspecting given tenant.
`<C,E> rx.Observable<C>`	`observable(Interest<C,E> interest)` NOTE: The subscribers will receive the notifications even after they failed.
`Relationships.Read`	`relationships()` Global access to all relationships.
`Tenants.ReadWrite`	`tenants()` Entry point into the inventory.

Methods inherited from interface java.lang.AutoCloseable
close

- Method Detail
  - initialize
```
void initialize(Configuration configuration)
```
    Initializes the inventory from the provided configuration object.
    
    Parameters:
    
    configuration - the configuration to use.
  - tenants
```
Tenants.ReadWrite tenants()
```
    Entry point into the inventory. Select one (ResolvingToSingle.get(Object)) or more (ResolvingToMultiple.getAll(org.hawkular.inventory.api.filters.Filter...)) tenants and navigate further to the entities of interest.
    
    Returns:
    
    full CRUD and navigation interface to tenants
  - relationships
```
Relationships.Read relationships()
```
    Global access to all relationships. Use this with caution as it may result in scanning across the potentially very large number of relationships present in the inventory.
    To create relationships, first navigate to one of its endpoint entities and create it from there using the API calls.
    
    Returns:
    
    the read access to relationships.
  - inspect
```
default Tenants.Single inspect(Tenant tenant)
                        throws EntityNotFoundException
```
    Provides an access interface for inspecting given tenant.
    
    Parameters:
    
    tenant - the tenant to steer to.
    
    Returns:
    
    the access interface to the tenant
    
    Throws:
    
    EntityNotFoundException
  - inspect
```
default Environments.Single inspect(Environment environment)
                             throws EntityNotFoundException
```
    Provides an access interface for inspecting given environment.
    
    Parameters:
    
    environment - the environment to steer to.
    
    Returns:
    
    the access interface to the environment
    
    Throws:
    
    EntityNotFoundException
  - inspect
```
default Feeds.Single inspect(Feed feed)
                      throws EntityNotFoundException
```
    Provides an access interface for inspecting given feed.
    
    Parameters:
    
    feed - the feed to steer to.
    
    Returns:
    
    the access interface to the feed
    
    Throws:
    
    EntityNotFoundException
  - inspect
```
default Metrics.Single inspect(Metric metric)
                        throws EntityNotFoundException
```
    Provides an access interface for inspecting given metric.
    
    Parameters:
    
    metric - the metric to steer to.
    
    Returns:
    
    the access interface to the metric
    
    Throws:
    
    EntityNotFoundException
  - inspect
```
default MetricTypes.Single inspect(MetricType metricType)
                            throws EntityNotFoundException
```
    Provides an access interface for inspecting given metric type.
    
    Parameters:
    
    metricType - the metric type to steer to.
    
    Returns:
    
    the access interface to the metric type
    
    Throws:
    
    EntityNotFoundException
  - inspect
```
default Resources.Single inspect(Resource resource)
                          throws EntityNotFoundException
```
    Provides an access interface for inspecting given resource.
    
    Parameters:
    
    resource - the resource to steer to.
    
    Returns:
    
    the access interface to the resource
    
    Throws:
    
    EntityNotFoundException
  - inspect
```
default ResourceTypes.Single inspect(ResourceType resourceType)
                              throws EntityNotFoundException
```
    Provides an access interface for inspecting given resource type.
    
    Parameters:
    
    resourceType - the resource type to steer to.
    
    Returns:
    
    the access interface to the resource type
    
    Throws:
    
    EntityNotFoundException
  - inspect
```
default Relationships.Single inspect(Relationship relationship)
```
  - inspect
```
default <E extends AbstractElement<?,U>,U extends AbstractElement.Update,Single extends ResolvableToSingle<E,U>> Single inspect(E entity,
                                                                                                                                Class<Single> accessInterface)
```
    A generic version of the inspect methods that accepts an element and returns the access interface to it.
    If you don't know the type of element (and therefore cannot deduce access interface type) you can always use ResolvableToSingle type which is guaranteed to be the super interface of all access interfaces returned from this method (which makes it almost useless but at least you can get the instance of it).
    
    Type Parameters:
    
    E - the type of the element
    
    Single - the type of the access interface
    
    Parameters:
    
    entity - the element to inspect
    
    accessInterface - the expected access interface
    
    Returns:
    
    the access interface instance
    
    Throws:
    
    ClassCastException - if the provided access interface doesn't match the element
  - inspect
```
default <E extends AbstractElement<?,U>,U extends AbstractElement.Update,Single extends ResolvableToSingle<E,U>> Single inspect(CanonicalPath path,
                                                                                                                                Class<Single> accessInterface)
```
    Another generic version of the inspect method, this time using the CanonicalPath to an element.
    If you don't know the type of element (and therefore cannot deduce access interface type) you can always use ResolvableToSingle type which is guaranteed to be the super interface of all access interfaces returned from this method (which makes it almost useless but at least you can get the instance of it).
    
    Type Parameters:
    
    Single - the type of the access interface
    
    Parameters:
    
    path - the path to the element (entity or relationship)
    
    accessInterface - the expected access interface
    
    Returns:
    
    the access interface instance
    
    Throws:
    
    ClassCastException - if the provided access interface doesn't match the element
  - hasObservers
```
boolean hasObservers(Interest<?,?> interest)
```
    This method is mainly useful for testing.
    
    Parameters:
    
    interest - the interest in changes of some inventory entity type
    
    Returns:
    
    true if the interest has some observers or not
  - observable
```
<C,E> rx.Observable<C> observable(Interest<C,E> interest)
```
    NOTE: The subscribers will receive the notifications even after they failed. I.e. it is the subscribers responsibility to unsubscribe on error
    
    Type Parameters:
    
    C - the type of object that will be passed to the subscribers of the returned observable
    
    E - the type of the entity the interest is expressed on
    
    Parameters:
    
    interest - the interest in changes of some inventory entity type
    
    Returns:
    
    an observable to which the caller can subscribe to receive notifications about inventory mutation

Interface Inventory

Method Summary

Methods inherited from interface java.lang.AutoCloseable

Method Detail

initialize

tenants

relationships

inspect

inspect

inspect

inspect

inspect

inspect

inspect

inspect

inspect

inspect

hasObservers

observable