Return to readme.jmpi CVS log

Up to [Pegasus] / pegasus

BUG#: 5938
TITLE: JMPI add client/server choice for libjvm.so

DESCRIPTION:
Adding PEGASUS_JAVA_TYPE.

//%2006////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2000, 2001, 2002 BMC Software; Hewlett-Packard Development
// Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems.
// Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L.P.;
// IBM Corp.; EMC Corporation, The Open Group.
// Copyright (c) 2004 BMC Software; Hewlett-Packard Development Company, L.P.;
// IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.
// Copyright (c) 2005 Hewlett-Packard Development Company, L.P.; IBM Corp.;
// EMC Corporation; VERITAS Software Corporation; The Open Group.
// Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
// EMC Corporation; Symantec Corporation; The Open Group.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to
// deal in the Software without restriction, including without limitation the
// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
// sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
// ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
// "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
// LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
// PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
// ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
// WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
//
//==============================================================================

Java Manageability Programming Interface (JMPI)
-----------------------------------------------

JMPI is a bridge between clients and providers written in Java and the Open
Pegasus project.

More information on JMPI's status can be found at
   http://www.openpegasus.org/page.tpl?ggid=799


Environment settings
--------------------

In order to build this support a few environment variables have to used.
The following script has been proven useful for setting up the build and execution environment.
You might need to adjust this to your system layout.

   an example setJPeg script file:
   export PEGASUS_HOME=`pwd`
   export PEGASUS_ROOT=${PEGASUS_HOME}
   export PEGASUS_PLATFORM=LINUX_IX86_GNU
   export PEGASUS_ENABLE_JMPI_PROVIDER_MANAGER=true
   export PEGASUS_JVM=sun
   export JAVA_SDK=/usr/java/j2sdk1.4.2_08
   export JAVA_SDKINC=${JAVA_SDK}/include
   export PEGASUS_JAVA_ARCH=i386
   export PEGASUS_JAVA_TYPE=client
   export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${JAVA_SDK}/jre/lib/${PEGASUS_JAVA_ARCH}/server:${JAVA_SDK}/jre/lib/${PEGASUS_JAVA_ARCH}/native_threads:${JAVA_SDK}/jre/lib/${PEGASUS_JAVA_ARCH}
   export PATH=${JAVA_SDK}/bin/:${PEGASUS_HOME}/bin:${PATH}
   export CLASSPATH=${CLASSPATH}:${PEGASUS_HOME}/lib/JMPIImpl.jar

Lets walk through the manditory environment variables.  The first tells Pegasus to build the
Java provider manager.
   export PEGASUS_ENABLE_JMPI_PROVIDER_MANAGER=true

The second says which JRE to use.  The choices are as follows:
   export PEGASUS_JVM=gcj     Gnu's jvm (ex: gcj (GCC) 4.1.1 20061011 (Red Hat 4.1.1-30))
   export PEGASUS_JVM=sun       Sun's jvm (ex: j2sdk1.4.2_07)
   export PEGASUS_JVM=ibm       IBM's jvm (ex: IBMJava2-142)
   export PEGASUS_JVM=bea       Suse's IBM jvm (ex: BEAJava2-1.4.2)
So, pick one and export that variable to the environment.  For example,
   export PEGASUS_JVM=sun
NOTE: The gcj and sun options were the only tested JVMs.
NOTE: gcj is only supported using gcc version 4.1.1 or later.

The third and fourth say where the JRE libraries and header files are located.  This may or may not
be necessary depending upon the compiler's default search paths.
Since we are using Sun's JRE, point to Sun's paths.
   export JAVA_SDK=/usr/java/j2sdk1.4.2_08
   export JAVA_SDKINC=${JAVA_SDK}/include

The fifth variable defines the Java architecture of the JMV
   export PEGASUS_JAVA_ARCH=i386

The sixth variable defines which version of the jvm library to link to (the
client or the server).
   export PEGASUS_JAVA_TYPE=client

As a test to make sure your environment variables are correct
   ls ${JAVA_SDK}/jre/lib/${PEGASUS_JAVA_ARCH}/${PEGASUS_JAVA_TYPE}
should show you libjvm.so for Sun's JRE.

The seventh may be necessary to tell the linker where to load the JRE libraries.
   export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${JAVA_SDK}/jre/lib/${PEGASUS_JAVA_ARCH}/server:${JAVA_SDK}/jre/lib/${PEGASUS_JAVA_ARCH}/native_threads:${JAVA_SDK}/jre/lib/${PEGASUS_JAVA_ARCH}

The eighth one may be necessary to get the JVM's executable files into the PATH.
   export PATH=${JAVA_SDK}/bin/:${PEGASUS_HOME}/bin:${PATH}

The nineth tells the JRE to include JMPI's Java classes.
   export CLASSPATH=${CLASSPATH}:${PEGASUS_HOME}/lib/JMPIImpl.jar

There are a couple of optional environment variables to determine how the JRE is initialized.  These are
as follows (the variable name and what JRE option that it corresponds to):

PEGASUS_JMPI_MAX_HEAP               -Xmx
PEGASUS_JMPI_INITIAL_HEAP           -Xms
PEGASUS_JMPI_JAVA_THREAD_STACK_SIZE -Xss

So, for example, you would perform the following if you want to change the maximum heap size to 128 megabytes.

export PEGASUS_JMPI_MAX_HEAP=128m

There is a new optional environment variable that tells the JVM to output more debugging information.  The variable name
is called PEGASUS_JMPI_VERBOSE.  An example usage is as follows:

export PEGASUS_JMPI_VERBOSE="jni,class"

This will tell the JVM to output debug information on the JNI layer and class loading.

When using this script, place a copy of this script above your PEGASUS_HOME directory.
"cd" to PEGASUS_HOME, and issue ". ./setJPeg". Then do a normal make.


Known restrictions
------------------

This installment has the following restrictios:

   Unloading of idle providers is not supported and Java will increase the memory footprint.
   Java 1.5 is not currently supported.


Level of coverage
-----------------

All interfaces to a provider have a sample provider written for them and are part of the
testcases.  All main CIM java classes have testcases written for them as well.


Outstanding issues
------------------

Java documentation needs to be written for the classes and methods within JMPI.


Testing
-------

This installment has a set of tests located under src/Pegasus/ProviderManager2/JMPI/org/pegasus/jmpi/tests/

   Static/

      These tests have been modelled after wetest/static.
      For the tests, I had to modify "diff" to "diff -w", why that is needed I do not understand.

   Providers/

      These tests implement the many variants of provider interfaces.

   Client/

      These tests test out the client code and various Java classes.


Running the tests
-----------------

Tests are run with the following process.
If the repository has not been built before then issue the following:

   cd to ${PEGASUS_HOME}/src/Pegasus/ProviderManager2/JMPI/
   Issue "make repository"

   This will load a schema to the repository and register the provider.

Next, run the tests.

   cd to ${PEGASUS_HOME}/src/Pegasus/ProviderManager2/JMPI/
   Issue "find -name \*.rsp -exec rm {} \;" to clean up *.rsp files from failed tests.
   Issue "make poststarttests"


Samples
-------

 There are four sample providers located in
   ${PEGASUS_HOME}/src/Pegasus/ProviderManager2/JMPI/org/pegasus/jmpi/tests/Providers/

   Associations/

      This provider implements an association provider.

   Instances/

      This provider implements an instance provider.

   Indications/

      This provider implements an indication provider.

   Properties/

      This provider implements a property provider.

   There is also sample Java code that deals with CIM classes that is located in
   ${PEGASUS_HOME}/src/Pegasus/ProviderManager2/JMPI/org/pegasus/jmpi/tests/Client/


Provider Registration
---------------------

   JMPI providers are registered as usual. The Location property in PG_ProviderModule has a special format.
        The format is: <jar-file-name>:<provider-class-name>

   JMPI providers now fall into two groups.
   1) Legacy providers use:
      InterfaceType = "JMPI"
   and use one of the 3 following based on existing JMPI samples:
      InterfaceVersion = "1.0.0";
      InterfaceVersion = "2.0.0";
      InterfaceVersion = "2.2.0";
   Note that there is no difference in behavior in the three versions.

   instance of PG_ProviderModule
   {
      Name             = "JMPIInstanceProviderModule";
      Location         = "JMPIInstanceProvider.jar:Instances/JMPIInstanceProvider";
      Vendor           = "OpenPegasus";
      Version          = "2.0.0";
      InterfaceType    = "JMPI";
      InterfaceVersion = "1.0.0";
   };

   2) New style providers use:
      InterfaceType = "JMPIExperimental"
   and:
      InterfaceVersion = "0.0.1";

   instance of PG_ProviderModule
   {
      Name             = "JMPIExpInstanceProviderModule";
      Location         = "JMPIExpInstanceProvider.jar:Instances/JMPIExpInstanceProvider";
      Vendor           = "OpenPegasus";
      Version          = "2.0.0";
      InterfaceType    = "JMPIExperimental";
      InterfaceVersion = "0.0.1";
   };


Bug reports
-----------

   Use normal Pegasus bugzilla procedures to report malfunctions.