JXTA

net.jxta.peer
Interface PeerInfoService

All Superinterfaces:
Module, Service

public interface PeerInfoService
extends Service

The PeerInfoService is a generic API for getting information about the local Peer as well as remote Peers.

The most important type of information about a Peer may be gotten through the Monitoring Service that may be accessed via the PeerInfoService. The Monitoring Service provides an open mechanism for reporting any type of Metrics gathered on a Peer by a ServiceMonitor. Attached Service Monitors are identified by their ModuleClassID. A ServiceMonitor may monitor anything (ie it is not restricted to JXTA Services).

There are several methods for accessing the capabilities and metrics from ServiceMonitors attached to the Peer (either locally or from remote peers).

Cumulative MonitorReports containing metrics since the Monitoring began (or was reset) on a local/remote Peer may be obtained. Alternatively, you may register listeners get periodic MonitorReports (at a specified rate) of metrics (since the previous report). The amount of information obtained (either cumulatively or periodically) is determined by a MonitorFilter whi

The PeerInfoService utilizes the ResolverService to send queries and receive responses (PeerInfoQueryMessage / PeerInfoResponseMessage). These contain requests and responses that are specific to the type of info being requested. Depending upon the type of information requested, a peer may provide multiple varying responses over time (as is the case for periodic remote peer Monitoring).

At the time of writing this documentation Service Monitoring is the only type of Peer Information available though the implementation and underlying protocol can support other types of information.

See the document:

Since:
JXTA 1.0
See Also:
MonitorFilter, MonitorReport, ServiceMonitor, PeerMonitorInfo, PeerInfoQueryMessage, PeerInfoResponseMessage

Field Summary
 
Fields inherited from interface net.jxta.platform.Module
START_AGAIN_PROGRESS, START_AGAIN_STALLED, START_DISABLED, START_OK
 
Method Summary
 long addMonitorListener(MonitorFilter monitorFilter, long reportRate, boolean includeCumulative, MonitorListener monitorListener)
          Get MonitorReports at a specified rates of metrics accrued over time from the ServiceMonitors (specified in the MonitorFilter) about the local Peer.
 void addRemoteMonitorListener(PeerID peerID, MonitorFilter monitorFilter, long reportRate, boolean includeCumulative, MonitorListener monitorListener, long lease, long timeout)
          Get MonitorReports at a specified rates of metrics accrued over time from the ServiceMonitors (specified in the MonitorFilter) about the specified remote Peer.
 long getBestReportRate(long desiredReportRate)
          Asynchronous reporting of Monitored data may be obtained only at rates supported by the MonitorManager on the peer.
 MonitorReport getCumulativeMonitorReport(MonitorFilter monitorFilter)
          Get a MonitorReport of total accumulated metrics from the ServiceMonitors (specified in the MonitorFilter) since they were created/reset for the local Peer.
 void getCumulativeMonitorReport(PeerID peerID, MonitorFilter monitorFilter, MonitorListener monitorListener, long timeout)
          Get a MonitorReport of total accumulated metrics from the ServiceMonitors (specified in the MonitorFilter) since they were created/reset for the specified remote Peer.
 PeerMonitorInfo getPeerMonitorInfo()
          Obtain the monitoring capabilities of the Local Peer.
 void getPeerMonitorInfo(PeerID peerID, PeerMonitorInfoListener peerMonitorInfoListener, long timeout)
          Obtain the monitoring capabilities of a Remote Peer.
 long[] getSupportedReportRates()
          Asynchronous reporting of Monitored data may be obtained only at rates supported by the MonitorManager on the peer.
 boolean isLocalMonitoringAvailable()
          See if Local Monitoring is available on this Peer Local monitoring is only available if you are using a version of of jxta.jar that was build with metering activated.
 boolean isLocalMonitoringAvailable(ModuleClassID moduleClassID)
          See if Local monitoring is available from a specific ServiceMonitor.
 boolean isSupportedReportRate(long reportRate)
          Asynchronous reporting of Monitored data may be obtained only at rates supported by the MonitorManager on the peer.
 boolean removeMonitorListener(MonitorListener monitorListener)
          Stop the periodic reporting for all registered filters corresponding to this MonitorListener
 void removeRemoteMonitorListener(MonitorListener monitorListener, long timeout)
          Stop the periodic reporting for all registered filters to the all remote Peers corresponding to this MonitorListener.
 void removeRemoteMonitorListener(PeerID peerID, MonitorListener monitorListener, long timeout)
          Stop the periodic reporting for all registered filters to the specified Peer corresponding to this MonitorListener.
 
Methods inherited from interface net.jxta.service.Service
getImplAdvertisement, getInterface
 
Methods inherited from interface net.jxta.platform.Module
init, startApp, stopApp
 

Method Detail

isLocalMonitoringAvailable

boolean isLocalMonitoringAvailable()
See if Local Monitoring is available on this Peer Local monitoring is only available if you are using a version of of jxta.jar that was build with metering activated.

See the document:

Returns:
true if local monitoring is available

isLocalMonitoringAvailable

boolean isLocalMonitoringAvailable(ModuleClassID moduleClassID)
See if Local monitoring is available from a specific ServiceMonitor. Local monitoring is only available if you are using a version of of jxta.jar that was build with metering activated.

See the document:

Parameters:
moduleClassID - The Module classID of the ServiceMonitor. Note that the ServiceMonitor moduleClassID is not the same as moduleClassID of the Service being monitored.
Returns:
true if local monitoring is available for a specific module

getSupportedReportRates

long[] getSupportedReportRates()
Asynchronous reporting of Monitored data may be obtained only at rates supported by the MonitorManager on the peer. This method returns the locally supported rates (in milliseconds)

Returns:
all supported rates

isSupportedReportRate

boolean isSupportedReportRate(long reportRate)
Asynchronous reporting of Monitored data may be obtained only at rates supported by the MonitorManager on the peer. This method validates whether a specific rate (in milliseconds) is locally supported.

Parameters:
reportRate - the report rate to check
Returns:
true if a report rate is supported

getBestReportRate

long getBestReportRate(long desiredReportRate)
Asynchronous reporting of Monitored data may be obtained only at rates supported by the MonitorManager on the peer. This method supplies the closest (rounded up) rate (in milliseconds) to the specified rate that is locally supported.

Parameters:
desiredReportRate - the desired rate
Returns:
the desired rate

getPeerMonitorInfo

PeerMonitorInfo getPeerMonitorInfo()
Obtain the monitoring capabilities of the Local Peer.

The PeerMonitorInfo provides:

Returns:
PeerMonitorInfo

getPeerMonitorInfo

void getPeerMonitorInfo(PeerID peerID,
                        PeerMonitorInfoListener peerMonitorInfoListener,
                        long timeout)
                        throws MonitorException
Obtain the monitoring capabilities of a Remote Peer.

The PeerMonitorInfo provides:

Via the PeerMonitorInfoListener, you will be informed of the PeerMonitorInfo or why it was not provided (error, timeout, unavailable, etc)

Parameters:
peerID - The PeerID of the Peer you wish information about
peerMonitorInfoListener - The Listener to be told about the obtained PeerMonitorInfo
timeout - Generate a timeout event if no answer has been received in this time (in Milliseconds)
Throws:
MonitorException - if a monitor error occurs

getCumulativeMonitorReport

MonitorReport getCumulativeMonitorReport(MonitorFilter monitorFilter)
                                         throws MonitorException
Get a MonitorReport of total accumulated metrics from the ServiceMonitors (specified in the MonitorFilter) since they were created/reset for the local Peer.

Parameters:
monitorFilter - The MonitorFilter containing the specific ServiceMonitors and types of Service Metrics desired
Returns:
the report
Throws:
MonitorException - if a monitor error occurs

getCumulativeMonitorReport

void getCumulativeMonitorReport(PeerID peerID,
                                MonitorFilter monitorFilter,
                                MonitorListener monitorListener,
                                long timeout)
                                throws MonitorException
Get a MonitorReport of total accumulated metrics from the ServiceMonitors (specified in the MonitorFilter) since they were created/reset for the specified remote Peer.

Parameters:
peerID - The PeerID of the Peer you wish information about
monitorFilter - The MonitorFilter containing the specific ServiceMonitors and types of Service Metrics desired
monitorListener - The Listener to obtain the report when it arrives (or timed out)
timeout - The timeout for reporting that the information has not arrived.
Throws:
MonitorException - if a monitor error occurs

addMonitorListener

long addMonitorListener(MonitorFilter monitorFilter,
                        long reportRate,
                        boolean includeCumulative,
                        MonitorListener monitorListener)
                        throws MonitorException
Get MonitorReports at a specified rates of metrics accrued over time from the ServiceMonitors (specified in the MonitorFilter) about the local Peer. For many applications it is required to obtain metrics from the beginning of time and then augment over time as more data arrives.

There is a problem with the following approach:

  1. Call getCumulativeMonitorReport to get the cumulative totals
  2. Call addMonitorListener to get periodic changes
  3. Add the periodic data to the totals

Because of a potential race condition related to metrics that are measured between the two calls it is possible to lose some metrics. To address this, this method supports this by combining them into a single call that allows you to specify whether you wish the first report delivered to be a cumulative report.

Parameters:
monitorFilter - The MonitorFilter containing the specific ServiceMonitors and types of Service Metrics desired
reportRate - The rate at which you wish metric delta reports
includeCumulative - Should the first report you receive be the cumulative data since the ServiceMonitors were created/reset?
monitorListener - The Listener to obtain the report when it arrives (or timed out)
Returns:
report rate
Throws:
MonitorException - if a monitor error occurs

addRemoteMonitorListener

void addRemoteMonitorListener(PeerID peerID,
                              MonitorFilter monitorFilter,
                              long reportRate,
                              boolean includeCumulative,
                              MonitorListener monitorListener,
                              long lease,
                              long timeout)
                              throws MonitorException
Get MonitorReports at a specified rates of metrics accrued over time from the ServiceMonitors (specified in the MonitorFilter) about the specified remote Peer. For many applications it is required to obtain metrics from the beginning of time and then augment over time as more data arrives.

There is a problem with the following approach:

  1. Call getCumulativeMonitorReport to get the cumulative totals
  2. Call addMonitorListener to get periodic changes
  3. Add the periodic data to the totals

Because of a potential race condition related to metrics that are measured between the two calls it is possible to lose some metrics. To address this, this method supports this by combining them into a single call that allows you to specify whether you wish the first report delivered to be a cumulative report.

Parameters:
peerID - The PeerID of the Peer you wish information about
monitorFilter - The MonitorFilter containing the specific ServiceMonitors and types of Service Metrics desired
reportRate - The rate at which you wish metric delta reports
includeCumulative - Should the first report you receive be the cumulative data since the ServiceMonitors were created/reset?
monitorListener - The Listener to obtain the report when it arrives (or timed out)
timeout - The timeout for reporting that the information has not arrived.
lease - the lease
Throws:
MonitorException - if a monitor error occurs

removeMonitorListener

boolean removeMonitorListener(MonitorListener monitorListener)
                              throws MonitorException
Stop the periodic reporting for all registered filters corresponding to this MonitorListener

Parameters:
monitorListener - the monitor listener
Returns:
true if successfully removed
Throws:
MonitorException - if a monitor error occurs

removeRemoteMonitorListener

void removeRemoteMonitorListener(PeerID peerID,
                                 MonitorListener monitorListener,
                                 long timeout)
                                 throws MonitorException
Stop the periodic reporting for all registered filters to the specified Peer corresponding to this MonitorListener.

Parameters:
peerID - The Peer that you wish to deregister periodic reporting
monitorListener - The MonitorListener that was originally registered
timeout - The timeout for reporting that the remote listener was acknowledged as deregistered
Throws:
MonitorException - if a monitor error occurs

removeRemoteMonitorListener

void removeRemoteMonitorListener(MonitorListener monitorListener,
                                 long timeout)
                                 throws MonitorException
Stop the periodic reporting for all registered filters to the all remote Peers corresponding to this MonitorListener.

Parameters:
monitorListener - The MonitorListener that was originally registered
timeout - The timeout for reporting that the remote listener was acknowledged as deregistered
Throws:
MonitorException - if a monitor error occurs

JXSE