org.rhq.core.clientapi.agent.discovery

Interface DiscoveryAgentService

public interface DiscoveryAgentService

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

Method Summary

Methods

Modifier and Type	Method and Description
void	disableServiceScans(int serverResourceId) Disable periodic scans for new services for the specified server.
void	enableServiceScans(int serverResourceId, org.rhq.core.domain.configuration.Configuration config) Enable periodic scans for new services for the specified server, using the specified discovery configuration.
org.rhq.core.domain.discovery.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.
boolean	executeServiceScanDeferred() This method asks that a service scan be performed, but it does not wait for the results of that scan.
void	executeServiceScanDeferred(int resourceId) This method asks that a service scan be performed, rooted at the specified Resource, 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.
org.rhq.core.domain.discovery.AvailabilityReport	getCurrentAvailability(org.rhq.core.domain.resource.Resource resource, boolean changesOnly) Returns the current availability for the specified resource.
org.rhq.core.domain.resource.Resource	getPlatform() Access to the current inventory managed by the plugin container.
org.rhq.core.domain.discovery.MergeResourceResponse	manuallyAddResource(org.rhq.core.domain.resource.ResourceType resourceType, int parentResourceId, org.rhq.core.domain.configuration.Configuration pluginConfiguration, int creatorSubjectId) Manually discover the resource of the specified type using the specified plugin configuration (i.e.
void	requestFullAvailabilityReport() This call will request that the agent produce a full availability report on its next availability scan.
void	synchronizePlatform(org.rhq.core.domain.discovery.PlatformSyncInfo syncInfo) Called by the server when requesting a full platform sync.
void	synchronizeServer(int resourceId, Collection<org.rhq.core.domain.discovery.ResourceSyncInfo> toplevelServerSyncInfo) Called by the server to update the agent with changed for specified top level server.
void	uninventoryResource(int resourceId) Shuts down and removes a Resource and its descendants from the PC's inventory.
void	updatePluginConfiguration(int resourceId, org.rhq.core.domain.configuration.Configuration newPluginConfiguration) This will update the plugin configuration for the resource with the given ID.

Method Detail

updatePluginConfiguration

void updatePluginConfiguration(int resourceId,
                             org.rhq.core.domain.configuration.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

synchronizePlatform

void synchronizePlatform(org.rhq.core.domain.discovery.PlatformSyncInfo syncInfo)

Called by the server when requesting a full platform sync. The provided info will guide the subsequent agent-initiated sync.

Parameters:

syncInfo - for the platform to be synchronized with the server.

synchronizeServer

void synchronizeServer(int resourceId,
                     Collection<org.rhq.core.domain.discovery.ResourceSyncInfo> toplevelServerSyncInfo)

Called by the server to update the agent with changed for specified top level server. The agent will synchronize its inventory for the server and its subtree given the provided information.

Parameters:

syncInfo - for the top level server to be synchronized with the server.

getPlatform

org.rhq.core.domain.resource.Resource getPlatform()

Access to the current inventory managed by the plugin container.

Returns:

the platform that is managed by this plugin container

executeServerScanImmediately

@NotNull
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

@NotNull
InventoryReport executeServiceScanImmediately()
                                              throws PluginContainerException

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

Returns:

the inventory report

Throws:

PluginContainerException - if the service scan fails

executeServiceScanDeferred

boolean executeServiceScanDeferred()

This method asks that a service scan be performed, but it does not wait for the results of that scan. The scan is not performed if a service scan is already in progress.

Returns:

true if the scan is launched, false if the scan was skipped due to a scan being in progress.

executeServiceScanDeferred

void executeServiceScanDeferred(int resourceId)

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

executeAvailabilityScanImmediately

org.rhq.core.domain.discovery.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
org.rhq.core.domain.discovery.AvailabilityReport getCurrentAvailability(org.rhq.core.domain.resource.Resource resource,
                                                                              boolean changesOnly)

Returns the current availability for the specified resource.

This call returns an availability report (rather just a simple availability of a single resource) because it also scans for the changes in availability in the child resources. Notice that the returned report may contain no results if changesOnly is set to true. If it is false, the report will always contain the availability of the supplied resource but can also additionally contain the availabilities of some of its child resources, if they were eligible for availability collection at the time of calling this method.

Also note that the availability types of the resources in the report may have any of the following values from the AvailabilityType enum - it may happen that the availability of the resource is AvailabilityType.UNKNOWN if the resource component is not started.

IMPORTANT: The report is NOT sent up to the server as a consequence of calling this method (unlike for example in the case of executeAvailabilityScanImmediately(boolean)). The caller itself is responsible to correctly handle the report within the server.

Parameters:

resource - the resource to return the availability of.

changesOnly - if true, only changes in availability will be reported, if false the report will contain the availabilities of all resources eligible for collection at the time of the call regardless of whether their availability changed or not.

Returns:

an availability report containing at least the availability of the supplied resource + possibly avails of some of the child resources that were eligible for avail collection at the time. The rest of the children are scheduled for availability collection in the next collector run (which happens approximately 30 seconds after this call).

requestFullAvailabilityReport

void requestFullAvailabilityReport()

This call will request that the agent produce a full availability report on its next availability scan.

manuallyAddResource

org.rhq.core.domain.discovery.MergeResourceResponse manuallyAddResource(org.rhq.core.domain.resource.ResourceType resourceType,
                                                                      int parentResourceId,
                                                                      org.rhq.core.domain.configuration.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

uninventoryResource

void uninventoryResource(int resourceId)

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

Parameters:

resourceId - the id of the Resource to remove

enableServiceScans

void enableServiceScans(int serverResourceId,
                      org.rhq.core.domain.configuration.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