Electric Communities: E Programming Language  


E Tools and Utilities


E provides several tools and utilities:

E compiler (ecomp)
E Java Interpreter (javaec)
Distributed Garbage Collector
ThreadWatcher utility
Class Blesser


E compiler (ecomp)

E provides its own compiler, called ecomp. ecomp compiles code directly to Java bytecodes (.class files). The ecomp compiler can compile Java code as well as E code.

Files generated by ecomp

Like other Java compilers, ecomp generates one .class file for every Java class defined in the source file.

For every E-class defined in the source files passed to ecomp, the compiler generates the following.class files:

ecomp

ecomp [-verbose][-obfuscate][-classpath path]
  {[-d directory]  filename(s) }

The ecomp command compiles E and Java source code into Java bytecodes. You then use the E Java interpreter, javaec, to interpret the Java bytecodes. The javaec command is similar to Java's java command, but adds E functionality such as the Trust Manager and Distributed Garbage Collector.

Options

Where ecomp outputs class files

E follows Java rules on packages and file hierarchy, and the compiler generates Java bytecode in a location based on your package name.

Where ecomp outputs the generated .class files depends on whether you specify a directory with the -d option, and if you specify a package in your source file. The basic rule is that if you specify a package in your source file, you should either be in that directory when you compile, or specify it with the -d option (and it must exist).

Without the -d option

If you do not specify a directory, or if you specify a directory that does not exist, ecomp create the class file(s) in the directory where the source file is.

Note that if you specify a package in your source file, but do not specify a directory when you compile, ecomp still outputs the generated class file(s) in the source file's directory, regardless of the path indicated by the package line. Unless you compile in the directory specified by the package, javaec will not be able to find these files later on when you try to run the program, since the package and the file directory do not match.

With the -d option

No package statement

ecomp creates the .class file(s) in the directory specified by the indicated path. For example, if you run the following line:

  ecomp -d /var/tmp filename

ecomp creates the class file(s) in /var/tmp.

With a package statement

With a corresponding directory path. If there is a directory path under the specified directory corresponding to the package statement, ecomp creates the .class files in that directory path, below the current directory specified by the package name. For example, if your source file contains the following line:

  package ec.misc.foo; 

and you run

  ecomp -d /var/tmp filename

ecomp creates the class file(s) in the directory /var/tmp/ec/misc/foo (providing /ec/misc/foo exists under/var/tmp).

Without a corresponding directory path. ecomp creates the .class file(s) in the current directory, where the source file exists. Be sure that in this situation you are already in the correct directory (specified by the package line in the source file) when you compile.


E Java Interpreter (javaec)

E provides its own Java interpreter, javaec, to interpret and execute Java bytecodes generated by the compiler. The javaec interpreter is based on Java's interpreter, java, but includes E features such as the Class Blesser, distributed garbage collector, and Trust Manager.

Note that to fully implement the distributed garbage collector, you must run javaec with the E system argument -ECenableDgc (described in the following section):

  javaec classname -ECenableDgc

To turn on the Class Loader, you must also include the following code in your main object:

  RtLauncher.setupClassLoader(int Security_Level);

This call turns on the E class loader. Add this line before any RtLauncher.launch calls. See the documentation on RtEEnvironment and also the section Creating access-controlled objects in the E Runtime chapter for more information.

The -EC* standard command-line arguments

E provides the -EC* system arguments that you can enter at the command line when you run an E program. These arguments are stripped out of the standard arguments array when you launch an object. This lets you run a program with E-provided system facilities, but not have these arguments passed in turn to any objects you launch in your program.

Currently, E provides the -ECenableDgc argument, which turns on distributed garbage collection.

Running javaec

To execute a Java or E program that has no package, you must be in the directory that contains the class file(s). To execute a packaged program, the following conditions apply:

To run javaec, its directory must be included in your PATH variable. E will specify a default directory during installation, but you must update your PATH if you change this directory.

javaec

javaec [-classpath path] [-ms n ] [-noasyncgc]
  [-ss x ][-oss x ][-v, -verbose ][-verify ]
  [-verifyremote][-noverify][-verbosegc]
  classname.class program arguments

Options

Class names

When you run javaec, you must fully qualify the class file name like you do in Java. This means that if you specified a package in the original source file, you must include the package hierarchy in the javaec command line. For example, if your source file myexampleclass has the line:

  package ec.e.examples:

you must run javaec with the package hierarchy:

  javaec ec.e.examples.myexampleclass

javaec passes any arguments following classname to the program.

The bytecodes for the E or Java class are in a file classname.class. ecomp generates this file when you compile the corresponding class source file. ecomp automatically adds this extension to the bytecode file when the class is compiled.

classname must contain a main() method, which E executes and then exits, unless main() creates one or more threads. If any threads are created by main(), then E doesn't exit until the last thread exits. The main() method is defined as follows:

  class Aclass {public static void main(String argv[]){
    < main code >
    }  
  }

As in Java, when you define your own E or Java classes, you need to specify their location using CLASSPATH. See the Java documentation on CLASSPATH for more details. Note that the system always appends the location of the system classes onto the end of the class path unless you use the -classpath option to specify a path.


Distributed garbage collector

The E product provides a distributed garbage collector. Unlike Java's garbage collector, which performs garbage collection only within the scope of your local machine, E's distributed garbage collector performs garbage collection over the net for your distributed objects.

To use the distributed garbage collector, pass the -ECenableDgc argument on the command line when you run javaec. For example:

  javaec Myfile -ECenableDgc


ThreadWatcher

import ec.util.ThreadWatcher;

ThreadWatcher is a Java class which creates a daemon thread to monitor all of the threads in the system and periodically print out what threads are running. You can set the periodicity, and start and stop the monitor. This utility is useful when you have a Java application that hangs, and you want to know what is running.

You can only have one ThreadWatcher instance active at one time.

Creation

You can not explicitly create a ThreadWatcher. The system does it for you through class methods which start watching.

Public variables

public static int waitTime = 5000

This is the wait interval, and can be changed while the ThreadWatcher is running. If it is changed, the former waitTime will still be used for the current "watch" slice, but it will then start using the new waitTime. waitTime is specified in milliseconds.

Methods

public static void startWatching()

Starts up the unique ThreadWatcher (if it is not already running), which will print out what threads are running every 5 seconds. Returns immediately, as the ThreadWatcher runs in it's own thread.

public static void startWatching(int timeToWait)

Starts up the unique ThreadWatcher (if it is not already running), which will print out what threads are running every "timeToWait" seconds. Returns immediately, as the ThreadWatcher runs in it's own thread. TimeToWait is specified in milliseconds.

public static void stopWatching()

Stops the unique ThreadWatcher (if it is not running)

public static void showThreads()

Shows all the threads (this is the same method that is called periodically by the ThreadWatcher itself). Note that the ThreadWatcher doesn't have to be started to call this, you can manually keep track of all the threads by calling this whenever you want.

Interfaces

None

Example

import ec.util.ThreadWatcher;

public class ThreadVoyeur
{
    public static void main(String args[]) {
  // Watch the threads every minute
        ThreadWatcher.startWatching(60000);
    SomeOtherFancyClass.doSomethingSpawningLotsOfThreads();
    }
    
    public userInvokedToSpewThreads () {
    ThreadWatcher.showThreads();
    }
    
    public userWantsToStopWatching () {
    ThreadWatcher.stopWatching();
    }
    
    public userWantsToWatchWithThisInterval(int newInterval) {
    ThreadWatcher.waitTime = newInterval;
    // Although probably better to just do this...
    ThreadWatcher.stopWatching();
        ThreadWatcher.startWatching(newInterval);      
    }
}


The Class Blesser

The E environment provides a user interface called the Class Blesser to manage the TBF, keys, certificates, and E's trust relationships in general. (See the Authentication section in the E Runtime chapter for a discussion of these topics.) You can invoke the Class Blesser either through an interactive graphical user interface, or a command-line interface. When invoking from the command-line, an input file of commands may be specified for the Class Blesser to execute as a batch.

The Interactive Interface

To invoke the graphical user interface for the Class Blesser, run the E Java interpreter (javaec) with the Class Blesser argument, with no command-line options:

  javaec ec.clbless.ClBless 

The graphical interface has several menus, which are explained in the following paragraphs:

File Menu

Certificate Menu

The commands in the Certificate menu are used for manipulation and management of E trust certificates, and are largely self-explanatory.

Keys Menu

The Keys menu is similar to the Certificate menu; it is used for generation and manipulation of keys.

Help Menu

The Command-Line Interface

You can also invoke the Class Blesser from the command line by using options:

  javaec ec.clbless.ClBless options

where options are chosen from among:

  -log <LogFile>
  -verbose
  -help [<cmd>]
  -infile <InputFile>
  -cmd NAME <arg1> [<arg2> .. <argn>]
  -tbf <input file>

Command-Line Options

Key Commands

Certificate Commands

Command File Syntax

A command is interpreted as everything between a -cmd and either the next -cmd or the end of the file. The command file may contain comment lines; any line beginning with # or // is ignored.

The order of arguments in a single command is ignored. If the same argument (such as -sigKey) appears more than once in a command, the last argument given will be used.

If multiple -cmds are specified on the shell command line invoking the Class Blesser, only the first one will be processed.


Copyright (c) 1996 Electric Communities. All rights reserved worldwide.
Most recent update: 7/19/96