# Configuring the Client

The SBLIM CIM Client for Java has a broad set of configuration options that influence the runtime behavior of the client.

## The Configuration File

The SBLIM CIM Client for Java can be configured by a configuration file which follows the Java properties approach. So, `key=value` entries can be used to define values for the many available properties. The file name of the configuration file is `sblim-cim-client2.properties`. The client searches by default these directories in the given order:

- the active directory
- the active user's home directory
- `/etc/java`

If the file is found once, the search stops and that file is used as input. So it is not possible to use two configuration files in parallel. If properties are not defined in the used configuration file, the default values are taken.

The user may override the default search location by specifying the JVM system property `sblim.wbem.configURL`:

- `javaw -jar myapp.jar -Dsblim.wbem.configURL=file:/root/myproperties`
  will set the location at JVM startup
- `System.setProperty(WBEMConfigurationProperties.CONFIG_URL, "file:/root/myproperties");`
  will set the location from within your application. This way the timing is critical, because the `WBEMConfiguration` class will load the configuration file in its static initializer and any change of the property afterwards won't have any effect.

Note that `sblim.wbem.configURL` contains a URL, so you're not restricted to a local file but can load the properties file from an HTTP server or some other remote location.

The configuration file contains documentation and declarations of all recognized configuration properties. The declarations are commented out by default. To change a property delete the leading # from the declaration and set the appropriate value. Here is an example:

    # Specifies the XML parser for parsing CIM-XML responses.
    # The SAX parser is the default choice since it is fast, resource saving
    # and interoperable. The streaming algorithm of the PULL parser uses the
    # fewest possible resources but at the prize to keep the CIMOMs response
    # open for a long time. That works with many but not all CIMOMs. The DOM
    # parser is slow and resource hungry but nice to debug.
    #
    # Type: Discrete
    # Recognition: Anytime
    # Range: DOM, PULL, SAX
    # Default: SAX
    #
    sblim.wbem.cimxmlParser=PULL

The sample will use the value `PULL` for the property `sblim.wbem.cimxmlParser`. The lines starting with a `#` are comments and will be ignored.

Be Careful: The property keys are case sensitive. So, please avoid typos.

## Configuration During Runtime

All configuration properties can be set during runtime. The interface `WBEMConfigurationProperties` contains constants for every property together with detailed documentation on each property.

### Global Settings

The global settings have JVM scope. Most properties are set via `System.setProperty()`, a few ones via `Security.setProperty()` (see documentation of corresponding properties). The documentation also explains when a property change will be recognized.

The code that loads the configuration file calls `System.setProperty()` or `Security.setProperty()` as well to engage the configuration.

When you try to set the settings that have recognition "startup" like `sblim.wbem.configURL` or `sblim.wbem.logFileLevel` keep in mind that these settings are evaluated in the static initializers of the internal classes `WBEMConfiguration` or `LogAndTraceBroker`. These classes are referenced by many classes of the CIM Client. Therefore you have to ensure that you set these properties before you reference a CIM Client class in your code (what will trigger the class loader and thus the static initializers).

### Client Settings

It is possible to override the global configuration for an individual `WBEMClient` instance. These settings are shared between all threads using that client instance. In order to do this cast the `WBEMClient` to `WBEMClientSBLIM` and call `setProperty()`. Note that most properties will have no effect if set after the `initialize()` method was called.

### Listener Settings

It is possible to override the global configuration for an individual `WBEMListener` instance. These settings are shared between all threads using that listener instance. In order to do this cast the `WBEMListener` to `WBEMListenerSBLIM` and call `setProperty()`. Note that most properties will have no effect if set after the `addListener()` method was called. It is also possible to set a listener's properties by creating a new `java.util.Properties` object and passing it to the `WBEMListenerSBLIM` variant of `addListener()` that accepts properties.

### Local Settings

Imagine you've multiple threads using the same client instance concurrently and you want to reconfigure the instance in one thread, but keep the other threads unaffected. This is what the local settings do. They override the client and global settings, but are recognized by the current thread only. You can set a local property by casting the `WBEMClient` to `WBEMClientSBLIM` and calling `setLocalProperty()`. Local settings are inherited from parent thread to child thread: When the child thread is created it receives the initial values from its parent thread. Afterwards the local settings of parent and child are completely independent.

### Bottom Line

The client has four possible layers for any configuration property. They override each other in the following order:

1. local setting
2. client or listener setting
3. global setting
4. default value

The global settings can be initialized either from a configuration file or via method calls. Client, listener and local settings are initialized via method calls only. The default values are compile time constants and not subject to change.