Best practises

Always close iterators

Enumeration and association traversal operations return a CloseableIterator. Make sure that this iterator gets always closed. In current implementations the iterator is closed automatically when you iterate behind the last element. However there's no guaranteee whatsoever that this behaviour is kept for future releases. Moreover you have to ensure that the iterator is closed when you stop iterating before the end is reached either normally or caused by an exception.

If you fail to close the iterator we will leak a network socket.

			
  final CloseableIterator iterator = client.enumerateInstanceNames(new CIMObjectPath(
    "CIM_RegisteredProfile", "root/cimv2"));
  try {
    while (iterator.hasNext()) {
      final CIMObjectPath path = (CIMObjectPath) iterator.next();
      System.out.println(path.toString();
    }
  } finally {
    iterator.close();
  }
        

Sharing vs pooling of WBEMClients

The WBEMClient class is designed for thread-safety. It contains a HTTP client pool that allows to reuse network connections used for previous operations. You are able to set configuration properties that apply to the current thread only.

Bottom line: We did a lot of work to ensure that sharing a WBEMClient between threads is safe and convenient to use. Therefore create just one WBEMClient per CIMOM and share it. I don't know a compelling reason for having a pool of multiple clients per CIMOM. This is a pattern used with other client libraries that had not been thread-safe.

Choose the right parser

The SBLIM CIM Client for Java offers three different XML parsers: DOM, SAX and PULL. All three produce identical results out of a CIM-XML response. What is different is the way the are producing these results.

Bottom line: When you are dealing with large numbers of objects and you CIMOM works with the PULL parser ... choose the PULL parser. For all other case SAX is the first choice. DOM shouldn't be used in a production environment.

Restrain tracing for problem determination

The SBLIM CIM Client for Java can produce a lot of trace data. That's nice during your application development or when you have to analyze a problem at customer site. It's wasting performance and capacity if tracing runs in healthy production system.

Traces are much bigger than logs. This data has to be written, that comes at a cost of performance. The trace code analyses the stack trace on every message that is written. That eats up performance too.

Bottom line: Tracing is convenient for problem determination, but nothing suitable for a healthy production environment. So do not ship your product with tracing configured by default.

Have a look at the configuration options

The SBLIM CIM Client for Java has a good number of configuration options. Probably you can live with the defaults we have chosen in most of the times. But have look first. There are some option you cannot find a good default for. E.g. the HTTP timeout. We've chosen zero as default which means that we will never timeout while waiting on a CIMOM response. That might not be what you want.

Pegasus local authentication

The SBLIM CIM Client for Java supports the local authentication mechanism of OpenPegasus. In order to use it you have to set a configuration property:

...
final Subject subject = new Subject();
subject.getPrincipals().add(new UserPrincipal("root"));
WBEMClientSBLIM client = (WBEMClientSBLIM) WBEMClientFactory.getClient("CIM-XML");
client.setProperty(WBEMConfigurationProperties.HTTP_AUTHENTICATION_MODULE, PegasusLocalAuthInfo.class.getName());
client.initialize(path, subject, new Locale[] { Locale.US });
...
        

With this property you specify the authentication module to be used. We ship two modules:

You might also create you own module by subclassing org.sblim.cimclient.internal.http.AuthInfo. Keep in mind this is "internal" API, so it might be subject to change.

Object Paths

An object path has the general form of [scheme:host:port//]namespace:[classname[.key=value]*]. We distinguish 3 types of object paths:

So far, so good. The scheme:host:port part is optional, so you may not rely on it. Therefore the SBLIM CIM Client for Java ignores the host information when calling CIMObjectPath.equals().

Unfortunately the CIM-XML protocol specification defines quite strange behaviour regarding object paths. E.g. an instance retrieved via EnumerateInstances contains one, but retrieved via GetInstance contains none at all. The SBLIM CIM Client hides this as best as possible from the application. Therefore you can expect a full object path any time, but the host information is still optional. See the table below:

 SBLIM CIM Client for JavaCIM-XML
Operationhostnamespaceclasname/keyshostnamespaceclasname/keys
EnumerateClassNamesnoyesyesnonoyes
EnumerateClassesnoyesyesnonoyes
GetClassnoyesyesnonoyes
EnumerateInstanceNamesnoyesyesnonoyes
EnumerateInstancesnoyesyesnonoyes
GetInstancenoyesyesnonono
AssociatorNamesmaybeyesyesmaybemaybeyes
Associatorsyesyesyesyesyesyes
ReferenceNamesmaybeyesyesmaybemaybeyes
Referencesyesyesyesyesyesyes