hypercast.MonitorAndControl
Interface I_Monitor

All Superinterfaces:
I_Stats
All Known Implementing Classes:
Monitor

public interface I_Monitor
extends I_Stats

The Monitor class provides the API used to access remote Portals. This class can be seen as the combination of PortalListManager and MCSocket with a few extra services. Remote Portals are addressed using integer indices. Once an index is assigned to a Portal, that index is bound to that Portal for the duration of the existence of the Monitor, i.e. indices are never reassigned (unless compactPortalList() or clearPortalList() is called). Responsible for: - ensuring uniqueness of message ids - registering callbacks for message receipt and timeouts - delegating calls to MCSocket and PortalListManager


Method Summary
 void clearPortalList()
          Clear the portal list.
 void closeMonitor()
          explicitly close monitor
 void compactPortalList()
          Compact the portal list Remove all inactive portals from Monitor data structures.
 hypercast.MonitorAndControl.MonMessage createGetRequest()
          create a GetRequest message "GetRequest" message is used to query for one or more statistics on a Portal.
 hypercast.MonitorAndControl.MonMessage createReadSchemaRequest()
          create a ReadSchema request "ReadSchema" message is used to query the schemas of a list of the readable statistics on a Portal.
 hypercast.MonitorAndControl.MonMessage createSetRequest()
          create a SetRequest message "SetRequest" message is used to set the values of a list of statistics on a Portal.
 hypercast.MonitorAndControl.MonMessage createWriteSchemaRequest()
          create a WriteSchema request "WriteSchema" message is used to query the schemas of a list of the writable statistics on a Portal.
 int[] getActivePortalIndices()
          Get an integer array containing the indices of active portals.
 int[] getAllPortalIndices()
          Get An integer array containing the indexes of all.
 int[] getInactivePortalIndices()
          Get an integer array containing the indices of inactive portals.
 hypercast.I_LogicalAddress getPortalAddress(int portalIndex)
          Get the logical address of a Portal
 int indexOfPortal(hypercast.I_LogicalAddress portalLogicalAddress)
          Get the index of a portal by its logical address.
 boolean isPortalActive(int portalIndex)
          Check if a portal is still active
 void openMonitor()
          Explicitly open monitor.
 void sendTo(int portalIndex, hypercast.MonitorAndControl.MonMessage message, hypercast.MonitorAndControl.I_ReceiveCallback receiveCallback, hypercast.MonitorAndControl.I_TimeoutCallback timeoutCallback)
          Sends an MonMessage to a single Portal.
 void sendToAll(hypercast.MonitorAndControl.MonMessage message, hypercast.MonitorAndControl.I_ReceiveCallback receiveCallback, hypercast.MonitorAndControl.I_TimeoutCallback timeoutCallback)
          Send a MC message to all portals by multicast.
 void setSilentOff()
          Causes a Monitor to begin sending MonitorAdvertise messages to Portals
 void setSilentOn()
          Causes a Monitor to cease sending MonitorAdvertise messages to Portals
 void startTranscript(java.lang.String filename)
          Causes MCMessages to be recorded in a transcript file.
 void stopTranscript()
          Stops transcripting.
 
Methods inherited from interface hypercast.I_Stats
getReadSchema, getStats, getStatsName, getWriteSchema, setStats, setStatsName
 

Method Detail

getActivePortalIndices

public int[] getActivePortalIndices()
Get an integer array containing the indices of active portals.

Returns:
An integer array containing the indices of active portals, can be zero length array, but never null. The length of this array is at most the number of Portals.

getInactivePortalIndices

public int[] getInactivePortalIndices()
Get an integer array containing the indices of inactive portals.

Returns:
An integer array containing the indices of inactive portals, can be zero length array, but never null. The length of this array is at most the number of Portals.

getAllPortalIndices

public int[] getAllPortalIndices()
Get An integer array containing the indexes of all.

Returns:
An integer array containing the indexes of all portals, can be zero length array, but never null. The length of this array is the number of Portals.

isPortalActive

public boolean isPortalActive(int portalIndex)
                       throws NoSuchPortalException
Check if a portal is still active

Parameters:
portalIndex - the index of the portal
Returns:
active status of specified Portal
Throws:
NoSuchPortalException - if this portal doesn't exist.

clearPortalList

public void clearPortalList()
Clear the portal list. Remove all portal entires. Does not cause Portals to stop. This is a local operation on Monitor data structures.


compactPortalList

public void compactPortalList()
Compact the portal list Remove all inactive portals from Monitor data structures.


sendTo

public void sendTo(int portalIndex,
                   hypercast.MonitorAndControl.MonMessage message,
                   hypercast.MonitorAndControl.I_ReceiveCallback receiveCallback,
                   hypercast.MonitorAndControl.I_TimeoutCallback timeoutCallback)
            throws NoSuchPortalException
Sends an MonMessage to a single Portal. A reply message from the Portal having the same message ID as the request message sent from the Monitor will be the parameter of the receiveCallback for handling by the application. The application need not provide a receiveCallback (can be null) if it is uninterested in the response. If no reply is received during the timeout time (configured in the config file), the timeoutCallback will be invoked with the request message as a parameter (a copy of the request message is made by the Monitor to ensure that the original request message is given to the caller in the timeoutCallback, this is because a caller is free to use a message object many times, possibly changing the contents between uses). A timeoutCallback need not be specified if the application is not interested in timeouts (in this case no copy of the original message is made). Note that a caller may use the same message object again and again as a parameter to this method and each invocation will be interpreted as a new request so long as the message id field is cleared before each call of this method In the case of a timeoutCallback invocation, an application that wants to retransmit a request can call sendTo() again with the message reference that is passed via the timeoutCallback (this reference points to a copy of the original message that was made when it was sent). Doing this invokes a retransmission using the same message id as the original transmission. Do not clear the message id before calling sendTo() for retransmission.The subsequent call to sendTo() will detect that the message was aready sent and not assign a new message id to the request. Be careful not to change the state of the message after calling sendTo() for a retransmission because in that situation the Monitor implementation and the application both have a pointer to the same data structure. Remember the the Monitor made a copy of the message on the first send so that it could give a pointer to the copy to the application on a timeout. By calling sendTo() with this reference you are simply passing a pointer to an object that should be considered internal state of the Monitor.

Parameters:
portalIndex - index of destination portal
message - message to send, cannot be null
receiveCallback - callback object handling the reply message, can be null
timeoutCallback - callback to handle the timeout event, can be null
Throws:
java.lang.NullPointerException - if message is null
NoSuchPortalException

sendToAll

public void sendToAll(hypercast.MonitorAndControl.MonMessage message,
                      hypercast.MonitorAndControl.I_ReceiveCallback receiveCallback,
                      hypercast.MonitorAndControl.I_TimeoutCallback timeoutCallback)
Send a MC message to all portals by multicast. A reply message with the same message ID as the message sent will be sent to the receiveCallback for handling.

Parameters:
message - message to send, cannot be null
receiveCallback - callback to handle reply message
timeoutCallback - callback to handle situation when no portal replies
Throws:
java.lang.NullPointerException - if message is null

indexOfPortal

public int indexOfPortal(hypercast.I_LogicalAddress portalLogicalAddress)
                  throws NoSuchPortalException
Get the index of a portal by its logical address.

Parameters:
portalLogicalAddress - the logical address of the portal
Returns:
the index of the portal
Throws:
NoSuchPortalException - if no portal exists with that logical address

getPortalAddress

public hypercast.I_LogicalAddress getPortalAddress(int portalIndex)
                                            throws NoSuchPortalException
Get the logical address of a Portal

Parameters:
portalIndex - The index of the Portal.
Returns:
The logical address of the Portal.
Throws:
NoSuchPortalException - If the portal doesn't exist.

createGetRequest

public hypercast.MonitorAndControl.MonMessage createGetRequest()
create a GetRequest message "GetRequest" message is used to query for one or more statistics on a Portal. After the mesage is created, it can be manipulated to add or remove statistics of interest.

Returns:
a MonMessage of "GetRequest" type

createSetRequest

public hypercast.MonitorAndControl.MonMessage createSetRequest()
create a SetRequest message "SetRequest" message is used to set the values of a list of statistics on a Portal. After thie mesage is created, it can be manipulated to add, remove, or remove XPath expression to represent the statistics of interest, and the new XML value of the statistics to be set.

Returns:
a MonMessage of "SetRequest" type

createReadSchemaRequest

public hypercast.MonitorAndControl.MonMessage createReadSchemaRequest()
create a ReadSchema request "ReadSchema" message is used to query the schemas of a list of the readable statistics on a Portal. After thie mesage is created, it can be manipulated to add, remove, or remove XPath expression to represent the statistics of interest.

Returns:
a MonMessage of "ReadSchema" type

createWriteSchemaRequest

public hypercast.MonitorAndControl.MonMessage createWriteSchemaRequest()
create a WriteSchema request "WriteSchema" message is used to query the schemas of a list of the writable statistics on a Portal. After thie mesage is created, it can be manipulated to add, remove, or remove XPath expression to represent the statistics of interest.

Returns:
a MonMessage of "WriteSchema" type

startTranscript

public void startTranscript(java.lang.String filename)
                     throws java.io.FileNotFoundException,
                            java.lang.IllegalStateException,
                            HyperCastWarningRuntimeException
Causes MCMessages to be recorded in a transcript file. Depending on the options present in the configuration file either messages that are sent, received, or both will be recorded.

Parameters:
filename - The name of the transcript file.
Throws:
HyperCastWarningRuntimeException - If the header cannot be written to the transcript file.
HyperCastWarningRuntimeException - If the configuration specifies that neither sent nor received messsages should be recorded.
java.io.FileNotFoundException - If the specified file cannot be accessed
java.lang.IllegalStateException - If a transcript is already started

stopTranscript

public void stopTranscript()
                    throws java.lang.IllegalStateException,
                           HyperCastWarningRuntimeException
Stops transcripting.

Throws:
java.lang.IllegalStateException - If no transcript is active.
HyperCastWarningRuntimeException

openMonitor

public void openMonitor()
Explicitly open monitor. A Monitor cannot be used until it's opened.


closeMonitor

public void closeMonitor()
explicitly close monitor


setSilentOn

public void setSilentOn()
Causes a Monitor to cease sending MonitorAdvertise messages to Portals


setSilentOff

public void setSilentOff()
Causes a Monitor to begin sending MonitorAdvertise messages to Portals