Full Example User's Guide :
---------------------------

I - Description :
----------------
This example is written in order to demonstrate a significant part of the capabilities of the SDK and JESMF agent.

This example is composed of two component products :
	- The STORE Component Product that simulates a very simple database server which offers the functionnality of storing and retrieving string {key,value} pairs.
	- The MSG Component Product that simulates a very simple logging server which offers the functionnality of logging messages into a file.

The STORE Component Product is an RMI server which exposes 3 services :
    public String SEARCH(String key) throws RemoteException;
    public String MODIFY(String key, String value) throws RemoteException;
    public String REMOVE(String key) throws RemoteException;

The MSG Component Product is an RMI server which exposes 2 services :
     public void LOG(String message) throws RemoteException;
     public void MSG(String message) throws RemoteException;

The STORE Component Product is using the LOG service of the MSG Component service.

The both component products have been instrumented using the MFWK SDK.:

- The STORE CP exposes transaction metrics for the 3 services it offers.
  It also exposes resource metrics for the STORE resource (that represents the logical resource that stores the {key,value} pairs) and external resource metrics for the MSG external resource (that represents the logical association we have between the 2 component products).

- The STORE Component product can be run in secure or unsecure mode.

- The MSG CP exposes transaction metrics for the 2 services if offers.


Note : The RMI connection is used only for the services and not for the monitoring.


II - Layout 
-----------

1/ Under BASEDIR/opt/SUNWmfwk/examples/full/storeCP/
    The following classes are used to build the STORE component product :
	STORE_SRV.java is the RMI interface definition of the STORE server.
	STORE_SRVImpl.java is the main implementation of the STORE server.
	STORE.java is the implementation of the STORE resource.
	MSG_SRV.java is the implementation of the MSG external resource.
	STORE_CLIENT.java is a simple test client to use the services offered by the STORE_SRV.

    The following classes are used to build the CACAO STORE module :
	STORE_SRVModule.java  the CACAO module implementation.

    The CACAO STORE deployment descriptor is com.sun.mfwk.storeCP_module.xml

2/ Under BASEDIR/opt/SUNWmfwk/examples/full/msgCP/
    The following classes are used to build the MSG component product :
        MSG_SRV.java is the RMI interface definition of the MSG server.
        MSG_SRVImpl.java is the main implementation of the MSG server.

    The following classes are used to build the CACAO MSG module :
        MSG_SRVModule.java  the CACAO module implementation.

    The CACAO MSG deployment descriptor is com.sun.mfwk.msgCP_module.xml


III - Deployment :
-----------------

1/ To compile this example, you need to install previously:
	-JDMK5.1 software
	-CACAO software

2/ To compile this example :
Specify the following jar files in your classpath:
  jdmk and jmx jars files:  jdmkrt.jar jmxremote.jar jmxremote_optional.jar jmxri.jar 
  cacao jar file : cacao_cacao.jar
  MFWK SDK jar file : mfwk_sdk.jar
  MFWK J2EE management jar file : javax77.jar
  
If all packages have been installed in default root directory, your classpath should be :
# export CLASSPATH=BASEDIR/opt/SUNWjdmk/5.1/lib/jmx.jar:BASEDIR/opt/SUNWjdmk/5.1/lib/jmxremote.jar:BASEDIR/opt/SUNWjdmk/5.1/lib/jmxremote_optional.jar:BASEDIR/opt/SUNWjdmk/5.1/lib/jdmkrt.jar:BASEDIR/opt/SUNWcacao/lib/cacao_cacao.jar:BASEDIR/opt/SUNWmfwk/lib/mfwk_sdk.jar:BASEDIR/opt/SUNWmfwk/lib/javax77.jar

Specify a correct JAVA_HOME. For example:
# export JAVA_HOME=/usr/jdk/jdk1.5.0
# export PATH=$JAVA_HOME:$PATH

Then invoke javac command :
# cd BASEDIR/opt/SUNWmfwk/examples/full
# javac -d . -classpath <classpath> msgCP/*.java storeCP/*.java

Then build your modules jars files :
# jar -cvf msgCP/msgCP_module.jar com/sun/mfwk/examples/msgCP/MSG_SRVModule.class
# jar -cvf storeCP/storeCP_module.jar com/sun/mfwk/examples/storeCP/STORE_SRVModule.class

3/ To deploy your CACAO modules :
copy modules deployment descriptors into CACAO modules directory :
# cp msgCP/com.sun.mfwk.msgCP_module.xml /etc/opt/SUNWcacao/modules/
# cp storeCP/com.sun.mfwk.storeCP_module.xml /etc/opt/SUNWcacao/modules/



IV - Run :
---------

1/ Start CACAO :
- In order to have an html access on the agent, modify the CACAO properties file /etc/opt/SUNWcacao/cacao.properties to add the following line :
	com.sun.cacao.insecure.html.adaptor.port=8082
- You can also add the following property to use jconsole (gives a better view than the HTML adaptor):
        com.sun.cacao.insecure.rmi.connector.port=2002
        com.sun.cacao.insecure.rmi.connector.uri=jmxrmi
- set your environement variable JAVA_HOME to point to a Java 1.4.2_03 or higher:
# export JAVA_HOME=/usr/jdk/jdk1.5.0
# export PATH=$JAVA_HOME:$PATH

# cd BASEDIR/opt/SUNWcacao/bin
# ./cacaoadm restart

2/ Start the MSG Component product :

- Set your classpath :
Specify the following jar files in your classpath:
  jdmk and jmx jars files:  jdmkrt.jar jmxremote.jar jmxremote_optional.jar jmxri.jar 
  cacao jar file : cacao_cacao.jar
  MFWK SDK jar file : mfwk_sdk.jar
  MFWK J2EE management jar file : javax77.jar
Also add the path to the directory where you have compiled this example to your classpath.
If you have run javac command from the current directory then your classpath should be :

# export CLASSPATH=BASEDIR/opt/SUNWmfwk/examples/full:BASEDIR/opt/SUNWjdmk/5.1/lib/jmx.jar:BASEDIR/opt/SUNWjdmk/5.1/lib/jmxremote.jar:BASEDIR/opt/SUNWjdmk/5.1/lib/jmxremote_optional.jar:BASEDIR/opt/SUNWjdmk/5.1/lib/jdmkrt.jar:BASEDIR/opt/SUNWcacao/lib/cacao_cacao.jar:BASEDIR/opt/SUNWmfwk/lib/mfwk_sdk.jar:BASEDIR/opt/SUNWmfwk/lib/javax77.jar

# rmiregistry &

# java com.sun.mfwk.examples.msgCP.MSG_SRVImpl

3/ Start the STORE Component product :

- Set your environment to use jdk1.5 JAVA version.
# export JAVA_HOME=/usr/jdk/jdk1.5.0
# export PATH=$JAVA_HOME:$PATH

- Set your classpath :
Specify the following jar files in your classpath:
  jdmk and jmx jars files:  jdmkrt.jar jmxremote.jar jmxremote_optional.jar jmxri.jar 
  cacao jar file : cacao_cacao.jar
  MFWK SDK jar file : mfwk_sdk.jar
  MFWK J2EE management jar file : javax77.jar
Also add the path to the directory where you have compiled this example to your classpath.
If you have run javac command from the current directory then your classpath should be :

# export CLASSPATH=BASEDIR/opt/SUNWmfwk/examples/full:BASEDIR/opt/SUNWjdmk/5.1/lib/jmx.jar:BASEDIR/opt/SUNWjdmk/5.1/lib/jmxremote.jar:BASEDIR/opt/SUNWjdmk/5.1/lib/jmxremote_optional.jar:BASEDIR/opt/SUNWjdmk/5.1/lib/jdmkrt.jar:BASEDIR/opt/SUNWcacao/lib/cacao_cacao.jar:BASEDIR/opt/SUNWmfwk/lib/mfwk_sdk.jar:BASEDIR/opt/SUNWmfwk/lib/javax77.jar

- for UNSECURE mode, run:
# java com.sun.mfwk.examples.storeCP.STORE_SRVImpl

- for SECURE mode, you need first to generate the security materials for the STORE component product.
  This is done by running the cpgenkey command. The synopsis for the cpgenkey is:
  # BASEDIR/opt/SUNWmfwk/bin/cpgenkey -n <name> -p <passwd file>
    -n <name> : string which identify the component product
    -p <passwd file> : path to a file containing the password which will be used
                       to protect the keystore. The file must exist.
  Ex. for the STORE component product:
    # echo "storepass" > /etc/opt/SUNWmfwk/security/passwd.storeCP
    # BASEDIR/opt/SUNWmfwk/bin/cpgenkey -n StoreCP -p /etc/opt/SUNWmfwk/security/passwd.storeCP
    The /etc/opt/SUNWmfwk/security/keystore.StoreCP keystore will be created.
    and protected by the "storepass" password.

    Then you can run the component product in secure mode:
    # run java com.sun.mfwk.examples.storeCP.STORE_SRVImpl -k /etc/opt/SUNWmfwk/security/keystore.StoreCP -f /etc/opt/SUNWmfwk/security/passwd.storeCP
    -k to specify the path to the keystore of the STORE component product.
    -f to specify the path to the file containing the keystore's password.

4/ To use the STORE server and make the metrics interesting :

- Set your environment to use jdk1.5 JAVA version.
# export JAVA_HOME=/usr/jdk/jdk1.5.0
# export PATH=$JAVA_HOME:$PATH

- Set your classpath :
Specify the following jar files in your classpath:
  jdmk and jmx jars files:  jdmkrt.jar jmxremote.jar jmxremote_optional.jar jmxri.jar 
  cacao jar file : cacao_cacao.jar
  MFWK SDK jar file : mfwk_sdk.jar
  MFWK J2EE management jar file : javax77.jar
Also add the path to the directory where you have compiled this example to your classpath.
If you have run javac command from the current directory then your classpath should be :

# CLASSPATH=BASEDIR/opt/SUNWmfwk/examples/full:BASEDIR/opt/SUNWjdmk/5.1/lib/jmx.jar:BASEDIR/opt/SUNWjdmk/5.1/lib/jmxremote.jar:BASEDIR/opt/SUNWjdmk/5.1/lib/jmxremote_optional.jar:BASEDIR/opt/SUNWjdmk/5.1/lib/jdmkrt.jar:BASEDIR/opt/SUNWcacao/lib/cacao_cacao.jar:BASEDIR/opt/SUNWmfwk/lib/mfwk_sdk.jar:BASEDIR/opt/SUNWmfwk/lib/javax77.jar
 
# java com.sun.mfwk.examples.storeCP.STORE_CLIENT -t <REMOVE|MODIFY|SEARCH> -k key [-v value]

This command enables you to invoke services offered by the STORE server and so forces the instrumentation metrics to change.


V - Test :
---------

1/ Connect to the STORE CP :
use html adaptor on port 8083

2/ Connect to the MSG CP :
use html adaptor on port 8084

3/ Connect to the Agent :
use html adaptor on port 8082

4/ Use STORE_CLIENT to make instrumentation metrics changed and check the values in the html adaptors.

5/ if you want to change the Availability status of the STORE services. Stop the MSG CP then the Availability status changes to the DEGRADED state. If you restart the MSG CP then the Availability status goes back to the AVAIL state.

6/ Another way to test is to use jconsole (the Java 5.0 console) to access the CIB objects:

export JAVA_HOME=/usr/jdk/jdk1.5.0
export PATH=$JAVA_HOME:$PATH
export CLASSPATH=BASEDIR/opt/SUNWmfwk/examples/full:BASEDIR/opt/SUNWjdmk/5.1/lib/jmx.jar:BASEDIR/opt/SUNWjdmk/5.1/lib/jmxremote.jar:BASEDIR/opt/SUNWjdmk/5.1/lib/jmxremote_optional.jar:BASEDIR/opt/SUNWjdmk/5.1/lib/jdmkrt.jar:BASEDIR/opt/SUNWcacao/lib/cacao_cacao.jar:BASEDIR/opt/SUNWmfwk/lib/mfwk_sdk.jar:BASEDIR/opt/SUNWmfwk/lib/javax77.jar:/usr/lang/JAVA/jdk1.5/lib/jconsole.jar
export DISPLAY=<your display here>

# Then launch jconsole (as root):
/usr/jdk/jdk1.5.0/bin/java sun.tools.jconsole.JConsole "service:jmx:cacao-jmxmp://localhost;wellknown=true;username=root"

# After the connection is established, go to the 'MBeans' tab. You should
# see the 'com.sun.mfwk.storeCP_module' mbeans.



