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

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

The Blocks SpaceKit for Java Server: SpaceBxxd Configuration

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

Configuration File Format

      SpaceBxxd requires a configuration file in order to start.

      The configuration file defines general server parameters as well as the available profiles and their associated parameters. A typical configuration file contains the following parameters and profiles:

  <?xml version="1.0"?>

  <!DOCTYPE config PUBLIC "-//Blocks//DTD BXXD CONFIG//EN"
            "http://xml.resource.org/blocks/bxxd/config.dtd">

  <config>
    <bxxd port="10288">
      <parameter name="homeDirectory"   value="/usr/local/bxxd" />
      <parameter name="moduleDirectory" value="modules" />
      <parameter name="banner"
                 value="sqa.invisible.net ready to go" />
      <parameter name="logFile"         value="logs/bxxd.log" />
      <parameter name="debugLevel"      value="none" />

      <profile uri="http://xml.resource.org/profiles/sasl/OTP"
               module="sasl-otp">
        <parameter name="authDirectory" value="auth/" />
      </profile>

      <profile uri="http://xml.resource.org/profiles/sasl/ANONYMOUS"
               module="sasl-anon">
        <parameter name="acl"           value='subtree "" privs "fetch"' />
      </profile>

      <profile uri="http://xml.resource.org/profiles/NULL/ECHO"
               module="null">
        <parameter name="mode"          value="echo" />
      </profile>

      <profile uri="http://xml.resource.org/profiles/NULL/SINK"
               module="null">
        <parameter name="mode"          value="sink" />
      </profile>
    </bxxd>
  </config>

      This is a configuration file for the default port 10288.

Running SpaceBxxd from the Command Line

      SpaceBxxd can run from the command line in "stand-alone" mode. Once started, it continues to run indefinitely. When a client connects, it is the exclusive connection to the server until the close of the session. This mode of running is typically used for testing purposes.

      When running in stand-alone mode, the "$CLASSPATH" environment variable should contain all classes required by the server, including spacekit.jar and any additional modules.

      This example starts the server on port 12345 using the configuration file in the current directory named bxxd.config:

java SpaceBxxd -standalone -portno 12345 bxxd.config

      Without "-portno" the server uses the default port, 10288.

Running SpaceBxxd Under inetd

      To run the server under the supervision of inetd, first add the following to /etc/services:

bxxp            10288/tcp

      Secondly, add the following to /etc/inetd.conf (Note: this shows as being on two lines but should actually be one line):

bxxp stream tcp nowait bxxpuser /usr/java1.2/bin/java java -classpath
/iw/SpaceKit/java/current/classes/spacekit.jar SpaceBxxd /usr/local/bxxd/etc/bxxd.config

      Where:

1. bxxpuser is the supervisory username of the server.
2. /usr/java1.2/bin/java is the path to the java runtime executable.
3. /iw/SpaceKit/java/current/classes/spacekit.jar is the full pathname to the SpaceKit spacekit.jar file.
4. /usr/local/bxxd/etc/bxxd.config is the full pathname to the server configuration file.

      Finally, restart inetd as super-user:

kill -HUP pid

      Where "pid" is the process id of inetd.

User Properties File Format

      A properties file defines users of the system. The location of the user properties file is found in the configuration file. Two elements, the "homeDirectory" and the "authDirectory" combine to form the directory name containing the properties file. The filename itself is a combination of the port number with the ".profiles" suffix.

      For port 12345 the typical user file pathname is:

/usr/local/bxxd/auth/12345.properties

      The user file contains any number of users.

      An example entry for a user file is:

username.fmorton.name=Frank Morton
username.fmorton.authentication.mechanism=otp
username.fmorton.authentication.sequence=9911
username.fmorton.authentication.seed=rwcsqa0120696
username.fmorton.authentication.key=c055f88c0ca8c0ac
username.fmorton.authentication.privacy=none
username.fmorton.authentication.algorithm=sha1

      To create an OTP key, see the SpaceKeyOtp utility.

A Complete Module Example For The Impatient

      You can create your own modules by defining a new profile and implementing a new server module as well as the client using the new profile.

      In the example, we create a module named "reverse" that receives a server request, reverses the order of the octets in the request, and responds back to the client with the reversed results.

Profile Definition

      To access your new module, first define the new profile and its corresponding module in the configuration file for the port using the new profile:

      <profile uri="http://xml.resource.org/profiles/NULL/REVERSE"
               module="reverse">
      </profile>

      If you are using the server in stand-alone mode, you will need to restart since the configuration file loads at start time.

Server-side SpaceModuleREVERSE

      A module extends the class "SpaceModuleThead" as in the SpaceModuleREVERSE example:

public class SpaceModuleREVERSE extends SpaceModuleThread {

//------------------------------------------------------------------------------
//  run
//------------------------------------------------------------------------------
public void run() {
     try {
          //---------------------------------------------------------------
          //  see if channel start
          //---------------------------------------------------------------
          if(isStart()) {
               start("");
               return;
               }

          //--------------------------------------------------------------------
          //  normal processing for the module
          //--------------------------------------------------------------------
          String reverse = (new StringBuffer(request.toString())).reverse().toString();

          //--------------------------------------------------------------------
          //  return a response
          //--------------------------------------------------------------------
          respond(reverse);

          //--------------------------------------------------------------------
          //  log the reverse response
          //--------------------------------------------------------------------
          log("reverse request complete");
          }
     catch(SpaceTimeout e) {
          //---------------------------------------------------------------
          //  timeout
          //---------------------------------------------------------------
          fatal(e);
          }
     catch(SpaceException e) {
          //---------------------------------------------------------------
          //  exception
          //---------------------------------------------------------------
          fatal(e);
          }
     }
}

      A module has two main jobs:

1. Start the channel.
2. Process requests.

      See "Module Structure" below and the reference section for a complete description of the SpaceModuleThread class.

Client-side SpaceReverse

      The SpaceReverse application is an example of how to access the "reverse" module:

public class SpaceReverse {

//------------------------------------------------------------------------------
//  main
//------------------------------------------------------------------------------
public static void main(String[] argv) {
     SpaceServer server = null;

     try {
          //--------------------------------------------------------------------
          //  parse the command line
          //--------------------------------------------------------------------
          String host = null;
          int port = SpaceServer.defaultPort;

          for(int k=0;k<argv.length;++k) {
               //---------------------------------------------------------------
               //  -portno
               //---------------------------------------------------------------
               if(argv[k].equalsIgnoreCase("-portno")) {
                    port = InvisibleUtil.parseInt(argv[++k]);
                    continue;
                    }

               //---------------------------------------------------------------
               //  host
               //---------------------------------------------------------------
               host = argv[k];
               }

          //--------------------------------------------------------------------
          //  instantiate the blocks server
          //--------------------------------------------------------------------
          server = new SpaceServer(host,port);

          //--------------------------------------------------------------------
          //  connect to blocks server
          //--------------------------------------------------------------------
          SpaceResponse greeting = server.connect(true);

          server.free(greeting);

          //--------------------------------------------------------------------
          //  start a reverse channel
          //--------------------------------------------------------------------
          SpaceChannel channel = server.getChannel("http://xml.resource.org/profiles/REVERSE");
          SpaceResponse reverseStart = channel.start(true);

          //--------------------------------------------------------------------
          //  make a reverse request
          //--------------------------------------------------------------------
          SpaceResponse reverseResponse = channel.request("sdlroW elbisivnI");

          System.out.println("Response: " + reverseResponse.toString());

          channel.free(reverseResponse);
          channel.free(reverseStart);
          }
     catch(NullPointerException e) {
          System.err.println("java SpaceReverse [-portno port] host");
          }
     catch(SpaceTimeout e) {
          System.err.println(e.toString());
          }
     catch(SpaceException e) {
          System.err.println(e.toString());
          }
     finally {
          //--------------------------------------------------------------------
          //  close the connection
          //--------------------------------------------------------------------
          if(server != null) {
               server.close();
               }
          }
     }
}

      Sample output from SpaceReverse:

Response:
>tseuqer/<Invisible Worlds
>'1'=onqer tseuqer<

Module Structure

      All modules extend the class "SpaceModuleThread."

      Since SpaceBxxp is a multi-threaded server, all modules must be thread safe.

      Module names specified in the configuration file, such as "sasl-otp," convert to a class name made up of "SpaceModule" and the "module" capitalized with all hyphens removed. So, for the module "sasl-otp," "SpaceModuleSASLOTP" is the final class name. This is necessary to avoid class naming problems.

      The following protected instance variables are defined in SpaceModuleThread and are fully accessible by modules extending the class:

• SpaceConfig config
• SpaceUserCache userCache
• SpaceProfile profile
• SpaceServer server
• SpaceRequest request

      See the reference for a full definition of each class.

      To access the content of the request, a module uses "request.toString()."

Next » The Blocks SpaceKit for Java Server: SpaceBxxd - Responses.

 Copyright © 2000 Invisible Worlds. All Rights Reserved.

contact | about | site map | home