hypercast.MonitorAndControl
Class Monitor

java.lang.Object
  |
  +--hypercast.MonitorAndControl.Monitor
All Implemented Interfaces:
hypercast.MonitorAndControl.I_MCRaw_Callback, I_Monitor, I_Stats

public class Monitor
extends java.lang.Object
implements I_Monitor, I_Stats, hypercast.MonitorAndControl.I_MCRaw_Callback

For full description of the Monitor class follow the "see" links. From an implementation standpoint, many methods are delegated to either the PortalListManager or the MCSocket. This class does implemented the send methods. Also, this class implements the CallbackManager mechanism that is responsible for matching responses to requests and for issuing timeouts.

See Also:
I_Monitor, PortalListManager, From the Monitor and Control design doc: "A monitor set to silent mode does not set entries in the portal list as inactive."

Constructor Summary
Monitor(hypercast.HyperCastConfig config)
          Construct a Monitor with a config object
 
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
 org.w3c.dom.Element[] getReadSchema(org.w3c.dom.Document doc, org.apache.xpath.XPath xpath)
          Dynamically generates a subtree of the Readable Schema rooted at the path specified by the xpath.
 org.w3c.dom.Element[] getStats(org.w3c.dom.Document doc, org.apache.xpath.XPath xpath)
          Gets statistics information from an object which implements this interface.
 java.lang.String getStatsName()
          Gets the element name of this I_Stats instance.
 org.w3c.dom.Element[] getWriteSchema(org.w3c.dom.Document doc, org.apache.xpath.XPath xpath)
          Dynamically generates a subtree of the Writable Schema rooted at the path specified by the xpath.
 int indexOfPortal(hypercast.I_LogicalAddress logicalAddress)
          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 receiveMCRawMessage(hypercast.MonitorAndControl.MCRawMessage message)
          Receives an MC Raw message.
 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
 org.w3c.dom.Element[] setStats(org.w3c.dom.Document doc, org.apache.xpath.XPath xpath, org.w3c.dom.Element setValue)
          Sets statistics information for an object which implements this interface.
 void setStatsName(java.lang.String name)
          Assigns a name to this I_Stats instance.
 void startTranscript(java.lang.String filename)
          Causes MCMessages to be recorded in a transcript file.
 void stopTranscript()
          Stops transcripting.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Monitor

public Monitor(hypercast.HyperCastConfig config)
Construct a Monitor with a config object

Parameters:
config - the config object to read configuration attributes from
Method Detail

startTranscript

public void startTranscript(java.lang.String filename)
                     throws java.io.FileNotFoundException
Description copied from interface: I_Monitor
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.

Specified by:
startTranscript in interface I_Monitor
Parameters:
filename - The name of the transcript file.
Throws:
java.io.FileNotFoundException - If the specified file cannot be accessed
See Also:
I_Monitor.startTranscript(String)

stopTranscript

public void stopTranscript()
Description copied from interface: I_Monitor
Stops transcripting.

Specified by:
stopTranscript in interface I_Monitor
See Also:
I_Monitor.startTranscript(String)

getPortalAddress

public hypercast.I_LogicalAddress getPortalAddress(int portalIndex)
                                            throws NoSuchPortalException
Description copied from interface: I_Monitor
Get the logical address of a Portal

Specified by:
getPortalAddress in interface I_Monitor
Parameters:
portalIndex - The index of the Portal.
Returns:
The logical address of the Portal.
Throws:
NoSuchPortalException - If the portal doesn't exist.
See Also:
I_Monitor.getPortalAddress(int)

getActivePortalIndices

public int[] getActivePortalIndices()
Description copied from interface: I_Monitor
Get an integer array containing the indices of active portals.

Specified by:
getActivePortalIndices in interface I_Monitor
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.
See Also:
I_Monitor.getActivePortalIndices()

getAllPortalIndices

public int[] getAllPortalIndices()
Description copied from interface: I_Monitor
Get An integer array containing the indexes of all.

Specified by:
getAllPortalIndices in interface I_Monitor
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.
See Also:
I_Monitor.getAllPortalIndices()

isPortalActive

public boolean isPortalActive(int portalIndex)
                       throws NoSuchPortalException
Description copied from interface: I_Monitor
Check if a portal is still active

Specified by:
isPortalActive in interface I_Monitor
Parameters:
portalIndex - the index of the portal
Returns:
active status of specified Portal
Throws:
NoSuchPortalException - if this portal doesn't exist.
See Also:
I_Monitor.isPortalActive(int)

indexOfPortal

public int indexOfPortal(hypercast.I_LogicalAddress logicalAddress)
                  throws NoSuchPortalException
Description copied from interface: I_Monitor
Get the index of a portal by its logical address.

Specified by:
indexOfPortal in interface I_Monitor
Parameters:
logicalAddress - the logical address of the portal
Returns:
the index of the portal
Throws:
NoSuchPortalException - if no portal exists with that logical address
See Also:
I_Monitor.indexOfPortal(I_LogicalAddress)

clearPortalList

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

Specified by:
clearPortalList in interface I_Monitor
See Also:
I_Monitor.clearPortalList()

sendTo

public void sendTo(int portalIndex,
                   hypercast.MonitorAndControl.MonMessage message,
                   hypercast.MonitorAndControl.I_ReceiveCallback receiveCallback,
                   hypercast.MonitorAndControl.I_TimeoutCallback timeoutCallback)
            throws NoSuchPortalException
Description copied from interface: I_Monitor
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.

Specified by:
sendTo in interface I_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
NoSuchPortalException
See Also:
I_Monitor.sendTo(int, MonMessage, I_ReceiveCallback, I_TimeoutCallback)

sendToAll

public void sendToAll(hypercast.MonitorAndControl.MonMessage message,
                      hypercast.MonitorAndControl.I_ReceiveCallback receiveCallback,
                      hypercast.MonitorAndControl.I_TimeoutCallback timeoutCallback)
Description copied from interface: I_Monitor
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.

Specified by:
sendToAll in interface I_Monitor
Parameters:
message - message to send, cannot be null
receiveCallback - callback to handle reply message
timeoutCallback - callback to handle situation when no portal replies
See Also:
I_Monitor.sendToAll(MonMessage, I_ReceiveCallback, I_TimeoutCallback)

createGetRequest

public hypercast.MonitorAndControl.MonMessage createGetRequest()
Description copied from interface: I_Monitor
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.

Specified by:
createGetRequest in interface I_Monitor
Returns:
a MonMessage of "GetRequest" type
See Also:
I_Monitor.createGetRequest()

createSetRequest

public hypercast.MonitorAndControl.MonMessage createSetRequest()
Description copied from interface: I_Monitor
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.

Specified by:
createSetRequest in interface I_Monitor
Returns:
a MonMessage of "SetRequest" type
See Also:
I_Monitor.createSetRequest()

createReadSchemaRequest

public hypercast.MonitorAndControl.MonMessage createReadSchemaRequest()
Description copied from interface: I_Monitor
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.

Specified by:
createReadSchemaRequest in interface I_Monitor
Returns:
a MonMessage of "ReadSchema" type
See Also:
I_Monitor.createReadSchemaRequest()

createWriteSchemaRequest

public hypercast.MonitorAndControl.MonMessage createWriteSchemaRequest()
Description copied from interface: I_Monitor
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.

Specified by:
createWriteSchemaRequest in interface I_Monitor
Returns:
a MonMessage of "WriteSchema" type
See Also:
I_Monitor.createWriteSchemaRequest()

compactPortalList

public void compactPortalList()
Description copied from interface: I_Monitor
Compact the portal list Remove all inactive portals from Monitor data structures.

Specified by:
compactPortalList in interface I_Monitor
See Also:
I_Monitor.compactPortalList()

setSilentOn

public void setSilentOn()
Description copied from interface: I_Monitor
Causes a Monitor to cease sending MonitorAdvertise messages to Portals

Specified by:
setSilentOn in interface I_Monitor
See Also:
I_Monitor.setSilentOff()

setSilentOff

public void setSilentOff()
Description copied from interface: I_Monitor
Causes a Monitor to begin sending MonitorAdvertise messages to Portals

Specified by:
setSilentOff in interface I_Monitor
See Also:
I_Monitor.setSilentOff()

openMonitor

public void openMonitor()
Description copied from interface: I_Monitor
Explicitly open monitor. A Monitor cannot be used until it's opened.

Specified by:
openMonitor in interface I_Monitor
See Also:
I_Monitor.openMonitor()

closeMonitor

public void closeMonitor()
Explicitly close monitor. NB: closes the transcript file, if there is one. This file must be explicitly reopened if the monitor is reopened.

Specified by:
closeMonitor in interface I_Monitor

getStatsName

public java.lang.String getStatsName()
Description copied from interface: I_Stats
Gets the element name of this I_Stats instance. The element name is originally assigned from the attribute StstsName in the configuration file, and can be changed by this method.

Specified by:
getStatsName in interface I_Stats
See Also:
I_Stats.getStatsName()

setStatsName

public void setStatsName(java.lang.String name)
Description copied from interface: I_Stats
Assigns a name to this I_Stats instance. The assigned name becomes the tag of the element associated to this I_Stats instance on the statistics tree.

Specified by:
setStatsName in interface I_Stats
Parameters:
name - the name assigned to the I_Stats instance.
See Also:
I_Stats.setStatsName(String)

getStats

public org.w3c.dom.Element[] getStats(org.w3c.dom.Document doc,
                                      org.apache.xpath.XPath xpath)
                               throws HyperCastStatsException
Description copied from interface: I_Stats
Gets statistics information from an object which implements this interface. Statistics are arranged in a tree structure. This method has the ability to query an arbitrary subtree.

Specified by:
getStats in interface I_Stats
Parameters:
xpath - Specifies the statistic subtree to query.
doc - The document is used as a factory to create XML objects such as Nodes and Elements as needed. TODO: describe how the XML document in the doc is used.
Throws:
HyperCastStatsException - If the xpath does not specify a valid subtree.
See Also:
I_Stats.getStats(org.w3c.dom.Document, org.apache.xpath.XPath)

setStats

public org.w3c.dom.Element[] setStats(org.w3c.dom.Document doc,
                                      org.apache.xpath.XPath xpath,
                                      org.w3c.dom.Element setValue)
                               throws HyperCastStatsException
Description copied from interface: I_Stats
Sets statistics information for an object which implements this interface. Statistics are arranged in a tree structure. This method has the ability to set an arbitrary subtree of statistics.

Specified by:
setStats in interface I_Stats
Parameters:
xpath - Specifies the statistic subtree to use when updating values.
doc - The document is used as a factory to create XML objects such as Nodes and Elements as needed. TODO: describe how the XML document in the doc is used.
Throws:
HyperCastStatsException - If the xpath does not specify a valid subtree or if any part of the the subtree is read-only, or if the newValue does not conform with the expected format.
See Also:
I_Stats.setStats(org.w3c.dom.Document, org.apache.xpath.XPath, org.w3c.dom.Element)

getReadSchema

public org.w3c.dom.Element[] getReadSchema(org.w3c.dom.Document doc,
                                           org.apache.xpath.XPath xpath)
                                    throws HyperCastStatsException
Description copied from interface: I_Stats
Dynamically generates a subtree of the Readable Schema rooted at the path specified by the xpath. The Readable Schema is distrubuted among the componenets of hypercast. Each component knows how to generate its portion of the Readable Schema. If a component has sub-components, it calls getReadSchema recursively. Note that the Readable Schema is disjoint from the Writable Schema. The Readable Schema is not modeled as a subset of the Writable Schema.

Specified by:
getReadSchema in interface I_Stats
Throws:
HyperCastStatsException - If some part of the specified subtree does not correctly implement this interface method.
See Also:
I_Stats.getReadSchema(org.w3c.dom.Document, org.apache.xpath.XPath)

getWriteSchema

public org.w3c.dom.Element[] getWriteSchema(org.w3c.dom.Document doc,
                                            org.apache.xpath.XPath xpath)
                                     throws HyperCastStatsException
Description copied from interface: I_Stats
Dynamically generates a subtree of the Writable Schema rooted at the path specified by the xpath. The Writable Schema is distrubuted among the componenets of hypercast. Each component knows how to generate its portion of the Writable Schema. If a component has sub-components, it calls getWriteSchema recursively. Note that the Readable Schema is disjoint from the Writable Schema. The Readable Schema is not modeled as a subset of the Writable Schema.

Specified by:
getWriteSchema in interface I_Stats
Throws:
HyperCastStatsException - If some part of the specified subtree does not correctly implement this interface method.
See Also:
I_Stats.getWriteSchema(org.w3c.dom.Document, org.apache.xpath.XPath)

receiveMCRawMessage

public void receiveMCRawMessage(hypercast.MonitorAndControl.MCRawMessage message)
Description copied from interface: hypercast.MonitorAndControl.I_MCRaw_Callback
Receives an MC Raw message.

Specified by:
receiveMCRawMessage in interface hypercast.MonitorAndControl.I_MCRaw_Callback
Parameters:
message - Raw message that is passed to the callback

getInactivePortalIndices

public int[] getInactivePortalIndices()
Description copied from interface: I_Monitor
Get an integer array containing the indices of inactive portals.

Specified by:
getInactivePortalIndices in interface I_Monitor
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.