Writing a Provider that Parses WQL Query Strings

The general procedure for writing a provider that parses WQL queries using the Query APIs follows.

How to Write A Provider that Parses WQL Query Strings

1. Initialize the WQL parser, for example:

   ---

    
       /* Read query string passed to execQuery from the CIM Object 
          Manager into an input data stream. */
       ByteArrayInputStream in = new ByteArrayInputStream(query.getBytes()); 
   
       /* Initialize the parser with the input data stream. */
       WQLParser parser = new WQLParser(in);
          

   ---

2. Create a vector to store the result of the query. For example:

   ---

    
       Vector result = new Vector();

   ---

3. Get the select expression from the query. For example:

   ---

    
       /* querySpecification returns the WQL expression from the parser.
         (SelectExp)parser casts the WQL expression to a select expression. */
       SelectExp q = (SelectExp)parser.querySpecification();  

   ---

4. Get the select list from the select expression. For example:

   ---

    
       /* Use the SelectList method in the SelectExp class
          to return the select list. The select list is the list 
          of attributes, or CIM properties. */
       SelectList attrs = q.getSelectList();     

   ---

5. Get the From clause. For example:

   ---

    
       /* Use the getFromClause method in the SelectExp class 
          to return the From clause. Cast the From clause to a 
          Non Join Expression, a table that represents a single 
          CIM class. */
       NonJoinExp from = (NonJoinExp)q.getFromClause();

   ---

6. Use the enumInstances method to return a deep enumeration of the class. For example:

   ---

    
      /* Returns all instances, including inherited and local properties, 
         belonging to the specified class (cc). */
       Vector v = new Vector();
       v = enumInstances(op, true, cc, true);
       ...  

   ---

7. Iterate through the instances in the enumeration, matching the query expression and select list to each instance. For example:

   ---

    
     /* Test whether the query expression in the WHERE 
   	    clause matches the CIM instance. Apply the select 
        list to the CIM instance and add any instance that 
        matches the select list (list of CIM properties) 
        to the result. */
     for (int i = 0; i < v.size(); i++) {
   	  if ((where == null) || // If there is a WHERE clause
     	    (where.apply((CIMInstance)v.elementAt(i)) == true)) { 
   	         result.addElement(attrs.apply((CIMInstance)v.elementAt(i)));
      ...        

   ---

8. Return the query result. For example:

   return result;

Example — Implementing the execQuery Method

The sample program in Example 5–6 uses the Query APIs to parse the WQL string passed to it by the execQuerymethod. This program parses the Select Expression in the query string, does a deep enumeration of the class, and iterates through the instances in the enumeration, matching the query expression and select list to each instance. Finally, the program returns a vector containing the enumeration of the instances that match the query string.

Example 5–6 Provider that Implements the execQuery Method

/*
     * The execQuery method will support only limited queries 
     * based upon partial key matching. An empty Vector is 
     * returned if no entries are selected by the query.
     *
     * @param	op			The CIM object path of the CIM instance to be returned
     * @param	query	The CIM query expression
     * @param	ql			The CIM query language indicator
     * @param	cc			The CIM class reference
     *
     * @return	A vector of CIM object instances
     *
     * @version    1.19	01/26/00
     * @author	   Sun Microsystems, Inc.
     */
    public Vector execQuery(CIMObjectPath op, 
			    String query, 
			    int ql,
			    CIMClass cc) 
	    throws CIMException {

	ByteArrayInputStream in = new ByteArrayInputStream(query.getBytes());
	WQLParser parser = new WQLParser(in);
	Vector result = new Vector();
	try {
	    SelectExp q = (SelectExp)parser.querySpecification();
	    SelectList attrs = q.getSelectList();
	    NonJoinExp from = (NonJoinExp)q.getFromClause();
	    QueryExp where = q.getWhereClause();

	    Vector v = new Vector();
	    v = enumInstances(op, false, cc, true);

	    // filtering the instances
	    for (int i = 0; i < v.size(); i++) {
		    if ((where == null) || (where.apply((CIMInstance)v.elementAt(i)) == true)) {
		        result.addElement(attrs.apply((CIMInstance)v.elementAt(i)));
		     } 
	    }
	} catch (Exception e) {
	    throw new CIMException(CIMException.CIM_ERR_FAILED, e.toString());
	}
	return result;
    } // execQuery
}