pegasus/readme.jmpi - diff

Return to readme.jmpi CVS log

Up to [Pegasus] / pegasus

Diff for /pegasus/readme.jmpi between version 1.6 and 1.18

version 1.6, 2005/06/07 18:28:02

version 1.18, 2008/12/01 17:48:58

Line 1

//%LICENSE////////////////////////////////////////////////////////////////

// Licensed to The Open Group (TOG) under one or more contributor license

// agreements. Refer to the OpenPegasusNOTICE.txt file distributed with

// this work for additional information regarding copyright ownership.

// Each contributor licenses this file to you under the OpenPegasus Open

// Source License; you may not use this file except in compliance with the

// License.

// 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

Java Manageability Programming Interface (JMPI)

-----------------------------------------------

Author: Adrian Schuur, schuur@de.ibm.com - 30 Apr 2004 -

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

Pegasus project.

First installment

More information on JMPI's status can be found at

http://www.openpegasus.org/page.tpl?ggid=799

This installment of JMPI has been committed to the 2.4 branch.

This installment has been build and tested on Suse 9.0 with Sun's j2sdk 1.4.2_04.

Environment settings

--------------------

In order to build this support a few environment variables have to used.

In order to build the JMPI support a few environment variables have to used.

The following script has been proven useful for setting up the build and execution environment.

The following script has been proven useful for setting up the build and

You might need to adjust this to your system layout.

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_CMPI_PROVIDER_MANAGER=1

export PEGASUS_ENABLE_JMPI_PROVIDER_MANAGER=true

export PEGASUS_ENABLE_JMPI_PROVIDER_MANAGER=1

export PEGASUS_DEBUG=1

export JAVA_SDK=/usr/java/j2sdk1.4.2_04

export JAVA_SDKINC=$JAVA_SDK/include

export LD_LIBRARY_PATH=$PEGASUS_HOME/lib:$JAVA_SDK/jre/lib/i386/server:$JAVA_SDK/jre/lib/i386/native_threads:$JAVA_SDK/jre/lib/i386

export PATH=$JAVA_SDK/bin:$PATH

export CLASSPATH=$PEGASUS_ROOT/src/Pegasus/ProviderManager2/JMPI

export PATH=$PEGASUS_HOME/bin:$PATH

export PEGASUS_ROOT=$PEGASUS_HOME

export LD_ASSUME_KERNEL=2.2.5

cd $PEGASUS_HOME

There is now a new variable to determine which JVM to link with. The choices are as follows:

PEGASUS_JVM sun Sun's jvm (ex: j2sdk1.4.2_07)

PEGASUS_JVM ibm IBM's jvm (ex: IBMJava2-142)

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: This is currently listened to for Linux builds.

export JAVA_SDK=/usr/java/j2sdk1.4.2_08

export JAVA_SDKINC=${JAVA_SDK}/include

There are a couple of optional environment variables to determine how the JRE is initialized. These are

export PEGASUS_JAVA_ARCH=i386

as follows (the variable name and what JRE option that it corresponds to):

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 an example for the mandatory environment variables.

(1) The first tells Pegasus to build the Java provider manager:

export PEGASUS_ENABLE_JMPI_PROVIDER_MANAGER=true

(2) 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=ibm64 IBM's jvm for 64 bit machine.

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: As the primary maintainer of the JMPI code, IBM developers have

independently tested (and routinely test) JMPI with the following JREs.

The results of these tests are not yet reported on the OpenPegasus Nightly

Build and Test Status page.

- LINUX_IX86_GNU (Fedora Core 5), Sun JVM 1.4.2_08

- LINUX_IX86_GNU (Fedora Core 5), Gcc JVM 4.1.1 20060525

- LINUX_IX86_GNU (RHEL 5.1), Gcc JVM 4.1.2 20070626

- LINUX_X86_64_GNU (SLES 9 SP3), Sun JVM 1.4.2_15

- LINUX_X86_64_GNU (RHEL 5.0), IBM Classic VM (build 1.4.2, J2RE 1.4.2 IBM build cxz64142-20070317 (SR8) (JIT disabled))

- LINUX_ZSERIES64_GNU (RHEL 5.0), IBM J9SE VM (build 2.2, J2RE 1.4.2 IBM J9 2.2 Linux amd64-64

- ZOS_ZSERIES_IBM (z/OS 1.7), J2RE 1.4.2 IBM z/OS Persistent Reusable VM build cm142-20060824 (SR6)

- ZOS_ZSERIES_IBM (z/OS 1.8), J2RE 1.4.2 IBM z/OS Persistent Reusable VM build cm142-20060824 (SR6)

- ZOS_ZSERIES_IBM (z/OS 1.9), J2RE 1.4.2 IBM z/OS Persistent Reusable VM build cm142-20060824 (SR6)

- WIN32_IX86_MSVC (Microsoft Windows XP Professional), Sun JVM 1.6.0_02

(3, 4) 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 in this example we are using Sun's JRE, we

point to Sun's paths:

export JAVA_SDK=/usr/java/j2sdk1.4.2_08

export JAVA_SDKINC=${JAVA_SDK}/include

(5) The fifth variable defines the Java architecture of the JMV:

export PEGASUS_JAVA_ARCH=i386

(6) 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 in this

example:

ls ${JAVA_SDK}/jre/lib/${PEGASUS_JAVA_ARCH}/${PEGASUS_JAVA_TYPE}

should show you libjvm.so for Sun's JRE.

(7) 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}

(8) 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}

(9) 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.

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 environment variable that tells the JVM to output more debugging information. The variable name

There is a new optional environment variable that tells the JVM to output more

is called PEGASUS_JMPI_VERBOSE. An example usage is as follows:

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.

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

When using this script, place a copy of this script above your PEGASUS_HOME directory.

When using this script, place a copy of this script above your PEGASUS_HOME

"cd" to PEGASUS_HOME, and issue ". ../setJPeg". Then do a normal make.

directory, "cd" to PEGASUS_HOME, and issue ". ./setJPeg". Then do a normal

make.

This installment has a number of restrictios:

Known restrictions

------------------

The provider interfaces follow the SNIA OpenWBEM APIs

This installment has the following restrictions:

Only Instance and Association providers are supported at the moment.

SetProperty and GetProperty CIM operations will crash cimserver

Jar support is not yet implemented - all classes must be accessable via the CLASSPATH variabe.

The Makefiles are not yet Pegasus conforming.

cimmofl must be used for provider registration.

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

Unloading of idle providers is not supported and Java will increase the

memory footprint.

Java 1.5 is not currently supported.

poststarttests

Gcj on 31 bit machines is only supported using gcc version 4.1.1 or later.

Gcj on 64 bit machines is not supported. Bugs 5913, 5921, and 5963 have

been written to address that issue. Instead, you should use the Sun ported

JVM from the Blackdown project located at www.blackdown.org.

This installment has a set of tests modelled after wetest/static. All tests work properly except

the Property tests. I had to modify "diff" to "diff -w", why that is needed I do not understand.

Level of test coverage

----------------------

Building poststarttests:

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.

cd to .../src/Pegasus/ProviderManager2/JMPI/org/pegasus/jmpi/tests/Load

Issue "make"

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

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, we

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 already been built 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.

Running poststarttests:

Next, run the tests.

cd to .../src/Pegasus/ProviderManager2/JMPI/org/pegasus/jmpi/tests

cd to ${PEGASUS_HOME}/src/Pegasus/ProviderManager2/JMPI/

Issue "find -name "*.rsp" -exec rm {} \;" to clean up *.rsp files

Issue "find -name \*.rsp -exec rm {} \;" to clean up *.rsp files from failed tests.

Issue "make poststarttests"

Samples

-------

The provider used for posstarttest,

There are four sample providers located in

.../JMPI/org/pegasus/jmpi/test/JMPI_TestPropertyTypes/JMPI_TestPropertyTest.java is a working

${PEGASUS_HOME}/src/Pegasus/ProviderManager2/JMPI/org/pegasus/jmpi/tests/Providers/

example of how to code an JMPI tyle instance provider.

This directors also constains the required Makefile.

.../JMPI/org/pegasus/jmpi/sample contains more samples, one of which is an incomplete CIMClient

Associations/

sample.

Notice that all provider classes must be accessibe via the CASSPATH environment setting.

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 P_ProviderModule has a special format.

JMPI providers are registered as usual. The Location property in

The format is: <jar-file-name>:<provider-class-name>

PG_ProviderModule has a special format. The format is:

<jar-file-name>:<provider-class-name>

Although jar support is not yet working correctly, this format must be used. You should use cimmofl

JMPI providers now fall into two groups.

for registration untill cimmof is prepared for JMPI.

(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 = "JMPI_TestPropertyTypesModule";

Name = "JMPIInstanceProviderModule";

Location = "JMPI_TestPropertyTypes.jar:"

Location = "JMPIInstanceProvider.jar:Instances/JMPIInstanceProvider";

"org/pegasus/jmpi/tests/JMPI_TestPropertyTypes/JMPI_TestPropertyTypes";

Vendor = "OpenPegasus";

Vendor = "Pegasus Community";

Version = "2.0.0";

InterfaceType = "JMPI";

InterfaceVersion = "1.0.0";

};

(2) New style providers use:

InterfaceType = "JMPIExperimental"

and:

InterfaceVersion = "0.0.1";

Bug reports

instance of PG_ProviderModule

{

Use normal Pegasus bugzilla procedures to report malfunctions.

Name = "JMPIExpInstanceProviderModule";

Location = "JMPIExpInstanceProvider.jar:Instances/JMPIExpInstanceProvider";

Vendor = "OpenPegasus";

Version = "2.0.0";

InterfaceType = "JMPIExperimental";

InterfaceVersion = "0.0.1";

};

Regards, Adrian Schuur.

Bug reports

-----------

Use normal Pegasus bugzilla procedures to report malfunctions.

Legend:

Removed from v.1.6
changed lines
	Added in v.1.18

No CVS admin address has been configured