6. Agent Advanced Management Plug-in System (AMPS) Reference

A Resource represents a single entity in inventory, be it a platform, server or service. The precise semantics of platforms, servers, adn services is vague, so a Resource object encapsulates any resource no matter what its category.

ResourceCategory is an enumeration that is associated with each Resource and indicates if the Resource is considered a platform, server, or service.

ResourceType represents types of resource instances that can be added to inventory. ResourceTypes are defined by plug-in descriptors. Another way of looking at it is that a ResourceType defines an application or service that can be managed by JBoss ON. ResourceTypes are added to JBoss ON as agent plug-ins are deployed, so a JBoss AS plug-in allows you to manage JBoss servers, a Tomcat plug-in manages Tomcat servers, and a custom plug-in can manage a custom application.

This facet provides basic availability checking - is a managed resource up or down? When the plug-in container needs to know if a resource is running or not, it will ask the resource component's availability facet. Unlike the other facets, the AvailabilityFacet is required to be implemented by all resource components. You are forced to implement it because the ResourceComponent interface extends the AvailabilityFacet. You can optionally use the asynchronous availability collector to perform the avail checking.

This facet provides the ability for a resource component to modify the configuration of the actual managed resource. When a resource component implements this facet, it is saying it has the capability to get the current configuration of the managed resource as well as be able to change it. As an example, the JBoss AS Data Source Service resource component implements the ConfigurationFacet because it can report back to the user what the current settings are of that data source (e.g. its JDBC driver, its JNDI name, its connection pool size, etc) and it can allow the user to change those settings.

Resources may have content associated with them including deployed software or software parts and other content. This system can be used to inventory these software parts and to install and remove them. Examples of deployed content are RPMs on Linux, EARs and WAR applications or libraries and deployment files on JBoss Application Server. Plug-ins can support arbitrary types of content with this system

Resources may have additional files (aka "content") associated with it - configuration files, deployment files, etc. Those resources that have associated content can implement the ContentFacet to help create, delete and manage that content.

This facet should be implemented by the ResourceDiscoveryComponent class for types of resources that can be manually added to inventory via the JBoss ON GUI. In addition, the corresponding server or service elements in the plug-in descriptor must include the supportsManualAdd="true" attribute. Manual add can be a useful capability when a particular Resource cannot be auto-discovered for some reason.

This facet exposes the capability for the component to collect measurement data from the managed resource and to report that data back to the server. For a measurement facet to work, the plug-in must define one or more metric definitions for the resource component's resource type in the plug-in descriptor. The resource component does not have to concern itself with how to schedule measurement collections and when it should collect the data. The only thing the MeasurementFacet requires the resource component to do is go out to the actual managed resource and collect the requested data. The plug-in container will manage all measurement collection schedules and will only call into the resource component's MeasurementFacet when the time is appropriate and it will only ask for the metrics that need to be collected at that time.

The measurement facet is what provides the graphs of measurement data that you see in the JBoss ON GUI Console.

This facet allows the resource component to perform operations (aka control actions) on the managed resource itself. This allows, for example, the JBoss AS Server resource component to provide the capability to start and stop the JBoss AS server. Other examples of operations are being able to clear a connection pool for a data source, or ask a resource to empty a data cache. Whatever the managed resource can be told to do, a resource component can expose that as an operation to the JBoss ON user.

Some resource components can support the creation and deletion of child resources (for example, a resource component representing the JBoss AS server can create and delete JBoss AS data source services by creating and deleting *-ds.xml files). This facet exposes this functionality.

To support managed resources, there is some data that support organizations might wish to know about regarding a managed resource, such as the contents of its log files, data files, and configuration files. The SupportFacet will provide a hook into this "support and maintenance" view of the managed resource.

The discovery component is an implementation written by the plug-in writer that performs the discovery of the actual managed resources. The discovery component's job is to scan the platform (that is, the machine the agent/plug-in container/plug-in is running on) and to report back what it finds. A discovery component is only responsible for finding resources that it directly is in charge of managing. That is to say, a JBoss AS plug-in discovery component is not responsible for discovering all Apache Web Servers - it only needs to find JBoss AS resources (leave the discovery of Apache Web Servers to the Apache plug-in).

A discovery component will be told to go hunt for resources at an appropriate time by the plug-in container. When the plug-in container asks the discovery component to go discover more resources, it will send in a ResourceDiscoveryContext object to the discovery component. This context contains all the information the component needs to perform its duties of finding and creating new resources. The discovery context is also used to inject resources into the discovery component, in the case where the plug-in container was able to discover new resources on behalf of the discovery component. A plug-in container can only auto-discover resources if the appropriate metadata is supplied to it via the plug-in's descriptor.

A resource component is a plug-in abstraction that represents an actual managed resource. A resource component is stateful whose lifecycle is managed by the plug-in container.

The plug-in container will start and stop a resource component at the appropriate times. When a resource component is started, it typically connects to its underlying resource (the managed resource it represents) and maintains that connection until it is stopped by the plug-in container (this is an implementation detail that a plug-in writer is free to change). A resource component implementation provides a way for the plug-in container to ask for the availability of the managed resource ("is this resource up? or has it gone down?") and to access optional functionality facets that a plug-in writer chooses to expose. More on facets below.

The plug-ins will have access to a SystemInfo object that is specific to the hardware/OS platform on which the plug-in is running. Once a plug-in obtains a SystemInfo object from its context (either ResourceDiscoveryContext or ResourceContext), it can make calls to that object which will call down into the native libraries to obtain the requested data from the operating system. If there are no native libraries available, the SystemInfo will be backed with a pure Java implementation of some, but not all, of the methods defined in the SystemInfo interface (see the JavaSystemInfo implementation of that interface). The methods that are not supported by the pure Java implementation will throw an UnsupportedOperationException.

One interesting feature the SystemInfo interface provides is the ability to probe the operating system's process table. This is useful for your ResourceDiscoveryComponent implementations because they can scan the list of running processes and try to determine if it can auto-detect a managed resource that it is tasked to discover.

Through the use of the ProcessInfoQuery object, you can find processes that match a given set of criteria, defined by the Process Info Query Language (PIQL). You can even set pre-defined PIQL queries in your plug-in's descriptor via the process-scan tag to have the plug-in container scan the process table on behalf of your plug-in.