DAJ Documentation

For an introduction into the concepts of DAJ and the main motivation behind it John's Masters Thesis is the most appropriate source.

The syntax for traversal (.trv) files is defined below.

        TraversalAspect:
                aspect AspectName { Declarationsopt }
        Declarations:
                Declaration
                Declarations Declaration
        Declaration:
                TraversalDeclaration
                StrategyDeclaration
        TraversalDeclaration:
                declare traversal : MethodHeader : Strategy ( VisitorName ) ;
        Strategy:
                StrategyString
                StrategyName
        StrategyDeclaration:
                declare strategy : StrategyName : StrategyString ;
      

• MethodHeader is a Java method signature. A traversal method with this signature will be added to all source classes of the traversal strategy.
• StrategyString is a string literal (in double-quotes) containing a traversal strategy expression. The traversal strategy syntax is documented in the DemeterJ User Manual, extended with intersection:

        StrategyExpression:
                intersect ( StrategyExpression , StrategyExpressions )
        StrategyExpressions:
                StrategyExpression
                StrategyExpression , StrategyExpressions
      

The semantics of traversal strategies is defined in the paper Navigating through Object Graphs Using Local Meta-Information.

• StrategyName is a Java identifier naming a strategy declared in the same traversal file. Strategy names may also be referred to inside strategy strings.
• VisitorName is a Java identifier naming a class (declared elsewhere) containing visitor methods which are invoked during the traversal. Arguments to the traversal will be passed to the constructor of the visitor. There are five kinds of visitor methods:

  • void start()

    is invoked at the beginning of the traversal.

  • void before(ClassName)

    is invoked when an object of the given class is encountered during the traversal, before its fields are traversed.

  • void after(ClassName)

    is invoked when an object of the given class is encountered during the traversal, after its fields have been traversed.

  • void finish()

    is invoked at the end of the traversal, that is, after all the fields of the root object have been traversed.
  • Object getReturnValue() is invoked at the end of the traversal, and its value is returned as the result of the traversal (suitably cast to the traversal's return type).

Here is an example of a traversal file:

        aspect FileSystemTraversals {
          declare strategy: eachFile: "intersect(from CompoundFile to File, down)";

          declare traversal:
            void listAll(): eachFile(FileLister);

          declare traversal:
            void findDirectory(Ident target):
              "intersect(from CompoundFile to CompoundFile, down)" (DirFinder);

          declare strategy: down: "from * bypassing -> *,parent,* to *";
          declare strategy: up: "from * bypassing -> *,contents,* to *";
        }
   

The syntax for class dictionary (.cd) files is described in the DemeterJ User Manual. Construction edges are turned into fields, but no accessor methods are generated. Repetition classes are turned into subclasses of java.util.ArrayList that throw ClassCastException when objects of the wrong type are added to the collection. Object graphs can be created using the parse methods generated for each class:

• static ClassName parse(java.io.Reader) throws antlr.ANTLRException

  reads an object graph sentence from a character stream.

•  static ClassName parse(java.io.File) throws antlr.ANTLRException,
             java.io.FileNotFoundException

  reads an object graph sentence from a file.

• static ClassName parse(String)

  reads an object graph sentence from a string, converting a parse error into a RuntimeException (because usually this method is called with a literal string, so a parse error is a programmer error).

Here is an example of a class dictionary file:

        FileSystem = <root> CompoundFile EOF.
        File : SimpleFile | CompoundFile common <name> Ident.
        SimpleFile = "simple".
        CompoundFile = "compound" <contents> FileList [<parent> CompoundFile].  
        FileList ~ "(" { File } ")".