...
draw.io Diagram | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Category Specializations
Some categories have specialisations. An example is the category Queue. It has specialisations corresponding to the queue types supported by the Broker e.g. StandardQueue, PrirorityQueue etc.
Attributes
Each ConfiguredObject instance has zero or more attributes. Attributes have a name and a value which can be a Java primitive value or an instance of any class for which an AttributeValueConverter exist. This mechanism allows attribute values to be Lists, Sets, Maps, or arbitrary structured types ManagedAttributeValues. Attributes
Attributes are marked up in the code with method annotations @ManagedAttribute
@ManagedAttribute
AttributeValueConverter
Threading
...
annotations @ManagedAttribute which defines things whether the attribute is mandatory or mutable. Attributes can also be marked a secure which indicates restrictions no how the attribute is used (used for attributes that that store passwords or private-keys).
Attributes can have default values. The default value applies if the user omits to supply a value when the object is created. Defaults themselves can be defined in terms of context variable references.
Context Variables
Each ConfiguredObject instance has zero or more context variable assignments. These are simply name/value pairs where both name and value are strings.
When resolving an attribute's value, if the attribute's value (or attribute's default) contains a context variable reference (e.g.${foo}
), the variable is first resolved using the ConfiguredObject's own context variables. If the ConfiguedObject has no definition for the context variable, the entity's parent is tried, then its grandparent and so forth, all the way until the SystemContext is reached. If the SystemContext provides no value, the JVM's system properties are consulted.
A context variable's value can be defined in terms of other context variables.
Context variables are useful for extracting environment specific information from configuration for instance path stems or port numbers.
Lifecycle
ConfiguredObjects have a lifecycle.
A ConfiguredObject is created exactly once by a call its parent's #createChild() method. This brings the object into existence. It goes through a number of phases during creation (ConfiguredObject#create)
- resolution (where the attribute values are resolved and assigned to the object)
- creation validation (ensuring business rules are adhered to)
- registration with parents
- implementation specific creation (#onCreate)
- implementation specific opening (#onOpen)
When the Broker is restarted objects that exist in the configuration store are said to be recovered. During recovery, they follow the opening (ConfiguredObject#open)
- resolution (where the attribute values are resolved and assigned to the object)
- validation (ensuring business rules are adhered to)
- implementation specific opening (#onOpen)
Some ConfiguredObjects support starting (ConfiguredObject#start()) and stopping (ConfiguredObject#stop()) but this have not yet been extended to all objects.
ConfiguredObject#delete() caused the object to be deleted.
AbstractConfiguredObject
Most configured object implementations extent AbstractConfiguredObject (ACO). ACO provides the mechanics behind the configured implementations: attributes, context variables, state and lifecycle, and a listener mechanism: ConfigurationChangeListener.
Threading
The threading model must be understood before changes can be made safely.
The Broker and VirtualHost ConfiguredObject instances have a task executor backed by single configuration thread. Whenever the a configuration object needs to be changed, that change MUST be made by the nearest ancestor's configuration thread. This approach ensures avoids the need to employ locking. Any thread is allowed to observe the state of a ConfiguredObject at any time. For this reasons, changes must be published safely so they can be read consistently by the observing threads.
The implementations of the mutating methods (#setAttributes(), #start(), #stop() etc) within AbstractConfiguredObject are already implemented to adhere to these rules.
Configuration Persistence
ConfiguredObject categories such as SystemConfig and VirtualhostNode take responsibility for managing the storage of their children. This is marked up in the model with the @ManagedObject annotation (#managesChildren). These objects utilise a DurableConfigurationStore to persist their durable children to storage. ConfigurationChangeListener are used to trigger the update of the storage each time a ConfiguredObject is changed.
AMQP IO Layer
AMQP Protocol Engines
Queues
...