Method Signatures

If you were looking carefully at the example code in the preceding section, you might be saying something along the lines of, “Wait a minute, in GET_EXAMPLES_ARGS, I defined one argument, the location argument. What are these other two arguments, theEvent and theContext? Where did they come from and what do I do with them?” The answer partly lies in the older version of the Administration Services framework. The first version of the framework did not do all the type checking and parameter parsing that the new level does, so all command handling methods had the following signature:

  public boolean handlerMethod(CommandEvent theEvent) { }

It was up to each method to then extract and handle the arguments along the lines of:

  String theLocation = theEvent.getRawParameter("Location");		
  if (theLocation == null) {
    // oops - this shouldn't happen!
    return false;
  }

Or, if the parameter was supposed to be a numeric value:

  int theNumber = 0;
  String theValue = theEvent.getRawParameter("Value");
  if (theValue == null) {
    // oops - this shouldn't happen!
    return false;
  }
  try {
    theNumber = Integer.parseInt(theValue)
  }
  catch (Exception ex) {
    return false;
  }

In most cases, theEvent object was used mostly to get the parameters for the command. When the framework was upgraded, theEvent object was retained as the first argument to the command handler methods, even though it is rarely used.

The second argument, theContext, is actually a field in theEvent object; if you want to return results to the client, you must do so through the ServiceContext reference. Since every command handling method at some time would call theEvent.getServiceContext(), we decided to add it as a second parameter to every command handling method.

As a result of these decisions, every command handling method has the following signature:

  public boolean handlerMethod(CommandEvent theEvent,
          ServiceContext theContext,
          Class0 value0,
          ...,
          ClassN, ValueN);

Where the ClassX parameters are described by the CommandDescriptor for the method.

In addition, even though the method is declared boolean, the framework never looks at the return value from a command handler method. Return values are handled within each method by a mechanism explained later in this document.