
  #######################################################################
  # Java ES Monitoring Framework OSS/J Web Services Adaptor README File #
  #######################################################################


1. Introduction
---------------

This version of JESMF includes a preview for the OSS/J Web Services Adaptor
feature.

The interfaces exposing this feature are classed as "unstable" meaning 
(1) they can change in an incompatible way (including being removed totally) in a future release
and (2) that they are delivered in order to give an early access for customers protyping this type of 
web service--they must not be used in production systems.

2. Definition
-------------

The purpose of the WS Adaptor is to provide a Web Services access to the OSS/J
job factories of JESMF. This allows to handle jobs remotely, in a firewall
friendly way. This also allows better interoperability for job handling: no 
specific language/platform is required to access the OSS/J layer.

The WS Adaptor exports the OSS/J interfaces as Web Services interfaces.
Once a call is done to the Adaptor, it is translated into a call to the
matching OSS/J job factory.

Currently only a part of the methods of the threshold factory interface
(JVTThresholdMonitorSession) is implemented.

There is also a publish/subsrcibe mechanism that allows to receive the alarm
events generated after a threshold job has been created.

3. Interfaces
-------------

The current exposed WSDL files exported by the WS Adaptor are located in the
xml directory:

- ThresholdMonitor.wsdl: WS interface mapping the JVTThresholdMonitorSession
(partially implemented)
- AlarmMonitorNotifServer.wsdl: WS interface for subsrcibing/unsubscribing to
alarm events

A client that has subscribed to the alarm events may receive them through the
Web Service defined in:

- AlarmMonitorNotifClient.wsdl

All the WSDL files import XML shemas (xsd files) that are also located under the
xml directory.

3. Enable the WS Adaptor
------------------------

The Adaptor is implemented with JAXWS 2.0 that mandates a 1.5 VM or higher.

When the agent is running in a 1.5 or higher VM, the following properties are
relevant in the mfwk.properties property file for JESMF:

- mfwk.agent.cms.ws.adaptor.enable: set to true to turn the Adaptor on
(default value is false)
- mfwk.agent.cms.ws.adaptor.port: set the HTTP TCP port the Adaptor is listening
to (default value is 9876)

Note: to use a 1.5 or higher VM, change the java.home property in the
cacao.properties property file of CACAO.

4. Run the example client console
---------------------------------

As an example, a simple WS console has been written to demonstrate the OSS/J WS
feature. This console supports all the features that are covered by the current
WSDL interfaces implementation in the Adaptor.

The console is a Java GUI program and may be launched using the script located
in the script directory.

Please refer to this script for usage:

ksh script/ossj_ws_console.ksh -h

5. Console usage example
------------------------

The following scenario will create a threshold job that will trigger a new
alarm event:

+ Create the job:

- In 'Threshold' main  tab, 'Creation' tab put:
  - name for the job: 'testjob'
- Click on next
- Choose a CMM objects containing 'type=CMM_LinuxEthernetPortStats' or
  'type=CMM_SolarisEthernetPortStats' depending on your OS type. This is the
  object that holds statistics for an ethernet interface of the machine. We
  choose this object as an example, because it is always instanciated, and you
  do not need an instrumented product to be started for the test. It is also a
  good object, as its 'PacketsReceived' attribute always evolve as there are
  always packets arriving to the ethernet card.
- In the new 'Choice of attribute' dialog box, choose the 'PacketsReceived'
  attribute.
- In the new 'Threshold definition' dialog box, set the value to 0 (you always
  have some packets received so the threshold will cross immediately) then click
  ok ('Threshold definition' dialog box is closed).
- Click ok ('Choice of attribute' dialog box is closed)
- Click next
- Let the schedule as it is by default (job will start immediatly and run
  forever)
- Click finish
- The sum up of your choices is displayed, click ok.
- The job is created

+ See the new alarm event:

- Click on the 'Alarm' main tab
- In the 'Alarm Events' tab, you should see a NotifyNewAlarmEvent that has just
  been triggered.
- Select it
- Click Show to display more detailed information about the just received event
