Package recoder.java

This package contains classes that cover the Java programming language.

See:
Description

Interface Summary

Declaration	Declaration.
Expression	General expression.
ExpressionContainer	Expression container.
LoopInitializer	Loop initializer.
NamedProgramElement	Named program element.
NonTerminalProgramElement	Non terminal program element.
ParameterContainer	Describes program elements that contain ParameterDeclarations.
ProgramElement	A part of the program syntax that carries semantics in the model.
Reference	References are uses of names, variables or members.
ScopeDefiningElement	The property of a non terminal program element to define a scope.
SourceElement	A source element is a piece of syntax.
Statement	Statement.
StatementContainer	Statement container.
TerminalProgramElement	Terminal program element.
TypeScope	The property of a non terminal program element to define a scope for types.
VariableScope	The property of a non terminal program element to define a scope for variables.

Class Summary

Comment	A comment, possibly with multiple lines.
CompilationUnit	A node representing a single source file containing TypeDeclarations and an optional PackageSpecificationand an optional set of Imports.
DocComment	Contains tags with
Identifier	Identifier.
Import	Import.
JavaNonTerminalProgramElement	Top level implementation of a Java NonTerminalProgramElement.
JavaProgramElement	Top level implementation of a Java ProgramElement.
JavaProgramFactory
JavaProgramFactory.TraceItem
JavaSourceElement	Top level implementation of a Java SourceElement.
PackageSpecification	Package specification.
PrettyPrinter	A configurable pretty printer for Java source elements.
ProgramElement.TreeStructure	Provides hashcodes and structural equality checking for syntax trees.
SingleLineComment	Any non-SingleLineComment is a multi line comment.
SourceElement.Position	The position of a source element, given by its line and column number.
SourceVisitor	A source visitor defines actions to be triggered while visiting source elements.
StatementBlock	Statement block.
TagInfo	Information about the tags in a java style structured comment (DocComment).

Exception Summary

PrettyPrintingException

This runtime exception wraps an IOException thrown by the pretty printer's writer.

Package recoder.java Description

This package contains classes that cover the Java programming language. These classes are fundamental for syntactical transformations and deserve a detailed overview.

Source and Program Elements

A SourceElement is a syntactical entity and not necessary a ModelElement, such as a Comment. Each SourceElement knows its ProgramFactory, its indentation and how to SourceElement.deepClone() itself.

A ProgramElement is a SourceElement and a ModelElement. It is aware of its parent in the syntax tree, while a pure SourceElement is not considered as a member of the AST even though it is represented in the sources.

ProgramElements are further classified into TerminalProgramElements and NonTerminalProgramElements (this is another Composite pattern). While TerminalProgramElement is just a tag class, NonTerminalProgramElements know their AST children (while it is possible that they do not have any). A complete source file occurs as a CompilationUnit.

JavaSourceElement and JavaProgramElement are abstract classes defining standard implementations that already know their JavaProgramFactory.

Validation

Calling the ModelElement.validate() method of a ModelElement will check its consistency similar to the analysis a compiler does. In case of an inconsistency, a ModelException is thrown. The ModelElement.validate() method of a ProgramElement will check its children if necessary. Calling ModelElement.validate() for a CompilationUnit will check the consistency of the whole module.

A NonTerminalProgramElement defines a NonTerminalProgramElement.makeParentRoleValid() method that sets all parent links of the current children. Not that a SourceElement automatically keeps track of any attached Comment. The method is automatically invoked by each constructor that creates a concrete and valid program element. Since some constructors create partially initialized nodes only, there is no need to make them valid at that time.

Expressions and Statements

Expression and Statement are self-explanatory. A LoopInitializer is a special Statement valid as initializer of For loops. LoopInitializer is subtyped by ExpressionStatement and LocalVariableDeclaration).

Concrete classes and further abstractions are bundled in the recoder.java.expression and recoder.java.statement packages.

Syntax Tree Parents

There are a couple of abstractions dealing with properties of being a parent node, which is used for upwards traversals in the syntax tree.

These are TypeDeclarationContainer, ExpressionContainer, StatementContainer, ParameterContainer, NamedProgramElement and TypeReferenceContainer. A An ExpressionContainer contains Expressions, a StatementContainer contains Statements, a ParameterContainer (either a MethodDeclaration or a Catch statement) contains ParameterDeclarations. A NamedProgramElement is a subtype of NamedModelElement. A TypeReferenceContainer contains one or several names, but these are names of types that are referred to explicitely by a TypeReference.

References

A Reference is an explicite use of an entity. Most of these References are NameReferences and as such NamedProgramElements, e.g. the TypeReference. Subtypes of References are bundled in the recoder.java.reference package.

Modifiers and Declarations

Modifiers are (exclusively) used in the context of Declarations. Modifiers occur explictely, since they occur as syntactical tokens that might be indented and commented. Declarations are either declarations of types or other entities such as MemberDeclaration or VariableDeclaration. Concrete Modifiers and Declarations are bundled in the recoder.java.declaration.modifier and recoder.java.declaration packages.

Comments

A ProgramElement can have a list of Comments attached.

While a pure Comment can extend to several lines, a SingleLineComment may not contain linefeeds. A DocComment is a special comment used for documentation systems such as JavaDoc or DOC++.