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.

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:

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:

EBoolean

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:

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.

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.

RtClock

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.

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.

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.

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.

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 RtNetworkControllerstopNetworkEnvironment
method or the RtConnectiondisconnect method, or implicitly
when a connection fails).

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.

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.

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.

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.

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

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.

Constants

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:

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.
//

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.

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.

Interfaces

RtFileDataOutput

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.

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.

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.

Interfaces

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.

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.

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:

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.

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.

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.

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.