Interface | Description |
---|---|
CallerContext.Constants |
Constants for use with CallerContext.
|
JavaConstants |
All general-purpose constant values used by the java
parser/compiler.
|
JavadocTokens |
The
JavaDocTokens interface defines the constants for
the various tokens of the a JavaDoc comment in the Java Language. |
JavaErrors |
All error-related constants.
|
JavaOperators |
All expression-related constant values used by the java
parser/compiler.
|
JavaPreferences |
Constants for source preferences, mostly formatting preferences.
|
JavaPreferences.MemberOrder |
Defines keys within the member order hash structure.
|
JavaProvider |
The
JavaProvider interface defines the requirements of
the compiler for retrieving class information. |
JavaProvider2 |
Extends the JavaProvider interface.
|
JavaTokens |
The
JavaTokens interface defines the constants for the
various tokens of the Java Language. |
Class | Description |
---|---|
BindingRegistry |
Manages keys for use with NodeBinding.
|
CallerContext |
Defines the calling context for use in resolving source references.
|
CallerContext.InputOptions |
Input options for use with CallerContext.
|
CallerContext.Output |
Output data from CallerContext.
|
JavaParser |
Raw API for generating parse trees.
|
SourceFactory |
The factory class for SourceElements.
|
Enum | Description |
---|---|
JdkVersion |
Presents JDK versions supported by JOT in enum format.
|
This is your basic orientation into the parser/compiler system.
oracle/javatools/parser/javatools/v2/* Parser entrypoint and exitpoint. Scanner, parser, and compiler constants. Sorted alphabetically, the package consists of: BindingRegistry.java Interface for obtaining keys for use with the SourceElement's data binding feature. See model/NodeBinding and model/SourceElement. CallerContext.java Interface for performing compiler resolution at an arbitrary entrypoint (SourceElement) in the tree. JavaConstants.java Parser and compiler constants. Does not contain implementation specific constants. Defines SRC_*, ELEM_*, ACC_*, PRIMITIVE_*, etc. JavadocTokens.java Javadoc scanner constants. Defines TK_DOC_* and TAG_*. JavaErrors.java Parser and compiler constants specific to error reporting. Defines ERROR_*. JavaOperators.java Parser constants specific to expressions. Defines OPT_*. JavaParser.java The entrypoint into the parser. JavaProvider.java The exitpoint from the compiler. Defines the class loading interface used by the compiler. JavaTokens.java Java scanner constants. Defines J2SE_*, TK_*, OP_*, and KW_*. SourceFactory.java Methods for constructing various SourceElement's. oracle/javatools/parser/javatools/v2/classfile/* Class file reader implementation. Only intended for use by JavaProvider implementations. oracle/javatools/parser/javatools/v2/common/* Code common to both client and implementation. Also, there is a set of abstract classes for clients for implementing the JavaProvider interface (you don't have to use them if you don't want to). oracle/javatools/parser/javatools/v2/model/** The data model (and ONLY the data model) API. Provides read and compiled data model. Also contains part of the write model. Interfaces that do not implement JavaElement or SourceElement do NOT belong here, with the sole exceptions of NodeBinding and Readme. Interfaces related to the scanner go in the scanner package. Interfaces related to the write model go in the write package. Everything else goes in the common package. oracle/javatools/parser/javatools/v2/scanner/* The scanner API and implementation. oracle/javatools/parser/javatools/v2/util/* Various utility classes, also interfaces that don't fit anywhere else. oracle/javatools/parser/javatools/v2/write/* The write model API. Contains the remainder of the write data model. That is, here resides the API that is not itself part of the data model. These include transactional support and notification support.
For the scanner client, you'll be using JavaTokens (or JavadocTokens)
and the scanner package. Here's some example code:
Note: JavadocTokens and JavaTokens do not conflict and therefore,
clients may import both sets of constants safely.
import oracle.javatools.buffer.TextBuffer; import oracle.javatools.parser.java.v2.JavaTokens; import oracle.javatools.parser.java.v2.JdkVersion; import oracle.javatools.parser.java.v2.scanner.JavaLexer; // Uses the JavaLexer to scan through the input text buffer. void scan( TextBuffer textBuffer ) { // Create a lexer using a jdk 1.5 keyword table. final JavaLexer lexer = new JavaLexer( JdkVersion.JDK_1_5 ); lexer.setTextBuffer( textBuffer ); // Tells the lexer to skip comments and not return comments as // part of the token stream. lexer.setSkipComments( true ); // Set the lexer to start at offset 0 in the text buffer. lexer.setPosition( 0 ); while ( true ) { final int token = lexer.lex(); if ( token == JavaTokens.TK_EOF ) break; final int startOffset = lexer.getStartOffset(); final int endOffset = lexer.getEndOffset(); // Do stuff. } }
To the parser client, you'll be using JavaConstants, JavaParser, and
Source* interfaces from the model package and its subpackages. Be
careful not to call any methods coming from a Java* interface because
they trigger an implicit resolution or compilation. If you expect
SourceFile.getURL() to return something meaningful, you'll need to set
the URL cookie via SourceFile.setURL( URL u ).
Note: Typically, only JavaProvider implementations will be directly
calling JavaParser to construct SourceFile trees based on TextBuffer
input.
To the javadoc client, your API has not been finalized.
To the compiler client, you'll be like the parser client with some
additional usage. In order for resolution or compilation to work, you
need to use the JavaProvider cookie via SourceFile.setProvider(
JavaProvider p ). The JavaProvider is the class-loading interface used
by the compiler. You may use a normal class-loading implementation or
you may supply a custom implementation. For example, a debugger may
want to supply a JavaProvider implementation that loads classes from a
debugger connection.
Note: Typically, only JavaProvider implementations will be directly
initializing SourceFile's for compilation.
To the write model client, you'll be like the parser client with some
additional usage. You'll be using the write package and a wealth of
SourceFile methods. To create SourceElement's, you call
SourceFile.getFactory(). The SourceFile must be provided with a
TextBuffer instance. Set the text buffer with SourceFile.setTextBuffer(
TextBuffer t ). To atomically set and pin the text buffer, use
SourceFile.pinTextBuffer( TextBuffer t ). Begin your transaction with
SourceFile.beginTransaction() and don't forget to either abort or
commit the transaction when you're done.
Note: Typically, only JavaProvider implementations will be directly
setting, pinning, and clearing TextBuffer cookies. The typical client
will only need to worry about calling SourceFile.beginTransaction().
Here are some examples of writing using the write model.
import oracle.javatools.parser.java.v2.JavaConstants; import oracle.javatools.parser.java.v2.model.SourceMethod; import oracle.javatools.parser.java.v2.model.SourceFile; import oracle.javatools.parser.java.v2.model.SourceImport; import oracle.javatools.parser.java.v2.write.SourceTransaction; // Opens a transaction on the input SourceFile and adds the // specified import declaration. void addImport( SourceFile file, String importString ) { final SourceTransaction transaction = file.beginTransaction(); final SourceFactory factory = file.getFactory(); final SourceImport importDeclaration = factory.createImportDeclaration( importString ); importDeclaration.addSelf( file ); transaction.commit(); } // Adds the public modifier to the method. void addPublic( SourceMethod method ) { final SourceFile file = method.getOwningFile(); final SourceTransaction transaction = file.beginTransaction(); // You could alternatively use Modifier.PUBLIC too. method.addModifiers( JavaConstants.ACC_PUBLIC ); transaction.commit(); }To the JavaProvider implementer, you'll want to take a look at the classes in the common package for a starting point. You need to be concerned with implementing Java* interfaces in the model package. Don't worry about Compiled* interfaces. You don't have to return the same JavaType instance for the same input name over two calls, but life would run far more efficiently if you did.
The following is a map from oracle/jdeveloper/jot/* to
oracle/javatools/parser/java/v2/model/*. If <n/a>, it means that the
jot class is not part of the source model. Some mappings indicate a
footnote which are explained further below. If <none>, it means that
concept is not supported in the source model.
Jot -> <n/a> JotAllocation -> <none> JotAnonymousClass -> expression/SourceClassCreatorExpression *7 JotArrayAllocation -> expression/SourceArrayCreatorExpression JotArrayDereference -> expression/SourceArrayAccessExpression JotArrayInitializer -> expression/SourceListExpression *9 JotAssignment -> expression/SourceInfixExpression *6 JotBaseName -> *11 JotBlockElement -> statement/SourceBlockStatement JotBlockStatement -> <none> JotBooleanLiteral -> expression/SourceLiteralExpression *8 JotBreak -> statement/SourceBreakStatement JotCase -> statement/SourceSwitchLabel JotCatch -> statement/SourceCatchClause JotCharacterLiteral -> expression/SourceLiteralExpression *8 JotClass -> SourceClass JotClassAllocation -> expression/SourceClassCreatorExpression JotClassInitializer -> SourceClassInitializer JotClassLiteralExpression -> expression/SourceUnaryExpression *8 JotCodeBlock -> SourceBlock JotCodeElement -> <none> JotComment -> SourceComment JotConditional -> statement/SourceConditionalStatement JotConstructor -> SourceMethod *1 JotContinue -> statement/SourceContinueStatement JotDo -> statement/SourceDoStatement JotDocComment -> doc/SourceDocComment JotElement -> SourceElement JotElementList -> <none> JotElementUpdate -> <n/a> JotElse -> statement/SourceElseClause JotError -> SourceError JotException -> <n/a> JotExpression -> expression/SourceExpression JotExpressionStatement -> statement/SourceExpressionStatement JotField -> SourceFieldVariable JotFieldAccess -> *11 JotFieldDeclaration -> SourceFieldDeclaration JotFile -> SourceFile JotFileElement -> <none> JotFileLock -> <n/a> JotFor -> statement/SourceForStatement JotForInitializer -> <none> JotHasChildStatement -> statement/SourceCompoundStatement JotHasCodeBlock -> SourceHasBlock JotHasModifiers -> SourceHasModifiers JotIdentifier -> SourceLexicalToken *3 JotIf -> statement/SourceIfStatement JotImport -> SourceImport JotInfixExpression -> expression/SourceInfixExpression JotInnerClass -> SourceClass *2 JotIntegerLiteral -> expression/SourceLiteralExpression *8 JotInvalidElementException -> <n/a> JotJavaType -> <none> JotKeyword -> SourceLexicalToken *3 JotLibrary -> <n/a> JotLibraryMember -> <n/a> JotLocalClass -> SourceClass *2 JotLocalVariable -> SourceLocalVariable JotLocalVariableDeclaration -> SourceLocalsDeclaration JotManager -> <n/a> JotManipulations -> <n/a> JotMember -> SourceMember JotMethod -> SourceMethod JotMethodCall -> expression/SourceMethodCallExpression JotModel -> <n/a> JotModelFactory -> <n/a> JotModifier -> SourceLexicalToken *3 JotName -> SourceName JotNameOrAccess -> *11 JotNameable -> SourceHasName JotNames -> <n/a> JotNestedExpression -> *11 JotNodeID -> JavaConstants *10 JotNullLiteral -> expression/SourceLiteralExpression *8 JotPackageStatement -> SourcePackage JotParameter -> SourceLocalVariable *4 JotParameterList -> SourceFormalParameterList JotPostIncrementOrDecrement -> SourceUnaryExpression *5 JotPreIncrementOrDecrement -> SourceUnaryExpression *5 JotPrimaryExpression -> *11 JotQualifiedName -> *11 JotQuestionExpression -> expression/SourceQuestionExpression JotReturn -> statement/SourceReturnStatement JotStatement -> statement/SourceStatement JotStatementExpression -> <none> JotStringLiteral -> expression/SourceLiteralExpression *8 JotSuper -> *11 JotSwitch -> statement/SourceSwitchStatement JotSynchronized -> statement/SourceSynchStatement JotThis -> *11 JotThrow -> statement/SourceThrowStatement JotTry -> statement/SourceTryStatement JotType -> SourceTypeReference JotTypeInfo -> JavaType JotTypecast -> expression/SourceTypecastExpression JotUnaryExpression -> expression/SourceUnaryExpression JotUtils -> <n/a> JotVariable -> SourceVariable JotVariableDeclaration -> SourceVariableDeclaration JotWhile -> statement/SourceWhileStatement JotWorkArea -> <n/a> JotWorkAreaUpdate -> <n/a>Here are Source* classes that are not shown in the above mapping:
SourceAnnotation SourceClassBody SourceInterfacesClause SourceSuperclassClause SourceThrowsClause SourceTypeArgument SourceTypeParameter SourceWhitespace statement/SourceEndClause statement/SourceFinallyClause statement/SourceAssertStatement statement/SourceEmptyStatement statement/SourceSimpleStatement statement/SourceStatementLabel expression/SourceDereferenceExpression expression/SourceDotExpression expression/SourceSimpleNameExpression expression/SourceTypeExpression expression/SourceWrapperExpressionExplanation of footnotes:
1. SourceMethod represents both constructor and method declarations. Hence, JotConstructor maps to SourceMethod. 2. JotClass, JotInnerClass, and JotLocalClass are all represented by SourceClass. 3. All tokens are represented by SourceLexicalToken. This includes: JotIdentifier, JotKeyword, and JotModifier. 4. JotParameter is a special case of SourceLocalVariable. 5. JotPostIncrementOrDecrement and JotPreIncrementOrDecrement are special cases of SourceUnaryExpression. 6. JotAssignment is a special case of SourceInfixExpression. 7. JotAnonymousClass is a special case of the SourceClassCreatorExpression. 8. The various literal expressions are all represented by SourceLiteralExpression which represents lexer literals. This includes: JotBooleanLiteral, JotCharacterLiteral, JotIntegerLiteral, JotNullLiteral, and JotStringLiteral. It's important to note that JotClassLiteral is NOT a lexer literal and is represented by a SourceUnaryExpression. 9. JotArrayInitializer is a special case of SourceListExpression. 10. JavaConstants is actually not in the model package. It's full path is oracle/javatools/parser/java/v2/JavaConstants. The node constants are prefixed as SRC_*. 11. Primary expressions are handled differently in the Source model. Most of the primary expressions will boil down to SourceSimpleNameExpression, SourceDotExpression, or SourceMethodCallExpression.Here are some other useful notes:
JotElement.EMPTY_ARRAY -> SourceElement.EMPTY_ARRAY JotElement.getChildren() -> SourceElement.getChildren() *1 JotElement.getContainedElemen -> SourceElement.getChildren() *1 JotElement.getElementName() -> SourceHasName.getName() JotElement.getElementType() -> SourceElement.getSymbolKind() JotElement.getEndOffset() -> SourceElement.getEndOffset() JotElement.getID() -> <n/a> JotElement.getJotWorkArea() -> <n/a> *2 JotElement.getNodeID() -> SourceElement.getSymbolKind() JotElement.getParent() -> SourceElement.getParent() JotElement.setParent(J) -> SourceElement.addSelf(S) *3 JotElement.getStartOffset() -> SourceElement.getStartOffset() JotExpression.getExpressionType() -> SourceExpression.getExpressionCode() JotExpression.getExpressionString() -> SourceElement.getText() JotExpression.resolve() -> SourceElement.getResolvedObject() JotStatement.getLabels() -> SourceStatement.getStatementLabels() JotStatement.getStatementText() -> SourceElement.getText() JotStatement.getStatementType() -> SourceElement.getSymbolKind() JotStatement.removeLabel(S) -> SourceStatementLabel.removeSelf() *3Explanation of footnotes:
1. Collections and Lists are now returned in place of arrays. 2. There really is no equivalent to JotWorkArea in the parser package. The closest you'll get is SourceElement.getOwningFile().getProvider(). That gets you the supporting JavaProvider instance. 3. To add or remove SourceElement's, you have two choices. One, if you have a List returned by a SourceElement, then you can just add it wherever you like. For example, you can say parent.getChildren().add( child ). Or you can say sourceClass.getSourceConstructors().add( 0, newConstructor ). Likewise, you can also use List.remove(I). parent.getSourceMethods().remove( 0 ). If you merely have a Collection (as opposed to a List), then you cannot add or remove anything from it. Alternatively, you can also tell a SourceElement to addSelf() or removeSelf().One concept you must get accustomed to is that the source-model and the compiled-model are now kept separate. You can see the model Readme for more information on this.