Name: wildfly-capabilities
Owner: wildfly
Description: Registry of capabilities accessible via the management layer of a WildFly Core base server
Created: 2015-07-03 19:14:50.0
Updated: 2018-05-16 15:43:07.0
Pushed: 2018-05-16 15:43:06.0
Homepage: null
Size: 83
Language: null
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
http://wildfly.org
This project provides the central registry of descriptive information about capabilities accessible via the management layer of a WildFly Core based process. The intent is to provide a central location where capability developers can go to learn about other capabilities available in the WildFly ecosystem and to advertise their capability. Most importantly, registering capabilities helps ensure that different capabilities won't use the same name.
This project does not produce a build. It is simply a registry of information.
The registry consists of two primary elements:
A capability is a piece of functionality used in a WildFly Core based process that is exposed via the WildFly Core management layer. Capabilities may depend on other capabilities, and this interaction between capabilities is mediated by the WildFly Core management layer.
Some capabilities are automatically part of a WildFly Core based process, but in most cases the configuration provided by the end user (i.e. in standalone.xml, domain.xml and host.xml) determines what capabilities are present at runtime. It is the responsibility of the handlers for management operations to register capabilities and to register any requirements those capabilities may have for the presence of other capabilities.
Capability names are simple strings, with the dot character serving as a separator to allow namespacing.
The 'org.wildfly' namespace is reserved for projects associated with the WildFly organization on github (https://github.com/wildfly)
The structure of this repository is based on the structure of capability names. The name is split based on the dot character and then each section becomes a directory in the repository. Each directory whose path from the repository root represents a complete capability name then includes a capability.adoc file describing that capability.
The full name of a capability is either statically known, or it may include a statically known base element and then a dynamic element. The dynamic part of the name is determined at runtime based on the address of the management resource that registers the capability. For example, the management resource at the address '/socket-binding-group=standard-sockets/socket-binding=web' will register a dynamically named capability named 'org.wildlfy.network.socket-binding.web'. The 'org.wildlfy.network.socket-binding' portion is the static part of the name.
All dynamically named capabilities that have the same static portion of their name should provide a consistent feature set and set of requirements. The entry in this registry should be for the static part of the capability name. So, for the socket-binding example above, the registry.txt file would include a line for 'org.wildlfy.network.socket-binding' and the repository would include a capability.adoc file at location org/wildfly/network/socket-binding/capability.adoc.
Typically a capability functions by registering a service with the WildFly process' MSC ServiceContainer, and then dependent capabilities depend on that service. The WildFly Core management layer orchestrates registration of those services and service dependencies by providing a means to discover service names.
The capability.adoc entry for a capability should provide information about the service made available by the capability, if there is one.
Instead of or in addition to providing MSC services, a capability may expose some other API to dependent capabilities. This API must be encapsulated in a single class (although that class can use other non-JRE classes as method parameters or return types).
The capability.adoc entry for a capability should provide information about the custom integration API made available by the capability, if there is one.
A capability may rely on other capabilities in order to provide its functionality at runtime. The management operation handlers that register capabilities are also required to register their requirements.
There are three basic types of requirements a capability may have:
Hard and optional requirements may be for either statically named or dynamically named capabilities. Runtime-only requirements can only be for statically named capabilities, as such a requirement cannot be specified via configuration, and without configuration the dynamic part of the required capability name is unknown.
The capability.adoc entry for a capability should provide information about capability requirements, if there are any.
Not all capabilities are usable as a runtime-only requirement, and the capability.adoc entry for a capability should express this.
Any dynamically named capability is not usable as a runtime-only requirement.
For a capability to support use as a runtime-only requirement, it must guarantee that a configuration change to a running process the removes the capability will not impact currently running capabilities that have a runtime-only requirement for it. This means:
A capability can be private if the project that registers it does not wish its services or custom integration API to be depended upon by others. Any service or custom integration API exposed by the capability can be changed at any time and it is not necessary to record information in this registry about such services or integration API. However, the capability itself should be recorded, including descriptive information about what it does and what requirements it may have.
Private capabilities are useful because only a capability can depend upon another capability and use its services and integration API. “Anonymous” code cannot require capabilities because that would result in users not being able to determine what functionality would be lost if a required capability were removed. However, just because code wishes to use another capability and is willing to register itself as doing so doesn't mean it is willing to publish a contract that other, unknown capabilities can rely upon.
Private capabilities are allowed to provide services or a custom integration API for use by other capabilities controlled by the maintainer of the private capability. However the private capability implementation is free to change those at any time. This kind of usage scenario is analogous to typical use of package-protected Java methods.
The following is information describing the contents of a capability.adoc file. See the template.adoc file in the repository root for context.
NAME: The name of the capability. See above.
DESCRIPTION: A free form description of the capability
REGISTERED BY: Information about the project that is responsible for the integration contract exposed by the capability. There may be multiple projects that provide an implementation the capability, but there should be a single project responsible for the capability's contract. The contract is defined by the capability.adoc file and by the Java API of any classes referenced in the “SERVICE PROVIDED” and “CUSTOM INTEGRATION API” sections below. The following information should be provided:
DYNAMIC: True if the capability is dynamically named; false otherwise.
PRIVATE: True if the capability should not be used outside of its respective codebase; false otherwise. If true, any SERVICE PROVIDED or CUSTOM INTEGRATION API information provided is purely informational and is subject to change at any time.
SUPPORTS RUNTIME ONLY: True if the capability can be depended upon by another capability as a runtime-only requirement. Must be 'false' if DYNAMIC is 'true'.
SERVICE PROVIDED: Information about an MSC service registered by the capability which can be depended upon or injected by other capabilities, if there are any.
CUSTOM INTEGRATION API: Information about the custom integration API provided by the capability, if there is one.
HARD REQUIREMENTS: Information about other capabilities that must be present if this capability is registered, if there are any. For each such capability the following should be provided:
OPTIONAL REQUIREMENTS: Information about other capabilities that must be present if some aspect of this capability's configuration is present, if there are any. For each such capability the following should be provided:
RUNTIME ONLY REQUIREMENTS: Information about other capabilities that cannot be required by this capability's configuration, but which will be detected and used if present.