Developer Guide
The POC uses a multi layer API design
The 1st Level API is what clients interact with. Is is defined in package io.fabric.core.api. The main entry points are the ContainerManager and ProfileManager
This level has the following properties
- Dependable - Clients can interact with this API throughout the lifetime of the system
- Thread Safe - Clients can freely access this API concurrently
- Immutable - Clients receive immutable data objects
The 1st Level API is provided by a set of services that is not subject of dynamic change. When the system has completed its bootstrap procedure the top-level entry services are available and do not go away until system shutdown.
Clients use immutable data objects to interact with this API level. The state of these client objects represent the state of the system at a particular moment in time. References to other object are made by identity not inclusion. For example, a Container object references associated Profiles by ProfileIdentity and does not contain the profiles directly. Due to their shallow immutable nature, these client object are easily remotable via JMX, REST, etc
The 1st Level API shields the client from the possible dynamic nature of lower level APIs. This is currently done via a notion of state permits
The 2nd Level API is what 1st level constructs interact with. Is is defined in package io.fabric.core.spi.
This level has the following properties
- Dynamic - Services may have a lifetime shorter than that of the system
- Thread Safe - 1st level API can freely access this API concurrently
- Immutable - Exchange of immutable data objects
The 2nd Level API may be provided by a set of dynamic services - these can come and go any time. 1st and 2nd level API use a common coordinator service to control the dynamic nature of these constructs.
Like 1st level, immutable data objects are used to interact with this API level. This API controls concurrent access and locking of system state. All system state mutation operations must go through 2nd level services.
Internally, 2nd level API services may interact with lower level APIs using mutable object that must however be confined to the duration of a call. 2nd level services may assume that access is protected by a permit, hence service state will remain stable for the duration of a call.
These are internal services and data structures - no assumptions are made. Clients will not see constructs used at this level.
For example, an implementation of the ContainerService may chose to maintain container runtime state in a data base accessed via Hibernate. Later, this may be replaced using an Infinispan distributed cache. Neither implementation should leak into higher level API - the ContainerService contract would stay stable.