//
// $Id: readme.txt,v 1.2 2002/01/13 15:32:55 david Exp $
//

These instructions are provided for version 0.7 of the openCIMOM suite 
10th Sept 2001. For the latest information and release please check the
SNIA website:

http://www.snia.org


**WARNING**

Please note that version 0.7 includes changes that result
in any persisted classes/instances being incompatible with the new
CIMOM (if you are upgrading from any earlier version). Therefore,
existing repositories cannot be used with this version.

** IMPORTANT CHANGES **
Please be sure to read this enture section carefully. Changes 
described here may affect applications using these APIs and CIMOM!

The default port for HTTP requests used by v0.7 is 5988 since
this is the port allocated by IANA for WBEM HTTP. If you have 
applications using port 80 then they either should also be updated
or you should use -p to specify an alternative port when starting
the CIMOM. 

By default 0.7 will use a Vector of CIMProperty when invoking a 
method provider. If you still wish to use providers that use a
Vector of CIMValue then you must set callMethodsWithValues to
true in GlobalConfig (this config value is not dynamically settable).

Providers are now passed the classname of the class being
requested rather than the class for which they might have been
registered. Therefore providers should avoid extracting the
classname from the passed class instance unless this is their
intended behaviour - generally providers must know the class(es)
which they handle.


CIMObjectPath now more clearly indicates that a host/namespace has
not been set by using default values of "NotSet". This should
help indicate when the information hasn't been set but it also
represents a change in behaviour.

Enumerations of class names now return CIMObjectPath instances
to align with the WBEM API JSR. Previously the enumeration was
Strings containing the class name rather than the complete
object path.

Association providers must now be prepared to accept a call
where the association class is null. This is passed in the
case where the caller did not specify any particular
association class to be used and the CIMOM is traversing 
those which are relevant. In such case the provider should
surface/traverse all relevant associations for the object that 
has been specified. Assigning (for referenceNames) the correct
classname to the returned object path(s).



Please read section 2.0 if you are using an IDE or other tools
that automatically locate java source files that need to be
compiled.

If you are still using JDK 1.1 then refer to section 2.1 which
has updated build instructions which need to be followed before
compiling the CIMOM. The current supported JDK for the CIMOM
is JDK1.3.

Changes in head
===============
- CommandClient now supports -U and -P for specifying username and
  password.
- cim.properties can now be used to specify the setting for 
  callMethodsWithValues (from Jean Lamontagne).
- From Jean Lamontage.  Added support for the propagation of CIMEvent(s) 
  toward any CIMProvider(s) that will have previously registered a 
  CIMListener using the new CIMOMHandle.addCIMListener() interface method.
- From Heung-for Cheng - the DEFAULT_PORT constant used by WbemExecCommand
  now needs to be picked up from CIMNameSpace.
- From Jean Lamontage.  Fixed problem that made it possible to establish
  a connection with a CIMServer using invalid 'userName' and/or invalid
  'password'.  Such erratic behavior was happening for any connection 
  that was attempted ONLY AND ONLY after a first connection would have
  been established successfully.  Both connections are assumed to be
  using the same instance of the JVM.  
- From Jean Lamontage & Jean-Noel. After further discussions onto
  the SUN WBEM mailing-list, there has been confirmation from SUN that
  the CIMValue is currently used from the top (e.g.: CIMClient side)
  to the bottom (e.g.: CIMProvider side) in both directions.  Fixes
  have now been made to XMLMethodCall in order to fully comply to
  the usage of CIMValue at all levels.  Obviously, these changes
  are applicable ONLY AND ONLY when the following condition is 'TRUE': 
  (GlobalConfig.callMethodsWithValues == true).  

New in 0.7
==========

- From Jean Lamontagne. Fixed the handling of CIMValue passing to method
  handlers - previously CIMProperty was being passed if that was what
  had been passed into the main cimom handler - it now extracts the
  CIMValue. (added since beta)
- Fixed null pointer exception in CIMOMClassStoreDisk when class did
  not exist (thanks to Jean Lamontagne for pointing this out).
  (added since beta)
- Added further checks to CIMOMClassStoreDisk to ensure no null
  derefs. Fixed getAllClasses() which could previously under certain
  circumstances add a ClassAndPath instance to the returned
  enumeration rather than a CIMClass instance. (since beta)
- Fixed XMLMethodCall.java so that it uses the declared return type
  when building a value to return back to the caller. (since beta)
- Added Access Control based on JAAS and allows fine granular access
  control to CIMOM entities. A big thanks goes to Quan Wang and
  Viktor Mihajlovski. See the detail explanation in readme.acs.
- Fixed problem with UnsignedInt64 (thanks to Klaus Olszowi for
  spotting a work around for this) serialization.
- The core of the CIMOM has been re-written by Viktor - which has
  resulted in much tidier code and eliminated many of the previous
  restrictions such as synchronization and the cimom level. Please
  see the seperate design.txt which Viktor has provided.
- Thanks to Douglas Shue for fixing the deletion of classes from
  the CIMOM class tree (plus browser update for class deletion).
- Thanks to HP for updates to the wbemexec command:
	- generate required HTTP extension headers for the encapsulated
	  request, according to the Specification for CIM Operations
          over HTTP, Version 1.0.  
	- A command line option has also been added to allow
	  specification of the HTTP version for the request
	  (valid versions are 1.0 or 1.1).  By default, an
	  HTTP/1.1 request is generated.  
	- An updated man page for the wbemexec.
	- Removed dependency on GNU licensed GetOpt.
- Thanks to Viktor Mihajlovski for the SSL support. Please
  refer to section 8 for more information on this.
- Thanks to HP for the test framework (see new docs directory)
- Fixed output params in method invocations over XML (Thanks to
  Christine Wang and Quan Wang). Also thanks to Steve Jerman
  for a follow up fix.
- Added support for running the CIMOM as a servlet (Thanks to HP)
  within apache/tomcat. Please refer to tomcat_config.txt in
  org/snia/wbemcmd/servlets. The design doc is also in doc/webserver.
- Thanks to Jean Lamontagne for a number of bug fixes:
	- incorrect check on user/password in HTTPOutputHTTPClient
	- non ascii characters in the HTTPClient file
	  SimpleAuthHandler.java
	- In XML handling of associators/references check for null keys
          before fetching size()
- Added support for Character and Byte to findType in CIMDataType.
- Fixed hashCode for CIMObjectPath (Tatsuya Kainuma and
  Jean Lamontagne).
- Fixed UTCOffset calculations in various locations in CIMDateTime - 
  thanks Robert St Jacques (plus now defines constants rather than
  using them inline).
- When extracting CIM validation information during a feature request it 
  was possible that the substring was not found which would then result
  in an exception (thanks to Klaus Olszowi for pointing this out).
- CIMClient.java now makes the default namespace public so that it
  can be used elsewhere (previously CIMNameSpace had its own copy which
  could be out of sync).
- Thanks to Tim Woodall for fixing CIMQualifier's XML array parsing.
- Thanks to Daniel Abramovich for fixing equals() method in CIMObjectPath
  for handling non instance cases.
- The org.snia.wbem.cimom.properties system property (if specified) can 
  now be used to specify where the the properties file can be found. 
  This way ConfigFile and GlobalConfig can use the same file for 
  configuration properties. Thanks Viktor!
- Switch to using CIMProperty based vectors for method invocations
  when calling a provider. Set callMethodsWithValues to true in 
  GlobalConfig to enable previous behaviour.
- CIMObjectPath.java file now returns "NotSet" strings when user has not
  set all necessary data properly.  When the getFullNameSpace() method is
  called, the instance returned will also contain "NotSet" values. This will
  identify the current callers who do not set these data, and correct them.
  (Thanks Angela Lee)
- Class name enumerations now return object paths (Thanks again Angela).
- When handling class enumerations (class instances or names) be prepared
  to handle a null object path.
- CIMDataType significantly reworked to improve performance - once again
  thanks to Angela!
- Fixed a potential deadlock while obtaining a thread in HTTPInput (Thanks
  to Quan Wang).
- From Quan Wang. When there is no property provider, the instance that
  we set the value on (prior to calling back to the instance provider)
  must be a clone otherwise we are (potenially) modifying the real
  instance before the provider has had a chance to validate it (etc).
- CIMClass getProperties() has been fixed to only return the
  properties whose origin class name is equal to the class in question.
- Fixed key qualifiers (etc) on references when parsing MOF (thanks to
  Daniel Abramovich for pointing this out). 
- From Klaus Olszowi - when there is nothing for references to return
  use an empty enumeration not a null (similar fix applies to class
  name enumeration).



Fixes in 0.61
=============
- A huge thanks to Pam Wright of Imation for many fixes and 
  enhancements based on v0.6:
  - Made all subdirectory strings use the FileSeperator character
  - Fixed interval format of DateTime toString method to remove
    duplicate hours string
  - Changed DateTime to throw IllegalArgumentException rather 
    than InstantiationError (which is not an exception so it
    was falling through the catch blocks)
  - Fixed MOFLexer to allow /* */ style comments
  - Fixed MOFLexer to properly handle various constant formats 
    including hex, octal, binary, floats, characters, and NULL
  - Changed CIMOMCast to properly handle the various constant formats
  - Changed Unsigned64 to include a constructor with a BigInteger parameter
    and to validate the range
  - Added a series of mofs to use to test proper parsing of data types and
    constant values
  - Added progress messages to the MOF parser
  - Added setMessage to the MOFStatus interface and used this to display
    progress messages (The progress messages are displayed in the dialog while
    loading MOFs in the browser, or to the console in verbose mode using
    MOFComp)
  - Added success/fail messages to MOFComp
- Fixed capitalization of 'Code' and 'Description' in XML error
  returns
- Modified provider interface for associations so that resultClass
  is passed in.
- Thanks to Scott Thomas for the fix to setProperty() that ensures
  the provider can be specified at either the property or class
  level. Also for pointing out setProperty() and getProperty() were
  failing when the instance could not be located in the instance
  store.
- Also thanks for scott for finding missing fixes in 0.6 in CIMClient
  when checking for strings.
- Added code to support the specification of classnames when handling
  associations.
- Thanks to Scott Painter for the fix to AssociatorNames that ensures
  the namespace is correctly set.
- Thanks for Steve Jerman for various suggestions, fixes and the 
  fix to HTTPInput that ensures the XML encoding for ERROR is
  correctly capitalized.  
- Thanks for Angela Lee for fixes to HTTPOutputHTTPClient.java which
  was still referencing a null connection value (hopefully I've really
  caught all the others this time!).  Plus performance improvements
  to getName() in CIMInstance whereby it now caches the name.
- Added check to the creation of an instance using XML so that it
  does not allow an invalid instance path to be specified
- Thanks to Viktor for fixes to compare object paths (now performed on
  basis of string value rather than complete CIMValue instances which
  required correct typing).  
- Fixed XML encoding of ARRAY values (was missing <VALUE.ARRAY> tag!) -
  thanks to Angela for pointing this one out.
- Removed code that requires all XML responses to be either a valid
  return code or error (some returns may genuinely be void). Thanks
  again to Angela!
- Another from Angela - fixed long return values in UnsignedInt8
  and UnsignedInt32.
 
    
Fixes in 0.6
============
- A BIG thanks to Frank Piorko (piorko@suse.de) for providing query
  support. 
- Also another BIG thanks to Viktor Mihajlovski for the JAAS support
  (see text in section 5 below for how to build and use this!). 
  Please also refer to the revised build instructions if you do
  not require this and are using an IDE which automatically locates
  java source files which need to be built. 
- A final BIG thanks to Hewlett-Packard for the new wbemexec utility
  and configuration mechanism that allows the CIMOM to read properties
  from a file when the CIMOM is started, so that they may be changed
  between invocations without recompiling.  In some cases, properties
  may even be modified while the CIMOM is running (see section 7).

  Please see section 6 on building this and the wbemexec.html page
  provided in the directory org/snia/wbemcmd/wbemexec. 

  Please also refer to the revised build instructions if you do
  not require this and/or the CIMConfigCommand and are using an
  IDE which automatically locates java source files which need
  to be built. 

- Thanks to Dan Dahl for the fixes to the time/date handling code.
- Fixed resultClass checking for assocations (previously being
  ignored). 
- Thanks to Andrei Viktorov for further fixes to CIMDateTime that
  were resulting in errors in building the string forms. Also for
  fixes to CIMDataType that were resulting in the wrong types
  being returned for datetime arrays. 
- Thanks to Michael Leizin for fixes to handle null array elements,
  fixes to caching for the disk based instance store and others.
- Thanks to Angela Lee for fixes to XMLEnumerateClasses, CIMDataType
  and so much more.
- Thanks to Viktor Mihajlovski for fixes to CIMClient to ignore case
  when comparing protocol strings. New ProviderCIMOMHandle.
- Thanks to Adrian Schuur for fixes to XMLReferenceNames and
  XMLAssociatorNames which were incorrectly building the name
  enumeration. (Also submitted by Andrei Viktorov).
- Fixed associators/associatornames so that when there is no return
  values an empty enumeration is passed back rather than null.
- Fixed association production for XML when qualifiers have not
  been requested (previously were being stripped by the core
  cimom such that the necessary path information could not be
  reconstructed by the XML encoding methods).
- Modified association handling code so that each instance of an
  association will only be processed once (and not for every
  class that it might be an instance of).
- Modified browser so that by default instances are not deeply
  enumerated. There is now a menu option that allows this to be
  selected when required.
- Fixed XMLNode so that it no longer access null references when
  generating exceptions.
- Thanks to Bapu Patil for fixes to HTTPWriter that prevent
  duplicate options.
- Thanks to Peter Rivera for a whole set of fixes to cover
  missing values, checks etc in the CIM classes. 
- Removed non standard methods from CIMOMHandle.
- Made fixes to socket handling to prevent CIMOM from hanging
  up when connections are repeatedly made/broken.
- Thanks to Roger Kumpf for fixing setProperty() in ServerNameSpace
  so that null values are now correctly detected.
- Added fix to XMLCreateInstance() so that it now correctly sets
  the namespace in the path that it returns. 

Fixes in 0.5
============

Thanks to Scott Baker, Viktor Mihajlovski, Heung-For Cheng,  
Mahendra Ramachandran, Heung-for Cheng, Angela Lee, Mike LaRocca,
Bhaskar Vedamurthy and everyone who contributed fixes, bugreports etc.

- Now compatible with xerces 1.0.4. 
- Added UnsignedInt? classes for handling unsigned values.
- Added CIMDateTime class
- Narrowed differences in error message ids between this implementation
  and the JSR.
- CIMInstance.toString() now returns a string similarly formatted to WBEM APIs
  version.
- Fixed escaping of instance names (etc)
- Fixed code for persistence with subname spaces.
- Added test code for escaping.
- Switched values from always being strings to being the correctly underlying
  java type.
- Reintroduced the ability to use the builtin cutdown webserver, see the
  httpClient tuneable in the configuration file. 
- Use URL information directly to get port information (see CIMClient)
- deleteInstance now correctly calls the instanceStore only if a provider
  cannot be found.
- InstanceProvider.createInstance() now returns the CIMObjectPath 
- CIMNamespace now accepts '\' as a delimited in addition to '/'  
- Requiring authorization can now be switched off in the cimom - see
  requireAuthorization in GlobalConfig.
- Made constructor on MOFMOFStatus public.
- Improved error checking on CIMOM http receive handling code so that
  an error within the CIMOM does not pernamently hang a connection.
- Added support for decoding the other XML documents that can be
  sent when enumerating assocations/references.
- Add support <VALUE_NAMEDOBJECT) on GetClass operations.
- Add support <VALUE_NAMEDOBJECT) on EnumInstances/GetInstance operation.
- Added support <VALUE_OBJECT>.
- Fixed names for attribute names so that they are now treated in a
  case insensitive fashion.
- Fixed CIMProperty which was not initializing the qualifier vector 
  causing problems elsewhere.
- Fixed browser so exceptions aren't thrown if a namespace node entry
  in the tree is selected.  
- Added new note on using policy files with RMI access - see RMI
  section below.
- Added functionality to allow MOF updates to force changes in
  the CIMOM.
- Fixed problem in CIMNameSpace whereby deleting names spaces
  were given null exceptions. 
- In case of error responses, with error messages containing quotes, the
  generated XML document was incorrect. Fixed by escaping quotes and
  apostrophies (org/snia/wbemcmd/xml/XMLCIM.java).
- It was not possible to invoke a method on an instance of class
  implemented by an Instance Provider. The reason was that an exception is
  thrown by CIMOMInstanceStore.getCIMInstance(), since this instance is
  un beknown to it. Fixed by using the method instanceExists() before we
  try to retrieve the instance.
- Allow location of persistence directory to be specified - see
  persistenceDir in org\snia\wbemcfg\GlobalConfig.java.



Fixes in 0.41
=============
- Thanks to Peter Rivera, Naveen Sharma, Mahendra Ramachandran,
  Jim Stawn, Sharad Tripathi, Heung-for Cheng, Joy M Underhill
  and everyone else that contributed Fixes and bug reports!

- Fixed gray panel that appeared in the browser.
- Fixed display problems under JDK1.3 with browser.
- Fixed clone() method on CIMMethod to copy names.
- Fixed CIMClass() so that a null reference is never returned
  for methods.
- Fixed association traversal so that regular providers aren't
  called when locating instances of associations.
- Added getHostURL() and parse() to CIMNameSpace.
- Fixed URL handling in CIMClient.
- createInstance() now returns a CIMObjectPath. 

New for Version 0.4
===================
- Persistence. By default all classes, qualifiers and instances
  will be persisted. To disable set usePersistence=false in
  org\snia\wbemcfg\GlobalConfig.java.
- HTTP authentication - Please follow instructions in section 2.2 
  below for configuring authentication. As a side effect there is
  now improved HTTP 1.1 support for the browser.
- Support for deleting instances from the browser.
- BUG FIX - set properties in an instance could result in the datatype
  not being set for the property.
- BUG FIX - method invocations on instances were seeing only the class
  portion of the object path.
- BUG FIX - RMI start up of server was failing due to bad boot
  up sequencing.
- Added mapping from Long Java objects to CIM 32 bit integers.
- Fixed constructor CIMValue constructor so null can be passed in
- Fixed data type mappings for Date objects.
- Added support for creating array based CIMValue instances from
  Java array objects (includes changes to the toXml() function
  to support this).
- BUG FIX. When properties are obtained dynamically from a provider
  the property provider is no longer called if it has been
  declared.
- Fixed TODO in CIMFlavor constructor - now throws an exception
- BUG FIX. CIMProperty constructor sets datatype on
  basis of passed type
- BUG FIX. Qualifiers on properties or method declarations
  that are overriden in a class definition are now propagated
  if they aren't defined by the overriding entity (previously
  ther were ignored).
- BUG FIX. Strings in object paths are now escaped if they themselves
  contain either quotes or other escaped characters.
- BUG FIX. Relying on parsing strings to generate object paths
  can lead to problems when associations are involved. The browser
  now caches object paths so that they don't need to be regenerated. 
- Modified xml parsing for associations and references so that an
  instance path element without an enclosing object path element
  will be accepted in a response (The MS implementation sends
  such constructs).


New for Version 0.3
===================

- Compatibility with SUN WBEM APIs v2.2. Includes new AssociatorProvider
  interface support.
- Faster MOF parsing and XML handling. On a 400Mhz system the 2.3 schema
  can now be parsed (with a "local" cimom in approx 6 seconds) and
  to a CIMOM on local host using XML in 20-25 seconds. Please refer
  to the new performance section (5) below because tuning the memory size
  for the JVM is vital to achieve maximal performance.
- Improved network buffer management. The XML bytestream is now
  directly read from the network rather than being buffered 
  multiple times.

BUG FIXES:
- Thanks to cv.vick@intel.com for fixing bug in MOF parsing that caused
  failures when no qualifiers were provided on a class declaration.
- Thanks to mchang@intel.com for fixes to correctly set references
  within instance declarations and creating instances from MOF.
- Thanks to Frank Piorko (piorko@suse.de) for pointing out that
  associators(), associatorNames(), references() and referenceNames()
  in CIMClient were failing to correctly reset null namespace values
  on the object path. Also for providing the base for the example
  accesses.
- Also thanks to frank for spotting that a request for qualifier
  types would fail with an XML transport due to an assumption that
  there would always be at least one parameter to process in
  an XML request for an instrinsic function.
- Thanks to tiags.thiyagarajah@intel.com for adding provider support
  at the class level for method invokes.
- Added support for passing a CIMOMHandle to a provider.
- Added strictParse tuneable to GlobalConfig to specify whether
  whether MOF parsing should be strict. Non strict  parsing will allow
  classes to specify references without being formally qualified as an
  ASSOCIATION. This is necessary for the DMTF CIM 2.3 schema which 
  does not correctly specify such qualifiers.
- Fixed extractParameterStringArray() to allow empty IPARAMVALUE
  elements
- Fixed key regeneration in CIMInstance - certain forms of 
  properyUpdate could leave keys in an inconsistent state.
- Moved standalone classes so they are now scoped under org.snia.
- Removed CIMInstanceAndPath as this was being used to incorrectly
  return instances with their pathnames.
- Fixed bug with threading in HTTPInput whereby threads were 
  unintentionally re-using the same instance.

New for Version 0.2
===================
- New stand-alone MOF compiler (see org.snia.wbemcmd.mof.MOFComp).
- Support for threads (enabled by default but can be disabled by
  setting useThreads to false in org\snia\wbemcfg\GlobalConfig.java)
- Changes to browser including ability to execute methods on classes
  as well as instances. 
- Many fixes to HTTP support to ensure improved interoperability.
- No longer require responses to include Content-Length headers
- Fixes to XML encodings (removed VALUE.NAMEDELEMENT tags from 
  numerous encodings, fixed parameter encodings)
- Much improved support for logging both input and output.
- Made support for singleton key value xml encodings optional (many
  implementations require property names to be included).
- Significantly improved error reporting from the MOF compiler. Line
  numbers where the parse (etc) failure occured are now
  accurtately reported.
- Fixed missing calls to class name normalization functions in 
  ServerNameSpace.
- XML string generation now based on StringBuffer not String to
  improve efficiency. XML performance is significantly better
  (compared to v0.1) with a complete class enumeration for the
  CIM2.3 schema on a 400Mhz system taking approx 8secs. 
- Fixed namespace removal. Removal now correctly traverses
  childnamespaces.
- Added new example for creating a class dynamically that then
  is managed through an instance provider
  (see providers/Dynamic.java)
- Switched to xerces XML parser.

Notes
=====

This source uses the Solaris WBEM APIs version 2.2. Synchronization
will be maintained with the Solaris WBEM APIS, which are being
standardized through the Java Community Process.

Sun, Solaris and Java are trademarks or registered trademarks of
Sun Microsystems, Inc in the U.S. and other countries.

License
=======

Each file provided is subject to the following license:

The contents of this file are subject to the SNIA Public License Version 1.0
(the "License"); you may not use this file except in compliance with the
License. You may obtain a copy of the License at

		http://www.snia.org/resources/openSource.html

Software distributed under the License is distributed on an "AS IS" basis,
WITHOUT WARRANTY OF ANY KIND, either express or implied. See the 
License for the specific language governing rights and limitations
under the License.



In addition the files utils.java, HTTPReader.java, HTTPWriter.java are also
subject to:

Copyright (C)1996,1998 by Jef Poskanzer <jef@acme.com>. 
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

Visit the ACME Labs Java page for up-to-date versions of this and other
fine Java utilities: http://www.acme.com/java/




1. Other Required Components
============================

Before you can build the object manager and browser you will need to
download the following:

- swing
	if this is not part of the Java development kit that you have
	then it is available from www.javasoft.com

- The apache xerces XML parser. Please use version 1.0.4.

	Download from http://www.apache.org

- RMI (for windows/windows NT users using J++)
	Download from ftp://ftp.microsoft.com.developr/MSDN/UnSup-ed/

It is recommended that you use the most recent version of swing that is available for your platform.

To run the CIMOM, it is likely that you will require the CIM schema. This
can be downloaded from the DMTF website (www.dmtf.org).

This version of the CIMOM will operate with JDK 1.1 through 1.3. 

Users/developers with JDK 1.1 cannot take advantage of the setting/
saving of configuration options.


2. How To Build
===============

	Note: When using a standard editor, the source is best
	      viewed with tab stops set to 4 columns rather than
	      8 columns.

2.0 Removing optional packages (new for V0.6)

    The following directories contain optional packages for the
    CIMOM which have additional dependencies on external
    packages: 

	org/snia/wbemcmd/cliutils
	org/snia/wbemcmd/wbemexec
	org/snia/wbemcmd/config/CIMConfigCommand.java
	org/snia/wbemcmd/jaas 

    If you do not require the functionality that these packages/classes
    provide, have not downloaded the additional packages that they
    require in order to build and are using a IDE or other build
    tool which automatically locates java source files then you
    may need to remove these directories prior to any build of
    the CIMOM to prevent unresolved dependencies.

2.1 Building with JDK1.1.8
	
	Please update the org/snia/wbemcmd/config/ConfigFile.java
        to remove calls to methods not available with this JDK -
        search for JDK1.1 in ConfigFile.java and follow instructions.

	Set the CLASSPATH to include:
		- the jar files for swing and xerces.
 		- RMI
 		- The location where the HTTPClient subdirectory
 		  has been placed.
		- the top most directory where the cimom files
		  have been installed (typically the directory
		  where this README resided)
	
	In addition CLASSPATH should include the providers 
	subdirectory when running the CIMOM.

	Typically a command of the form below is required:

	set CLASSPATH=%CLASPATH%;c:\somedir\xerces.jar;c:\somedir\swing.jar;c:\somedir\HTTPClient;c:\installdir;c:\installdir\providers


	Build the CIMOM with:

		cd {installdir}org\snia\wbemcmd\cimom
		javac CIMServer.java
	
	Build the browser with:
	
		cd {installdir}org\snia\wbemcmd\browser
		javac DialogBrowser.java

	Build the namespace provider with:
	
		cd {installdir}org\snia\wbemcmd\providers\namespace
		javac __NameSpace.java

	Build the demonstration providers:
	
		cd {installdir}providers
		javac Provider1.java
		javac Provider2.java


	Alternatively for windows users, simply edit the make.bat
	file to specify the relevant CLASSPATH and execute the script.

2.2 	Using JDK 1.2 or 1.3 

	Please note that if you will be using query support you can
	make it more efficient by modifying:

	org.snia.wbemcmd.query.delete()

	- Please see comments in code.


2.3 Configuring Passwords
 
 	From version 0.4, by default the CIMOM requires a "passwords"
 	file to be provided if HTTP access is to be used. This 
 	should be placed in the directory where the CIMOM
 	is executed from and contains lines with the syntax:
 	
 	user_name:password
 	
 	For example:
 	
 	davidsi:foo

	The file should protected using OS file protection
	mechanisms. This is intended as an example password
	implementation - more sophisticated authentication 
	mechanisms can be integrated with the CIMOM by specifying
	an authentication module by assigning basicAuthModule 
	in the file org\snia\wbemcfg\GlobalConfig.java.
	
	It is assumed that most deployments of the object manager
	will use a system specific mechanism that ties the Object
	Manager into the hosting platform's mechanism(s) for
	authenticating users.
	
	
2.4 Running the CIMOM and Browser

	Run the CIMOM using:
		
		java org.snia.wbemcmd.cimom.CIMServer

	
	Run the browser using:
		
		java org.snia.wbemcmd.browser.DialogBrowser


	To automate this the batch files cimom.bat and cimbrowser.bat
	are provided and simply need to be modified to include the
	relevant classpath values prior to use.

	The clean.bat script will remove all class files from the directory
	hierarchy and ensure a build is from scratch.


	If you wish to load all the MOF for the CIM schema v2.2, then
	additional memory must be made available for the JVM using
	the -mx option, e.g.:

		-mx 400000000 
			(the max value possible will depend on your platform)


	See section 3 for more information
	
	
	It is possible to improve the performance of the CIMOM and/or 
	Browser under windows my modifying their properties (right click
	on the appropriate .bat icon and select "Properties") so that
	their idle sensitivity is "low" on the "Misc" tab.
	

2.5 Building with other Java development tools based on javac/java

	Follow the instructions as per JDK 1.1.8 but it may be necessary
	depending on the precise version of javac to build individual 
	files,  e.g. use javac *.java until all files are built without error

2.6 Building with J++

	Under "File" select "New Project"

	Click on the "Existing" tab of the "New Project" Dialog

	Use the file browser to select (click once, not twice) the topmost
	directory where the source files are located (normally the
	directory containing this readme).
	
	Click on the "Import Project Folder" button.

	On the Project menu, select "<name> Properties"	 where name is 
	the name of the directory that the files where located in.

	Select the "Classpath" tab and add the necessary directories that
	contain the swing, xml and rmi classes. 

	Use the dialog to select any other options required such as
	debugging and optimization values.

	On the Launch tab:
	
		To run the browser from within J++ set
			"org.snia.wbemcmd.browser.DialogBrowser"
	
		To run the cimom from within J++ set
			"org.snia.wbemcmd.cimom.CIMServer"


2.7 Using RMI

	To use RMI you will need ensure that you have the rmic tool
	(not part of j++)

	Build an RMI enabled server by running RMIC on CIMServerRemote:

		rmic org.snia.wbemcmd.cimom.CIMServerRemote

	Depending on the JDK you may need to create a policy file. This
        is achieved by running the command "policytool" (provided with
	the JDK).  The resulting file allows the client's to receive
        the data from the server through the socket with the security
	manager installed.

	The file must be given on the command line with the -D option:
	
	java -Djava.security.policy=policy.txt -mx35000000 -ms35000000
		org.snia.wbemcmd.browser.DialogBrowser


	A typical security file which permits all access would contain:
	
	grant {
	    permission java.security.AllPermission;
	};


2.8 Per site configuration
	
	The file org\snia\wbemcfg\GlobalConfig.java contains the following 
	useful "tuneables":

	disconnectAfterTransfer
		disconnectAfterTransfer determines whether the server drops
		each connection from a client after servicing it. When true
		a connection is only maintained for the duration of a request.
		If false then the connection is held open. 

		Holding the connection open is faster but until the server is
		multithreaded  it prevents it being shared between clients.
		This value is true by default, but if you only intend using
		the server from one client at a time it can be set true
		for improved performance.

	DEBUG_XML
		When true debug information for xml will be output
	
	DEBUG_XMLDECODE
		When true the decoded XML elements will be output

	tempPath
		Determines location of temporary files used when building
		the XML input stream. Currently each instance of either a
		server or client will write files in this location and 
		therefore it needs to be on a per-user basis


	usePersistence
		When true all qualifiers, instances and classes are
		persisted.
		
	Other configuration information is provided in 
	org\snia\wbemcfg\GlobalConfig.java for log file location.

	

3. Using the Browser
====================


	When the browser starts the user will be prompted for a system
	name, a namespace and connection type.  

	The system name can
	be either a IP address or any name (i.e. DNS name) that can be 
	mapped to a system on the network.

	The namespace should be a namespace that is being exported by
	the cimom on that system.

	The three connection types supported are:

	RMI   - The fastest remoting protocol but only compatible with
		the openCIMOM server. This will not work, for example, with
		the SUN server which also supports RMI.
	XML   - The standard mechanism.
	LOCAL - Makes no connection but instantiates a local, private
		CIMOM which is useful for testing only.


	The port used for communication can be modified on the "Advanced"
	tab.


	The browser will attempt to connect. If a connection is made it
	will download the available classes. Depending on the number
	of classes loaded into the CIMOM there may be a delay while this
	occurs.

	Once started, the browser will show the available classes as
	a tree. If the CIMOM has not been loaded with any class
	definitions then use the "Open MOF" menu item on the "Project"
	menu to load the required MOF files.  The entire CIM v2.2 schema
	may be loaded using the CIM_Schema22.mof" file. Note that additional
	memory must be provided to both the browser and server if they
	are being run using the jdk "java" command. 

	Due to errors in the DMTF definitions, the following changes
	should be made:

	Remove the defintions for CIM_ServiceComponent and 
	CIM_AdaptiveActiveConnection from the CIM_Network22.mof
	file as these are duplicate definitions. Alternatively
	you may use the files as provided and use the "ignore"
	option when the errors are reported.


	An example for providers can be seen by loading the
	Providers/ProviderExample.mof file (ensure that the core
	schema has not already been loaded) and looking at the classes:
	
	CIM_ManagedSystemElement->
		CIM_LogicalElement->
			CIM_System->
				CIM_ComputerSystem->
					EXP_UnitaryComputerSystem


	and

	CIM_ManagedSystemElement->
		CIM_LogicalElement->
			CIM_System->
				CIM_ComputerSystem->
					EXP_UnitaryComputerSystem->
						EXP_DemoComputerSystem

	EXP_DemoComputerSystem also is an example of a method provider.
	Once selected on the instances window, click on the "Methods"
	tab. Then select "MyMethod" and "Execute" from the "Object"
	menu. Click on the "Execute" button in the "Set Arguments" dialog.

	

	


4. CIMServer options
====================

	When starting the server the following options are available:

	-p x
		Sets the port number to x. By default 80 is used.

	-r
		Enable rmi support. By default RMI is disabled.

5. JAAS SUPPORT
===============

Author: Viktor Mihajlovski (mihajlov@de.ibm.com), IBM Linux Technology Center

This package implements the org.snia.wbemcmd.xml.Authorizer interface and
provides basic authentication through Java Authentication and Authorization
Services. It is a replacement for the standard BasicAuthorization class that
comes with the SNIA CIMOM.

The advantage of JAAS is that it provides a framework allowing to plug
in authentication modules (aka as Login Modules). A range of authentication
plugins are available from Sun Microsystems, e.g. for NT, Solaris and X.500.

A sample Linux login module for JAAS can be requested by sending email
to Viktor.

For more information about JAAS please refer to the JAAS documentation
available at http://java.sun.com.

Prerequisites:
- JDK 1.3 or higher
- JAAS 1.0 or higher

Installation:
- Build org/snia/wbemcmd/jaas/JAASAuthorization.java
- if JAAS is not installed as extension, include jaas.jar in the classpath of
  the CIMOM startup script
- create a login configuration file (see example below) and modify the CIMOM
  startup script to point the java.security.auth.login.config to this file
  e.g:  java -Djava.security.auth.login.config=cimom.config \
                                        org.snia.wbemcmd.cimom.CIMServer
- in org/snia/wbemcfg/GlobalConfig.java replace the basicAuthModule as follows:
        static public String basicAuthModule =
                        "org.snia.wbemcmd.jaas.JAASAuthorization";
  and rebuild the GlobalConfig class

Sample login configuration:

/** cimom.config for NT **/

CimomLogin {
        com.sun.security.auth.module.NTLoginModule required;
}




6. Notes on configuration mechanism
===================================

A command line interface is provided (the CIMConfigCommand class) to
update the configuration file and to report configuration changes to a
running CIMOM process.

The DEBUG_XML and DEBUG_XMLDECODE flags have been set up to allow
dynamic modification.  XML debugging may be turned on or off in the
CIMOM with immediate effect.

Other properties may be added to the dynamic configuration capability
through implementation of the ConfigPropertyOwner interface.  (The
"PropertyOwner" class defines the semantics of a particular property.)
The DebugXMLPropertyOwner and InternalRMIPropertyOwner classes are
examples of owners for properties that may and may not be updated
dynamically, respectively.


7. Performance
==============

To maximize the performance of the CIMOM and the browser you will need
to ensure that you have correctly allocated sufficient memory. We have
found that it is worth using both -mx and -ms flags when starting java
to ensure an appropriate maximum is set and to pre-size the memory.
Without the -ms flag the garbage collector may work overtime during
any initial mof load.

Because both -ms and -mx are often used setting the memory values is
a delicate balancing act because if you assign to much memory and
your system swaps then performance rapidly degrades. 

To help tune memory, it is recommended that you use the -verbosegc
flag on java to see how much work the garbage collector is running.
Some amount of activity during an initial mof load is acceptable
but too much and the load will take significantly longer than it 
needs to.

8. SSL Support
==============

Author: Viktor Mihajlovski (mihajlov@de.ibm.com), IBM Linux Technology Center

This package adds communication security between CIM Client and Server to the
SNIA CIMOM. It is implemented on top of the Sun Java Secure Socket Extension.
Note: only HTTP (or more accurate HTTPS) is secured. RMI is still insecure.

For more information about JSSE please refer to the JSSE documentation
available at http://java.sun.com.

Design Information:
A major objective was not to expose the SSL vs. plain socket issues to the
application. Therefore the SocketProvider interface was introduced, that
basically serves as a socket factory interface. The application is thus 
required to create new sockets via the socket provider and not with the normal
Socket() or ServerSocket() constructors. Two socket providers are included, one
for plain sockets and another one for SSL sockets. They can be set through
the new SocketProvider field in GlobalConfig.java (see below).
Both the HTTPOutputSimple and HTTPOutputHTTPClient are now enabled for SSL.

Changes:
- Enabled HTTP over SSL communication
- Extended HTTPOutputSimple to support basic authentication, with this change
  HTTPClient is now needed only for communication through a firewall 

Prerequisites:
- JDK 1.3 or higher
- JSSE 1.0.2 or higher

Installation:
- install JSSE as JDK extension (follow the JSSE instructions and perform 
  installation verification)
- rebuild the SNIA CIMOM (make sure that JSSESocketProvider is compiled too)

Configuration:
- in org/snia/wbemcfg/GlobalConfig.java there's a new required line specifying
  the Socket Provider:
	static public String SocketProvider = 
			"org.snia.wbemcmd.xml.JSSESocketProvider";
- if you don't want SSL just specify:
	static public String SocketProvider = 
			"org.snia.wbemcmd.xml.PlainSocketProvider";

Running:
- In order to run with SSL enabled it is necessary to modify the run 
  scripts for server and clients as certain system properties must be set for
  JSSE to work:
  For the server add "-Djavax.net.ssl.keyStore=<keystore> -Djavax.net.ssl.keyStorePassword=<keystorepass>" 
  to the command line. 
  For the client add "-Djavax.net.ssl.trustStore=<truststore>" to the command
  line.
- If you use the supplied truststore and keystore files then the following
  values apply:
  <keystore>=cimom.key
  <keystorepass>=cimomkeypass
  <truststore>=cimom.trust
- A shell script "mkcert.sh" is included in this package which helps to 
  generate the keystore and truststore files.

*************************************IMPORTANT*********************************

Generate your own keystore and truststore for your environment ASAP (follow the
instructions in the JSSE documentation). Using the default truststore will
allow anybody with read access to this file to eavesdrop (or worse) on your 
CIM connections. This includes the rt. honourable author of this package ;-)

*******************************************************************************
	
9. Areas Under Development
==========================

	This project started as an exercise to learn Java, and there is
	still much to do and areas to revisit. 	The below items are areas 
	that are still to be worked on and ideas for future improvements.
	
	Why not join in and help us make this the ultimate WBEM solution!!


	Reduced memory footprint
	MOF generation (toMOF functions)
	Exception generation - some exceptions are still strings rather
		that pre-defined constants
	Make source javadoc friendly
	Format source to 80 cols
	Support queries and indications
	Namespace deletion 
	Support for aliases in MOF (only partially implemented)
	Error checking and returns as per the CIM OPs over HTTP Spec
	Semantic checks
		- Need to verify that OVERRIDE does not change
		  the data types or the ref/prop/method names.
	MOF parse in browser needs to be thread safe
	MOF parsing not detecting reserved words (true for XML as well)
	HTTP code robustness and HTTP 1.1 compliance
	Need to support HTTP chunking - and use for enum of classes etc
		so as to prevent requiring large amounts of memory
	Other classes provided by SUN
	XML parsing needs to rely less on bringing in the entire
	  tree (which is bad for large transfers)
	See other "TODO" comments in code.
