Gathering Handy Constants

The wonderful world of science and mathematics is replete with useful constant values. For this example, let's just pick three:

• pi = 3.14159265...
• e = 2.7182818285...
• gamma = 0.577215664...

In Java code, we can set up those values as a Map in a static field. Thus we start forming our source file, ConstantHandler.java :

import java.util.HashMap;
import java.util.Map;
import jpl.eda.product.QueryHandler;
public class ConstantHandler
  implements QueryHandler {
  private static final Map CONSTANTS = new HashMap();
  static {
    CONSTANTS.put("pi",    "3.14159265...");
    CONSTANTS.put("e",     "2.7182818285...");
    CONSTANTS.put("gamma", "0.577215664...");
  }
}

As you can see, we're storing both the constant name and its value as java.lang.String objects.

Defining the Query Expression

Recall that the XMLQuery class can use parsed queries (where it generates postfix boolean stacks) or unparsed ones. While unparsed ones are easier, we'll go with parsed ones to demonstrate how on the server-side you deal with those postfix stacks.

Using the XMLQuery's expression language, we'll look for queries of the form:

constant = name

where name is the name of a constant. That will form a postfix "where" stack with exactly three QueryElement objects on it:

1. The first (top) QueryElement will have role = elemName and value = constant .
2. The second (middle) QueryElement will have role = LITERAL and a value equal to the constant name .
3. The third (bottom) QueryElement will have role = RELOP and value = EQ .

If we get any other kind of stack, we'll reject it and return no matching results. That's reasonable behavior; after all, a query for donutsEaten > 5 AND RETURN = episodeNumber may be handled by a SimpsonsEpisodeQueryHandler that's also installed in the same product server.

We'll define a utility method, getConstantName , that will take the XMLQuery , check for the postfix "where" stack as described, and return the matching constant name . If it gets a stack whose structure doesn't match, it will return null . We'll add this method to our ConstantHandler.java file:

import java.util.List;
import jpl.eda.xmlquery.XMLQuery;
import jpl.eda.xmlquery.QueryElement;
...
public class ConstantHandler
  implements QueryHandler {
  ...
  private static String getConstantName(XMLQuery q) {
    List stack = q.getWhereElementSet();
    if (stack.size() != 3) return null;
    QueryElement e = (QueryElement) stack.get(0);
    if (!"elemName".equals(e.getRole())
      || !"constant".equals(e.getValue()))
      return null;
    e = (QueryElement) stack.get(2);
    if (!"RELOP".equals(e.getRole())
      || !"EQ".equals(e.getValue()))
      return null;
    e = (QueryElement) stack.get(1);
    if (!"LITERAL".equals(e.getRole()))
	return null;
    return e.getValue();
  }
}

Here, we first check to make sure there's exactly three elements, returning null if not. There's no need to go further.

Assuming there's three elements, the code then checks the topmost element. For an expression constant = name , the topmost element will have role elemName and value constant . If neither condition is true, we return null right away. No need to check further.

If the topmost element checks out, we then check the bottommost element. For constant = name , the bottom element is generated from the equals sign. It will have role RELOP (relational operator) and value EQ , meaning "equals".

If it checks out, all we have to do is check the middle element. The infix expression constant = name generates a postfix middle element of name as the value, with a role of LITERAL . We make sure it's LITERAL . If not, we're done; it's not a valid expression for our query handler.

But if so, then the value of that query element is the name of the desired constant. So we return it, regardless of what it is.

Checking for Acceptable MIME Types

Since all of our mathematical constants are strings, we'll say that the result MIME type of our products is text/plain . That means that any incoming XMLQuery must include any of the following MIME types:

1. text/plain
2. text/*
3. */*

All of these match text/plain , which is the only product type we're capable of serving. (In your own product servers, you might have more complex logic; for example, you could write code to draw the numbers into an image file if the requested type is image/jpeg ... but I wouldn't want to.)

To support this in our query handler, we'll write another utility method. It'll be called isAcceptableType , and it will take the XMLQuery and examine it to see what MIME types are acceptable to the caller. If it finds any of the ones in the above list, it will return true , and the caller can continue to process the query. If not, it will return false , and the query handler will stop processing and return the XMLQuery unadorned with any results.

Here's the code:

import java.util.Iterator;
...
public class ConstantHandler
  implements QueryHandler {
  ...
  private static boolean isAcceptableType(XMLQuery q) {
    List mimes = q.getMimeAccept();
    if (mimes.isEmpty()) return true;
    for (Iterator i = mimes.iterator(); i.hasNext();) {
      String type = (String) i.next();
      if ("text/plain".equals(type)
        || "text/*".equals(type)
        || "*/*".equals(type)) return true;
    }
    return false;
  }
}

Here, we check if the list of acceptable MIME types is empty. An empty list is the same as saying */* , so that automatically says we've got an acceptable type. For a non-empty list, we go t hrough each type one-by-one. If it's any of the strings text/plain , text/* , or */* , then that's an acceptable type.

However, if we get through the entire list and we don't find any type that the user wants that we can provide, we return false . The query handler will check for a false value and return early from handling the query, leaving the XMLQuery untouched.

Inserting the Result

Assuming the query handler has found an acceptable MIME type, and has found a valid query and the name of the desired constant, it can lookup the constant in the CONSTANTS map. And assuming it finds a matching constant in that map, it can insert the value as a Result object.

To insert the constant's value, we'll develop yet another utility method, this time called insert . This method will take the name of the constant, its value, and the XMLQuery . It will add a Result object to the XMLQuery . When the query handler returns this modified XMLQuery object, the framework will return it to the product client, which can then display the matching result.

Result objects can also have optional Header objects that serve as "column headings" for tabular like results. Our result isn't tabular, it's just a single value, but we'll add a heading anyway just to demonstrate how it's done. (You could argue that it's a one-by-one table, too!) The header's name will be the same as the constant's name; the data type will be real and the units will be none .

Here's the code:

import java.util.Collections;
import jpl.eda.xmlquery.Header;
import jpl.eda.xmlquery.Result;
...
public class ConstantHandler
  implements QueryHandler {
  ...
  private static void insert(String name,
    String value, XMLQuery q) {
    Header h = new Header(name, "real", "none");
    Result r = new Result(name, "text/plain",
      /*profileID*/null, /*resourceID*/null,
      Collections.singletonList(h),
      value, /*classified*/false, Result.INFINITE);
    q.getResults().add(r);
  }
}

In this method, we first create the header. Then we create the result; the result's ID (which differentiates it from other results in the same XMLQuery is just the name of the constant. Its MIME type is text/plain . We set the profile ID and resource ID fields to null , as recommended back in the XMLQuery Tutorial . Then we add our sole header. Then we add the mathematical constant's value. Finally, this constant isn't classified, so we set the classified flag to false . Also, these mathematical constants should be valid forever, so we set the validity period to Result.INFINITE , a special value that means a never-ending validity period.

Handling the Query

With all of these utility methods in hand, it's easy to handle the query now. The jpl.eda.product.QueryHandler interface specifies a single method that we must implement, query . This method accepts an XMLQuery object and returns an XMLQuery object. The returned one may or may not be adorned with matching results.

Here's what we have to do:

1. Get the constant name with getConstantName . If we get null , it means the query's not of the form constant = name , so we ignore it.
2. See if the user's willing to accept a text/plain MIME type. If not, we ignore this query.
3. Find the constant in our CONSTANTS map. If it's not there, we ignore this query.
4. Insert the constant's value into the XMLQuery .
5. Returned the modified XMLQuery .

The source:

public class ConstantHandler
  implements QueryHandler {
  ...
  public XMLQuery query(XMLQuery q) {
    String name = getConstantName(q);
    if (name == null) return q;
    if (!isAcceptableType(q)) return q;
    String value = (String) CONSTANTS.get(name);
    if (value == null) return q;
    insert(name, value, q);
    return q;
  }
}

Complete Source Code

Here is the complete source file, ConstantHandler.java :

import java.util.Collections;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import jpl.eda.product.QueryHandler;
import jpl.eda.xmlquery.Header;
import jpl.eda.xmlquery.Result;
import jpl.eda.xmlquery.QueryElement;
import jpl.eda.xmlquery.XMLQuery;

public class ConstantHandler
  implements QueryHandler {
  private static final Map CONSTANTS = new HashMap();
  static {
    CONSTANTS.put("pi",    "3.14159265...");
    CONSTANTS.put("e",     "2.7182818285...");
    CONSTANTS.put("gamma", "0.577215664...");
  }
  private static String getConstantName(XMLQuery q) {
    List stack = q.getWhereElementSet();
    if (stack.size() != 3) return null;
    QueryElement e = (QueryElement) stack.get(0);
    if (!"elemName".equals(e.getRole())
      || !"constant".equals(e.getValue()))
      return null;
    e = (QueryElement) stack.get(2);
    if (!"RELOP".equals(e.getRole())
      || !"EQ".equals(e.getValue()))
      return null;
    e = (QueryElement) stack.get(1);
    if (!"LITERAL".equals(e.getRole()))
	return null;
    return e.getValue();
  }
  private static boolean isAcceptableType(XMLQuery q) {
    List mimes = q.getMimeAccept();
    if (mimes.isEmpty()) return true;
    for (Iterator i = mimes.iterator(); i.hasNext();) {
      String type = (String) i.next();
      if ("text/plain".equals(type)
        || "text/*".equals(type)
        || "*/*".equals(type)) return true;
    }
    return false;
  }
  private static void insert(String name,
    String value, XMLQuery q) {
    Header h = new Header(name, "real", "none");
    Result r = new Result(name, "text/plain",
      /*profileID*/null, /*resourceID*/null,
      Collections.singletonList(h),
      value, /*classified*/false, Result.INFINITE);
    q.getResults().add(r);
  }
  public XMLQuery query(XMLQuery q) {
    String name = getConstantName(q);
    if (name == null) return q;
    if (!isAcceptableType(q)) return q;
    String value = (String) CONSTANTS.get(name);
    if (value == null) return q;
    insert(name, value, q);
    return q;
  }
}

How should you go about compiling this and installing it in a product server? Read on!