Package oracle.javatools.parser.java.v2

The parser API.

See:
Description

Interface Summary

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 Summary

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

Package oracle.javatools.parser.java.v2 Description

The parser API.

Packages

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.

Client usage

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.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( JavaTokens.J2SE_15 );
    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.

Migration from oracle.jdeveloper.jot

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

Explanation 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() *3

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