namespace RMI

The top-level namespace for the Remote Method Invocation framework

Description

Using this framework it is possible to connect and also export objects to be accessed across any protocol, translation or transport layer. Object access is transparent to the programmer who can treat the services like locally created objects.

The framework consists of a set of layers. The protocol layer, the translation layer and finally the transport layer. The protocol layer translates the attribute access and method calls into a form that can be passed onto the translation layer. The translation layer provides a slot between the transport layer and the protocol to do extra processing. By default this layer does not do anything. If can be used to add encryption or other data transforms. The transport layer provides the comunication layer between client and server.

Example

Server-side:

uses "console", "rmi", "sys";

class SomeService
{
    string someValue;
    
    function SomeService( string value )
        .someValue = value;
    
    function getValue()
        return .someValue;
}

string host = "localhost";

if( Array.size(argv) > 0 )
    host = argv[0];

RMI.createService( "SomeResource", new SomeService( "If you can see this \"RMI\" is working!" ) );
RMI.addServiceListener( "::tcpip", "bind:$host:" );
RMI.listen();

Client-side:

uses "console", "rmi", "array";

object o = null, p;
string host = "localhost";

if( Array.size(argv) > 0 )
    host = argv[0];

o = RMI.connectToService( "::tcpip", "connect:$host:", "SomeResource" );
if( o != null )
{
    Console.println( "Testing o" );
    Console.println( "Return from o.getValue() == '${o.getValue()}'" );
    Console.println( "o.someValue = '${o.someValue}'" );
    o.attribute_set( "someValue", "Harrow Taxi Driver" );
    Console.println( "o.someValue = '${o.someValue}'" );    
    o.someValue = "Toothy Hurty";
    Console.println( "o.someValue = '${o.someValue}'" );    
    Console.println( "Return from o.getValue() == '${o.getValue()}'" );
}

namespace contents
Namespaces
namespace Error - Error return values. When an error occurs the err.num will be equal to one of these
Functions
function addServiceListener(string,string) - This function creates a service listening given a protocol stack.
function connectToService(string,string,string) - This function connects to RMI server and provides an object to interact with that service.
function createService(string,object) - Create a service for an object with a specified name
function getService(string) - Get a reference to an object for a given service name
function listen() - This is the main loop the RMI system travels in. Call this function to start the magic.
function registerProtocolLayer(string,string) - Register a class as a protocol layer
function registerTranslationLayer(string,string) - Register a class as a translation layer
function registerTransportLayer(string,string) - Register a class as a transport layer

Functions
function addServiceListener Click to go up to the list
This function creates a service listening given a protocol stack.
Declaration:
    function addServiceListener( string protocols, string url )
Description:
The result of this function is the creation of a service listener that can provide access to any of the previously created services.
Parameters:
    Parameter #1: string protocols - The protocols to use to listen for the remote service connection, e.g. ::tcpip
    Parameter #2: string url - The listen url to pass to the protocol stack specified in the previous parameter. Given the previous example, bind:locahost:.
Example:
RMI.addServiceListener( "::tcpip", "bind:locahost:" );
function connectToService Click to go up to the list
This function connects to RMI server and provides an object to interact with that service.
Declaration:
    function connectToService( string protocols, string url, string service )
Parameters:
    Parameter #1: string protocols - The protocols to use to connect to the remote service, e.g. ::tcpip
    Parameter #2: string url - The connection url to pass to the protocol stack specified in the previous parameter. Given the previous example, connect:host.
    Parameter #3: string service - The name of the service to connect to.
Returns:
    An object connected to the service, null otherwise.
Example:
object o = RMI.connectToService( "::tcpip", "connect:localhost:", "SomeResource" );
function createService Click to go up to the list
Create a service for an object with a specified name
Declaration:
    function createService( string name, object service )
Description:
This is the corner stone of any nutritious rmi session. Any service that is created can be viewed from any listening post.
Parameters:
    Parameter #1: string name - The name of the service to create
    Parameter #2: object service - The object to bind the service to.
Example:
RMI.createService("SomeResource",someObject);
function getService Click to go up to the list
Get a reference to an object for a given service name
Declaration:
    function getService( string name )
Parameters:
    Parameter #1: string name - The name of the service to get a handle of
Returns:
    The service object if it exists, null otherwise.

function listen Click to go up to the list
This is the main loop the RMI system travels in. Call this function to start the magic.
Declaration:
    function listen()
Returns:
    This function never returns.

function registerProtocolLayer Click to go up to the list
Register a class as a protocol layer
Declaration:
    function registerProtocolLayer( string name, string klass )
Description:
The aim of the protocol layer is to encode and decode the rmi aspects of the language. For instance it takes a method call with a set of arguments gets encoded on the client side, given to the translation layer who hands it to the transport and then hands it to the server (who does the reverse). The protocol layer doesn't need to worry about translation or transport.
Parameters:
    Parameter #1: string name - The name of the layer, e.g. std, xml
    Parameter #2: string klass - The name of the ferite class representing the protocol

function registerTranslationLayer Click to go up to the list
Register a class as a translation layer
Declaration:
    function registerTranslationLayer( string name, string klass )
Description:
The translation layer is the middle man between the top level protocol layer and the transport layer. For the most part the translation layer need not intervene in the rmi communication stack unless specific encoding is required: for instance encrypted data.
Parameters:
    Parameter #1: string name - The name of the layer, e.g. std, ssl
    Parameter #2: string klass - The name of the ferite class representing the translation

function registerTransportLayer Click to go up to the list
Register a class as a transport layer
Declaration:
    function registerTransportLayer( string name, string klass )
Description:
The transport layer is the bottom man between the beneath the translation layer. It is the job of the transport layer to communicate between the client and the server. It should be noted that the default port for the tcpip layer is 2048.
Parameters:
    Parameter #1: string name - The name of the layer, e.g. tcpip
    Parameter #2: string klass - The name of the ferite class representing the transport

Automatically generated at 12:08PM, Wednesday 25 May 2005 by feritedoc.