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
org.hawkular.inventory.base.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:
- 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.
org.hawkular.inventory.api.Environments.ReadWrite),
- 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
org.hawkular.inventory.api.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
org.hawkular.inventory.api.Environments.Multiple for example.