JBoss Community Archive (Read Only)

RHQ 4.9

Design-Asynchronous Availability Collector

With BZ 971556 implemented, this async avail collector is no longer used or needed and has been deprecated. Do not use it in plugins that are deployed in RHQ 4.10 or higher.

Asynchronous Availability Collector

If you read BZ 536173, you can get a sense of the problem that needs to be solved.

Typically, availability checks are very fast (sub-second). However, the plugin container puts a time limit on how long it will wait for a plugin's resource component to return availability status from calls to AvailabilityFacet#getAvailability(). This time limit is typically on the order of several seconds (5s at the time of this writing). The purpose of this time limit is to avoid having a rogue or misbehaving plugin from causing delays in availability reporting for the rest of the resources being managed within the system.

The Asynchronous Availability Collector provides an implementation to help resource components that can't guarantee how fast its availability checks will be. Some managed resources simply can't respond to avaiability checks fast enough. In this case, this class will provide an asynchronous method that will collect availability without a timeout being involved (in other words, availability will be retrieved by waiting as long as it takes). In order to tell the plugin container what the managed resource's current availability is, the Asynchronous Availability Collector will provide a fast method to return the last known availability of the resource. In other words, it will be able to return the last know availability that was last retrieved by the asynchronous task - this retrieval of the last known availability will be very fast.

The class that plugin developers need to know about is AvailabilityCollectorRunnable. You integrate this class into your ResourceComponent implementation in order to be able to perform availabilty checks asynchronously. This is how you do it:

public class YourResourceComponent implements ResourceComponent {

    // your component needs this data member - it is your availability collector
    private AvailabilityCollectorRunnable availCollector;

    public void start(ResourceContext context) {
        // As part of your start method, you need to create your availability collector
        // by asking your resource context for it.
        // When creating your availability collector, you need to supply an implementation
        // of an AvailabilityFacet. This AvailabilityFacet object that you provide is
        // the object that actually talks to your managed resource to see if it is available or not,
        // it is the object that is invoked asynchronously on a periodic basis (and you give it the 
        // interval to define the period).
        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, you must start it. Once started,
        // it is assigned a thread in a thread pool and begins periodically collecting availability.
        availCollector.start();

        // ...
        // ... and the rest of your component's start method goes here ...
    }

    public void stop() {
        // As part of your stop method, you need to stop your availability collector.
        // This cancels your collector and eventually kills the thread it is running in.
        availCollector.stop();

        // ...
        // ... and the rest of your component's stop method goes here ...
    }

    public AvailabilityType getAvailability() {
        // This is where the rubber meets the road.  The whole purpose of this availability
        // collector framework is to allow this getAvailability() method to return very fast.
        // The plugin container only gives you a few seconds to complete this method, otherwise,
        // it will be timed out.  Because you are not actually checking the managed resource here
        // (that is performed in the collector's availability facet implementation you provided in
        // the start method), this method is very fast since all it does is quickly return the
        // last known availability that was recorded by the availability collector.
        // This virtually guarantees you will never timeout in this method anymore.
        return availCollector.getLastKnownAvailability();
    }
}
JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-13 07:57:24 UTC, last content change 2013-12-05 15:15:37 UTC.