Overview  Package   Class  Tree  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.wbem.provider
Interface InstanceProvider

All Superinterfaces:
Provider
public interface InstanceProvider
extends Provider

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

Since:
JSR48 1.0.0

Method Summary
 CIMObjectPath createInstance(CIMInstance ci)
          Create the specified instance.
 void deleteInstance(CIMObjectPath op)
          Delete the instance specified.
 CloseableIterator enumerateInstanceNames(CIMObjectPath op)
          Enumerate the names of the instances for a specified class.
 CloseableIterator enumerateInstances(CIMObjectPath op, boolean localOnly, boolean includeClassOrigin, java.lang.String[] propertyList)
          Enumerate the instances of a class.
 CloseableIterator execQuery(CIMObjectPath op, java.lang.String query, java.lang.String ql)
          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 includeClassOrigin, java.lang.String[] propertyList)
          Get the instance specififed by the opbject path op.
 void modifyInstance(CIMInstance ci, java.lang.String[] propertyList)
          Modify the instance specified.
 
Methods inherited from interface javax.wbem.provider.Provider
close, initialize
 

Method Detail

createInstance

public CIMObjectPath createInstance(CIMInstance ci)
                             throws WBEMException
Create the specified instance.

Parameters:
ci - The instance to be created. Its keys and properties may be initialized by either the client or provider.
Returns:
the CIMObjectPath of the created instance. The provider should return non-NULL ONLY IF it initializes or changes one or more keys.
Throws:
WBEMException - 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)

deleteInstance

public void deleteInstance(CIMObjectPath op)
                    throws WBEMException
Delete the instance specified.

Parameters:
op - The object path of the instance to be deleted. It must include all of the keys.
Throws:
WBEMException - 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)

enumerateInstanceNames

public CloseableIterator enumerateInstanceNames(CIMObjectPath op)
                                         throws WBEMException
Enumerate the names of the instances for a specified class. The names of all subclass instances are returned.

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.
Returns:
An WBEMIterator that references CIMObjectPaths. Each element is an object path to an enumerated instance. If none found, then the Provider returns NULL.
Throws:
WBEMException - 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 CloseableIterator enumerateInstances(CIMObjectPath op,
                                            boolean localOnly,
                                            boolean includeClassOrigin,
                                            java.lang.String[] propertyList)
                                     throws WBEMException
Enumerate the instances of a class. The instances of all subclasses are also returned.

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 properties overridden or defined in the returned Instance are included in the response. If false, all properties of the returned Instance are returned.
includeClassOrigin - The class origin attribute is the name of the class that first defined the property. If true, the class origin attribute will be present for each property on all returned CIMInstances. If false, the class origin will not be present.
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.
Returns:
An array of CIMInstances. 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:
WBEMException - 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)

execQuery

public CloseableIterator execQuery(CIMObjectPath op,
                                   java.lang.String query,
                                   java.lang.String ql)
                            throws WBEMException
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 and propertyList is NULL; all local and inherited properties with the class origin 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.

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)
Returns:
An array of CIMInstances 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:
WBEMException - 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)

getInstance

public CIMInstance getInstance(CIMObjectPath op,
                               boolean localOnly,
                               boolean includeClassOrigin,
                               java.lang.String[] propertyList)
                        throws WBEMException
Get the instance specififed by the opbject path op.

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 properties overridden or defined in the returned Instance are included in the response. If false, all elements of the returned Instance are returned.
includeClassOrigin - The class origin attribute is the name of the class that first defined the property. If true, the class origin attribute will be present for each property returned for the CIMInstance. If false, the class origin will not be present.
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/.
Returns:
The retrieved filtered instance.
Throws:
WBEMException - 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)

modifyInstance

public void modifyInstance(CIMInstance ci,
                           java.lang.String[] propertyList)
                    throws WBEMException
Modify the instance specified.

Parameters:
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, the members of the array define one or more Property names. The Provider will modify or initialize only the values for the Property names in PropertyList. The Provider will not affect any other Property. Order is not important. The value of the specified Property is found in CIMInstance ci. If the specified Property value is not found in ci, then it will be ignored by the Provider. If PropertyList contains invalid Property names, the entire operation fails (i.e. no Property values of ci are modified). PropertyList may contain duplicate Property names. The Provider must ignore them but otherwise process the request normally. If PropertyList is an empty array, then no Property values in ci are updated. If PropertyList is NULL, then ci contains all Property values to be updated by the client or Provider. This argument can be used to perform the SetProperty operation as defined by the CIM operations over HTTP spec at http://www.dmtf.org/.
Throws:
WBEMException - 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)
Overview  Package   Class  Tree  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Java™ WBEM (JSR48) 1.0.0 API