Rocket Science » SpaceKit for Java » Tutorial Rocket Science Index »

SpaceKit for Java, page 6 1 Introduction 2 The Blocks SpaceKit for Java Client 3 Connecting and Channel Creation 4 Client Examples 5 The Blocks SpaceKit for Java Server: SpaceBxxd » SpaceBxxd - Responses 7 Localization Class Structure and Utilities 8 Reference this article in RFC-2629 formats

The Blocks SpaceKit for Java Server: SpaceBxxd Responses

download the code | copyright | legal | join the discussion list

      Four types of responses are available to client requests:

1. start
2. response
3. error
4. fatal

The start Response

      When any module receives a request, the module must first determine whether it is a start channel request. If it is, it should respond using the start method with content as defined by the module API. An empty response is commonly used to acknowledge the start of a channel:

if(isStart()) {
     start("");
     return;
     }

The response Response

      A response() is the normal method to respond to a request.

String results = yourResultsMethod();
respond(results);

The error Response

      Use the error() method to return error responses. To return a standard error response, such as error code 550:

     error(550);

      To return your own error code and message use:

     error(1000,"Your Error Message");

      See SpaceMessage in the reference section for a list of standard error messages.

      The error() methods log the errors as described in Logging below.

The fatal Response

      In the event that a SpaceException or SpaceTimeout is thrown in your module, at a minimum the fatal() method should be called when catching either exception:

catch(SpaceTimeout e) {
     //--------------------------------------------------------------------
     //  timeout
     //--------------------------------------------------------------------
     fatal(e);
     }
catch(SpaceException e) {
     //--------------------------------------------------------------------
     //  exception
     //--------------------------------------------------------------------
     fatal(e);
     }

      The fatal() method logs the exception as described in Logging below.

      The fatal() method may be called any time in your catch clause. It does not have to be the first or last call in the clause.

      The error() methods log the errors as described in Logging below.

Logging

      The log() methods cause a message to be appended to the log file specified for the port in the configuration file.

      The first form of the log method implies a "SpaceLog.info" message level:

log("your log message");

      The second form of the log method takes a message level and message as arguments:

log(SpaceLog.notify,"your notify message");

      See SpaceLog in the reference section for a complete list of message levels.

      The log contains the following items on each line:

• Date in the format mm/dd.
• Time in the form hh:mm:ss.
• Port number.
• If appropriate, the channel number on the port.
• If appropriate, the serial number of the request.
• The message text.

      Sample log messages from SpaceModuleREVERSE:

03/18 12:01:16 info    12345       listen
03/18 12:01:26 info    12345       connect
03/18 12:01:27 info    12345.0.1   module Reverse
03/18 12:01:27 info    12345.0.1   start
03/18 12:01:27 info    12345.1.1   module Reverse
03/18 12:01:27 info    12345.1.1   start
03/18 12:01:27 info    12345.1.1   reverse request complete
03/18 12:01:27 info    12345       disconnect

      The "module Reverse" message shows two times because the first request on channel 0 is the start channel request. The second message is from the request itself on channel 1. Since serial numbers are reused, both requests used serial number 1 in this example.

Users

      The user definition file for a particular port can be loaded using the loadUser() method. This loads all users for the port into a SpaceUserCache(). Note that subsequent calls to the method recognize that the cache is already loaded and therefore it will not be reloaded unnecessarily.

      The method getUser() gets a specific element from the cache. For example, if the user file contains this entry for the user fmorton:

username.fmorton.authentication.sequence=9911

      To get that value, pass the element class and name to the method:

String sequence = getUser("fmorton","authentication","sequence");

      Define any additional classes and elements by inserting the text into the user definition file. For example, if the SpaceModuleREVERSE wanted to optionally capitalize the reversed response for certain users, add an element:

username.fmorton.reverseattribute.capitalize=yes

      Then to get the value of the capitalize element in the module:

String capitalize = getUser("fmorton","reverseattribute","capitalize");

      The user definition file can contain any number of elements in any order.

Saving State

      Since multiple requests can be made on a channel, saving results from a previous request is often necessary. Every channel has an optional list of parameters that may be set. The parameters are key-value pairs.

      Parameters may be set on channel zero, the start channel and the current channel using:

1. setOnChannelZero()
2. setOnStartChannel()
3. set()

      As an example, the SpaceModuleSASLOTP saves the authenticator as a channel parameter during channel start in both the start channel and channel zero:

setOnChannelZero("authenticator",authenticator);
setOnStartChannel("authenticator",authenticator);

      Where the variable "authenticator" contains, as an example, the value "fmorton."

      To set a parameter on the current channel:

set("thingtoremenber",thingtoremember);

      To retrieve a value, use the following access methods:

1. getFromChannelZero()
2. getFromStartChannel()
3. get()

      To retrieve the authenticator from channel zero set by SpaceModuleSASLOTP:

String authenticator = getFromChannelZero("authenticator");

      Any number of parameters by any name may be set.

Next » Localization Class Structure and Utilities.

 Copyright © 2000 Invisible Worlds. All Rights Reserved.

contact | about | site map | home