[PATCH] AltRMI Sample documentation with code skeletons

[alvin schur <al...@dsl.ab.ca>]

Hi,


  Sorry about the missing attachment.
  
  Hopefully the file is attached this time.
  
  
  I am including the file in the body as well.
  
  I am not subscribed to commons-dev.
  
 
  BEGIN file --------------------

  See AltRMI proposal for a list of features and goals.

Classes a client uses to connect to a server

AltrmiHostContext
          provides host name (IP address), port for connecting to the server
AltrmiFactory
          defines location of generated Proxy class (either on server or client)

Example code from SocketClientTest:

      // connect to localhost, port 1234
      AltrmiHostContext arhc = 
        new SocketObjectStreamHostContext("127.0.0.1", 1234);

      // put generated Proxy class on client side
      AltrmiFactory af = new ClientClassAltrmiFactory(false);

      af.setHostContext(arhc);

      String[] listOfPublishedObjectsOnServer = af.list();
      TestInterface ti = (TestInterface) af.lookup("Hello");

      // now use ti as a local object with method calls sent to the server for
      // execution.
    

Classes a server uses

AbstractServer
          listens for connections from a client and processes the request

Example code from SocketServerTest

      // listen on port 1234
      AbstractServer as = new CompleteSocketObjectStreamServer(1234);

      // create an object to publish
      TestInterfaceImpl ti = new TestInterfaceImpl();

      as.publish(ti, "Hello", new PublicationDescription(TestInterface.class,
      TestInterface2.class));

      // start the server listening on the socket for client connections
      as.start();
    

Minimum run loop on server

ServerStreamReadWriter
          reads requests from the client stream and writes the response to the 
client stream
InvocationHandlerAdapter
          interprets and executes the client request

Note: this example ignores all error handling, start, stop, kill niceties. See: 
StreamServerConnection.run(),
AbstractServer (and subclasses) for error handling examples.

Maybe this code snippet can be embedded in a Servlet (non Http) service method.

      // choose the desired read/writer from the ServerStreamReadWriter
      // subclasses
      ServerStreamReadWriter readWriter;
      readWriter.setStreams( inputStream, outputStream );

      InvocationHandlerAdapter handler = new InvocationHandlerAdapter();

      AltrmiRequest request = null;
      AltrmiReply reply = null;

      while( true ) {
        // get a request 
        // if reply is null then
        //   writeReplyAndGetRequest writes nothing to the client
        // endif
        request = readWriter.writeReplyAndGetRequest(reply);
        reply = handler.handleInvocation(request);
      }
END file -----------------------------