org.rhq.core.clientapi.agent.discovery
Interface DiscoveryAgentService

public interface DiscoveryAgentService

The interface to a RHQ Agent's Resource discovery subsystem.

Method Summary

void	disableServiceScans(int serverResourceId) Disable periodic scans for new services for the specified server.
void	enableServiceScans(int serverResourceId, Configuration config) Enable periodic scans for new services for the specified server, using the specified discovery configuration.
AvailabilityReport	executeAvailabilityScanImmediately(boolean changedOnlyReport) Checks the availability of all resources and returns a report on their availability statuses.
InventoryReport	executeServerScanImmediately() Executes an immediate plugin discovery scan for top-level servers.
void	executeServiceScanDeferred() This method asks that a service scan be performed, but it does not wait for the results of that scan.
InventoryReport	executeServiceScanImmediately() Executes an immediate plugin discovery scan for services and non-top-level servers.
Availability	getCurrentAvailability(Resource resource) Returns the current availablity for the specified Resource if no other thread currently possesses a write lock on that Resource's ResourceComponent, or otherwise, returns the last-collected availablity for the Resource.
Resource	getPlatform() Access to the current inventory managed by the plugin container.
MergeResourceResponse	manuallyAddResource(ResourceType resourceType, int parentResourceId, Configuration pluginConfiguration, int creatorSubjectId) Manually discover the resource of the specified type using the specified plugin configuration (i.e. connection properties).
void	removeResource(int resourceId) Shuts down and removes a Resource and its descendents from the PC's inventory.
void	synchronizeInventory(ResourceSyncInfo syncInfo) Called to inform the agent of a status change for the resource represented by syncInfo.
void	updatePluginConfiguration(int resourceId, Configuration newPluginConfiguration) This will update the plugin configuration for the resource with the given ID.

Method Detail

updatePluginConfiguration

void updatePluginConfiguration(int resourceId,
                               Configuration newPluginConfiguration)
                               throws InvalidPluginConfigurationClientException,
                                      PluginContainerException

This will update the plugin configuration for the resource with the given ID. This effectively will change the way the resource component connects to/communicates with the resource, so it will require the resource component to be restarted.

Parameters:

resourceId - identifies the resource whose plugin configuration is to be updated

newPluginConfiguration - the new plugin configuration

Throws:

InvalidPluginConfigurationClientException - if failed to update the plugin configuration or failed to restart the component due to a bad plugin configuration

PluginContainerException - if failed for some other reason

synchronizeInventory

void synchronizeInventory(ResourceSyncInfo syncInfo)

Called to inform the agent of a status change for the resource represented by syncInfo. The agent processes the syncInfo for the resource and initiates a status update for its sub-tree.

Parameters:

syncInfo - for the root of the tree to be updated.

getPlatform

Resource getPlatform()

Access to the current inventory managed by the plugin container.

Returns:

the platform that is managed by this plugin container

executeServerScanImmediately

InventoryReport executeServerScanImmediately()
                                             throws PluginContainerException

Executes an immediate plugin discovery scan for top-level servers. This looks for servers not yet in inventory.

Returns:

the inventory report

Throws:

PluginContainerException - if the server scan fails

executeServiceScanImmediately

InventoryReport executeServiceScanImmediately()
                                              throws PluginContainerException

Executes an immediate plugin discovery scan for services and non-top-level servers. This looks for servers and services that are children of servers and services already in inventory.

Returns:

the inventory report

Throws:

PluginContainerException - if the service scan fails

executeServiceScanDeferred

void executeServiceScanDeferred()

This method asks that a service scan be performed, but it does not wait for the results of that scan.

executeAvailabilityScanImmediately

AvailabilityReport executeAvailabilityScanImmediately(boolean changedOnlyReport)

Checks the availability of all resources and returns a report on their availability statuses. This method blocks until all availabilities have been checked at which point in time the report is built and returned.

Parameters:

changedOnlyReport - if true, the report returned will only contain statuses for those resources that have changed availability status from their last known state. If false, the report will contain information on all known resources (which will make the report much larger than had true been passed in).

Returns:

the report

getCurrentAvailability

@NotNull
Availability getCurrentAvailability(Resource resource)

Returns the current availablity for the specified Resource if no other thread currently possesses a write lock on that Resource's ResourceComponent, or otherwise, returns the last-collected availablity for the Resource. If the availability is not known, "unknown" will be returned (that is, the AvailabilityType in the returned Availablity will be set to null).

Parameters:

resource - a Resource

Returns:

the current availablity for the specified Resource if no other thread currently possesses a write lock on that Resource's ResourceComponent, or otherwise, the last-collected availablity for the Resource; if the availability is not known, "unknown" will be returned (that is, the AvailabilityType in the returned Availablity will be set to null).

manuallyAddResource

MergeResourceResponse manuallyAddResource(ResourceType resourceType,
                                          int parentResourceId,
                                          Configuration pluginConfiguration,
                                          int creatorSubjectId)
                                          throws InvalidPluginConfigurationClientException,
                                                 PluginContainerException

Manually discover the resource of the specified type using the specified plugin configuration (i.e. connection properties). This will not only create a new resource, but it will also ensure the resource component is activated (and thus connects to the managed resource). If an error occurs, but the caller can still process the results, the returned object will contain a ResourceError that is associated with the new resource (this occurs when the new resource was created but its component could not be activated).

Parameters:

resourceType - the type of resource to be manually added

parentResourceId - the id of the resource that will be the parent of the manually discovered resource

pluginConfiguration - the properties that should be used to connect to the underlying managed resource

creatorSubjectId - the Subject id of the JON user that requested the addition of the resource

Returns:

the newly discovered resource with any associated ResourceError that might have occurred during the activation of the resource

Throws:

InvalidPluginConfigurationClientException - if connecting to the underlying managed resource failed due to an invalid plugin configuration.

PluginContainerException - if the manual discovery fails for any other reason

removeResource

void removeResource(int resourceId)

Shuts down and removes a Resource and its descendents from the PC's inventory.

Parameters:

resourceId - the id of the Resource to remove

enableServiceScans

void enableServiceScans(int serverResourceId,
                        Configuration config)

Enable periodic scans for new services for the specified server, using the specified discovery configuration. If service scans were already enabled, the server's discovery configuration is updated on the agent.

Parameters:

serverResourceId - resource id of the server

config - discovery configuration for the server

disableServiceScans

void disableServiceScans(int serverResourceId)

Disable periodic scans for new services for the specified server. If service scans were not enabled, this method is a no-op.

Parameters:

serverResourceId - resource id of the server