peerinfoservice.java

JXTA&#8482 is a set of open, generalized peer-to-peer (P2P) protocols that allow any networked devi

    /**
     * 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.
     * @param reportRate the report rate to check
     * @return true if a report rate is supported
     */
    public boolean isSupportedReportRate(long reportRate);

    /**
     * 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.
     * @param desiredReportRate the desired rate
     * @return the desired rate
     */
    public long getBestReportRate(long desiredReportRate);

    /**
     * Obtain the monitoring capabilities of the Local Peer. <P>
     * The PeerMonitorInfo provides:
     * <UL>
     * <LI> Whether any monitoring is available for this Peer </LI>
     * <LI> The supported rates of asynchronous monitoring </LI>
     * <LI> A list (as ModuleClassIDs) of ServiceMonitors attached to this Peer </LI>
     * </UL>
     * @return PeerMonitorInfo
     */
    public PeerMonitorInfo getPeerMonitorInfo();

    /**
     * Obtain the monitoring capabilities of a Remote Peer. <P>
     * The PeerMonitorInfo provides:
     * <UL>
     * <LI> Whether any monitoring is available for this Peer </LI>
     * <LI> The supported rates of asynchronous monitoring </LI>
     * <LI> A list (as ModuleClassIDs) of ServiceMonitors attached to this Peer </LI>
     * </UL>
     * <p/>
     * Via the PeerMonitorInfoListener, you will be informed of the PeerMonitorInfo or why it was
     * not provided (error, timeout, unavailable, etc)
     *
     * @param peerID                  The PeerID of the Peer you wish information about
     * @param peerMonitorInfoListener The Listener to be told about the obtained PeerMonitorInfo
     * @param timeout                 Generate a timeout event if no answer has been received in this time (in Milliseconds)
     * @throws net.jxta.meter.MonitorException if a monitor error occurs
     */
    public void getPeerMonitorInfo(PeerID peerID, PeerMonitorInfoListener peerMonitorInfoListener, 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 local Peer.
     *
     * @param monitorFilter The MonitorFilter containing the specific ServiceMonitors and types of Service Metrics desired
     * @return  the report
     * @throws net.jxta.meter.MonitorException if a monitor error occurs
     */
    public 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 specified remote Peer.
     *
     * @param peerID          The PeerID of the Peer you wish information about
     * @param monitorFilter   The MonitorFilter containing the specific ServiceMonitors and types of Service Metrics desired
     * @param monitorListener The Listener to obtain the report when it arrives (or timed out)
     * @param timeout         The timeout for reporting that the information has not arrived.
     * @throws net.jxta.meter.MonitorException if a monitor error occurs
     */
    public void getCumulativeMonitorReport(PeerID peerID, MonitorFilter monitorFilter, MonitorListener monitorListener, long timeout) 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. <P>
     * <p/>
     * There is a problem with the following approach:
     * <OL>
     * <LI>	Call getCumulativeMonitorReport to get the cumulative totals </LI>
     * <LI>	Call addMonitorListener to get periodic changes </LI>
     * <LI>	Add the periodic data to the totals </LI>
     * </OL>
     * <p/>
     * 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.
     *
     * @param monitorFilter     The MonitorFilter containing the specific ServiceMonitors and types of Service Metrics desired
     * @param reportRate        The rate at which you wish metric delta reports
     * @param includeCumulative Should the first report you receive be the cumulative data since the ServiceMonitors were created/reset?
     * @param monitorListener   The Listener to obtain the report when it arrives (or timed out)
     * @return report rate
     * @throws net.jxta.meter.MonitorException if a monitor error occurs
     */
    public 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 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. <P>
     * <p/>
     * There is a problem with the following approach:
     * <OL>
     * <LI>	Call getCumulativeMonitorReport to get the cumulative totals </LI>
     * <LI>	Call addMonitorListener to get periodic changes </LI>
     * <LI>	Add the periodic data to the totals </LI>
     * </OL>
     * <p/>
     * 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.
     *
     * @param peerID            The PeerID of the Peer you wish information about
     * @param monitorFilter     The MonitorFilter containing the specific ServiceMonitors and types of Service Metrics desired
     * @param reportRate        The rate at which you wish metric delta reports
     * @param includeCumulative Should the first report you receive be the cumulative data since the ServiceMonitors were created/reset?
     * @param monitorListener   The Listener to obtain the report when it arrives (or timed out)
     * @param timeout           The timeout for reporting that the information has not arrived.
     * @param lease the lease
     * @throws net.jxta.meter.MonitorException if a monitor error occurs
     */
    public void addRemoteMonitorListener(PeerID peerID, MonitorFilter monitorFilter, long reportRate, boolean includeCumulative, MonitorListener monitorListener, long lease, long timeout) throws MonitorException;

    /**
     * Stop the periodic reporting for all registered filters corresponding to this MonitorListener
     * @param monitorListener the monitor listener
     * @return  true if successfully removed
     * @throws net.jxta.meter.MonitorException if a monitor error occurs
     */
    public boolean removeMonitorListener(MonitorListener monitorListener) throws MonitorException;

    /**
     * Stop the periodic reporting for all registered filters to the specified Peer corresponding to this MonitorListener.
     *
     * @param peerID          The Peer that you wish to deregister periodic reporting
     * @param monitorListener The MonitorListener that was originally registered
     * @param timeout         The timeout for reporting that the remote listener was acknowledged as deregistered
     * @throws net.jxta.meter.MonitorException if a monitor error occurs
     */
    public void removeRemoteMonitorListener(PeerID peerID, MonitorListener monitorListener, long timeout) throws MonitorException;

    /**
     * Stop the periodic reporting for all registered filters to the all remote Peers corresponding to this MonitorListener.
     *
     * @param monitorListener The MonitorListener that was originally registered
     * @param timeout         The timeout for reporting that the remote listener was acknowledged as deregistered
     * @throws net.jxta.meter.MonitorException if a monitor error occurs
     */
    public void removeRemoteMonitorListener(MonitorListener monitorListener, long timeout) throws MonitorException;
}