javax.wbem.provider
Interface CIMInstanceProvider

All Superinterfaces:

CIMProvider

public interface CIMInstanceProvider

extends CIMProvider

This is the interface implemented by instance providers. Instance providers are used to serve up dynamic instances of classes.

Since:

WBEM 1.0

Method Summary

CIMObjectPath	createInstance(CIMObjectPath op, CIMInstance ci) This method creates the instance specified by the CIMInstance argument in the namespace specified by the CIMObjectPath argument.
void	deleteInstance(CIMObjectPath op) This method deletes the instance specified by the CIMObjectPath argument.
CIMObjectPath[]	enumerateInstanceNames(CIMObjectPath op, CIMClass cc) This method enumerates all of object paths to the instances of the class which is specified by the CIMObjectPath argument.
CIMInstance[]	enumerateInstances(CIMObjectPath op, boolean localOnly, boolean includeQualifiers, boolean includeClassOrigin, java.lang.String[] propertyList, CIMClass cc) This method enumerates all instances of the class specified by the CIMObjectPath argument.
CIMInstance[]	execQuery(CIMObjectPath op, java.lang.String query, java.lang.String ql, CIMClass cc) This method enumerates all instances of the class specified by the CIMObjectpath argument that satisfy the conditions defined by the query expression (query) in query language type (ql).
CIMInstance	getInstance(CIMObjectPath op, boolean localOnly, boolean includeQualifiers, boolean includeClassOrigin, java.lang.String[] propertyList, CIMClass cc) This method retrieves the instance specified by the CIMObjectPath argument.
void	setInstance(CIMObjectPath op, CIMInstance ci, CIMArgument[] propertyList) This method modifies the instance specified by by the CIMInstance argument in the namespace specified by the CIMObjectPath argument.

Methods inherited from interface javax.wbem.provider.CIMProvider

cleanup, initialize

Method Detail

enumerateInstanceNames

public CIMObjectPath[] enumerateInstanceNames(CIMObjectPath op,
                                              CIMClass cc)
                                       throws CIMException

This method enumerates all of object paths to the instances of the class which is specified by the CIMObjectPath argument. Just the object paths to the instances are returned, not the entire instances. This method is invoked in order to perform the EnumerateInstanceNames operation as defined by the CIM operations over HTTP spec at http://www.dmtf.org/.

Parameters:

op - The object path of the class to be enumerated. Only the name space and class name components are used. Any other information (e.g. keys) is ignored.

cc - The CIM class object

Returns:

An array of CIMObjectPath. Each element is an object path to an enumerated instance. If none found, then the Provider returns NULL.

Throws:

CIMException - If unsuccessful, one of the following status codes may be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED (provider does not support this method),
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (for this method),
   CIM_ERR_INVALID_CLASS (in this namespace),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

enumerateInstances

public CIMInstance[] enumerateInstances(CIMObjectPath op,
                                        boolean localOnly,
                                        boolean includeQualifiers,
                                        boolean includeClassOrigin,
                                        java.lang.String[] propertyList,
                                        CIMClass cc)
                                 throws CIMException

This method enumerates all instances of the class specified by the CIMObjectPath argument. The entire instances and not just the object paths to them are returned. This method is invoked in order to perform the EnumerateInstances operation as defined by the CIM operations over HTTP spec at http://www.dmtf.org/.

Parameters:

op - The object path of the class to be enumerated. Only the name space and class name components are used. Any other information (e.g. keys) is ignored.

localOnly - If true, only elements (properties, methods and qualifiers) defined or overridden within the class are included in the response. Propagated properties are NOT included, since their values are based on information in another class. If false, all elements of the class definition are returned. When instances are returned, the InstanceName must include all keys, including Propagated keys. So these attributes are included in the "name" part of the method response, but not in the "value" information.

includeQualifiers - If true, all Qualifiers for each Instance (including Qualifiers on the Instance and on any returned Properties) MUST be included as elements in the response. If false, no Qualifier elements are present in each returned Instance.

includeClassOrigin - If true, the CLASSORIGIN attribute MUST be present on all appropriate elements in each returned Instance. If false, no CLASSORIGIN attributes are present in each returned Instance. It is attached to a property to indicate the class where that property is first defined.

propertylist - If the PropertyList input parameter is not NULL, the members of the array define one or more Property names. Each returned Instance MUST NOT include elements for any Properties missing from this list. Note that if LocalOnly is specified as true this acts as an additional filter on the set of Properties returned (e.g. if Property A is included in the PropertyList but LocalOnly is set to true and A is not local to a returned Instance, then it will not be included in that Instance). If the PropertyList input parameter is an empty array this signifies that no Properties are included in each returned Instance. If the PropertyList input parameter is NULL this specifies that all Properties (subject to the conditions expressed by the other parameters) are included in each returned Instance. The PropertyList may contain duplicate or invalid Property names. The Provider must ignore them but otherwise process the request normally; i.e. the returned Instance(s) will not contain duplicate or invalid Property Names.

cc - The CIM class object

Returns:

An array of CIMInstance. Each element is the actual filtered instance. The Provider must ensure that no duplicate instances are returned. If none found, then the Provider returns NULL.

Throws:

CIMException - If unsuccessful, one of the following status codes may be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED (provider does not support this method),
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (for this method),
   CIM_ERR_INVALID_CLASS (in this namespace),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

getInstance

public CIMInstance getInstance(CIMObjectPath op,
                               boolean localOnly,
                               boolean includeQualifiers,
                               boolean includeClassOrigin,
                               java.lang.String[] propertyList,
                               CIMClass cc)
                        throws CIMException

This method retrieves the instance specified by the CIMObjectPath argument. This method is invoked in order to perform the GetInstance operation as defined by the CIM operations over HTTP spec at http://www.dmtf.org/. It can also be used to perform the GetProperty operation.

Parameters:

op - The object path of the instance to be retrieved. This must include all of the keys for the instance.

localOnly - If true, only elements (properties and qualifiers) defined or overridden within the class are included in the response. Propagated properties are NOT included, since their values are based on information in another class. If false, all elements of the class definition are returned. When instances are returned, the InstanceName must include all keys, including Propagated keys. So these attributes are included in the "name" part of the method response, but not in the "value" information.

includeQualifiers - If true, all Qualifiers for each Instance (including Qualifiers on the Instance and on any returned Properties) MUST be included as elements in the response. If false, no Qualifier elements are present in each returned Instance.

includeClassOrigin - If true, the CLASSORIGIN attribute MUST be present on all appropriate elements in each returned Instance. If false, no CLASSORIGIN attributes are present in each returned Instance. It is attached to a property to indicate the class where that property is first defined.

propertylist - If the PropertyList input parameter is not NULL, the members of the array define one or more Property names. Each returned Instance MUST NOT include elements for any Properties missing from this list. Note that if LocalOnly is specified as true this acts as an additional filter on the set of Properties returned (e.g. if Property A is included in the PropertyList but LocalOnly is set to true and A is not local to a returned Instance, then it will not be included in that Instance). If the PropertyList input parameter is an empty array this signifies that no Properties are included in each returned Instance. If the PropertyList input parameter is NULL this specifies that all Properties (subject to the conditions expressed by the other parameters) are included in each returned Instance. The PropertyList may contain duplicate or invalid Property names. The Provider must ignore them but otherwise process the request normally; i.e. the returned Instance(s) will not contain duplicate or invalid Property Names. This argument can be used to perform the GetProperty operation as defined by the CIM operations over HTTP spec at http://www.dmtf.org/.

cc - The CIM class object

Returns:

CIMInstance The retrieved filtered instance.

Throws:

CIMException - If unsuccessful, one of the following status codes may be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED (provider does not support this method),
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (for this method),
   CIM_ERR_INVALID_CLASS (in this namespace),
   CIM_ERR_NOT_FOUND (if instance does not exist),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

createInstance

public CIMObjectPath createInstance(CIMObjectPath op,
                                    CIMInstance ci)
                             throws CIMException

This method creates the instance specified by the CIMInstance argument in the namespace specified by the CIMObjectPath argument. This method is invoked in order to perform the CreateInstance operation as defined by the CIM operations over HTTP spec at http://www.dmtf.org/.

Parameters:

op - The object path of the instance to be created. Only the name space component is used. Any other information (e.g. keys) is ignored.

ci - The instance to be created. Its keys and properties may be initialized by either the client or provider.

Returns:

CIMObjectPath of the created instance. The provider should return non-NULL ONLY IF it initializes or changes one or more keys.

Throws:

CIMException - If unsuccessful, one of the following status codes may be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED (provider does not support this method),
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (for this method),
   CIM_ERR_INVALID_CLASS (in this namespace),
   CIM_ERR_ALREADY_EXISTS,
   CIM_ERR_FAILED (some other unspecified error occurred)
 

setInstance

public void setInstance(CIMObjectPath op,
                        CIMInstance ci,
                        CIMArgument[] propertyList)
                 throws CIMException

This method modifies the instance specified by by the CIMInstance argument in the namespace specified by the CIMObjectPath argument. This method is invoked in order to perform the ModifyInstance operation as defined by the CIM operations over HTTP spec at http://www.dmtf.org/. It can also be used to perform the SetProperty operation.

Parameters:

op - The object path of the instance to be set. It must include all of the keys.

ci - The instance to be set. Its properties may be initialized by either the client or Provider.

propertylist - If the PropertyList input parameter is not NULL, each array element define a Property name and its new value. The Provider will modify or initialize only the values for the Property names in PropertyList. The Provider will not affect another other Property. Order is not important. PropertyList may contain duplicate or invalid Property names. The Provider must ignore them but otherwise process the request normally. The value of a duplicate Property name will override its previous value. This argument can be used to perform the SetProperty operation as defined by the CIM operations over HTTP spec at http://www.dmtf.org/. If the PropertyList input parameter is NULL, then ci contains all property values to be initialized by the client or Provider.

Throws:

CIMException - If unsuccessful, one of the following status codes may be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED (provider does not support this method),
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (for this method),
   CIM_ERR_INVALID_CLASS (in this namespace),
   CIM_ERR_NOT_FOUND (if instance does not exist),
   CIM_ERR_NO_SUCH_PROPERTY (in this instance),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

deleteInstance

public void deleteInstance(CIMObjectPath op)
                    throws CIMException

This method deletes the instance specified by the CIMObjectPath argument. This method is invoked in order to perform the DeleteInstance operation as defined by the CIM operations over HTTP spec at http://www.dmtf.org/.

Parameters:

op - The object path of the instance to be deleted. It must include all of the keys.

Throws:

CIMException - If unsuccessful, one of the following status codes may be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED (provider does not support this method),
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (for this method),
   CIM_ERR_INVALID_CLASS (in this namespace),
   CIM_ERR_NOT_FOUND (if instance does not exist),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

execQuery

public CIMInstance[] execQuery(CIMObjectPath op,
                               java.lang.String query,
                               java.lang.String ql,
                               CIMClass cc)
                        throws CIMException

This method enumerates all instances of the class specified by the CIMObjectpath argument that satisfy the conditions defined by the query expression (query) in query language type (ql). The entire instances are returned, not just the object paths to them. NOTE: This method operates as if localOnly is false, includeQualifiers is true, includeClassOrigin is true and propertyList is NULL; i.e. all qualifiers and all local and inherited properties with CLASSORIGIN attributes of each instance are returned.

Typically, a provider parses the query string, enumerates the instances in the class (op), and then filters those instances to match the query string (query) expressed using the specified query language (ql). The provider then returns an array containing the instances that match the query string.

This method is invoked in order to perform the ExecQuery operation as defined by the CIM operations over HTTP spec at http://www.dmtf.org/. NOTE: In the CIM operations over HTTP spec at http://www.dmtf.org/, ExecQuery is its own functional group. For convenience, it is included as part of the Instance Provider, instead of in a separate Query Provider.

Providers with access to an entity that handles indexing can pass the query string to that entity for parsing. For those providers who do not have any indexing/query filtering capabilites, the provider may ask the CIM object manager to handle the filtering. A return array of all CIMInstance which have a possibility of matching the filter may be returned (this can be the same result as an enumerate instances call), but with the first element of the array set to NULL. This NULL value indicates to the CIM object manager that it needs to handle the filtering. The filter is applied by the object manager and the filtered result is returned to the client.

Parameters:

op - The object path of the class to enumerate and apply the query to. Only the name space and class name components are used. Any other information (e.g. keys) is ignored.

query - The CIM query expression (e.g. SELECT *)

ql - The CIM query language type (e.g. WQL)

cc - The CIM class object.

Returns:

An array of CIMInstance that met the specified criteria. Each element is an actual instance. The Provider must ensure that no duplicate instances are returned. If none found, then the Provider returns NULL.

Throws:

CIMException - If unsuccessful, one of the following status codes may be returned. The ORDERED list is:

    CIM_ERR_ACCESS_DENIED,
    CIM_ERR_NOT_SUPPORTED (provider does not support this method),
    CIM_ERR_INVALID_NAMESPACE,
    CIM_ERR_INVALID_PARAMETER (for this method),
    CIM_ERR_QUERY_LANGUAGE_NOT_SUPPORTED,
    CIM_ERR_INVALID_QUERY,
    CIM_ERR_FAILED (some other unspecified error occurred)