Red Hat Training

A Red Hat training course is available for Red Hat JBoss Operations Network

4.8. Extended Example: Asynchronous Availability Checks

Availability scans are performed by a resource plug-in itself, for its defined resource types, and then reported to the agent.
Note
Any async availability collector only applies to the resource types within the plug-in. This is much safer and more performant configuration than increasing the agent's availability availability scan time. The availability scan time applies to all plug-ins in the plug-in container, so a longer timeout interval could easily result in the agent delaying or missing sending availability updates to the JBoss ON server and spuriously skew the histories of all resources on the platform.
Resource availability is defined within a plug-in as part of starting a resource type, as described in Section 4.4.3, “Looking at the Plug-in Components (HttpComponent.java and HttpServiceComponent.java)”. The method for retrieving and setting an availability state for a resource is getAvailability().
When a resource is started, it is automatically set to an UP state. The plug-in container checks for that availability state as part of the agent's periodic availability and monitoring scans.
Availability checks are typically very fast, fractions of a second. The plug-in container limits how long an availability check can run to five seconds, to prevent a rogue plug-in from delaying availability reporting for all other resources managed by the agent. There can be instances where a certain plug-in or resource type consistently has scans longer than the five-second timeout period.
Custom plug-ins can use a special availability collector to perform asynchronous availability checking. Basically, with async availability checks, the resource component creates its own, independent thread to run availability checks. Within that thread, the availability checks can take as long as they need to complete. The availability checks can also be run fairly frequently, every minute by default, to make sure that the availability state is current, even if the full check takes longer to complete.
The component caches and then reports the most recent availability result to the plug-in container. That stored last availability can be delivered very quickly, in the fractions of a second that the plug-in container expects.
Async availability checks are implemented through the AvailabilityCollectorRunnable class.
The availability collector is defined in three parts of the plug-in.
First, the availability collector itself is added as a data member.

Example 4.27. Part 1: The Collector

public class YourResourceComponent implements ResourceComponent {
 
    // your component needs this data member - it is your availability collector
    private AvailabilityCollectorRunnable availCollector;
Then, the collector is added to the Section 6.2.1, “AvailabilityFacet” within the resource's start method. The facet object starts the collector, returns an availability type, and sets a collection interval for the longer availability checks. The facet is what connects to the resource, periodically, to check its availability.
The collector is part of the resource context and is defined in both the start and stop methods.

Example 4.28. Part 2: Start the Availability Collector

    public void start(ResourceContext context) {
        availCollector = resourceContext.createAvailabilityCollectorRunnable(new AvailabilityFacet() {
            public AvailabilityType getAvailability() {
                // Perform the actual check to see if the managed resource is up or not
                // This method is not on a timer and can return the availability in any amount of time
                // that it needs to take.
                return ...AvailabilityType...;
            }
        }, 60000L); // 1 minute - the minimum interval allowed
 
        // Now that you've created your availability collector, start it to assign it a thread in the pool.
        availCollector.start();
 
        // ... and the rest of your component's start method goes here ...
	}


    public void stop() {
        // Stop your availability collector to cancel the collector and kill its thread.
        availCollector.stop();
 
        // ... and the rest of your component's stop method goes here ...
    }
Resource availability — with or without asynchronous availability checking — is collected with the getAvailability() method. When the async availability collector is created, then the getAvailability() method needs to return the last known results stored in the collector rather than attempting to run a new availability scan.
So the last configuration point for the async availability check is to configure the return value for the getAvailability() method.

Example 4.29. Part 2: Return the Last Known Availability

    public AvailabilityType getAvailability() {
	// This method quickly returns the last known availability that was recorded 
	// by the availability collector.
        return availCollector.getLastKnownAvailability();
    }
}