Package edu.mit.ai.psg.jeva

Jeva is the core of a source code evaluator for Java programs; see edu.mit.ai.psg.jevaUI for user interfaces.

See:
Description

Interface Summary

CompileUnit.CompilerCommand	interface for invoking compilers using command line arguments
IAccessibleObject	IField mirrors java.lang.reflect.AccessibleObject, enabling Jeva to treat compiled members and interpreted members interchangeably.
IClass	IClass mirrors java.lang.Class, enabling Jeva to treat compiled classes and interpreted classes interchangeably.
IClassBodyDeclaration	Interface identifying nodes appearing in class bodies.
IConstructor	IConstructor mirrors java.lang.reflect.Constructor, enabling Jeva to treat compiled constructors and interpreted constructors interchangeably.
IDeclarationNode	Declaration nodes are top level declarations that appear in a compilation unit, e.g., package, import, interface, class.
IEnv	IEnv: Interface to objects in which names can be looked up.
IExpressionNode	Interface to nodes for Java expressions.
IExpressionStoreNode	Expression nodes valid on left of assignment.
IField	IField mirrors java.lang.reflect.Field, enabling Jeva to treat compiled fields and interpreted fields interchangeably.
IInterpretedObject	IInterpretedObject is implemented by all interpreter proxy classes
IJevaNode	IJevaNode: extends Node with methods for accessing the tokens and for printing out the token stream for this node.
IJevaVisitor	Slightly modified version of JevaParserVisitor generated by JJTree: Default method is on IJevaNode, not SimpleNode.
IMember	Similar to Member, but using IClass instead of Class.
IMethod	IMethod mirrors java.lang.reflect.Method, enabling us to treat compiled methods and interpreted methods interchangeably.
IPackage	IPackage is an interface for internal representations of known packages to store and retrieve the classes defined within them.
IStatementNode	Interface to parse nodes for Java statements.
IStore	IStore: interface to implementation objects for a storable location for assignment.
JevaParserConstants	Constants for Tokens constructed by parser.
JevaParserTreeConstants	Constants for SimpleNodes generated by parser.
JevaParserVisitor
Node

Class Summary

AccessibilityMethods	AccessibilityMethods --- methods for checking whether IllegalAccessException should be thrown.
ASCII_UCodeESC_CharStream	An implementation of interface CharStream, where the stream is assumed to contain only ASCII characters (with java-like unicode escape processing).
ClassPathMethods	ClassPathMethods.findInClassPath searches classpath to obtain an input stream from either source directories or jar files; verifyPackageNameFromClassPath checks that a directory structure or jar file entry exists corresponding to a package name starting from some root in the class path.
ClassPathMethods.ClassPathSearchResult	Class for multiple value return of with found location path, input stream, and modification date
ClassPathMethods.StarFilenameFilter	Filter to match filenames based on pattern with *'s in it
CompileUnit	CompileUnit -- compile a Java compilation unit (i.e., contents of a .java file) in a string.
CompileUnit.CompilerInOwnProcess
CompileUnit.JavaCInProcess
EnvBase	A base class for Environment nodes that forwards all requests to the next environment node.
EnvEnd	A tail environment node that holds the root package.
EnvLocalStore	LocalStore implements storage for a local variable in an environment chain.
EnvOptionBits	EnvOptionBits -- environment which specifies option bits; can be used to override the options of the environment, e.g., for debugger command prompt.
EnvProcedureBoundary	Env used at procedure-like boundaries so lookupLocal does not look any farther for local variable names.
EnvThis	EnvThis stores object self reference in an environment chain.
EvalMethods	Centralized static methods for evaluating nodes while catching exceptions.
EvalMethods.AbruptData	EvalHook data with AbruptCompletionException (includes ReturnException, ThrowException, BreakException, ContinueException)
EvalMethods.BodyData	EvalHook data used for method, constructor, and synchrhronized blocks just after entering and just before exitting body
EvalMethods.EnteredBodyData	EvalHook data used for method, constructor, and synchrhronized blocks just after entering body.
EvalMethods.EvalHookData	EvalHook is passed instance of EvalHookData:
EvalMethods.EvalHookPostData	EvalHook data, all cases after evaluating
EvalMethods.EvalHookPreData	EvalHook data, all cases prior to evaluating
EvalMethods.ExittingBodyAbruptlyData	EvalHook data used for method, constructor, and synchrhronized blocks just before exitting body.
EvalMethods.ExittingBodyData	EvalHook data used for method, constructor, and synchrhronized blocks just before exitting body.
EvalMethods.PreApplyData	EvalHook data after subexpression values have been evaluated, before node is evaluated
EvalMethods.PreEvalData	EvalHook data prior to evaluating expression or statement
EvalMethods.PreEvalToStoreData	EvalHook data prior to evaluating expression to store target for assignment
EvalMethods.ResultData	EvalHook data with expression result value
EvalMethods.ResultEnvData	EvalHook data with statement result environment
EvalMethods.ResultStoreData	EvalHook data with expression store target for assignment
ExpressionNode	A base class for Expressions which caches its type (and value if constant).
GenerateProxyClass	GenerateProxyClass.generateClass(InterpretedClass) generates the proxy class for an interpreted object from the InterpretedClass.
IEnv.ClassResult	class used for multiple value return.
InterpretedClass	InterpretedClass provides IClass methods for interpreted classes.
InterpretedConstructor	InterpretedConstructor implements IConstructor methods for interpreted constructors, e.g., to invoke constructor through the newInstance method.
InterpretedField	InterpretedField implements IField methods for fields of interpreted classes.
InterpretedMember	InterpretedMember implements IMember and IAccessibleObject for interpreted implementations of members (InterpretedField, InterpretedMethod, InterpretedConstructor).
InterpretedMethod	InterpretedMethod implements IMethod for interpreted methods, e.g., to invoke method through the invoke method.
Jeva	Jeva (Java Evaluator) is the entry point class of the core of a source code evaluator for Java programs; see edu.mit.ai.psg.jevaUI for user interfaces.
JevaNode	JevaNode extends SimpleNode so each node can echo back its token stream of Java code.
JevaParser	JevaParser: parse Java Expressions and Statements.
JevaParserTokenManager	Token Manager
JevaVisitorBase	Base class for visitor design pattern visitors.
JNCompilationUnit	JNCompilationUnit: parse node for a compilation unit, typically a source (.java) file.
JNDClassBody	JNDClassBody: parse node for the body of a class declaration.
JNDClassDeclaration	JNDClassDeclaration: Parse node for class and interface declarations.
JNDConstructorDeclaration	JNDConstructorDeclaration: parse node for constructors.
JNDFieldDeclaration	JNDFieldDeclaration: parse node for a field declaration.
JNDImportDeclaration	JNDImportDeclaration: parse node for import declarations.
JNDInitializer	Jeva parse Node for (static) initializers (statements in class body).
JNDMethodDeclaration	JNDMethodDeclaration: parse node for methods.
JNDPackageDeclaration	JNDPackageDeclaration: parse node for package declarations.
JNEAdditiveExpression	Jeva parse Node for binary + - Expressions [JavaLangSpec 1.0 sec 15.17 Additive Operators].
JNEAndExpression	Jeva parse Node for & Expressions [JavaLangSpec 1.0 sec 15.21 Bitwise and Logical Operators].
JNEArguments	JNEArguments: parse node for arguments for method call or constructor call.
JNEArrayAccessExpression	Jeva parse Node for array[index] Expressions [JavaLangSpec1.0 sec15.12 Array Access Expressions].
JNEArrayCreationExpression	Jeva parse Node for array creation Expressions: "new" Type [arraydims] or "new" Type [arraydims] { arrayinitializer }
JNEArrayDimensions	Jeva parse Node for dimensions in array creation Expressions.
JNEArrayInitializer	JNEArrayInitializer: parse node for array initializer in array creation expressions.
JNEAssignmentExpression	Jeva parse Nodes for all assignment Expressions (=, +=, *=, etc.) [JavaLangSpec1.0 sec 15.25].
JNEAssignmentOperator	Jeva parse Node for just assignment operator (=, +=, ...) in assignment Expressions.
JNECastExpression	Jeva parse Node for cast Expressions: (type) expr .
JNEConditionalAndExpression	Jeva parse Node for && Expressions.
JNEConditionalExpression	Jeva parse Node for ? : Expressions.
JNEConditionalOrExpression	Jeva parse Node for || Expressions.
JNEEqualityExpression	Jeva parse Node for == and != Expressions [JavaLangSpec 1.0 sec 15.20 Equality Operators].
JNEExclusiveOrExpression	Jeva parse Node for ^ Expressions [JavaLangSpec 1.0 sec 15.21 Bitwise and Logical Operators].
JNEInclusiveOrExpression	Jeva parse Node for | Expressions [JavaLangSpec 1.0 sec 15.21 Bitwise and Logical Operators].
JNEInstanceCreationExpression	Jeva parse Node for instance creation expressions: "new" Type(args...).
JNEInstanceOfExpression	Jeva parse Node for Expr instanceof Class [JavaLangSpec1.0 sec15.19.2 Type Comparison Operator instanceof]
JNELiteralExpression	Jeva parse node for literal expressions (1, 3.14, "Hi", etc.)
JNEMethodInvocationExpression	Jeva parse node for Method invocation expressions: target.method(args...) [JavaLangSpec 1.0 sec 15.11 Method Invocation Expressions].
JNEMultiplicativeExpression	Jeva parse Node for * % / Expressions [JavaLangSpec 1.0 sec 15.16 Multiplicative Operators].
JNEParenthesizedExpression	Jeva parse Node for (parenthesized expressions): This node exists to mark the beginning and end of the parenthesized expression so it can be reproduced in text (the "(" and ")" are not part of the expression they contain).
JNEPostfixExpression	Jeva parse node for postfix expressions (x++, x--).
JNEPreDecrementExpression	Jeva parse Node for --x Expressions.
JNEPreIncrementExpression	Jeva parse nodes for ++x expressions.
JNERelationalExpression	Jeva parse node for relational expressions (<,>,<=,>=) [JavaLangSpec 1.0 sec 15.19 Relational Operators]
JNEShiftExpression	Jeva parse Node for <<, >>, >>> expressions [JavaLangSpec 1.0 sec 15.18 Shift Operators].
JNEUnaryExpression	Jeva parse Node for unary expressions (!x, ~x, -x, +x) [Java Lang Spec 1.0 sec 15.14.3-6]
JNFormalParameter	Jeva parse Node for formal parameters of methods and constructors
JNFormalParameterList	Jeva parse node for formal parameter list of methods and constructors.
JNName	Jeva parse node for names (including parameters, fields, and class names); A name x.y.z is parsed with nested names as (((x).y).z).
JNNameList	Jeva parse Node for a list of classes, used in throws ---, extends ---, implements ---.
JNPrimitiveType	Jeva parse Node for primitive types (int, boolean, etc.)
JNResultType	Jeva parse Node for result types: "void" | Type().
JNSBlock	Jeva parse Node for block Statements: {...}
JNSBreakStatement	Jeva parse node for break Statements.
JNSContinueStatement	Jeva parse node for continue Statements.
JNSDoStatement	Jeva parse Node for do Statements.
JNSEmptyStatement	Jeva parse node for empty statements ";".
JNSExplicitConstructorInvocation	Jeva parse node for this(...) or super(...) constructor invocations.
JNSExpressionStatement	Jeva parse Node for expression statements "(expr);".
JNSExpressionStatementList	Jeva parse Node for lists of expression statements, used in for statements' initialize and update clauses.
JNSForStatement	Jeva parse Node for for statements.
JNSIfStatement	Jeva parse Node for if Statements.
JNSLabeledStatement	Jeva parse Node for labeled statements e.g., "label: while(true){ ...
JNSLocalVariableDeclaration	Jeva parse Node for local variable declarations, e.g., "int i = 0;".
JNSReturnStatement	Jeva parse Node for return Statements.
JNSSwitchLabel	Jeva parse Node for labels within a switch Statement.
JNSSwitchStatement	Jeva parse Node for switch Statements [JavaLangSpec1.0sec14.9].
JNSSynchronizedStatement	Jeva parse Node for synchronized(expr) {...} statements
JNSThrowStatement	Jeva parse Node for throw Statements.
JNSTryStatement	Jeva parse Node for try Statements [JavaLangSpec1.0sec14.18]
JNSVariableDeclarator	Jeva parse Node for variable declators, a component in variable declaration statements and field declarations.
JNSWhileStatement	Jeva parse Node for while Statements.
JNType	Jeva parse Node for type nodes, except void. ( PrimitiveType() | Name() ) [ ArrayDims() ]
LeftAssociativeOperatorExpression	Shared implementation for left associative operators.
LiteralMethods	Methods for creating primitives from literal strings.
ModifierMethods	Method to translate parser token to Modifier constant.
Package	Internal representation of packages, for name lookups.
PrimitiveOperations	Binary Operations on Primitive types (numbers and booleans) represented by their wrapper types (e.g., int represented by Integer).
SimpleNode	Root class for all parse tree nodes.
Token	Describes the input token stream.
TypeMethods	Predicates and Methods for testing and comparing types.
WrappedClass	WrappedClass wraps binary Class objects to implement IClass .
WrappedConstructor	WrappedConstructor wraps binary Constructor objects to implement IConstructor .
WrappedField	WrappedClass wraps binary Field objects to implement IField Invariant: if fieldA == fieldB, their wrappers are == also.
WrappedMethod	WrappedMethod wraps binary Method objects to implement IMethod Invariant: if methodA == methodB, their wrappers are == also.

Exception Summary

AbruptCompletionException	Instances of subclasses of AbruptCompletionException are thrown to implement abrupt completion of statements via break, continue, return, or throw.
BreakException	BreakExceptions are thrown to implement abrupt completion of statements.
ContinueException	ContinueExceptions are thrown to implement abrupt completion of a loop body statement.
IllegalConstructException	IllegalConstructException is thrown when Jeva finds a construct used in an illegal context, e.g., using "this" in a static method, or is malformed, e.g., an array initializer with too many elements.
IllegalNameException	IllegalNameException is thrown when Jeva finds a name conflict, e.g., a name that has already been used or is ambiguous.
IllegalTypeException	IllegalTypeException is thrown when Jeva finds a type conflict.
ParseException	This exception is thrown when parse errors are encountered.
ReturnException	ReturnExceptions are thrown to implement abrupt completion of methods.
ThrowException	ThrowExceptions are thrown to implement thrown exceptions.
VerifyingException	Base class for exceptions for illegal nodes found while verifying types; saves node and environment where problem occurred.

Error Summary

EvalMethods.EvalHookError
EvaluatingError	Error used to capture context of internal errors thrown while evaluating.
TokenMgrError	Error thrown by Token Manager
VerifyingError	Error used to capture context of internal errors thrown while verifying types in source code.

Package edu.mit.ai.psg.jeva Description

Jeva is the core of a source code evaluator for Java programs; see edu.mit.ai.psg.jevaUI for user interfaces.

Jeva (Java Evaluator) parses and evaluates Java expressions and statements, as specified in the Java Language Specification 1.0 and amended informally in Clarifications and Amendments to the JLS (in particular, final variables and .class expressions). This version of Jeva does not accept nested nor anonymous class declarations.

Jeva is designed to allow interpreted programs to interoperate with compiled libraries and systems. To enable objects with interpreted methods to be passed to compiled methods, they must satisfy the type signature requirements of the superclass and interfaces, so proxy classes are generated and compiled.

Installation Requirements

Thus, Jeva requires access to temporary file space (automatically provided via File.createTempFile) and uses the free Sun Java Development Kit JDK1.2 sun.tools.javac compiler (preferrably by including jdk1.2/lib/tools.jar in the classpath, though if not there CompileUnit will try to invoke javac as a process, which requires javac in the command path). (See edu.mit.ai.psg.jevaES if you just need to evaluate expressions and statements without these requirements.)

Using Jeva

Most uses will be through classes in the edu.mit.ai.psg.jevaUI user interface package, which provides user interfaces which accept typed expressions and statements.

Programs that need to evaluate individual expressions and statements usually only need to call methods in the Jeva class, e.g.,
Jeva.parseEvalStringExpression(expressionString), or
Jeva.parseEvalStringStatement(statementString).
To separate parsing from evaluation, call
Jeva.parse...(..), then EvalMethods.evaluate(...), using Jeva.defaultEnv().

Tracing Jeva

See edu.mit.ai.psg.jeva.examples for examples which use EvalMethods.EvalHookData for tracing single threaded evaluation. For multithreaded evaluation, see edu.mit.ai.psg.traveler.jevaHooks.

Hints

• Inner classes and interfaces from compiled libraries can be accessed through their renamed names, e.g., java.util.Map.Entry can be accessed through the name java.util.Map$Entry .
• Evaluating is much less expensive than parsing, so to evaluate the same expression with different values, evaluate it with different environments instead of constructing and parsing new strings. See DemoEvalWithEnv.

* * * Please read Jeva.copyright.

Jeva was developed using a parser generated by Sun's free Java parser generator JavaCC/JJTree (now maintained by the spinoff Metamata), using a modified version of the example Java grammar.