• NAME
• DESCRIPTION
• WRITING A PROVIDER
• Initializing
• Throwing exceptions
• Logging
• Dynamic unloading
• Triggering dynamic unloading
• PROVIDER METHODS
• canUnload
• enumInstanceNames
• enumInstances
• getInstance
• createInstance
• modifyInstance
• deleteInstance
• associators
• associatorNames
• references
• referenceNames
• invokeMethod
• SEE ALSO
• AUTHOR
• COPYRIGHT

NAME

Net::OpenWBEM::Provider - Perl provider interface for OpenWBEM

DESCRIPTION

This is owperlprovider, a Perl provider interface for OpenWBEM. This lets you write OpenWBEM providers in Perl. There are also client side Perl bindings for OpenWBEM, but they are in a different package.

This module contains no functionality on its own, it merely imports the necessary modules when writing a provider.

WRITING A PROVIDER

Writing a provider involves implementing a number of functions that are called by the CIMOM whenever data from a certain class (or classes) is needed.

Here you will find some general information about writing a provider. This is followed by a list of specific functions that you can implement.

Initializing

There is no initialize function. Perform any initializing tasks by putting code outside of any functions. This code will be run immediately after the script is loaded and compiled.

Throwing exceptions

To throw an exception, just use the standard Perl die statement. The provider interface wraps each method invocation in an eval { } block and then checks the value of $@ upon return from the Perl code. If the value of $@ is defined, an exception will be raised, and the text used in the die statement will be passed back to the caller.

Logging

Access to OpenWBEM's logging facility is available through the Provider Environment provided as first argument to all methods ($env).

 my $logger = $env->getLogger();

The logger provides the following methods:

 $logger->logDebug("Message", $fileName, $lineNumber, $methodName);
 $logger->logInfo(...);
 $logger->logError(...);
 $logger->logFatalError(...);

Only the first parameter (the log message) is mandatory.

Log::Log4perl-Style - methods are provided for convenience - they fill out the $fileName, $lineNumber and $methodName fields automatically.

These are:

 $log->debug("Message");
 $log->info("Message");
 $log->warn("Message");        # same as error
 $log->error("Message");
 $log->fatal("Message"); 
 $log->logdie("Message");      # same as $log->fatal("Message"); die "Message";

Dynamic unloading

OpenWBEM has the ability to dynamically unload providers. This holds true for Net::OpenWBEM::Provider plugins, too, but you have to keep some things in mind:

• Memory consumption
  
On most platforms the memory usage of OpenWBEM will be the maximum memory usage ever reached with all simultaneously loaded perl providers.

This is due to the fact that perl never returns memory back to the system (well, on most platforms), but only reuses it internally. This means that unloading a Perl provider does not decrease OpenWBEM's memory usage, but just frees up space which may be (re-) used by a Perl provider loaded afterwards.

• Persistence and Performance issues
  
It does only make sense to unload providers which do not keep persistent things (like Database handles and the like) in memory. Even if you might be able to rewrite such stuff in a non-persistent manner, this may result in a serious performance drawback.
• Initialization
  
A provider is initialized every time it is loaded. Make sure you don't initialize things that must not be initialized twice during the lifetime of openwbem if you're writing unloadable providers.
• Unload interval
  
Currently, Net::OpenWBEM::Provider unloads all perl providers which signal that they may be unloaded, whenever the CIMOM attempts to unload providers (every minute).

In contrast to other provider interfaces, Net::OpenWBEM::Provider does not check whether the provider has been idle for some time before unloading it.

Triggering dynamic unloading

Net::OpenWBEM::Provider will only unload Perl Providers which implement the following method:

 sub canUnload { return 1; };

Returning any true value from canUnload tells the provider interface that it may unload this provider.

Net::OpenWBEM::Provider will never unload providers which do not implement this method (though it will attempt to call it).

If you have providers which may become non-unloadable after some part of work do the following:

 my $CAN_UNLOAD = 1;    # a GLOBAL !
 
 sub canUnload { return $CAN_UNLOAD; }
 
 ...
 
 # somewhere else, maybe in invokeMethod or the like
 $CAN_UNLOAD = 0;
 
The provider will not unload after you've set $CAN_UNLOAD to 0.

PROVIDER METHODS

The provider interface is still considered incomplete. A C++ OpenWBEM provider has access to functions that are not documented here, because they are not currently available to Perl providers. This is not a limitation of Perl, only that the relevant calling code has not been written.

Following each function is a more detailed list of the parameters used when the function is invoked. It lists recommended names and the types of each parameter.

canUnload

  sub canUnload
  {
      return 1;
  }

When OpenWBEM is ready to unload a provider, it calls this method first, to see if it's ok to unload. Return any true value to allow OpenWBEM to proceed with the unload.

enumInstanceNames

  sub enumInstanceNames
  {
      my ($env, $ns, $className, $result, $cimClass) = @_;
  
      # foreach underlining object...
      {
          my $mcop = Net::OpenWBEM::CIMObjectPath->new($className, $ns);
  
          # fill key properties
          # ...
  
          $result->handle($mcop);
      }
  }

$env - Net::OpenWBEM::ProviderEnvironmentIFCRef
$ns - string
$className - string - if your provider handles more than one class, this parameter can be used to determine what class it's handling.
$result - Net::OpenWBEM::CIMObjectPathResultHandlerIFC - use this object to pass back the results of the operation, e.g. $result->handle($cop)
$cimClass - Net::OpenWBEM::CIMClass - contains class information

enumInstances

  sub enumInstances
  {
      my ($env, $ns, $className, $localOnly, $deep, $includeQualifiers,
          $includeClassOrigin, $result, $cimClass, $requestedClass,
                  $propertyList) = @_;

      # foreach underlining object...
      {
          my $ci = $cimClass->newInstance;

          # set instance properties
          # ...

          $result->handle($ci);
      }
  }

$env - Net::OpenWBEM::ProviderEnvironmentIFCRef
$ns - string
$className - string - if your provider handles more than one class, this parameter can be used to determine what class it's handling.
$localOnly - unsigned integer
$deep - unsigned integer
$includeQualifiers - unsigned integer
$includeClassOrigin - unsigned integer
$result - Net::OpenWBEM::CIMInstanceResultHandlerIFC - use this object to pass back the results of the operation, e.g. $result->handle($newinstance)
$cimClass - Net::OpenWBEM::CIMClass - use this object to create new instances
$requestedClass - Net::OpenWBEM::CIMClass
$propertyList - array reference - if defined, returned instances should only contain values for properties named in this array

getInstance

  sub getInstance
  {
      my ($env, $ns, $instanceName, $localOnly, $includeQualifiers,
          $includeClassOrigin, $propertyList, $cimClass) = @_;

      # get key values from $instanceName
      my $key1 = $instanceName->getStringKeyValue('key1');
      my $key2 = $instanceName->getIntegerKeyValue('key2');

      my $ci = $cimClass->newInstance;
        
      # set instance properties
      # ...
        
      return $ci;
  }

$env - Net::OpenWBEM::ProviderEnvironmentIFCRef
$ns - string
$instanceName - Net::OpenWBEM::CIMObjectPath - identifies the requested object. Providers need to query this object to determine what instance to return.
$localOnly - unsigned integer
$includeQualifiers - unsigned integer
$includeClassOrigin - unsigned integer
$propertyList - array reference - if defined, the returned instance should only contain values for properties named in this array
$cimClass - Net::OpenWBEM::CIMClass - use this object to create the instance to return.

To denote that the instance does not exist, just return undef.

createInstance

  sub createInstance
  {
      my ($env, $ns, $cimInstance) = @_;

      # create the underlining object
      # ...

      # create a path for the new instance
      my $cop = Net::OpenWBEM::CIMObjectPath->new($ns, $cimInstance);
      return $cop;
  }

$env - Net::OpenWBEM::ProviderEnvironmentIFCRef
$ns - string
$cimInstance - Net::OpenWBEM::CIMInstance - contains the instance data as sent by the client.

modifyInstance

  sub modifyInstance
  {
      my ($env, $ns, $modifiedInstance, $previousInstance,
          $includeQualifiers, $propertyList, $theClass) = @_;
        
      # modify the underlining data
      # ...
  }

$env - Net::OpenWBEM::ProviderEnvironmentIFCRef
$ns - string
$modifiedInstance - Net::OpenWBEM::CIMInstance
$previousInstance - Net::OpenWBEM::CIMInstance
$includeQualifiers - unsigned integer
$propertyList - array reference
$theClass - Net::OpenWBEM::CIMClass - use this object to create the instance to return.

deleteInstance

  sub deleteInstance
  {
      my ($env, $ns, $cop) = @_;

      # delete the underlining object
      # ...
  }

$env - Net::OpenWBEM::ProviderEnvironmentIFCRef
$ns - string
$cop - Net::OpenWBEM::CIMObjectPath - identifies the object that should be deleted

associators

  sub associators
  {
      my ($env, $result, $ns, $objectName, $assocClass, $resultClass,
          $role, $resultRole, $includeQualifiers, $includeClassOrigin,
          $propertyList) = @_;

      # for each underlining associated object...
      {
          my $ci = ...

          # set instance properties
          # ...

          $result->handle($ci);
      }
  }

$env - Net::OpenWBEM::ProviderEnvironmentIFCRef
$result - Net::OpenWBEM::CIMInstanceResultHandlerIFC - use this object to pass back the results of the operation, e.g. $result->handle($newinstance)
$ns - string
$objectName - Net::OpenWBEM::CIMObjectPath
$assocClass - string - Use this class to determine what class your provider is handling.
$resultClass - string
$role - string
$resultRole - string
$includeQualifiers - unsigned integer
$includeClassOrigin - unsigned integer
$propertyList - array reference - if defined, returned instances should only contain values for properties named in this array

associatorNames

  sub associatorNames
  {
      my ($env, $result, $ns, $objectName, $assocClass, $resultClass,
          $role, $resultRole) = @_;

      # foreach underlining associated object...
      {
          my $mcop = Net::OpenWBEM::CIMObjectPath->new($className, $ns);

          # fill key properties
          # ...

          $result->handle($mcop);
      }
  }

$env - Net::OpenWBEM::ProviderEnvironmentIFCRef
$result - Net::OpenWBEM::CIMObjectPathResultHandlerIFC - use this object to pass back the results of the operation, e.g. $result->handle($cop)
$ns - string
$objectName - Net::OpenWBEM::CIMObjectPath
$assocClass - string - Use this class to determine what class your provider is handling.
$resultClass - string
$role - string
$resultRole - string

references

  sub references
  {
      my ($env, $result, $ns, $objectName, $resultClass,
          $role, $includeQualifiers, $includeClassOrigin,
          $propertyList) = @_;

      # for each association...
      {
          my $ci = ...

          # set instance properties
          # ...

          $result->handle($ci);
      }
  }

$env - Net::OpenWBEM::ProviderEnvironmentIFCRef
$result - Net::OpenWBEM::CIMInstanceResultHandlerIFC - use this object to pass back the results of the operation, e.g. $result->handle($newinstance)
$ns - string
$objectName - Net::OpenWBEM::CIMObjectPath
$resultClass - string
$role - string
$includeQualifiers - unsigned integer
$includeClassOrigin - unsigned integer
$propertyList - array reference - if defined, returned instances should only contain values for properties named in this array

referenceNames

  sub referenceNames
  {
      my ($env, $result, $ns, $objectName, $resultClass, $role) = @_;

      # for each association...
      {
          my $mcop = Net::OpenWBEM::CIMObjectPath->new($resultClass, $ns);

          # fill key properties
          # ...

          $result->handle($mcop);
      }
  }

$env - Net::OpenWBEM::ProviderEnvironmentIFCRef
$result - Net::OpenWBEM::CIMObjectPathResultHandlerIFC - use this object to pass back the results of the operation, e.g. $result->handle($mcop)
$ns - string
$objectName - Net::OpenWBEM::CIMObjectPath
$resultClass - string
$role - string

invokeMethod

  sub invokeMethod
  {
      my ($env, $ns, $objectName, $methodName, $inParams, $outParams) = @_;

      # generate a value...
      my $value = ....
      return $value;
  }

$env - Net::OpenWBEM::ProviderEnvironmentIFCRef
$ns - string
$objectName - Net::OpenWBEM::CIMObjectPath
$methodName - string - name of the method being invoked
$inParams - CIMParamValueArray
$outParams - CIMParamValueArray

SEE ALSO

  Net::OpenWBEM
  Net::OpenWBEM::Client

AUTHOR

Jason Long - jason@long.name

COPYRIGHT

This file is part of owperlprovider.

Copyright (c) 2004-2005 Jason Long. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.