Contents  Home Page

The E Class Library

This chapter is a reference to the E classes.In addition to Java classes, E has its own library of classes to support the E runtime environment.

E provides two types of classes: those derived from E's EObject class, and those that are derived from Java's Object class. E also provides several Java interfaces, and its own E-interfaces.

EObject classes

The EObject class is similar to Java's Object class. It is E's root class; objects derived from EObject implement E's security and messaging capabilities. Many of these are similar to Java's classes. For example, EBoolean is very similar to Java's Boolean class, with the added E functionality.

In contrast to Java object classes, which contain methods that are invoked directly by other objects (using standard method call/return semantics), an E-object responds only to messages sent by other objects.

The EObject classes include:

EBoolean
EChannel
EDistributor
EDouble
EFalse
EFloat
EInteger
ELong
ENull
EObject
EPrintStream
ESealer
EString
ETrue
EUnsealer

Java Object E-runtime classes

The classes in E that derive from Java's Object class are also part of the E runtime. However, these classes do not have E functionality such as messaging. In E, these classes are generally prefixed by the letters Rt (with a few exceptions). These classes include:

PObjDB
RtClock
RtClockTerminator
RtConnection
RtConnector
RtDBViewLimiter
RtDecoder
RtEARL
RtEARLrestrictor
RtEException
RtEEnvironment
RtEncoder
RtEnvelope
RtFile
RtFileDataInput
RtFileDataOutput
RtFileDirectory
RtFileEnvironment
RtLauncher
RtNetworkController
RtRandomAccessFile
RtRegistration
RtRegistrar
RtSystem
RtTimer

E-interfaces

E provides its own E-interfaces, which describe E messages, like Java interfaces describe Java methods. Like Java, you use the import and implements statements to use E-interfaces. E provides the following E-interfaces:

ELaunchable
IBoolean

Java interfaces provided by E

E provides several interfaces that contain methods supporting the E runtime. These are regular Java interfaces; you use the import and implements statements to use them.

The E runtime Java interfaces include:

RtAwakeAfterDecoding
RtCodeable
RtDBViewFilter
RtDecodeable
RtEncodeable
RtNotificationHandler
RtTickHandling
RtTimeoutHandling

EBoolean

import ec.e.run.EBoolean;

import ec.e.db.*;

The EBoolean class is an EObject wrapper for boolean data values, and serves as a place for boolean-oriented operations.

Creation

EBoolean has no public constructor. Use its two built-in constants, etrue and efalse.

E-methods

None

Interfaces

RtCodeable

Return value

ETrue has the following return value method:

protected Object value() {return ((Object)(new Boolean(true)));

EFalse has the following return value method:

protected Object value() {return ((Object)(new Boolean(false)));

Example

None

EChannel

import ec.ec.run.EChannel;

EChannel is the base class for all channels, which are one-way conduits carrying messages in envelopes from one E-object to another. Channels do not respond to messages themselves.

Channels are one-way because E-messages do not have a return value. Each channel has a distributor that routes messages in the channel to the appropriate destination E-objects. Messaging is asynchronous. This means that when you forward a channel to a new recipient, it receives all the messages that have ever been sent through that channel.

Once you have forwarded a channel, you cannot unforward it, though you can forward a channel more than once. You can also forward a channel to many recipients simultaneously; all messages sent through that channel are received by all the recipients.

All variables descended from EObject that are not explicitly initialized are implicitly initialized to a new instance of EChannel and are initially unforwarded.

Creation

Create a new channel by using the new operator:

channelName = new EChannel();

or by declaring a new object:

EObjectchannelName

E-methods

None.

Example

Each of these two statements creates a new channel named hudson:

hudson = new EChannel();

Eobject hudson;

EDistributor

import ec.e.run.EDistributor;

EDistributor is the class of all distributors, which route the messages in a channel to the destination E-objects.

To extract a channel's distributor, use:

  &channelName

The result is of class EDistributor and you can treat it as a normal value; for example, you can pass it as a message parameter.

You can only use the & operator within the scope of the channel variable's initial declaration. You cannot use this operator on a channel which has been passed as the parameter of an E message or Java method call, or stored as an instance variable of an object other than that object itself.

Creation

Distributors are generated internally by using the & operator.

E-methods

To forward messages in a channel to an E-object, send a forward message to the channel's distributor with the forwarding destination as the parameter:

distributorName <- forward(destinationEObject);

or

&channelName <- forward(destinationEObject);

Example

Forward a a channel associated with a distributor called MyResult to an E-object Answer:

  emethod DieRollEwith (Edistributor MyResult)
    {
      MyResult <- forward (Answer);
    }

Forward a channel named hudson to an E-object named bob:

  &hudson <- forward(bob);

EDouble

import ec.e.lang.EDouble;

The EDouble class is an EObject wrapper for double data values, and serves as a place for double-oriented operations.

Creation

edouble = new EDouble(double value );

Constructs an EDouble wrapper for the specified double value.

E-methods

The following E-methods implement mathematical functions for an EDouble.

emethod dadd(EDouble operand, EDistributor result);

Add two EDoubles, resulting in a new EDouble.

emethod dsub(EDouble operand, EDistributor result);

Subtract two EDoubles, resulting in a new EDouble.

emethod dmul(EDouble operand, EDistributor result);

Multiply two EDoubles, resulting in a new EDouble.

emethod ddiv(EDouble operand, EDistributor result);

Divide two EDoubles, resulting in a new EDouble.

emethod dmod(EDouble operand, EDistributor result);

Take the modulus of two EDoubles, resulting in a new EDouble.

emethod dmax(EDouble operand, EDistributor result);

Max of two EDoubles, resulting in a new EDouble.

emethod dmin(EDouble operand, EDistributor result);

Min of two EDoubles, resulting in a new EDouble.

emethod atan2(EDouble operand, EDistributor result);

Rectangular arc tangent of two EDoubles, resulting in a new EDouble.

emethod pow(EDouble operand, EDistributor result);

Power of two EDoubles, resulting in a new EDouble.

emethod dneg(EDistributor result);

Negative of an EDouble, resulting in a new EDouble.

emethod dabs(EDistributor result);

Absolute value of an EDouble, resulting in a new EDouble.

emethod sin(EDistributor result);

Sine of an EDouble, resulting in a new EDouble.

emethod cos(EDistributor result);

Cosine of an EDouble, resulting in a new EDouble.

emethod tan(EDistributor result);

Tangent of an EDouble, resulting in a new EDouble.

emethod asin(EDistributor result);

Arc sine of an EDouble, resulting in a new EDouble.

emethod acos(EDistributor result);

Arc cosine of an EDouble, resulting in a new EDouble.

emethod atan(EDistributor result);

Arc tangent of an EDouble, resulting in a new EDouble.

emethod exp(EDistributor result);

Exponential of an EDouble, resulting in a new EDouble.

emethod log(EDistributor result);

Natural logarithm of an EDouble, resulting in a new EDouble.

emethod sqrt(EDistributor result);

Square root of an EDouble, resulting in a new EDouble.

emethod floor(EDistributor result);

Floor of an EDouble, resulting in a new EDouble.

emethod ceil(EDistributor result);

Ceiling of an EDouble, resulting in a new EDouble.

emethod rint(EDistributor result);

Integer value of an EDouble, resulting in a new EDouble.

emethod asInteger(EDistributor result);

Cast an EDouble to EInteger, resulting in a new EInteger.

emethod dlt(EDouble operand, EDistributor result);

Compare two EDoubles with less-than sign(<), resulting in an EBoolean.

emethod dleq(EDouble operand, EDistributor result);

Compare two EDoubles with less-than equal-to sign(<=), resulting in an EBoolean.

emethod dgt(EDouble operand, EDistributor result);

Compare two EDoubles with greater-than sign(>), resulting in an EBoolean.

emethod dgeq(EDouble operand, EDistributor result);

Compare two EDoubles with greater-than equal-to sign(>=), resulting in an EBoolean.

emethod deq(EDouble operand, EDistributor result);

Compare two EDoubles with equal-to sign(=), resulting in an EBoolean.

emethod dneq(EDouble operand, EDistributor result);

Compare two EDoubles with not equal-to sign (!=), resulting in an EBoolean.

Return value

Returns a Java double data type with the following value method:

  double value() {return mydouble};

EFalse

import ec.e.run.EFalse;

import ec.e.run.IBoolean;

An object of this class represents a EBoolean with a value of FALSE.

Creation

This class has one unique instance, referenced by the efalse keyword.

E-methods

emethod and(EBoolean operand, EDistributor result)

emethod or(EBoolean operand, EDistributor result)

emethod xor(EBoolean operand, EDistributor result)

emethod eqv(EBoolean operand, EDistributor result)

emethod not(EDistributor result)

E-interfaces

IBoolean

Return value

Returns a Java Boolean data type of false with the following value method:

protected Object value() {return((Object)(new Boolean(false)));}

EFloat

import ec.e.lang.EFloat;

The EFloat class is an EObject wrapper for float data values, and is a place for float-oriented operations.

Creation

newfloat = new EFloat (float value );

Constructs an EFloat wrapper for the specified float value.

E-methods

The following E-methods implement mathematical functions for an EFloat.

emethod add(EFloat operand, EDistributor result)

Add two EFloats, resulting in a new EFloat.

emethod sub(EFloat operand, EDistributor result)

Subtract two EFloats, resulting in a new EFloat.

emethod mul(EFloat operand, EDistributor result)

Multiply two EFloats, resulting in a new EFloat.

emethod div(EFloat operand, EDistributor result)

Divide two EFloats, resulting in a new EFloat.

emethod mod(EFloat operand, EDistributor result)

Take the modulus of two EFloats, resulting in a new EFloat.

emethod max(EFloat operand, EDistributor result)

Max of two EFloats, resulting in a new EFloat.

emethod min(EFloat operand, EDistributor result)

Min of two EFloats, resulting in a new EFloat.

emethod atan2(EFloat operand, EDistributor result)

Rectangular arc tangent of two EFloats, resulting in a new EFloat.

emethod pow(EFloat operand, EDistributor result)

Power of two EFloats, resulting in a new EFloat.

emethod neg(EDistributor result)

Negative of an EFloat, resulting in a new EFloat.

emethod abs(EDistributor result)

Absolute value of an EFloat, resulting in a new EFloat.

emethod sin(EDistributor result)

Sine of an EFloat, resulting in a new EFloat.

emethod cos(EDistributor result)

Cosine of an EFloat, resulting in a new EFloat.

emethod tan(EDistributor result)

Tangent of an EFloat, resulting in a new EFloat.

emethod asin(EDistributor result)

Arc sine of an EFloat, resulting in a new EFloat.

emethod acos(EDistributor result)

Arc cosine of an EFloat, resulting in a new EFloat.

emethod atan(EDistributor result)

Arc tangent of an EFloat, resulting in a new EFloat.

emethod exp(EDistributor result)

Exponential of an EFloat, resulting in a new EFloat.

emethod log(EDistributor result)

Natural logarithm of an EFloat, resulting in a new EFloat.

emethod sqrt(EDistributor result)

Square root of an EFloat, resulting in a new EFloat.

emethod floor(EDistributor result)

Floor of an EFloat, resulting in a new EFloat.

emethod ceil(EDistributor result)

Ceiling of an EFloat, resulting in a new EFloat.

emethod rint(EDistributor result)

Integer value of an EFloat, resulting in a new EFloat.

emethod asInteger(EDistributor result)

Cast an EFloat to EInteger, resulting in a new EInteger.

emethod lt(EFloat operand, EDistributor result)

Compare two EFloats with less-than operation (<) resulting in an EBoolean.

emethod leq(EFloat operand, EDistributor result)

Compare two EFloats with less-than or equal-to operation (<=) resulting in an EBoolean.

emethod gt(EFloat operand, EDistributor result)

Compare two EFloats with greater-than operation (>) resulting in an EBoolean.

emethod geq(EFloat operand, EDistributor result)

Compare two EFloats with greater-than or equal-to operation (>=) resulting in an EBoolean.

emethod eq(EFloat operand, EDistributor result)

Compare two EFloats with equal-to operation (==) resulting in an EBoolean.

emethod neq(EFloat operand, EDistributor result)

Compare two EFloats with not equal-to operation (!=) resulting in an EBoolean.

Return value

Returns a Java float data type with the following value method:

  float value() {return myfloat};

EInteger

import ec.e.lang.EInteger;

The EInteger class is an EObject wrapper for integer values. It holds a 32-bit value.

Creation

einteger = new EInteger(integer value );

E-methods

These E-methods implement mathematical functions for an EInteger.

emethod add(EInteger operand, EDistributor result);

Add two EIntegers, resulting in a new EInteger.

emethod sub(EInteger operand, EDistributor result);

Subtract two EIntegers, resulting in a new EInteger.

emethod mul(EInteger operand, EDistributor result);

Multiply two EIntegers, resulting in a new EInteger.

emethod div(EInteger operand, EDistributor result);

Divide two EIntegers, resulting in a new EInteger.

emethod mod(EInteger operand, EDistributor result);

Take the modulus two EIntegers, resulting in a new EInteger.

emethod band(EInteger operand, EDistributor result);

Bitwise AND of two EIntegers, resulting in a new EInteger.

emethod bor(EInteger operand, EDistributor result);

Bitwise OR of two EIntegers, resulting in a new EInteger.

emethod bxor(EInteger operand, EDistributor result);

Bitwise XOR of two EIntegers, resulting in a new EInteger.

emethod max(EInteger operand, EDistributor result);

Max of two EIntegers, resulting in a new EInteger.

emethod min(EInteger operand, EDistributor result);

Min of two EIntegers, resulting in a new EInteger.

emethod neg(EDistributor result);

Negative of an EInteger, resulting in a new EInteger.

emethod bnot(EDistributor result);

Bitwise NOT of an EInteger, resulting in a new EInteger.

emethod abs(EDistributor result);

Absolute value of an EInteger, resulting in a new EInteger.

emethod asDouble(EDistributor result);

Cast an EInteger to EDouble, resulting in a new EDouble.

emethod lt(EInteger operand, EDistributor result);

Compare two EIntegers with less than operation (<), resulting in an EBoolean.

emethod leq(EInteger operand, EDistributor result);

Compare two EIntegers with less than equal-to operation (<=), resulting in an EBoolean.

emethod gt(EInteger operand, EDistributor result);

Compare two EIntegers with greater than operation (>), resulting in an EBoolean.

emethod geq(EInteger operand, EDistributor result);

Compare two EIntegers with greater-than equal-to operation (>=), resulting in an EBoolean.

emethod eq(EInteger operand, EDistributor result);

Compare two EIntegers with equal-to operation (==), resulting in an EBoolean.

emethod neq(EInteger operand, EDistributor result);

Compare two EIntegers with not equal-to operation (!=), resulting in an EBoolean.

Return value

Returns a Java int data type with the following value method:

  int value() {return myint};

ELong

import ec.e.lang.ELong;

The ELong class is an EObject wrapper for long (64- bit) data values, and is a place for long-oriented operations.

Creation

newelong = new ELong (long value );

Constructs an ELong wrapper for the specified long value.

E-methods

The following E-emethods implement mathematical functions for an ELong.

emethod add(ELong operand, EDistributor result

Add two ELongs, resulting in a new ELong.

emethod sub(ELong operand, EDistributor result)

Subtract two ELongs, resulting in a new ELong.

emethod sub(ELong operand, EDistributor result)

Multiply two ELongs, resulting in a new ELong.

emethod div(ELong operand, EDistributor result)

Divide two ELongs, resulting in a new ELong.

emethod mod(ELong operand, EDistributor result)

Take the modulus of two ELongs, resulting in a new ELong.

emethod band(ELong operand, EDistributor result)

Bitwise AND of two ELong, resulting in a new ELong.

emethod bor(ELong operand, EDistributor result)

Bitwise OR of two ELongs, resulting in a new ELong.

emethod bxor(ELong operand, EDistributor result)

Bitwise XOR of two ELongs, resulting in a new ELong.

emethod max(ELong operand, EDistributor result)

Max of two ELongs, resulting in a new ELong.

emethod min(ELong operand, EDistributor result)

Min of two ELongs, resulting in a new ELong.

emethod neg(EDistributor result)

Negative of an ELong, resulting in a new ELong.

emethod bnot(EDistributor result)

Bitwise NOT of an ELong, resulting in a new ELong.

emethod abs(EDistributor result)

Absolute value of an ELong, resulting in a new ELong.

emethod asDouble(EDistributor result)

Cast an ELong to EDouble, resulting in a new EDouble.

emethod lt(ELong operand, EDistributor result)

Compare two ELongs with less than operation (<), resulting in an EBoolean.

emethod leq(ELong operand, EDistributor result)

Compare two ELongs with less than/equal-to operation (<=), resulting in an EBoolean.

emethod gt(ELong operand, EDistributor result)

Compare two ELongs with greater than operation (>), resulting in an EBoolean.

emethod geq(ELong operand, EDistributor result)

Compare two ELongs with greater than/equal to operation (>=), resulting in an EBoolean.

emethod eq(ELong operand, EDistributor result)

Compare two ELongs with equal to operation (==) resulting in an EBoolean.

emethod neq(ELong operand, EDistributor result)

Compare two ELongs with not equal to operation (!=) resulting in an EBoolean.

Return value

Returns a Java long data type with the following value method:

  long value() {return mylong};

ENull

import ec.e.run.ENull;

import ec.e.db.RtCodeable;

This class has one unique instance which is referenced when you use the enull keyword. An ENull is useful for two purposes:

• To put in places where semantically you mean "null", but aren't allowed to pass Java null (such as the put() method in a hashtable).
• As an E-object which will always return Java null from its value method, thus "passing" null into an ewhen. See the example.

Creation

This class has one unique instance, referenced by the enull keyword.

E-methods

None.

Interfaces

RtCodeable

Return value

Returns a null value with the following method:

protected Object value() {return null;}

Example

EObject nullobject;

// This will cause val in the ewhen to evaluate to null
&nullobject <- forward(enull); 
ewhen nullobject (Object val) {
// val == null when someone forwards enull to nullobject's
// distributor
......

EObject

import ec.e.run.EObject;

EObject is the base class for all objects in the E programming language. E-objects are special Java objects that communicate by passing messages; they give E its added messaging and security capabilities.

E-objects possess private and protected instance variables, Java methods, and E-methods. The instance variables and Java methods can only be accessed directly from within the E-object itself. All references to the instance variables or Java objects must be made relative to this or super, either explicitly or implicitly. References to E-objects can be passed across the network by sending them as parameters in messages.

An E-object has an E-method for each message it is designed to receive. The code in the E-method is invoked when the corresponding message is received.

E-objects can act on other E-objects only if they have privileges to do so, and they never acquire unlimited access to system resources. At load time, E grants capabilities to E-objects that specifically request them, but only if the capabilities are permitted to the particular E-object. The programmer controls permission for the capabilities of each E-object. Granting permission for capabilities imparts trust to an E-object by allowing it to send specific messages to specific objects.

Creation

None

E-methods

None

Example

None

EPrintStream

import ec.e.lang.EPrintStream;

The EPrintStream class is an EObject wrapper that implements an output stream, and contains methods for printing.

Creation

printobject =new EPrintStream(PrintStream stream);

E-methods

emethod printObject(Object obj);

Prints a Java object.

emethod printEObject(EObject anEObject);

Prints an object derived from EObject.

Example

None

ESealer

import ec.e.run.ESealer;

ESealer is the base class for all sealers, which encapsulate messages into sealed envelopes that are sent through channels to E-objects. Sealers, unsealers, and envelopes are implicit in message sends. You do not create or modify them directly.

An envelope encapsulates the parameters of a message and ensures that they can only be read by the recipient E-object with the correct unsealer. The envelope is created by the sealer method of the sending E-object, which marks the envelope to indicated the unsealer needed to open it. The message in the envelope is secured by the unforgeable sealer and unsealer associated with it.

Creation

None

E-methods

None

Example

None

EString

import ec.e.lang.EString;

The EString class is an EObject wrapper for character strings.

Creation

estring =new EString(string value );

E-methods

The following E-methods implement standard string functions.

emethod length(EDistributor result);

Take the length of an EString, resulting in a new EInteger.

emethod slt(EString operand, EDistributor result);

Compare two EStrings with the less-than operator (<), resulting in an EBoolean.

emethod sleq(EString operand, EDistributor result);

Compare two EStrings with the less-than equal-to operator (<=), resulting in an EBoolean.

emethod sgt(EString operand, EDistributor result);

Compare two EStrings with the greater-than operator (>), resulting in an EBoolean.

emethod sgeq(EString operand, EDistributor result);

Compare two EStrings with the greater-than equal-to operator (<=), resulting in an EBoolean.

emethod seq(EString operand, EDistributor result);

Compare two EStrings with the equal-to operator (==), resulting in an EBoolean.

emethod sneq(EString operand, EDistributor result);

Compare two EStrings with the not equal-to operator (!=), resulting in an EBoolean.

emethod substring(EInteger start, EInteger end, EDistributor result);

Compute a substring of an EString, resulting in new EString.

emethod concat(EString operand, EDistributor result);

Concatenate two EStrings, resulting in a new EString.

Return value

Returns a Java string data type with the following value method:

  String value() {return mystring};

ETrue

import ec.e.run.ETrue;

import ec.e.run.IBoolean;

This class represents a EBoolean with a value of TRUE.

Creation

This class has one unique instance, referenced by the etrue keyword.

E-methods

emethod and(EBoolean operand, EDistributor result)

emethod or(EBoolean operand, EDistributor result)

emethod xor(EBoolean operand, EDistributor result)

emethod eqv(EBoolean operand, EDistributor result)

emethod not(EDistributor result)

E-interfaces

IBoolean

Return value

Returns a Java Boolean data type of true with the following value method:

protected Object value() {return((Object)(new Boolean(true)));}

EUnsealer

import ec.e.run.EUnsealer;

EUnsealer is the base class for all unsealers, which open sealed envelopes sent to E-objects.

An envelope encapsulates the parameters of a message and ensures that they can only be read by the recipient E-object with the correct unsealer. The envelope is created by the sealer method of the sending E-object, which marks the envelope to indicated the unsealer needed to open it. The message in the envelope is secured by the unforgeable sealer and unsealer associated with it.

Sealers, unsealers, and envelopes are implicit in message sends. You do not create or modify them directly.

If several E-objects have references to the same unsealer, they should all be able to receive the same message.

Creation

None

E-methods

None

Example

None

PObjDB

import ec.e.db.PObjDB;

import ec.e.db.RtDBViewFilter;

import ec.e.db.RtEncodingManager;

import ec.e.db.RtDecodingManager;

This class lets you store objects to and retrieve them from a database. This lets you store your objects to disk and later retrieve them in other applications. You must create your own storage and retrieval procedures using the E functionality; E does not do either operation automatically.

Creation

databaseobject = new PObjDB(String fileName);

Construct a new database object (PObjDB) based on an existing disk file.

databaseobject = new PObjDB(PObjDB parent);

Construct a child database object based on an existing, currently open database object.

Methods

public RtStreamKey put(Object object) throws DBAccessException;

This saves an object to an object database, and return a RtStreamKey as a token.

public void put(Object rootKey, RtStreamKey streamKey) throwsDBAccessException;

Saves a stream key (RtStreamKey) to an object database under a root key name. Overwrites any existing root key with that name. Note that the root key cannot itself be a stream key.

public RtStreamKey get(Object rootKey) throws DBAccessException;

Get a stream key (RtStreamKey) that was previously stored under rootKey. If the stream key does not exist, null is returned. DBAccessException is returned if the request is illegal under security policies.

public Object get(RtStreamKey key) throws DBAccessException;

Given a RtStreamKey, return a copy of the object that was stored out and registered for it. Successive attempts at getting an object will return multiple copies.

public boolean contains(Object key) throws DBAccessException;

Test to determine if something is stored in the database under the given key. In this case, key can be either a RtStreamKey or a root key object.

public void commit() throws DBAccessException;

Commit the changes made to this database back into the parent database. This only works if this database is indeed a child and the permissions permit.

public synchronized void closeDB()

Close the database and store back file header information.

Interfaces

RtDBViewFilter

RtEncodingManager

RtDecodingManager

Example

import java.lang.*;
import ec.e.db.*;
import ec.e.stream.StreamDB;

public class DBexample
{
  public static void main (String args[]) {
    String dbFileName;
    if(args.length > 1) {
      StreamDB.setDebugOn();
    }
    try {
      System.out.println("Creating PObjDB");

      if(args.length == 0)
        dbFileName = "/tmp/ExampleDB";
      else dbFileName = args[0];

      PObjDB btdb = new PObjDB(dbFileName);
      System.out.println("DB created named: 
        " + dbFileName);
      Object cat1[] = new Object[2];
      Object cat2;
      cat1[0] = "Meow";
      cat1[1] = new Integer(123456);
      System.out.println("Storing first test object.");
      RtStreamKey catKey = btdb.put(cat1);
      System.out.println(catKey);
      System.out.println("Closing root PObjDB file");
      btdb.closeDB();
      System.out.println("Reopening root file with an 
        update view.");

      PObjDB db1 = new PObjDB(dbFileName);
      PObjDB db2 = new PObjDB(db1);
      cat2 = db2.get(catKey);
      System.out.println("Retrieved object " + cat2);
      System.out.println("Writing a string named DogName to
        the update view");
      String dog1 = new String("Woof");
      RtStreamKey dogKey = db2.put(dog1);

      db2.put("DogName", dogKey);
      System.out.println("Committing the update view 
        back against the root file.");
      db2.commit();
      db2.closeDB();
      db1.closeDB();
      System.out.println("Reopening the root file using a 
        read only view limiter");
      PObjDB db3 = new PObjDB(dbFileName);

    /* Now open the view limiter */
      RtDBViewLimiter readOnlyView = new RtDBViewLimiter
        (db3, true, false, false, null, null);
      RtStreamKey dog2Key = db3.get("DogName");
      Object dog2 = db3.get(dog2Key);
      System.out.println("Object retrieved under DogName 
        is " + dog2);
      System.out.println("Attempting to write to the
        readOnlyView");
      System.out.println("(This should produce a
        DBAccessException)");
      readOnlyView.put(new String("BadGuy"));
      System.out.println("Security failure");
    } 
    catch (Exception e) {e.printStackTrace();}
  }
}

RtClock

import ec.e.run.RtClock;

import ec.e.run.RtTickHandling;

RtClock is a Java class implementing basic timer services. All RtClock objects runs in their own thread (the RtClock thread), and call the method:

  void tick(Object arg, int time) 

on objects on every tick of the clock. See the interface definition for RtTickHanding for more information about the tick method.

Clocks are created by specifying the resolution of the clock, a target object to be sent the tick method on each clock tick, and an argument to be sent to the tick method.

The target object specified must implement the RtTickHandling interface. Note that the tick method is called in the RtClock thread, not the thread which was running at the time the RtClock was created.

Clocks are created in the stopped state, and must be explicitly started for ticks to occur.

Creation

clock = new RtClock(long resolution, EObject target, RtEnvelope envelope)

clock = new RtClock(long resolution, EObject target, RtEnvelope envelope, Object tickInfo[])

clock = new RtClock(long resolution, RtTickHandling target, Object arg)

clock = new RtClock(long resolution, EDistributor key)

• resolution is the fine grained resolution of the clock
• target is the object to have the tick method invoked for each tick. This target can either be an RtTickHandling object, or an E-object.
• arg is passed into the tick method on each tick.
• envelope is an object of class RtEnvelope; you can create this envelope and have it sent to the target with every tick.
• key is a distributor that is set to the tick number. You can do a ewhen or ewhenever on this key.
• tickInfo is an array of at least size 1 which will have the tick number (a java Integer object) stuck into its index 0 on each tick before the envelope is invoked on the target. The array can be larger than 1 so that the caller can put other information in indexes 1 and beyond.

This lets the method invoked by the envelope know for what tick it is being called. To accomplish this, the original caller of the RtClock constructor should create an array of at least one Object, and pass that in as tickInfo, and also put it in an argument in the envelope so the callback can see it.

Methods

public synchronized void start ()

Starts the clock so that the tick method is sent to the target on every clock tick. The clock starts at whatever time it was at when stopped. If this is the first time the clock has been started, it starts from 0.

public synchronized void start (int atTick)

Starts the clock from atTick.

public synchronized void stop ()

Stops the clock, tick methods are no longer sent.

public synchronized void reset ()

Resets the clock to time 0 without stopping the clock. If the clock was stopped it stays stopped.

public synchronized void set (int toTick)

Sets the clock to toTick without stopping the clock. If the clock was stopped, it stays stopped.

public synchronized int getTicks ()

Gets the current number of ticks since the clock was originally started or reset from 0.

public synchronized RtTickHandling getTarget()

Gets the target that is sent each tick.

public synchronized void setTarget (RtTickHandling target)

Sets the target that is sent each tick method.

public synchronized void setTargetAndEnvelope (EObject target, RtEnvelope envelope)

Set the E-object target and envelope that is sent on each tick.

public synchronized void getEnvelope()

Gets the envelope that is sent each tick.

public synchronized RtTickHandling getTarget ()

Gets the target that is sent each tick method.

public synchronized void setArg (Object arg)

Sets the arg value that is sent on each tick method.

public synchronized Object getArg ()

Gets the arg value that is sent on each tick method.

public synchronized void setResolution (int resolution)

Sets the resolution of the clock.

public synchronized int getResolution ()

Gets the resolution of the clock.

public void terminate ()

Stops the clock and frees all the resources it consumes. Clocks must be explicitly terminated as they are entered into a list of all clocks upon creation. They are not removed from this list until they are terminated, or the RtClockTerminator method terminateAllClocks is called.

Interfaces

RtTimeOutHandling

Example

import java.lang.*;
import ec.e.run.RtClock;
import ec.e.run.RtTickHandling;

class ClockTest implements RtTickHandling
{
  private static int n = 1;
  private static RtClock clock;
  
  public static void main (String args[]) {
    ClockTest test = new ClockTest();
    clock = new RtClock(1000, test, "Testing");

    System.out.println("Clock will tick once a 
      second for 10 seconds");
  }

  public void tick (Object arg, int n)  {
    System.out.println("Clock ticked (" + n + ") with
      " + arg);
    if (++n > 10) {
      RtClock.terminate();
    }
  }
}

Example 2

This example uses the tickInfo parameter.

public eclass EUsesClock {
  private String name = "anonymous";
// Constructor left as an exercise for the reader

  emethod exampleMethod () {
// TickInfo is a place for the clock to put the current tick
    Object tickInfo[] = new Object[1];
// Create the envelope (note <- is not a message send, but
// the envelope assignment operator in this usage)
    RtEnvelope env;
    env <- callbackMethod (name, tickInfo);
// Create the clock telling it to set the tick in tickInfo[0]
// and then to invoke callbackMethod on this object every 
// 1000 milliseconds ...
    RtClock clock = new RtClock(1000, this, env, tickInfo);
  }

// This is the actual callback method, it gets passed
// the current tick in tickInfo[0] 
  emethod callbackMethod (String name, Object tickInfo[]) {
    Integer tick = (Integer)tickInfo[0];
    System.out.println(name + " invoked on tick " + tick);
  }
}

RtClockTerminator

import ec.e.run.RtClockTerminator;

This class contains the terminateAllClocks method, which terminates the thread in which all clocks are run.

Creation

None

Methods

public static void terminateAllClocks ()

Terminates the clock thread.

RtConnection

import ec.e.comm.RtConnection;

This class handles network connections.

Creation

Implicitly created as network connections are formed.

Methods

public void disconnect ()

Disconnects the connection, causing the connection's listening thread to exit, and all resources used by the thread (including import and export tables) to be cleaned up.

public void registerForNotification (RtNotificationHandler handler, Object arg, String type)

Adds handler to list of objects which are notified when certain conditions occur. Upon notification, the arg is passed to the handler, the info object is the RtConnection, and the type details the specific notification. Currently, only the type RtConnection.RtDisconnectionNotification is recognized, and the notification is sent whenever the connection disconnects (either explicitly due to a call to the RtNetworkController stopNetworkEnvironment method or the RtConnection disconnect method, or implicitly when a connection fails).

public void unregisterForNotification (RtNotificationHandler handler, Object arg, String type)

Unregisters the object for notification of the specified type. Arg and type must match what was passed into the registerForNotification call.

public boolean isProxyOnConnection (Object object)

Returns true if the Object is an E Proxy for an object on the other side of the connection, false otherwise.

RtConnector

import ec.e.comm.RtConnector;

RtConnector is the class used to establish a network connector. A connector encapsulates the right to establish outbound connections to other objects in the network, named by their URL.

An E-object finds and connects to another E-object on the network by using one of RtConnector's lookup methods. You can restrict this access by limiting the EARL that can be looked up. You can restrict the domain name, object pathname, port, or class. See the Getting Started with E chapter for a description of how E-object EARLs are designated.

Creation

You get the first instance of this class by calling getConnector() on the RtEEnvironment object passed by the RtLauncher.

Methods

public void lookup(String domainName, String objectPath, EDistributor result)

public void lookupOnPort(String domainName, String objectPath, int port, EDistributor result)

Both of these methods look up an E-object on the network.

• domainName is the domain name of the connecting object.
• objectPath is the path name of the desired object.
• result is a distributor forwarded to the object if it is found.
• port is the network port on which the object is vended.

public RtEARLrestrictor getRestrictor()

Gets the current restrictions for the connector object.

public RtConnector restrictDomainName(String restriction)

Restrict domain name lookup access.

public RtConnector restrictObjectPath(String restriction)

Restrict object path name lookup access.

public RtConnector restrictRootClass(Class restriction)

Restrict class lookup access.

Example

This example shows a client connecting to a host using env.getConnector(), which creates a RtConnector. For the full source code, see the section Creating a connector and registrar in the E Runtime chapter.

import ec.e.comm.*;

//
// This is where it all starts, the main function 
//
public class HelloExample
{
    public static void main(String args[]) {
        RtLauncher.launch(new HelloLauncher(), args);
    }
}

//
// This object is totally trusted and makes subenvironment
// things that are passed to other less trusted objects.

eclass HelloLauncher implements ELaunchable
{
  emethod go(RtEEnvironment env) {
    RtNetworkController con;
    int defaultPortNumber = env.getDefaultPortNumber();

    String hostname = env.getProperty("host");
    .........
      // We're the client, connect to host
      HelloExampleClient client = new HelloExampleClient();
      con =
       env.startNetworkEnvironment(defaultPortNumber+1);
      client <- goClient(env, con, hostname);
    }
    }
}

eclass HelloNetworkObject
{
...network controller code

}

eclass HelloExampleClient extends HelloNetworkObject { emethod goClient (RtEEnvironment env, RtNetworkController con, String hostname) { HelloExampleHost host; this.setNetworkController(con); etry { System.out.println("Connecting to host"); env.getConnector().lookupOnPort(hostname, "HelloExampleHost", RtComMonitor.keBasePortNumber, &host); } ecatch (RtDirectoryEException e) { System.out.println("Client caught exception: " + e.getMessage()); } host <- helloThere("This is a string", this); } } eclass HelloExampleHost extends HelloNetworkObject { ...host code }

RtDBViewLimiter

import ec.e.db.RtDBViewLimiter;

import ec.e.db.RtDBViewFilter;

This class is an implementation of a DBViewFilter that imposes access control list semantics on an underlying database view.

The grantor creates a RtDBViewLimiter object, initialized with the desired policy control parameters. This can be passed on to the grantee, who will be restricted to the operations allowed. These objects can be chained, with each link further limiting the powers of the ultimate grantee. An attempt to establish a less restrictive policy will fail because all operations pass control back through the delegation chain.

There are three master control flags:

• readPolicy
• writePolicy
• commitPolicy

There are also two key control lists, which control which root keys the grantee is permitted to read or change. A null key control list has no access restrictions, and lets you read and store all root keys. Otherwise the list lets you read or store only the specified root keys. These lists do not effect access to stream keys, which are considered to be capabilities in themselves.

Creation

viewlimiter object = new RtDBViewLimiter(RtDBViewFilter parent, boolean readPolicy, booleanwritePolicy,boolean commitPolicy, Hashtable readKeys, HashtablewriteKeys);

Constructs a RtDBViewLimiter object, with appropriate access control policies, based on an existing, open PObjDB or RtDBViewLimiter object.

Methods

public RtStreamKey put(Object object) throws DBAccessException;

This saves an object to an object database, and return a RtStreamKey as a token.

public void put(Object rootKey, RtStreamKey streamKey) throwsDBAccessException;

Saves a stream key (RtStreamKey) to an object database under a root key name. Overwrites any existing root key with that name. Note that the RootKey cannot itself be a stream key.

public RtStreamKey get(Object rootKey) throws DBAccessException;

Get a stream key (RtStreamKey) that was previously stored under rootKey. If the stream key does not exist, null is returned. DBAccessException is returned if the request is illegal under security policies.

public Object get(RtStreamKey key) throws DBAccessException;

Given a RtStreamKey, return a copy of the object that was stored out and registered for it. Successive attempts at getting an object will return multiple copies.

public boolean contains(Object key) throws DBAccessException;

Test to determine if something is stored in the database under the given key. In this case, key can be either a RtStreamKey or a root key object.

public void commit() throws DBAccessException;

Commit the changes made to this database back into the parent database. This only works if this database is indeed a child and the permissions permit.

Interfaces

RtDBViewFilter

Example

None

RtDecoder

import ec.e.db.RtDecoder;

This class is a data input stream opened on an input stream buffer. RtDecoder implements the standard Java DataInputStream protocol, along with some extensions for reading and writing object references.

Creation

An object of this class is created internally.

Methods

public Object decode ()

Decodes the object and its information when reading it from an object database.

Example

import ec.e.comm.*;
import ec.e.stream.*;
import java.util.*;
import ec.e.db.*;

eclass HelloLauncher implements ELaunchable
{
  emethod go (RtEEnvironment env) {
    RtNetworkController con = env.startNetworkEnvironment();
    HelloReceiver r = new HelloReceiver();
    HelloSender   s = new HelloSender();
    r <- receive(env);
    s <- send(env, con);
  }
}
public class CoderExample
{
  public static void main(String args[]) {
    RtLauncher.launch(new HelloLauncher());
  }
}

class HelloEException extends RtEException { public HelloEException(String message) { super(message); } } class Opaque implements RtCodeable, RtAwakeAfterDecoding { Opaque next; Person person; Opaque (Person aPerson) { next = this; // Make a circular ref person = aPerson; // Person refers to us, we refer to person } public void encode (RtEncoder coder) { try { coder.encodeObject(person); coder.encodeObject(next); } catch (Exception e) { System.out.println("Exception occured encoding Opaque"); e.printStackTrace(); } } // This is an example of a seek routine public Object decode (RtDecoder coder) { System.out.println("In decodeObject for Opaque"); try { person = (Person) coder.decodeObject(); next = (Opaque) coder.decodeObject(); // Print of Person would fail, // person not fully decoded System.out.println("Person is " + person); } catch (Exception e) { System.out.println("Error decoding Opaque"); e.printStackTrace(); } // Return ourself return this; }

public void awakeAfterDecoding () { System.out.println("Opaque object woke up"); // Safe to do now, everything has been fully decoded System.out.println("Person is " + person); } } // // This class relies on the standard Encoding/Decoding // the system provides // class Person { String name; Opaque opie; String group; transient int temp; // Won't be encoded/decoded since transient static final int magic = 1234; // Static and final aren't encoded/decoded either Person (String aName, String aGroup) { name = aName; group = aGroup; opie = new Opaque(this); } public String toString () { return (name + " in " + group); } } eclass HelloSender { RtEEnvironment environment; RtNetworkController networkController; emethod send (RtEEnvironment env, RtNetworkController con) { HelloReceiver otherGuy; environment = env; networkController = con; Person whacker = new Person("Whacker", "Software"); Person wally = new Person("Wally", "Engineering");

// Lookup the other guy etry { env.getConnector().lookup("localhost", "Doohickey", &otherGuy); } ecatch (RtDirectoryEException e) { System.out.println("Caught exception on lookup: " + e.getMessage()); } // Send a message, this will result in sending // the "yeah" message to us otherGuy <- hello(whacker, this); // Send a message again, this time wrapping it in an etry // On the second message, the other guy will throw an E // exception which will propagate back into the ecatch. etry { otherGuy <- hello(wally, this); } ecatch (HelloEException e) { System.out.println("Caught expected exception: " + e.getMessage()); networkController.stopNetworkEnvironment(); } } emethod yeah () { System.out.println("Received a yeah message"); } } eclass HelloReceiver { boolean sent = false; emethod receive (RtEEnvironment env) { env.getRegistrar().register("Doohickey", this); } emethod hello (Person person, HelloSender sender) { System.out.println("Hola Mundo from " + person); if (sent == false) { sent = true; sender <- yeah(); } else { ethrow new HelloEException("Just testing"); } } }

RtEARL

import ec.e.comm.RtEARL

This class gets an EARL (E Absolute Reference Locator). An EARL is the E equivalent to a Universal Resource Locator (URL), and references an E-object.

Creation

reference = new RtEARL(String referenceString )

Creates an EARL from the unparsed absolute string.

reference = new RtEARL(String referenceString , int referencePort )

reference = new RtEARL(RtEARL seedEARL , String referenceString )

Creates an EARL from the unparsed EARL in the context of the specified EARL.

Methods

public String getProtocol()

Gets the protocol referred to by the EARL.

public String getHost()

Gets the host name referred to by the EARL.

public int getPort()

Get the port number referred to by this EARL.

public String getRef()

Gets the actual descriptor referred to by this EARL. For example, running getRef() on http://www.communities.com/filetoget returns filetoget.

public void ParseEARL(RtEARL seedEARL, String theString)

Generates an EARL object from a string, picking up default values from the seed given.

public EDirectoryServer connect(RtComMonitor thruMonitor)

Connects to a remote machine and gets a proxy to its directory server.

RtEARLrestrictor

import ec.e.comm.RtEARLrestrictor;

This class contains the restrictions for both connectors and registrars. Generally, your program does not directly access an object of this class. However, you can do so to find the restrictions of either of these objects.

Creation

This class is generated automatically when you create a restricted path environment for a connector or registrar. You get it in RtConnector's or RtRegistrar's getRestrictor method.

Methods

public String getDomainName()

public String getObjectPath()

public int getPort()

public Class getRootClass(

public RtEARLrestrictor restrictDomainName(String restriction)

public RtEARLrestrictor restrictObjectPath(String restriction)

public RtEARLrestrictor restrictPort(int restriction)

public RtEARLrestrictor restrictRootClass(Class restriction)

RtEException

import ec.e.run.RtEException;

RtEException is the base class for all E exceptions. These are exceptions thrown by ethrow and caught by ecatch blocks. All E exceptions must be based on this class.

Unlike Java, E does not require your E-methods to either catch or declare non-runtime E exceptions.

Note that RtEException is based on the Java RuntimeException class, not Exception, so it does not encapsulate a back stack trace.

Creation

exception = new RtEException (exceptionstring )

Methods

public String getMessage()

Gets the detail message of the exception.

Example

class UniqueEException extends RtEException {
    public UniqueEException(String message) {
        super(message);
    }
}

RtEEnvironment

import ec.e.comm.RtEEnvironment;

Use this class to create E environment objects. These objects contain classes and methods to create other objects that take full advantage of the E environment facilities, such as networking and file system access.

You "launch" an E-object to give it full access to all of an E Environment's facilities. From this trusted object, you can create a more specified, restricted environment and pass this to another object.

You can pass in arguments when you launch an object to set environment properties and arguments. You can pass in properties (those of x=y format, such as host=localhost), or arguments pertinent to your environment (arguments without "="). When you launch an object, those arguments are put into an environment dictionary.

You can pass in either arguments specific to that launched object, or the same ones that were entered at the command line. This lets you set the same environment properties for your launched object as you did for your main program.

In both Java and E, when you enter command line arguments to your program, these are put into a standard arguments array. In E, when you launch an object, any arguments of the form x=y are stripped out of the standard argument array, and put into a Properties hashtable, with x being the property key, and y being the property value. This makes it easy to specify properties on the command line, and then later retrieve specific ones to pass to environment objects. Arguments without "=" are retained in the standard argument string array.

NOTE: After you launch an object, E strips out any E-provided system arguments (the -EC* arguments) from the standard arguments array, since these are only pertinent to that execution of the program. See the description of these arguments in the E compiler documentation in Appendix A for more information.

To access the arguments and property hash table, you use RtEEnvironment's getObjectFromDictionary method.

Creation

environmentobject = new RtEEnvironment(RtNetworkEnvironment net,RtFileEnvironment file, Hashtable dict)

or

RtEEnvironment environmentobject

Constants

public final static String DefaultPropertyValue = "DefaultPropertyValue";

This is the default value for arguments passed in without values. For example, if you specify an argument "client=", and then get the property value, the value DefaultPropertyValue is returned. You can check for this default value using the == symbol. For example:

  if (env.getProperty("port")
    ==RtEEnvironment.DefaultPropertyValue)
  ...

Methods

public RtConnector getConnector()

Get the first instance of a RtConnector.

public RtFileEnvironment getFileEnvironment()

Get the first instance of a RtFileEnvironment.

public RtRegistrar getRegistrar()

Get the first instance of a RtRegistrar.

public Object putObjectInDictionary(Object key, Object value)

Stores the specified object in the environment dictionary.

public Object getObjectFromDictionary(Object key)

Gets the specified object from the environment dictionary. You can get either of the following:

• A hash table of all environment properties by specifying key "Properties"
• The command line arguments string array by specifying key "Args"

public boolean startNetworkEnvironment (int port)

public boolean startNetworkEnvironment ()

These two methods both start a network environment, and return a RtNetworkController object, which you can use to control and stop the network environment.

public boolean isNetworkEnvironmentStarted ()

Indicates whether the E network environment is started.

public RtEEnvironment createEEnvironment (Hashtable components)

This method creates a new RtEEnvironment object which is based on an existing environment. The caller (that is, the RtEnvironment on which this method) can selectively grant its capabilities to the new object (see the following list). The Hashtable can (but does not have to) contain the following:

• The key Connector and the value an RtConnector.
• The key Registrar and the value an RtRegistrar.
• The key FileEnvironment and the value an RtFileEnvironment.
• The key Dictionary and the value a hashtable.

Any of these that are not in the Hashtable will be taken from the RtEEnvironment object the method is called on.

public String getProperty (String key)

Returns the value for the specified key. Property value(s) are kept in a Property dictionary created by RtLauncher's launch method. RtLauncher.launch creates this dictionary from the passed-in array of arguments. For example, if you passed the argument host=localhost, calling object .getProperty("host") returns localhost.

Example

The following sample program demonstrates using RtEEnvironment to create restricted E application environments. This example restricts an object's file system access so it can only traverse a specific directory hierarchy.

Assume you run this example with the following line:

  javaec ec.examples.file path=/tmp/examples

This path argument will be passed to the launched object.

  import java.lang.*;
  import java.io.*;
  import java.util.Hashtable;
  
  import ec.e.comm.*;
  
  //
  // This is the boilerplate main that starts the whole
  // ball rolling. You launch something you trust and let
  // that make the determination of what it wants to hand
  // out to other objects.
  //
  public class FileExample
  {
    public static void main(String args[]) {
      if (args.length < 1) {
        System.out.println("Need to specify restriction 
          dir path");
        System.exit(0);
      }
      //In this launch method, args is the string array 
      //passed to main when you ran javaec
      RtLauncher.launch(new EFileExampleLauncher(), args);
    }
  }
  
  //
  // This is what is launched, and as stated before is something
  // you trust. It determines what to hand out to other entities.
  // In this (simple) case, it uses the directory handed to it
  // from the command line arguments (found in the RtEEnvironment)
  // to determine the subdirectory it grants access to.
  //

eclass EFileExampleLauncher implements ELaunchable { emethod go (RtEEnvironment env) { // Get the path property we entered at command line, // and use this as the directory to restrict to String resPath=env.getProperty("path"); System.out.println("Restricting path to " + resPath); // Get the file environment and make the more restricted one RtFileEnvironment fileEnv = env.getFileEnvironment(); RtFileEnvironment restrictedFileEnv = fileEnv.restrictPath(resPath); // Create the entity we trust with this restricted // file environment and hand it the file env in a message EFileExample theFileExample = new EFileExample(); theFileExample <- doStuff (restrictedFileEnv); } } // // This code would be loaded from somewhere else and // you would provide the restricted file environment to it. // eclass EFileExample { emethod doStuff (RtFileEnvironment fileEnv) { try { String dirName = "/test/temp"; System.out.println("Dir Env rooted at " + fileEnv.getDirectory(dirName).getPath()); // This will return an object for temp in the // restricted file env RtFileDirectory dir = fileEnv.getDirectory(dirName); // This will return a file object for temp/filetest RtFile testFile = dir.getFile("filetest"); // etc.... } catch (IOException e) { System.out.println("Exception occurred: " + e.getMessage()); e.printStackTrace(); } } }

RtEncoder

import ec.e.db.RtEncoder;

This class is a data output stream opened on an output stream buffer. RtEncoder implements the standard Java DataOutputStream protocol, along with some extensions for reading and writing object references.

Creation

An object of this class is created internally.

Methods

public void encode (Object object)

Encodes the object and its information to store it to an object database.

Example

import ec.e.comm.*;
import ec.e.stream.*;
import java.util.*;
import ec.e.db.*;

eclass HelloLauncher implements ELaunchable
{
  emethod go (RtEEnvironment env) {
    RtNetworkController con = env.startNetworkEnvironment();
    HelloReceiver r = new HelloReceiver();
    HelloSender   s = new HelloSender();
    r <- receive(env);
    s <- send(env, con);
  }
}

public class CoderExample
{
  public static void main(String args[]) {
    RtLauncher.launch(new HelloLauncher());
  }
}

class HelloEException extends RtEException { public HelloEException(String message) { super(message); } } class Opaque implements RtCodeable, RtAwakeAfterDecoding { Opaque next; Person person; Opaque (Person aPerson) { next = this; // Make a circular ref person = aPerson; // Person refers to us, we refer to person } public void encode (RtEncoder coder) { try { coder.encodeObject(person); coder.encodeObject(next); } catch (Exception e) { System.out.println("Exception occured encoding Opaque"); e.printStackTrace(); } } // This is an example of a seek routine public Object decode (RtDecoder coder) { System.out.println("In decodeObject for Opaque"); try { person = (Person) coder.decodeObject(); next = (Opaque) coder.decodeObject(); // Print of Person would fail, // person not fully decoded System.out.println("Person is " + person); } catch (Exception e) { System.out.println("Error decoding Opaque"); e.printStackTrace(); } // Return ourself return this; }

public void awakeAfterDecoding () { System.out.println("Opaque object woke up"); // Safe to do now, everything has been fully decoded System.out.println("Person is " + person); } } // // This class relies on the standard Encoding/Decoding // the system provides // class Person { String name; Opaque opie; String group; transient int temp; // Won't be encoded/decoded since transient static final int magic = 1234; // Static and final aren't encoded/decoded either Person (String aName, String aGroup) { name = aName; group = aGroup; opie = new Opaque(this); } public String toString () { return (name + " in " + group); } } eclass HelloSender { RtEEnvironment environment; RtNetworkController networkController; emethod send (RtEEnvironment env, RtNetworkController con) { HelloReceiver otherGuy; environment = env; networkController = con; Person whacker = new Person("Whacker", "Software"); Person wally = new Person("Wally", "Engineering"); // Lookup the other guy etry { env.getConnector().lookup("localhost", "Doohickey", &otherGuy);

} ecatch (RtDirectoryEException e) { System.out.println("Caught exception on lookup: " + e.getMessage()); } // Send a message, this will result in sending // the "yeah" message to us otherGuy <- hello(whacker, this); // Send a message again, this time wrapping it in an etry // On the second message, the other guy will throw an E // exception which will propagate back into the ecatch. etry { otherGuy <- hello(wally, this); } ecatch (HelloEException e) { System.out.println("Caught expected exception: " + e.getMessage()); networkController.stopNetworkEnvironment(); } } emethod yeah () { System.out.println("Received a yeah message"); } } eclass HelloReceiver { boolean sent = false; emethod receive (RtEEnvironment env) { env.getRegistrar().register("Doohickey", this); } emethod hello (Person person, HelloSender sender) { System.out.println("Hola Mundo from " + person); if (sent == false) { sent = true; sender <- yeah(); } else { ethrow new HelloEException("Just testing"); } } }

RtEnvelope

import ec.e.run.RtEnvelope;

RtEnvelope is the Java class for all envelopes, which encapsulate messages. Envelopes can be opened only by an E-object with the correct unsealer.

An envelope encapsulates the parameters of a message and ensures that they can only be read by a recipient E-object with the correct unsealer. The envelope is marked by a sealer that indicates the unsealer needed to open it. The message in the envelope is secured by the unforgeable sealer and unsealer associated with it.

Creation and methods

Envelopes are created implicitly on the E-message send, and are queued on the E runtime message queue, along with the object the message was sent to and the current runtime environment. The E compiler also creates unopened envelopes when you compile an E program.

Example

None

RtFile

import ec.e.comm.RtFile;

This class lets you get a series of file objects related to a file. These objects can be read-only, write-only and read-write.

Creation

An object of this class is created by a call to either a RtFileEnvironment or RtFileDirectory object.

Methods

public InputStream getInputStream() throws IOException

Returns an InputStream object associated with this file.

public OuputStream getOutputStream() throws IOException

Returns an OuputStream object associated with this file.

public RtFileDataInput getDataInput() throws IOException

Returns a read-only seekable file object that implements the Java DataInput interface.

public RtFileDataOutput getDataOutput() throws IOException

Returns a write-only seekable file object that implements the Java DataOutput interface.

public RtRandomAccessFile getRandomAccessFile() throws IOException

Returns a read-write seekable file object that implements the java DataInput and DataOutput interfaces, as well as other methods documented in the next section.

public String getPath()

Returns the path associated with the file.

RtFileDataInput

import ec.e.comm.RtFileDataInput;

This class is a data input wrapper class for java.io.RandomFileAccess. This class is a seekable read-only file.

Creation

An object of this class is created by invoking a getDataInput method on an existing RtFile object.

Methods

public void close() throws IOException

Closes the file.

public void seek(long pos) throws IOException

Sets the file pointer to the specified absolute position.

public int skipBytes(int n) throws IOException

public long getFilePointer() throws IOException

Returns the current location of the file pointer.

public long length() throws IOException

Returns the length of the file.

public int read() throws IOException

Read a byte.

public int read(byte b[],int off, int len) throws IOException

public int read(byte b[]) throws IOException

Read an array of bytes.

public final void readFully(byte b[]) throws IOException

public final void readFully(byte b[], int off, int len)throws IOException

public final boolean readBoolean() throws IOException

Read a boolean.

public final byte readByte() throws IOException

Read a byte.

public final int readUnsignedByte() throws IOException

Read an unsigned byte.

public final short readShort() throws IOException

Read a short.

public final int readUnsignedShort() throws IOException

Read an unsigned short.

public final char readChar() throws IOException

Read a char.

public final int readInt() throws IOException

Read an int.

public final long readLong() throws IOException

Read a long.

public final float readFloat() throws IOException

Read a float.

public final double readDouble() throws IOException

Read a double.

public final String readLine() throws IOException

Read a line terminated by a `/n' or EOF.

public final String readUTF() throws IOException

Read a UTF format string.

Interfaces

java.io.DataInput

RtFileDataOutput

import ec.e.comm.RtFileDataOuput;

This class is a data output wrapper class for java.io.RandomFileAccess, and is a seekable write-only file.

Creation

An object of this class is created by invoking a getDataOutput method on an existing RtFile object.

Methods

public void close() throws IOException

Closes the file.

public void seek(long pos) throws IOException

Sets the file pointer to the specified absolute position.

public int skipBytes(int n) throws IOException

public long getFilePointer() throws IOException

Returns the current location of the file pointer.

public long length() throws IOException

Returns the length of the file.

public void write(int b) throws IOException

Write a byte.

public void write(byte b[]) throws IOException

Write an array of bytes.

public void write(byte b[],int off,int len) throws IOException

public final void writeBoolean(boolean v) throws IOException

Write a boolean.

public final void writeByte(int v) throws IOException

Write a byte.

public final void writeShort(int v) throws IOException

Write a short.

public final void writeChar(int v) throws IOException

Write a char.

public final void writeInt(int v) throws IOException

Write an int.

public final void writeLong(long v) throws IOException

Write a long.

public final void writeFloat(float v) throws IOException

Write a float.

public final void writeDouble(double v) throws IOException

Write a double.

public final void writeBytes(String s) throws IOException

Write a string as a sequence of bytes.

public final void writeChars(String s) throws IOException

Write a string as a sequence of chars.

public final void writeUTF(String s) throws IOException

Write a string in UTF format.

Interfaces

java.io.DataOuput

RtFileDirectory

import ec.e.comm.RtFileDirectory;

This class lets you navigate and retrieve existing files and directories within its path. It cannot create or delete files or directories. You cannot use '..' as a file token.

Creation

An object of this class is created by a call on an RtFileEnvironment.

Methods

public RtFile getFile(String path) throws IOException

Returns file if it exists, otherwise it throws an exception.

public boolean exists(String path)

Returns true if a file object exists at that path.

public String[] list()

Returns a string array of the directories' contents.

public RtFileDirectory chdir(String path) throws IOException

Returns an RtFileDirectory object if there is a directory under that path, otherwise it throws an exception.

public RtFileDirectory getParent() throws IOException

Returns an RtFileDirectory object if there is a directory at that path, otherwise it throws an exception.

public String getPath()

Returns path within the restriction.

Example

None

RtFileEnvironment

import ec.e.comm.RtFileEnvironment;

This class encapsulates all of the file management functions, including getting, creating and deleting directories and files. It works within a restricted path. The RtFileEnvironment that you get from the E Environment starts with read/write access to the entire file system, which you can then restrict and give to less trusted objects.

You get files and objects by string names which return RtFileDirectory or RtFile objects. You cannot use '..' as a file token.

Creation

You get the first instance of this object by calling getFileEnvironment() on the RtEEnvironment passed by the RtLauncher.

Methods

public RtFileEnvironment restrictPath(String path)

Returns a further restricted RtFileEnvironment.

public boolean exists(String path)

Returns true if an object exists in that path, it does not distinguish between files and directories.

public boolean isFile(String path)

Returns true if there is a file at that path.

public boolean isDirectory(String path)

Returns true if there is a directory at that path.

public RtFile getFile(String path) throws IOException

Returns the RtFile if it exists.

public RtDirectory getDirectory(String path)

Returns a RtFileDirectory if it exists within the restricted scope, otherwise it returns null.

public RtFileDirectory mkdir(String path)

Returns a RtFileDirectory if creation was successful, otherwise it returns null.

public RtFileDirectory mkdirs(String path)

Returns a RtFileDirectory if creation of all the directories in the path was successful, otherwise it returns null.

public boolean renameTo(String path, String newName)

Renames the file object at that path, returns true if successful.

public boolean delete(RtFile thisFile)

Deletes the given file, returns true if successful.

public boolean delete(RtFileDirectory thisDir)

Deletes the given directory, returns true if successful.

public boolean delete(String path)

Tries to delete the path without distinguishing if it is a directory or a file, returns true if successful.

Example

This program excerpt restricts an object's file system access so it can only traverse a specific directory hierarchy. Assume you run this program with the following command line:

  javaec ec.examples.FileExample "path=/tmp/examples

The path string ("path=/tmp/examples") is passed to the launched object, which uses it to build a restricted file access.

  import java.util.Hashtable;
  import ec.e.comm.*;
  
  public class FileExample
  {
    public static void main(String args[]) {
      if (args.length < 1) {
        System.out.println("Need to specify restriction 
          dir path");
        System.exit(0);
      }
      RtLauncher.launch(new EFileExampleLauncher(), args);
    }
  }
  

eclass EFileExampleLauncher implements ELaunchable { emethod go (RtEEnvironment env) { // Get the path property we entered at command line, // and use this as the directory to restrict to String resPath=env.getProperty("path"); System.out.println("Restricting path to " + resPath); // Get the file environment and make the more restricted one RtFileEnvironment fileEnv = env.getFileEnvironment(); RtFileEnvironment restrictedFileEnv = fileEnv.restrictPath(resPath); // Create the entity we trust with this restricted // file environment and hand it the file env in a message EFileExample theFileExample = new EFileExample(); theFileExample <- doStuff (restrictedFileEnv); } } ..........

RtLauncher

import ec.e.comm.RtLauncher;

RtLauncher is the class that launches objects in the E runtime. This class's launch method creates general RtEEnvironment instances, and launches a target object by invoking the go method of the ELaunchable E-interface. That object can restrict the environment and launch other objects with the more restricted environment.

Creation

None. Only static methods are used in this class.

Methods

static public void launch(EObject userObject)

static public void launch (EObject userObject, String args)

Both of these methods launch a new object containing all the RtEEnvironment functionality. You create objects from this class and then give them more specific functionality, such as a file server. args is a string array that lets you pass in arguments. You can pass in the argument string array entered at the command line (by using the args parameter) or a argument string specific to that object. This feature lets you pass these same arguments to objects you are "sub-launching".

If you pass in an argument of the form x=y (for example, host=george), E strips this argument out of the argument array and puts it in a properties table, with x being the key, and y being the value. You can then use RtEEnvironment's getProperty method to retrieve a value associated with a specific key. See the documentation on this method for more information.

Note that any standard EC* arguments are stripped out of the standard arguments array when you launch an object. This lets you run a program with standard command-line arguments without them being passed to any objects you launched. See the description of these arguments in the E Java Interpreter documentation in Appendix A, E Tools and Utilities.

static public void setupClassLoader(int securitymode);

You can set up E's class loader to run in three different security modes:

• 0 (SL_NONE)

The loader does not check the class for proper certification.

• 1 (SL_PERMISSIVE)

The loader checks the class for the proper certificate, but still loads the class even if the class check fails.

• 2 (SL_STRICT)

If the loader encounters an "illegal" class, it does not load the class, and exits.

Levels 0 and 1 are for development purposes only. They let you develop and test without having a completely built certificate database. Level 0 is especially fast since it does no checking; this makes it useful for testing purposes (for example, testing performance). Level 1 is slower, but does not require signed certificates during development and testing. For more information on E's certification and authentication features, see the E Runtime chapter's section on Authentication, and also the Class Blesser section in Appendix A, E Tools and Utilities.

Example

This example launches a EFileExampleLauncher object. The arguments passed to launch is the string argument passed from the command line.

  import java.lang.*;
  import java.util.Hashtable;
  import ec.e.comm.*;
  
  //
  // This is the boilerplate main that starts the whole
  // ball rolling. You launch something you trust and let
  // that make the determination of what it wants to hand
  // out to other objects.
  //
  public class FileExample
  {
    public static void main(String args[]) {
      if (args.length < 1) {
        System.out.println("Need to specify restriction 
          dir path");
        System.exit(0);
      }

//In this launch method, args is the string array //passed to main when you ran javaec RtLauncher.launch(new EFileExampleLauncher(), args); } } // // This is what is launched, and as stated before is something // you trust. It determines what to hand out to other entities. // In this (simple) case, it uses the directory handed to it // from the command line arguments (found in the RtEEnvironment) // to determine the subdirectory it grants access to. // eclass EFileExampleLauncher implements ELaunchable { emethod go (RtEEnvironment env) { // Get the path property we entered at command line, // and use this as the directory to restrict to String resPath=env.getProperty("path"); System.out.println("Restricting path to " + resPath); // Get the file environment and make the more restricted one RtFileEnvironment fileEnv = env.getFileEnvironment(); RtFileEnvironment restrictedFileEnv = fileEnv.restrictPath(resPath); // Create the entity we trust with this restricted // file environment and hand it the file env in a message EFileExample theFileExample = new EFileExample(); theFileExample <- doStuff (restrictedFileEnv); } } .............

RtNetworkController

import ec.e.run.EEnvironment;

This class contains the stopNetworkEnvironment method, which lets you stop a network environment. Only those objects with access to the RtNetworkController class can shut down a network environment.

Creation

An instance of this class is returned from a RtEEnvironment's startNetworkEnvironment method.

Methods

public void stopNetworkEnvironment ()

public void stopNetworkEnvironment (boolean stopAllConnectionsToo)

Both of these methods shut down an E network environment started by the startNetworkEnvironment method.

The first method takes no arguments, and stops all connections. The second method shuts down all connections if stopAllConnectionsToo is true; if false, they are not stopped.

public RtConnection getConnectionForHost(String hostname)

public RtConnection getConnectionForHostAndPort(String hostname, int port)

These two methods both get the RtConnection object for the given hostname. You can pass in localhost for the local machine. The getConnectionForHostAndPort distinguishes the port as well.

public void setNetworkDelegate(Object delegate)

Example

eclass HelloLauncher implements ELaunchable
{
  emethod go (RtEEnvironment env) {

// This is the new API, you get back a network controller
// from the startNetworkEnvironment method on the RtEEnvironment

    RtNetworkController con = env.startNetworkEnvironment();

// We trust one of these objects with the capability to
// shutdown the network, but we don't want to let other
// objects (like "LessTrustedObject") have this capability

    MoreTrustedObject mto = new HelloReceiver(env, con);
    LessTrustedObject lto = new LessTrustedObject(env);
  }
}

eclass MoreTrustedObject
{
  RtNetworkController networkController;

  MoreTrustedObject (RtEEnvironment env, 
      RtNetworkController con) {
    networkController = con;
        // ...
  }

  emethod shutdown () {
  // This object can shut down the Com system because it
  // has the capability implicit in the networkController.

    networkController.stopNetworkEnvironment();
        // ...
  }
}

RtRandomAccessFile

import ec.e.comm.RtRandomAccessFile;

This class wraps a complete random access file. It encapsulates the methods for Java's RandomAccessFile class.

Creation

An object of this class is created by invoking a getRandomAccessFile method on an existing RtFile object.

Methods

These methods are the same as Java's RandomAccessFile class.

public void close() throws IOException

Close the file.

public void seek(long pos) throws IOException

Set the file pointer to the specified absolute position.

public int skipBytes(int n) throws IOException

public long getFilePointer() throws IOException

Return the current location of the file pointer.

public long length() throws IOException

Return the length of the file.

public int read() throws IOException

Read a byte.

public int read(byte b[], int, int) throws IOException

public int read(byte b[]) throws IOException

Read an array of bytes.

public final void readFully(byte b[]) throws IOException

public final void readFully(byte b[], int off,int len) throws IOException

public final boolean readBoolean() throws IOException

Read a Boolean.

public final byte readByte() throws IOException

Read a byte.

public final int readUnsignedByte() throws IOException

Read unsigned byte.

public final short readShort() throws IOException

Read a short.

public final int readUnsignedShort() throws IOException

Read an unsigned short.

public final char readChar() throws IOException

Read a char.

public final int readInt() throws IOException

Read a int.

public final long readLong() throws IOException

Read a long.

public final float readFloat() throws IOException

Read a float.

public final double readDouble() throws IOException

Read a double.

public final String readLine() throws IOException

Read a line terminated by a `/n' or EOF.

public final String readUTF() throws IOException

Read a UTF format string.

public void write(int b) throws IOException

Write a byte.

public void write(byte b[]) throws IOException

Write an array of bytes.

public void write(byte b[],int off,int len) throws IOException

public final void writeBoolean(boolean v) throws IOException

Write a boolean.

public final void writeByte(int v) throws IOException

Write a byte.

public final void writeShort(int v) throws IOException

Write a short.

public final void writeChar(int v) throws IOException

Write a char.

public final void writeInt(int v) throws IOException

Write an int.

public final void writeLong(long v) throws IOException

Write a long.

public final void writeFloat(float v) throws IOException

Write a float.

public final void writeDouble(double v)throws IOException

Write a double.

public final void writeBytes(String s) throws IOException

Write a string as a sequence of bytes.

public final void writeChars(String s) throws IOException

Write a string as a sequences of chars.

public final void writeUTF(String s) throws IOException

Write a string in UTF format.

Interfaces

java.io.DataInput

java.io.DataOutput

RtRegistration

import ec.e.comm.RtRegistration;

This class encapsulates functionality for an E-object that is registered (through E registration facilities) on the network.

Creation

Registering an E-object using RtRegistrar's register method returns an object of this class. You do not create a RtRegistration object manually.

Methods

public void unregister() throws RtDirectoryException

Unregisters an object from the network.

Example

None

RtRegistrar

import ec.e.comm.RtRegistrar;

This class encapsulates the right to register objects by name in the local machine's object directory.

To register an E-object, use the register method. You can use the methods in this class to generate a more restricted registration path, and pass that down to objects that register in a more restricted environment. To unregister an object, use RtRegistration's unregister method.

Creation

Created internally by RtEEnvironment. You get the first instance of this class by calling getRegistrar() on an RtEEnvironment object.

Methods

public RtEARLrestrictor getRestrictor()

Returns the current registrar's restricted path.

public RtRegistrar restrictObjectPath(String restriction)

public RtRegistrar restrictRootClass(Class restriction)

public RtRegistration register(String objectPath, EObject obj)

Registers the object on the network according to the objectPath. This method returns an object of class RtRegistration.You can use RtRegistration's unregister method to unregister your object.

public RtNetworkEnvironment getNetworkEnvironment()

Example

This example instantiates a host object, and then uses the getRegistrar() method to register it, which creates an RtRegistrar. A client can then use this information to connect to the host. For the full code, see the section Creating a connector and registrar in the E Runtime chapter.

import ec.e.comm.*;

//
// This is where it all starts, the main function 
//
public class HelloExample
{
  public static void main(String args[]) {
    RtLauncher.launch(new HelloLauncher(), args);
  }
}

//
// This guy is totally trusted and makes subenvironment
// things that are passed to other less trusted objects.

eclass HelloLauncher implements ELaunchable
{
  emethod go(RtEEnvironment env) {
    RtNetworkController con;
    int defaultPortNumber = env.getDefaultPortNumber();

    String hostname = env.getProperty("host");
    if (hostname == null) {
      // We'll be the host
      HelloExampleHost host = new HelloExampleHost();
      con = env.startNetworkEnvironment(defaultPortNumber);
      host <- goHost(env, con);
  .....
    }
  }
}

eclass HelloNetworkObject { code } eclass HelloExampleClient extends HelloNetworkObject { ....client code } eclass HelloExampleHost extends HelloNetworkObject { emethod goHost (RtEEnvironment env, RtNetworkController con) { this.setNetworkController(con); System.out.println("Registering host"); env.getRegistrar().register("HelloExampleHost", this); } emethod helloThere (String theString, EObject sender) { System.out.println("Hello World"); if (sender != null) sender <- stopNetwork(); this <- stopNetwork(); } }

RtSystem

import ec.e.comm.RtSystem;

This class encapsulates the functionality of the java.lang.System class, and provides similar access to system functionality in the E runtime. You should use this class instead of java.lang.System in your E program.

Creation

You do not create an object of this class manually.

Variables

in

public static InputStream in = System.in.

Standard input stream.

out

public static OutputStream out = System.out

Standard output stream. This stream lets you print messages.

err

public static PrintStream err = System.err;

Standard error stream. You can use this stream to print error messages.

Methods

public static long currentTimeMillis()

Returns the current system time in milliseconds GMT since this epoch (00:00:00: UTC, January 1, 1970). It is a signed 64 bit integer and will not overflow until the year 292280995.

public static void arraycopy(Object src, int src_position,Object dst,int dst_position,int length)

Copies an array of Java objects.

• src is the source data.
• src_position is the start position in the source data.
• dst is the destination
• dst_position is the start position in the destination data.
• length is the length of the data to be copied.

public static void gc()

Returns the Java garbage collector (note that this is not the E distributed garbage collector). You generally do not have to call this manually since the Java garbage collector runs automatically whenever the system is idle, or when object allocation fails.

public static void runFinalization()

Runs the finalization methods of any objects pending finalization. You generally do not have to call this method manually since finalization methods are called asynchronously by a finalization thread. However, since you choose finalized resources, there is no built-in equivalent of the garbage collector running when the system runs out of memory. You can use this method to build equivalent functionality into your resource allocators.

RtTimer

import ec.e.run.RtTimer;

RtTimer is a Java class implementing basic timer services. An RtTimer object runs in its own thread, and calls a handleTimeout method on objects when a specified timeout occurs. See the interface definition for RtTimeoutHandling for more information about the handleTimeout method.

Timeouts are requested by specifying a timeout interval in milliseconds, and an object to call back when the timeout occurs. The object specified must implement the Java RtTimeoutHandling interface, as the method handleTimeout is called when the timeout occurs. Note that the handleTimeout method should be called in the RtTimer's thread, not the thread which was running at the time of the request.

Note there is one thread per RtTimer. If you just want to have one timer thread, only create one RtTimer and have everything use that.

Creation

timer = new RtTimer();

You can also optionally specify a name to be used as the name of the thread:

timer = new RtTimer(String name);

Methods

public int setTimeout (long millis, RtTimeoutHandling target, Object arg)

public int setTimeout (long millis, EObject target, RtEnvelope envelope)

public int setTimeout (long millis, EDistributor key){

• millis is the millisecond timeout value
• target is an object implementing RtTimeoutHandling which will have its handleTimeout method invoked when the timeout occurs
• arg is an argument which will be passed to the target object's handleTimeout method.The return value is a timer ID which is unique within this specific RtTimer instance. This can be used to cancel the timeout, and is passed to the target object's handleTimeout methods.

public boolean cancelTimeout (int tid)

tid is the timer ID returned by a previous call to setTimeout on the same RtTimer.

public void terminate ()

Stops the thread running the timer. All pending timeouts are cancelled.

Example

eclass ThingThatHandlesTimeouts
{
  emethod doSomething (EObject other) {
    EBoolean timeout;
    EInteger result;
    RtTimer timer = new RtTimer();
    int tid;
    
    // set timeout
    tid = timer.setTimeout(1000, &timeout);
    
    // Ask some other object to do something for us
    other <- askForResult(&result);
    
    // Other object notifies us it is done 
    // by forwarding something to result
    ewhen result (int res) {
      timer.cancelTimeout(tid); // We don't need it
      timer.terminate();  
      System.out.println("Got result: " + res);
    }
    // We'll enter here if we timeout before 
    // the other responds
    eorwhen timeout (boolean t) {
      System.out.println("Timed out");
      timer.terminate();  
    }
  }
}

ELaunchable

import ec.e.comm.ELaunchable;

This E-interface contains the go method. You use this method when creating E Environment objects that create restricted environments for other objects. See the Creating access-controlled objects section in the E Runtime chapter for an example.

E-methods

go (RtEEnvironment env );

To create an E Environment object, you first launch a trusted object with RtLauncher.launch. In the class definition of this trusted object, you invoke the go method to give the E- object full access to the E environment capabilities. The go method passes an RtEEnvironment object parameter so your class can access the RtEEnvironment facilities.

IBoolean

import ec.e.run.IBoolean;

This E-interface contains mathematical functions used for EBoolean objects.

E-methods

and(EBoolean operand, EDistributor result);

or(EBoolean operand, EDistributor result);

xor(EBoolean operand, EDistributor result);

eqv(EBoolean operand, EDistributor result);

not(EDistributor result);

RtAwakeAfterDecoding

import ec.e.db.RtAwakeAfterDecoding;

This is a method interface for objects that need to take some action after a graph of objects has been decoded. RtDecoder checks objects it decodes to see if they implement this interface, and remembers the ones that do. After decoding an entire graph, RtDecoder calls the awakeAfterDecoding method on all of the objects that implement this interface.

Methods

void awakeAfterDecoding ()

This is called on objects (that implement the RtAwakeAfterDecoding interface) after all objects in a graph of objects have been decoded. This allows objects in a complex graph to take some action (such as start a thread running) when it is sure that all of the objects that are a part of that graph have been decoded (it might not be safe to do certain things in the decode() method called on objects, as other objects in the graph might not be completely decoded at that point).

RtCodeable

import ec.e.db.RtCodeable;

This class is an interface for object storage methods. Using the methods in this interface lets you define your own methods for storing and filing a class state to and from the stream objects used to implement persistence and communication. This can be more efficient than relying on the native method stream-in and stream-out code. It can also be more robust with respect to instance variable type and position changes. For example, you can include code for your class that recognizes older versions streamed out long ago.

This interface extends RtEncodeable and RtDecodeable, and thus contains their encode and decode methods (respectively). Generally, you should use RtCodeable to encode/decode objects, rather than using than RtEncodeable or RtDecodeable.

However, there will be situations where an object should be only codeable but not decodeable, and vice versa. For example, you may want to encode an object of class A so that it is decoded as an instance of a different class B, but not want to force instances of class B to be encodeable. In these types of situations, implement the object(s) using either RtEncodeable (to use only the encode method), or RtDecodeable (to only use the decode method). See the documentation on these interfaces for more information.

Methods

Contains the RtEncodeable.encode and RtDecodeable.decode methods since it extends both of these classes. See the documentation on these methods for more information.

RtDecodeable

import ec.e.db.RtDecodeable;

This interface contains the decode method used for retrieving an object from a object database. Using the decode method lets you define your own method for recalling an object (from the data stream) that is used to implement persistence and communication. This can be more efficient than relying on the native stream-in code. It can also be more robust with respect to instance variable type and position changes.

Generally, you will want to use the RtCodeable interface when encoding and decoding objects. This interface extends RtDecodeable and RtEncodeable, and thus contains the encode and decode methods of these interfaces.

However, there will be situations where an object should be only decodeable, and not encodeable, and vice versa. For example, assume you encode an object of class A so that it is decoded as an instance of a different class B. However, you might not want to force instances of class B to be encodeable just because you want to decode them; in other words, you want objects of class B to be sent over the network by reference only, even though they can show up as a copy when an A is encoded.

To do this, have class A implement RtEncodeable, and class B implement RtDecodeable. This lets instances of A be encodeable, but only lets instances of B (encoded from an A) be decoded, and not encodeable themselves.

Methods

Object decode (RtDecoder coder);

Read an object from the stream. This method calls the appropriate read method on the RtDecoder object to load internal state. RtDecoder implements the standard Java DataInputStream protocols, along with some extensions for reading and writing objects.

You can override this method with your own decoding methods to customize how your objects are read from the database.

Note that the decode method is expected to return the object decoded, which should usually be yourself. (In some special cases this object can be different from the object sent the decode message, if necessary).

The decode method attempts to respect the interconnections of objects in the context of a given stream-out or stream-in operation.

If the object needs to decode a sub-object, it can call decode on the RtDecoder.

RtEncodeable

import ec.e.db.RtEncodeable;

This interface contains the encode method used for storing an object to an object database. Using the encode method lets you define your own method for storing an object that is used to implement persistence and communication. This can be more efficient than relying on the native stream-out code. It can also be more robust with respect to instance variable type and position changes. For example, you can include code for your class that recognizes older versions streamed out long ago.

Generally, you will want to use the RtCodeable interface when encoding and decoding objects, instead of this interface. RtCodeable extends RtDecodeable and RtEncodeable, and thus contains the encode and decode methods of these interfaces.

However, there will be situations where an object should be only decodeable, and not encodeable, and vice versa. For example, assume you encode an object of class A so that it is decoded as an instance of a different class B. However, you might not want to force instances of class B to be encodeable just because you want to decode them; in other words, you want objects of class B to be sent over the network by reference only, even though they can show up as a copy when an A is encoded.

To do this, have class A implement RtEncodeable, and class B implement RtDecodeable. This lets instances of A be encodeable, but only lets instances of B (encoded from an A) be decoded, and not encodeable themselves.

Methods

void encode (RtEncoder coder);

Stores an object to an output stream. This method calls appropriate write methods on the RtEncoder object to save internal state. RtEncoder implements the standard JavaDataOutputStream protocol, along with some extensions for writing objects.

You can override this method with your own encoding method to customize how your objects are saved to the database.

encode attempts to respect the interconnections of objects in the context of a given stream-out or stream-in operation. If the object needs to encode a sub-object, it can call encode on the RtEncoder. Conversely, a sub-object can be decoded using the decodeObject method on the RtDecoder.

RtDBViewFilter

import ec.e.db.RtDBViewFilter;

This class is an interface to a persistent object database. You can use the methods in this interface to impose access restrictions.

Methods

public RtStreamKey put(Object object) throws DBAccessException;

This saves an object to an object database, and return a RtStreamKey as a token.

public void put(Object rootKey, RtStreamKey streamKey) throwsDBAccessException;

Saves a stream key to an object database under a root key name. Overwrites any existing root key with that name. Note that the RootKey cannot itself be a stream key.

public RtStreamKey get(Object rootKey) throws DBAccessException;

Get a stream key that was previously stored under rootKey. If the stream key does not exist, null is returned. DBAccessException is returned if the request is illegal under security policies.

public Object get(RtStreamKey key) throws DBAccessException;

Given a RtStreamKey, return a copy of the object that was stored out and registered for it. Successive attempts at getting an object will return multiple copies.

public boolean contains(Object key) throws DBAccessException;

Test to determine if something is stored in the database under the given key. In this case, key can be either a RtStreamKey or a root key object.

public void commit() throws DBAccessException;

Commit the changes made to this database back into the parent database. This only works if this database is indeed a child and the permissions permit.

RtNotificationHandler

import ec.e.comm.RtNotificationHandler;

This is an interface that defines the handleNotification method.

Methods

public void handleNotification (String type, Object arg, Object info)

This method is called when notifications are sent to a NotificationHandler instance. Type is a string identifying the notification type, arg is an arg passed in when registering for the notification, and info is additional information sent by the agency posting the notification.

RtTickHandling

import ec.e.run.RtTickHandling;

RtTickHandling is an interface objects must implement if they are a target for an RtClock object. The interface defines the tick method which is invoked each time the clock ticks.

Methods

public void tick(Object arg, int ticks)

• arg is an argument passed to the constructor for the RtClock.
• ticks is the number of ticks that have elapsed since the timer was started from 0 or reset.

Example

import java.lang.*;
import ec.e.run.RtTickHandling;
import ec.e.run.RtClock;

class ClockTest implements RtTickHandling
{
  private static int n = 1;
  private static RtClock clock;
  public static void main (String args[]) {
    ClockTest test = new ClockTest();
    clock = new RtClock(1000, test, "Testing");
    System.out.println("Clock will tick once a 
      second for 10 seconds");
  }
  public void tick (Object arg, int n) {
    System.out.println("Clock ticked (" + n + ") with
      " + arg);
    if (++n > 10) {
      RtClockTerminator.terminateAllClocks();
    }
  }
}

RtTimeoutHandling

import ec.e.run.RtTimeoutHandling;

RtTimeoutHandling is a Java interface. An object that is the target for a setTimeout on an RtTimer object must implement RtTimeoutHandling. The interface defines the handleTimeout method which is invoked when the request timeout occurs.

Methods

public abstract void handleTimeout (Object arg, int timerId)

• arg is the argument passed into the setTimeout method on the RtTimer .
• timerId is the timer ID returned from the call to the RtTimer's setTimeout method made to setup the timeout.

Example

import java.lang.*;
import ec.e.run.RtTimeoutHandling;
import ec.e.run.RtTimer;

class TimerTest implements RtTimeoutHandling {
  static RtTimer tt = new RtTimer();
  static final long timeToWait = 2000L;
  public static void main (String args[]) {
    TimerTest test = new TimerTest();
    int tid;
    tid = tt.setTimeout(timeToWait, test, "Main");
    System.out.println("Waiting " + timeToWait + 
    " millis for " + tid);
  }
  public void handleTimeout (Object arg, int tid){
    System.out.println("Timer fired for " + tid + 
    " arg was " + arg);
    tt.terminate();
  }
}