Skip to main content
Submitted by Xenoveritas on
Topics

So I'm reading through the documentation for this product, which is rather lacking, and come against a snippet like the following (no, it wasn't originally JDBC, but to protect the guilty, it is now):

For example, the following Java code contains the executeQuery call:

if(command!=null && command.equals("RunQuery"))
{
    //query = request.getParameter("query")
    System.out.println("query "+query);
try{
     results = statement.executeQuery(query);
}

Why, yes, yes it does contain a call to executeQuery. What do you know.

Several fun things to note.

  1. They commented out the line defining the query, for some reason. Why? Who knows.
  2. The types for "query", "statement", and "results" are never given. "query" must be a string, because "request.getParameter(String)" is a JSP method that gets a string. "statement" could be anything, as could "results".
  3. For no apparent reason, the "if" block is never closed.
  4. Yes, it really was indented like that, with the nested try block out with the if block.
  5. Yes, they really did switch bracing styles in the example. Pick one, please.
  6. It never shows us how to actually use the method. OK, so it executes a query, and returns some results. How do we use the results? What are the results? We never find out...
  7. It contains code that is completely irrelevant to the example. What's command? What does it have to do with the executeQuery method? Nothing.
  8. It contains a try, but no catch. What execeptions can this thing throw? Who knows. How should we handle them? Who knows.

Effectively, this example may as well have been:

results = statement.executeQuery(query);

It tells you exactly as much as you'd know otherwise - ie, nothing.

The next example is even worse.

For example, the following Java code contains the API call openURL:

 try
{
       object.openURL( new URL ( url ) ) ;
   }
   catch ( MalformedURLException e )
   {
       .
       .
       .
   }
   catch ( Exception e )
   {
       //
       // Error opening the url
       //
       .
       .
       .
   }

OK, so we see no error handling. The MalformedURLException is part of the Java API, so that teaches us nothing. In fact, it may as well have been:

object.openURL(url);

It doesn't tell us anything about how the openURL method works, other than it can throw exceptions and takes a URL object.

In short, neither of these "examples" are really examples of anything other than how to call methods in Java which doesn't really help us learn the API. It looks like whoever wrote the documentation had a requirement to "include examples" and so they did, without worrying if the examples were actually, say, useful.

(The best part is that the first example is now deprecated. There's no mention in the documentation - anywhere - of how to use the replacement. Fortunately their demo app uses the new API, but they didn't bother documenting the new API.)