readme.jmpi

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