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.
 

Class Summary
MfDiscoveryActualClient  
MfDiscoveryActualResponder  
MfDiscoveryResponder Allows to implement the discovery service on the Component Product side.
MfDiscoveryService The "MfDiscoveryService" MBean is responsible to send a DISCOVERY PDU everytime a CP module registers to become a notification listener.
MfTypeIOUtil  
 

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.



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[]