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 this support a few environment variables have to used.
  46 The following script has been proven useful for setting up the build and execution environment.
  47 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_DEBUG=1
  55    export JAVA_SDK=/usr/java/j2sdk1.4.2_08
  56    export JAVA_SDKINC=${JAVA_SDK}/include
  57    export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${JAVA_SDK}/jre/lib/i386/server:${JAVA_SDK}/jre/lib/i386/native_threads:${JAVA_SDK}/jre/lib/i386
  58    export PATH=${JAVA_SDK}/bin/:${PEGASUS_HOME}/bin:${PATH}
  59    export CLASSPATH=${CLASSPATH}:${PEGASUS_HOME}/lib/JMPIImpl.jar
  60
  61 There is now a new variable to determine which JVM to link with.  The choices are as follows:
  62      PEGASUS_JVM        sun     Sun's jvm (ex: j2sdk1.4.2_07)
  63      PEGASUS_JVM        ibm     IBM's jvm (ex: IBMJava2-142)
  64      PEGASUS_JVM        bea     Suse's IBM jvm (ex: BEAJava2-1.4.2)
  65 So, pick one and export that variable to the environment.  For example,
  66      export PEGASUS_JVM=sun
  67 NOTE: This is currently listened to for Linux builds.  And the sun option was the only
  68       tested version.
  69
  70 There are a couple of optional environment variables to determine how the JRE is initialized.  These are
  71 as follows (the variable name and what JRE option that it corresponds to):
  72
  73 PEGASUS_JMPI_MAX_HEAP               -Xmx
  74 PEGASUS_JMPI_INITIAL_HEAP           -Xms
  75 PEGASUS_JMPI_JAVA_THREAD_STACK_SIZE -Xss
  76
  77 So, for example, you would perform the following if you want to change the maximum heap size to 128 megabytes.
  78
  79 export PEGASUS_JMPI_MAX_HEAP=128m
  80
  81 There is a new optional environment variable that tells the JVM to output more debugging information.  The variable name
  82 is called PEGASUS_JMPI_VERBOSE.  An example usage is as follows:
  83
  84 export PEGASUS_JMPI_VERBOSE="jni,class"
  85
  86 This will tell the JVM to output debug information on the JNI layer and class loading.
  87
  88 When using this script, place a copy of this script above your PEGASUS_HOME directory.
  89 "cd" to PEGASUS_HOME, and issue ". ./setJPeg". Then do a normal make.
  90
  91
  92 Known restrictions
  93 ------------------
  94
  95 This installment has the following restrictios:
  96
  97    Unloading of idle providers is not supported and Java will increase the memory footprint.
  98    Java 1.5 is not currently supported.
  99
 100
 101 Level of coverage
 102 -----------------
 103
 104 All interfaces to a provider have a sample provider written for them and are part of the
 105 testcases.  All main CIM java classes have testcases written for them as well.
 106
 107
 108 Outstanding issues
 109 ------------------
 110
 111 Java documentation needs to be written for the classes and methods within JMPI.
 112
 113
 114 Testing
 115 -------
 116
 117 This installment has a set of tests located under src/Pegasus/ProviderManager2/JMPI/org/pegasus/jmpi/tests/
 118
 119    Static/
 120
 121       These tests have been modelled after wetest/static.
 122       For the tests, I had to modify "diff" to "diff -w", why that is needed I do not understand.
 123
 124    Providers/
 125
 126       These tests implement the many variants of provider interfaces.
 127
 128    Client/
 129
 130       These tests test out the client code and various Java classes.
 131
 132
 133 Running the tests
 134 -----------------
 135
 136 Tests are run with the following process.
 137 If the repository has not been built before then issue the following:
 138
 139    cd to ${PEGASUS_HOME}/src/Pegasus/ProviderManager2/JMPI/
 140    Issue "make repository"
 141
 142    This will load a schema to the repository and register the provider.
 143
 144 Next, run the tests.
 145
 146    cd to ${PEGASUS_HOME}/src/Pegasus/ProviderManager2/JMPI/
 147    Issue "find -name \*.rsp -exec rm {} \;" to clean up *.rsp files from failed tests.
 148    Issue "make poststarttests"
 149
 150
 151 Samples
 152 -------
 153
 154  There are four sample providers located in
 155    ${PEGASUS_HOME}/src/Pegasus/ProviderManager2/JMPI/org/pegasus/jmpi/tests/Providers/
 156
 157    Associations/
 158
 159       This provider implements an association provider.
 160
 161    Instances/
 162
 163       This provider implements an instance provider.
 164
 165    Indications/
 166
 167       This provider implements an indication provider.
 168
 169    Properties/
 170
 171       This provider implements a property provider.
 172
 173    There is also sample Java code that deals with CIM classes that is located in
 174    ${PEGASUS_HOME}/src/Pegasus/ProviderManager2/JMPI/org/pegasus/jmpi/tests/Client/
 175
 176
 177 Provider Registration
 178 ---------------------
 179
 180    JMPI providers are registered as usual. The Location property in PG_ProviderModule has a special format.
 181         The format is: <jar-file-name>:<provider-class-name>
 182
 183    JMPI providers now fall into two groups.
 184    1) Legacy providers use:
 185       InterfaceType = "JMPI"
 186    and use one of the 3 following based on existing JMPI samples:
 187       InterfaceVersion = "1.0.0";
 188       InterfaceVersion = "2.0.0";
 189       InterfaceVersion = "2.2.0";
 190    Note that there is no difference in behavior in the three versions.
 191
 192    instance of PG_ProviderModule
 193    {
 194       Name             = "JMPIInstanceProviderModule";
 195       Location         = "JMPIInstanceProvider.jar:Instances/JMPIInstanceProvider";
 196       Vendor           = "OpenPegasus";
 197       Version          = "2.0.0";
 198       InterfaceType    = "JMPI";
 199       InterfaceVersion = "1.0.0";
 200    };
 201
 202    2) New style providers use:
 203       InterfaceType = "JMPIExperimental"
 204    and:
 205       InterfaceVersion = "0.0.1";
 206
 207    instance of PG_ProviderModule
 208    {
 209       Name             = "JMPIExpInstanceProviderModule";
 210       Location         = "JMPIExpInstanceProvider.jar:Instances/JMPIExpInstanceProvider";
 211       Vendor           = "OpenPegasus";
 212       Version          = "2.0.0";
 213       InterfaceType    = "JMPIExperimental";
 214       InterfaceVersion = "0.0.1";
 215    };
 216
 217
 218 Bug reports
 219 -----------
 220
 221    Use normal Pegasus bugzilla procedures to report malfunctions.