readme.jmpi

   1 //%LICENSE////////////////////////////////////////////////////////////////
   2 //
   3 // Licensed to The Open Group (TOG) under one or more contributor license
   4 // agreements.  Refer to the OpenPegasusNOTICE.txt file distributed with
   5 // this work for additional information regarding copyright ownership.
   6 // Each contributor licenses this file to you under the OpenPegasus Open
   7 // Source License; you may not use this file except in compliance with the
   8 // License.
   9 //
  10 // Permission is hereby granted, free of charge, to any person obtaining a
  11 // copy of this software and associated documentation files (the "Software"),
  12 // to deal in the Software without restriction, including without limitation
  13 // the rights to use, copy, modify, merge, publish, distribute, sublicense,
  14 // and/or sell copies of the Software, and to permit persons to whom the
  15 // Software is furnished to do so, subject to the following conditions:
  16 //
  17 // The above copyright notice and this permission notice shall be included
  18 // in all copies or substantial portions of the Software.
  19 //
  20 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  21 // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  22 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  23 // IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  24 // CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  25 // TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  26 // SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  27 //
  28 //////////////////////////////////////////////////////////////////////////
  29
  30 Java Manageability Programming Interface (JMPI)
  31 -----------------------------------------------
  32
  33 JMPI is a bridge between clients and providers written in Java and the Open
  34 Pegasus project.
  35
  36 More information on JMPI's status can be found at
  37    http://www.openpegasus.org/page.tpl?ggid=799
  38
  39
  40 Environment settings
  41 --------------------
  42
  43 In order to build the JMPI support a few environment variables have to used.
  44 The following script has been proven useful for setting up the build and
  45 execution environment. You might need to adjust this to your system layout.
  46
  47    An example setJPeg script file:
  48    export PEGASUS_HOME=`pwd`
  49    export PEGASUS_ROOT=${PEGASUS_HOME}
  50    export PEGASUS_PLATFORM=LINUX_IX86_GNU
  51    export PEGASUS_ENABLE_JMPI_PROVIDER_MANAGER=true
  52    export PEGASUS_JVM=sun
  53    export JAVA_SDK=/usr/java/j2sdk1.4.2_08
  54    export JAVA_SDKINC=${JAVA_SDK}/include
  55    export PEGASUS_JAVA_ARCH=i386
  56    export PEGASUS_JAVA_TYPE=client
  57    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}
  58    export PATH=${JAVA_SDK}/bin/:${PEGASUS_HOME}/bin:${PATH}
  59    export CLASSPATH=${CLASSPATH}:${PEGASUS_HOME}/lib/JMPIImpl.jar
  60
  61 Lets walk through an example for the mandatory environment variables.
  62
  63 (1) The first tells Pegasus to build the Java provider manager:
  64       export PEGASUS_ENABLE_JMPI_PROVIDER_MANAGER=true
  65
  66 (2) The second says which JRE to use.  The choices are as follows:
  67       export PEGASUS_JVM=gcj    Gnu's jvm (ex: gcj (GCC) 4.1.1 20061011 (Red Hat 4.1.1-30))
  68       export PEGASUS_JVM=sun    Sun's jvm (ex: j2sdk1.4.2_07)
  69       export PEGASUS_JVM=ibm    IBM's jvm (ex: IBMJava2-142)
  70       export PEGASUS_JVM=ibm64  IBM's jvm for 64 bit machine.
  71       export PEGASUS_JVM=bea    Suse's IBM jvm (ex: BEAJava2-1.4.2)
  72     So, pick one and export that variable to the environment.  For example:
  73       export PEGASUS_JVM=sun
  74     NOTE: As the primary maintainer of the JMPI code, IBM developers have
  75     independently tested (and routinely test) JMPI with the following JREs.
  76     The results of these tests are not yet reported on the OpenPegasus Nightly
  77     Build and Test Status page.
  78       - LINUX_IX86_GNU (Fedora Core 5), Sun JVM 1.4.2_08
  79       - LINUX_IX86_GNU (Fedora Core 5), Gcc JVM 4.1.1 20060525
  80       - LINUX_IX86_GNU (RHEL 5.1), Gcc JVM 4.1.2 20070626
  81       - LINUX_X86_64_GNU (SLES 9 SP3), Sun JVM 1.4.2_15
  82       - 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))
  83       - LINUX_ZSERIES64_GNU (RHEL 5.0), IBM J9SE VM (build 2.2, J2RE 1.4.2 IBM J9 2.2 Linux amd64-64
  84       - ZOS_ZSERIES_IBM (z/OS 1.7), J2RE 1.4.2 IBM z/OS Persistent Reusable VM build cm142-20060824 (SR6)
  85       - ZOS_ZSERIES_IBM (z/OS 1.8), J2RE 1.4.2 IBM z/OS Persistent Reusable VM build cm142-20060824 (SR6)
  86       - ZOS_ZSERIES_IBM (z/OS 1.9), J2RE 1.4.2 IBM z/OS Persistent Reusable VM build cm142-20060824 (SR6)
  87       - WIN32_IX86_MSVC (Microsoft Windows XP Professional), Sun JVM 1.6.0_02
  88
  89 (3, 4) The third and fourth say where the JRE libraries and header files are
  90     located. This may or may not be necessary depending upon the compiler's
  91     default search paths. Since in this example we are using Sun's JRE, we
  92     point to Sun's paths:
  93       export JAVA_SDK=/usr/java/j2sdk1.4.2_08
  94       export JAVA_SDKINC=${JAVA_SDK}/include
  95
  96 (5) The fifth variable defines the Java architecture of the JMV:
  97       export PEGASUS_JAVA_ARCH=i386
  98
  99 (6) The sixth variable defines which version of the jvm library to link to
 100     (the client or the server):
 101       export PEGASUS_JAVA_TYPE=client
 102
 103     As a test to make sure your environment variables are correct in this
 104     example:
 105       ls ${JAVA_SDK}/jre/lib/${PEGASUS_JAVA_ARCH}/${PEGASUS_JAVA_TYPE}
 106     should show you libjvm.so for Sun's JRE.
 107
 108 (7) The seventh may be necessary to tell the linker where to load the JRE
 109     libraries:
 110       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}
 111
 112 (8) The eighth one may be necessary to get the JVM's executable files into the
 113     PATH:
 114       export PATH=${JAVA_SDK}/bin/:${PEGASUS_HOME}/bin:${PATH}
 115
 116 (9) The nineth tells the JRE to include JMPI's Java classes:
 117       export CLASSPATH=${CLASSPATH}:${PEGASUS_HOME}/lib/JMPIImpl.jar
 118
 119 There are a couple of optional environment variables to determine how the JRE
 120 is initialized.  These are as follows (the variable name and what JRE option
 121 that it corresponds to):
 122
 123   PEGASUS_JMPI_MAX_HEAP               -Xmx
 124   PEGASUS_JMPI_INITIAL_HEAP           -Xms
 125   PEGASUS_JMPI_JAVA_THREAD_STACK_SIZE -Xss
 126
 127 So, for example, you would perform the following if you want to change the
 128 maximum heap size to 128 megabytes:
 129
 130   export PEGASUS_JMPI_MAX_HEAP=128m
 131
 132 There is a new optional environment variable that tells the JVM to output more
 133 debugging information.  The variable name is called PEGASUS_JMPI_VERBOSE.
 134 An example usage is as follows:
 135
 136   export PEGASUS_JMPI_VERBOSE="jni,class"
 137
 138 This will tell the JVM to output debug information on the JNI layer and class
 139 loading.
 140
 141 When using this script, place a copy of this script above your PEGASUS_HOME
 142 directory, "cd" to PEGASUS_HOME, and issue ". ./setJPeg". Then do a normal
 143 make.
 144
 145
 146 Known restrictions
 147 ------------------
 148
 149 This installment has the following restrictions:
 150
 151    Unloading of idle providers is not supported and Java will increase the
 152      memory footprint.
 153
 154    Java 1.5 is not currently supported.
 155
 156    Gcj on 31 bit machines is only supported using gcc version 4.1.1 or later.
 157    Gcj on 64 bit machines is not supported.  Bugs 5913, 5921, and 5963 have
 158      been written to address that issue. Instead, you should use the Sun ported
 159      JVM from the Blackdown project located at www.blackdown.org.
 160
 161
 162 Level of test coverage
 163 ----------------------
 164
 165 All interfaces to a provider have a sample provider written for them and are
 166 part of the testcases.  All main CIM java classes have testcases written for
 167 them as well.
 168
 169
 170 Outstanding issues
 171 ------------------
 172
 173 Java documentation needs to be written for the classes and methods within JMPI.
 174
 175
 176 Testing
 177 -------
 178
 179 This installment has a set of tests located under
 180   src/Pegasus/ProviderManager2/JMPI/org/pegasus/jmpi/tests/
 181
 182     Static/
 183
 184       These tests have been modelled after wetest/static. (For the tests, we
 185       had to modify "diff" to "diff -w", why that is needed I do not
 186       understand.)
 187
 188    Providers/
 189
 190       These tests implement the many variants of provider interfaces.
 191
 192    Client/
 193
 194       These tests test out the client code and various Java classes.
 195
 196
 197 Running the tests
 198 -----------------
 199
 200 Tests are run with the following process.
 201
 202 If the repository has not already been built then issue the following:
 203
 204    cd to ${PEGASUS_HOME}/src/Pegasus/ProviderManager2/JMPI/
 205    Issue "make repository"
 206
 207    This will load a schema to the repository and register the provider.
 208
 209 Next, run the tests.
 210
 211    cd to ${PEGASUS_HOME}/src/Pegasus/ProviderManager2/JMPI/
 212    Issue "find -name \*.rsp -exec rm {} \;" to clean up *.rsp files from failed tests.
 213    Issue "make poststarttests"
 214
 215
 216 Samples
 217 -------
 218
 219  There are four sample providers located in
 220    ${PEGASUS_HOME}/src/Pegasus/ProviderManager2/JMPI/org/pegasus/jmpi/tests/Providers/
 221
 222    Associations/
 223
 224       This provider implements an association provider.
 225
 226    Instances/
 227
 228       This provider implements an instance provider.
 229
 230    Indications/
 231
 232       This provider implements an indication provider.
 233
 234    Properties/
 235
 236       This provider implements a property provider.
 237
 238    There is also sample Java code that deals with CIM classes that is located in
 239    ${PEGASUS_HOME}/src/Pegasus/ProviderManager2/JMPI/org/pegasus/jmpi/tests/Client/
 240
 241
 242 Provider Registration
 243 ---------------------
 244
 245 JMPI providers are registered as usual. The Location property in
 246 PG_ProviderModule has a special format. The format is:
 247   <jar-file-name>:<provider-class-name>
 248
 249 JMPI providers now fall into two groups.
 250
 251 (1) Legacy providers use:
 252       InterfaceType = "JMPI"
 253     and use one of the 3 following based on existing JMPI samples:
 254       InterfaceVersion = "1.0.0";
 255       InterfaceVersion = "2.0.0";
 256       InterfaceVersion = "2.2.0";
 257     Note that there is no difference in behavior in the three versions.
 258
 259     instance of PG_ProviderModule
 260     {
 261        Name             = "JMPIInstanceProviderModule";
 262        Location         = "JMPIInstanceProvider.jar:Instances/JMPIInstanceProvider";
 263        Vendor           = "OpenPegasus";
 264        Version          = "2.0.0";
 265        InterfaceType    = "JMPI";
 266        InterfaceVersion = "1.0.0";
 267     };
 268
 269 (2) New style providers use:
 270       InterfaceType = "JMPIExperimental"
 271     and:
 272       InterfaceVersion = "0.0.1";
 273
 274     instance of PG_ProviderModule
 275     {
 276        Name             = "JMPIExpInstanceProviderModule";
 277        Location         = "JMPIExpInstanceProvider.jar:Instances/JMPIExpInstanceProvider";
 278        Vendor           = "OpenPegasus";
 279        Version          = "2.0.0";
 280        InterfaceType    = "JMPIExperimental";
 281        InterfaceVersion = "0.0.1";
 282     };
 283
 284
 285 Bug reports
 286 -----------
 287
 288    Use normal Pegasus bugzilla procedures to report malfunctions.