Initial dump of the work on the inventory.

[metlos]

A sketch of the API and the impl based on blueprints is provided.

I'm not even sure if the REST API works but there are tests provided for
the programmatic interface. REST API tests will follow.

There are virtually no comments in the code which I'd like to make up for by the below description ;) Obviously the comments will need to be added if we decide to use this arch.

The API is best "felt" by going through the unit tests.

Description of the API

Package org.hawkular.inventory.api

Contains the interfaces that comprise the API + the entity and filtering classes. The API is not tied in any form to the underlying storage mechanism but expresses the graph nature of the inventory. The main idea of the API is that it

1. is highly regular
2. needs to express the "walk" through the inventory graph easily.

There are therefore 2 kinds of interfaces:

1. ones that express the common operations on various entities (expressed by the generic ReadInterface, WriteInterface and RelateInterface,
2. ones that define the possible next steps on walk, together referred to as Browsers.

There is a bunch of final uninstantiable classes in this package with names in the plural of the various entity types. These "wrap" the definition of the browser and operation interfaces for given type of entity. I.e. the Environments class defines the browser interface Environments.Browser and the operation interface Environments.ReadWrite as its inner classes.

This pattern is followed for all the other entity types.

While the interfaces might look a bit impenetrable and hard to follow, they provide for a (IMHO) very nice flow when composing a "traversal" through the inventory, which can be illustrated by the following example:

Set<Metric> metrics = inventory.tenants().get("com.acme.tenant").environments().get("production").resources().get("host").metrics().getAll(Related.asTargetWith(metricDefinition, Relationships.Wellknown.defines));

This will find all the metrics with the type defined by the metricDefinition which are associated with the "host" resource in the "production" environment of the "com.acme.tenant" tenant.

Package org.hawkular.inventory.api.model

Contains the POJOs for various entities understood by the inventory. The POJO entity classes are immutable but should be JAXB-friendly. Some of the classes define a Blueprint inner class. Such blueprint classes are used when creating a entity. In those situations you generally don't need to provide all the data.

Package org.hawkular.inventory.filters

There is a finite set of possible filter types which are captured by the various classes in this package. The base class is surprisingly called Filter and is basically only a marker class (with some builder-like facilities but no actual filtering definitions possible). Other classes express the filtering by various relations in the inventory (with 1 generic relationship filter - Related) or filtering by id or type - the With class and its inner classes.

The idea of these filters is that the implementations of the API are not forced to provide some generic filtering mechanism but are only required to provide support for this small set of predefined filter types.

Package org.hawkular.inventory.impl.blueprints

This package contains classes that implement the inventory API on top of blueprints graph API.

[metlos]

Closing in favor of PR #15 which is identical but wants to merge into the "future" branch in this repo, where we will work on the more complex version of inventory until the code in the master branch is no longer needed for MVP purposes.