Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

## 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?

``

- On the Component product

- 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

- On the mfwk agent

- 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

- NB on security

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.

- Packet format

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES