Writing Custom Plug-ins
JBoss Operations Network 3.1.1
guidelines for writing custom server and agent resource plug-ins
June 12, 2012, updated October 3, 2012
Abstract
JBoss Operations Network can be extended and customized by developing new plug-ins. The functionality of the server can be extended through server-side plug-ins. Additional resource types can be managed by JBoss ON by creating custom agent resource plug-ins.
This guide outlines the requirements and available plug-in configurations for server-side and agent plug-ins to help plug-in writers deploycustom plug0ins in JBoss ON.
This guide is not a tutorial in how to write plug-ins, generally.
1. An Overview of JBoss ON Plug-ins
A plug-in makes an application more useful in a specific kind of way. It is a way of providing new functionality or more options for existing functionality. In JBoss ON, there are two categories of plug-ins, depending on what functionality needs to be created: server-side plug-ins and agent plug-ins. JBoss ON has a very simple and tightly integrated framework for deploying new plug-ins, which makes it relatively easy to extend JBoss ON to do a specific, custom task. Almost any subsystem or functionality in JBoss ON can be expanded and customized by writing additional plug-ins. This guide is an introduction to how to write and implement plug-ins in JBoss ON.
1.1. Extending JBoss ON: Plug-ins Defined
JBoss ON follows a hub and spoke approach with a server at its heart. The agents are deployed locally on resources and interact with the resources, as well as the JBoss ON server. The server (or cluster of servers) processes data coming in from agents. The data are stored in a database connected to the server. Users can look at the data and trigger operations through a web-based GUI on the server.
Figure 1. JBoss ON Architecture
A plug-in defines what features it is using and then it contains the code (or API) necessary carry out whatever features or operations it has defined. In JBoss ON, a plug-in is targeted to work on either a server or on an agent.
Server-side plug-ins relate to any operation or task that is performed by the server. This includes alerting and notifications, managing content and packages, setting GUI appearance and functionality, and integrating JBoss ON information with other applications. A server-side plug-in is first identified by the server subsystem which it is associated with, and then with its functionality.
Agent plug-ins are used for any task that relates to resources, primarily managing inventory (by defining resource types) and configuring monitoring. An gent plug-in, then, is associated purely by its resource type.
There are some similarities between server-side and agent plug-ins structurally.
- Every plug-in is packaged as a JAR file.
- Every plug-in has a required XML file, the plug-in descriptor, which defines all of the plug-in capabilities.
- Every plug-in contains compiled Java files which contain the code necessary to perform all of the actions defined in the descriptor.
- Plug-ins run inside a plug-in container, which is the entity that directly interacts with the plug-ins and starts and stops all plug-ins.
- All custom plug-ins are deployed to the JBoss ON server. Server-side plug-ins are propagated across the high availability cloud to all of the other servers, while agent plug-ins are made available through the server for the agents to download.
1.2. Basic Components of Plug-ins in JBoss ON
There are some common elements that comprise plug-ins in JBoss ON. Each of these elements is described in more detail in the server-side and agent plug-in sections, but this sections provides some more general context on these elements and compares some differences in the way that server-side and agent plug-ins use these elements.
1.2.1. Plug-in Containers
All JBoss ON plug-ins run inside a plug-in container. This container is responsible for loading, starting, and stopping all plug-ins. Neither the agent nor the server interacts directly with plug-ins; rather, the agent and server both host plug-in containers. The agent or server talks to the plug-in container, and the plug-in container talks to the plug-ins.
For an agent plug-in, there is nothing relevant about the plug-in container; all agent plug-ins use the same one. The container is essentially invisible to plug-in writers.
Server-side plug-ins, however ,have a very different relationship with the plug-in containers. The server runs multiple plug-in containers, each one designated for a specific subsystem or purpose. The plug-in container, itself, provides some configuration for server-side plug-ins by providing additional schema definitions and certain kinds of functionality. The plug-in container is the first identifying category for a server-side plug-in by distinguishing the type of server-side plug-in.
The plug-in container, along with controlling the relationship between the agent or server and the plug-in, also moderates the relationship between plug-ins and their classes. The plug-in container manages plug-in dependencies (for agent plug-ins), shared classes, and external libraries required by the plug-in.
1.2.2. Plug-in Descriptor
The plug-in descriptor is the file which defines what a specific plug-in does. This file loads the required API classes that allow the plug-in to interact with its plug-in container and, by extension, the server or agent. It defines the specific configuration for the plug-in instance, sets schedules or operations, and explicitly defines the intended functionality for the plug-in.
The plug-in descriptor is always an XML file. Both agent and server-side plug-ins require that the plug-in descriptor be placed in a
META-INF/ directory in the JAR file of the plug-in. For server-side plug-ins, this file must be named rhq-serverplugin.xml, and for agent plug-ins, rhq-plugin.xml.
1.2.3. Plug-in Schema Definitions
Since the plug-in descriptor is an XML file, there must be a schema definition to use to configure elements and attributes within the file. All of the plug-ins in JBoss ON use a core schema defined with the agent plug-ins,
rhq-configuration.xsd. Server-side plug-ins extend that schema with an additional schema definition file, rhq-serverplugin.xsd, and then custom schema definitions for each server-side plug-in type.
1.2.4. Java Files
The actual code for the plug-in is contained in Java files within the plug-in JAR package.
Agent plug-ins usually have at least two and sometimes several Java files for each plug-in. There are several reasons for this:
- Agent plug-ins can define both parent and children elements (platforms, servers, and services) in the same plug-in, and each resource type uses its own plug-in code.
- Agent plug-ins have two and sometimes three discrete functions. Almost every agent plug-in must have a discovery component (discovery Java file) that dictates how to identify and inventory whatever resource type is defined by the plug-in. Additionally, agent plug-ins may enable event collection for resources, which requires a separate component (event poller Java file) to track the resource logs. Last, there has to be a component (Java file) which actually implements the plug-in functionality.
- Agent plug-ins allow dependencies. Parent plug-ins can share classes with their children. An agent plug-in can set a dependency on any other agent plug-in that allows it to load that plug-ins classes. To make plug-ins perform better and to make it easier to access the relevant plug-in code, agent plug-ins are frequently broken into smaller Java files to allow the plug-in code to be reused.
Server-side plug-ins usually have only a single Java file to define the plug-in behavior. Since server-side plug-ins do not have dependencies with each other and do not interact with other subsystems (like discovery and event monitoring) everything related to the plug-in can be defined in a single file.
1.2.5. External Libraries
Any library or class that a plug-in requires that is not contained within its own Java files is an external library.
Agent plug-ins can interact through dependencies and shared classes. External libraries or classes for an agent plug-in refer to libraries or classes defined in another agent plug-in. This is one reason that it is so common for agent plug-ins to require JMX plug-in dependency, because it makes all of the JMX and EMS libraries in that plug-in available to the other agent plug-in. Agent plug-ins can also share their classes with a child plug-in, which both simplifies library management (by making the same library available to multiple plug-ins at once) and simplifies plug-in writing.
Server plug-ins do not interact with one another, so it is not possible to establish dependencies or share classes between server-side plug-ins, even in the same plug-in container. However, server-side plug-ins do allow external libraries to be packaged in the plug-in JAR file and can access any library in the
lib/ directory within the JAR file.
1.3. Downloading the Plug-in Files
Sample plug-ins are available through the RHQ source code. To check out the code:
git clone http://git.fedorahosted.org/git/rhq/rhq.git
Example agent and server-side plug-ins are in the sourceRoot
/etc/samples/ directory. These include both fully-developed examples and plug-in templates that can be used for writing new plug-ins. Rather than checking out the entire source code, you can manually download the sample files at this URL:
http://git.fedorahosted.org/git/?p=rhq/rhq.git;a=tree;f=etc/samples;hb=master
