Package com.sun.mfwk.discovery
Provides interfaces that should be implemented by each configuration
provider.
See:
          Description
| Interface Summary | 
| MfDiscoveryInfo | A discovery client is registered in the agent (MfDiscoveryService) and notifies
 CP module that have registered themselves to provide them with discovery
 RESPONSE message that are received from the CP instances unning on the node. | 
| MfDiscoveryServiceMBean | This is the management interface explicitly defined for the "MfDiscoveryServiceMBean" standard MBean. | 
 
 
Package com.sun.mfwk.discovery Description
Provides interfaces that should be implemented by each configuration
provider.
Overview
The discovery mechanism:
 - enables the agent to detect Component Product (CP) running on
the node.
 - allows the agent to retrieve component product information:
    - to identify them (product name & product
instance)
    - to connect them (connection URI)
    - to get additional custom CP information (such as
credentials...)
    - allows to secure this additional information using
a symtric key mechanism
                        -----------
                        |         |
                        |  Agent  |
                        |         |
                        -----------
                            ^|                             
                            ||
                            |v
              ---------------------------------
              |      Multicast Channel        |
              ---------------------------------
                 ^|          ^| 
                 ||          ||
                 |v          |v
                ----        ----
                |CP|        |CP|
                ----        ----
How does it work?
- the MfDiscoveryResponder allows to join the discovery multicast
channel where it emits and receives data
- the MfDiscoveryResponder is initialized with the following data:
 * product
 * product Instance
 * product URI
 * userData (optionally encrypted using the key parameters if
userDataKey is set).
- the above information is emitted in a discovery RESPONSE multicast
packet:
 * at startup
 * every time the agent requests it 
- a discovery client is registered in the agent (MfDiscoveryService)
- it will emit a discovery DISCOVERY multicast packet everytime a cacao
CP module is registering 
  itself as an MfDiscoveryService listener
- this discovery client listens for discovery RESPONSE multicast packet.
- when some are detected, the discovery client checks their validity
and wraps them up in 
  a JMX notification that is sent to all its registered clients.
The notification type is
  set to the product name (this enables you module to filter the
notification it is interested in).
- The object received in the notification has to be casted in a 
DiscoveryInfo object on which 
  information filled in through MfDiscoveryResponder can be
retrieved.
  - Multicast channel configuration
If not defined defaults discovery multicast channel is defined as:
group:  225.225.225.1 
port 12345
Multicast port & group default values can be overriden
in the /etc/opt/SUNWmfwk/config/agent.properties 
file (Solaris), /etc/opt/sun/mfwk/config/agent.properties 
file (Linux).
NB1: the multicast channel definition is global/centralized (all CP as
well
as the agent use the values defined in this file).
NB2: changing these values at run time has no effect for product
already running
     if the port or the group is changed, it is
recommended to stop/restart all
     JES CP as wel as the Agent (or to reboot the
node).
This Multicast channel is *BOUND* on the Loopback interface
  -> Loopback interface has to have multicast enabled
    (NB: this is not the default on Linux)
  -> Packet should never go out of the box
A mechanism is provided for encrypting the userData part provided in
the MfDiscoveryResponder.
The principle is that you can encrypt these data using a key (if the
key is set, userData will 
be encrypted)
The DiscoveryClient will decode the user data *before* notifying the
listener using the key
in the /etc/opt/SUNWmfwk/security/disc.key (Solaris),
/etc/opt/sun/mfwk/security/disc.key (Linux) .
Read carefully what follows if you intend to use this mechanism
- the key you provide in the API *has to be the same* as the one
contained in the 
/etc/opt/SUNWmfwk/security/disc.key
file (Solaris)
/etc/opt/sun/mfwk/security/disc.key file (Linux)
- when you retrieve the data in the CP module using the
DiscoveryInfo.getUserData() method, the data is already
  decrypted
- if the keys do not match, the key is invalid (not generated with
/opt/SUNWmfwk/bin/discgenkey), the key file
  is not there or not readable by the agent, the discovery packet
will be dropped and ignored.
-> HEADER
magic                     byte[6]          -> "US-ASCII" encoding
hdrsize                   short 
msgtype                   char[8]          -> "US-ASCII" encoding
securityLevel             short 0,1 ,2 or 3 
                00 => no security
                01 => secure mcast userdata
                10 => secure connexion
                11 => secure mcast userdata & connexion
jesversion                short            
discversion               short            
productsize               short >0
productinstancesize       short >0
urisize                   short >=0
userdatasize              short >=0
res1size                  short    
res2size                  short                 
res3size                  short                 
res4size                  short                 
res5size                  short                 
-> PAYLOAD
product                   byte[]            -> "UTF-8" encoding
productinstance           byte[]            -> "UTF-8" encoding
uri                       byte[]            -> "UTF-8" encoding
userdata                  byte[]
res1                      byte[]
res2                      byte[]
res3                      byte[]
res4                      byte[]
res5                      byte[]