Demeter/C++ to Demeter/Java transition document
===============================================

A significant amount of documentation about
Demeter/C++ has been written: 

In the book "Adaptive Object-Oriented Software", the Demeter/C++ syntax
is used in the examples which explain the concepts.

The following documents are all on-line:

User's Guide
Laboratory Guide
FAQ
man pages

It will take time to update those documents. In the mean-time, we
provide this document which explains the differences between the
two systems.

CONCEPTUAL DIFFERENCES

Demeter/Java uses context objects described at URL
http://www.ccs.neu.edu/research/demeter/biblio/context.html
instead of propagation patterns with wrappers and transportation patterns.
A propagation pattern is now expressed by a method attached
to some class. The class defines a traversal function f and
the method instantiates
one or more context objects c1, c2, ... and invokes
the traversal function with a call someObject.f(c1,c2, ...).
While the traversal function f executes, the context objects
execute the "wrappers" which are expressed in the context class
definitions.

Traversal functions are attached to a class in Demeter/Java.
This makes the "from" part of a directive superfluous
since the traversal starts from the class to which
the traversal function is attached. The "from" part
is therefore optional.

The conceptual changes are discussed in:
http://www.ccs.neu.edu/research/demeter/course/f96/APbookWithDemJava.html

NAME CHANGES

The terminal classes have been renamed as follows:

C++			Java
---                     ----
DemNumber		Integer
DemString		String
DemIdent		Ident
DemText			Text
DemReal			Double

Integer and String are defined in package java.lang.

SYNTACTIC DIFFERENCES

Demeter/C++ puts all keywords between *. Demeter/Java uses
reserved words instead. They are:

after
before
to
traversal
bypassing

Current deficiency:

Doug
We need syntax to specify directives independently of a traversal
function. The same directive can be reused for many different
purposes: building block of other directives, traversals with different
visitors, subtraversals.

Proposed syntax (approximate):

directives {
  D1 = from A to B;
  D2 = from B to D;
  D3 = D1 join D3;
  D4 = from A bypassing {X,Y} to B; 	// bypass classes X and Y
  D5 = from A bypassing {-> F,g,G} to B; 	// bypass edges (all)
  D6 = from A through {Y,Z} to B; 		// through classes Y or Z
  D7 = from A through {-> F,g,G} to B; 	// through edges (at least one)
}

Wild card symbols should be allowed.




SYSTEM USE DIFFERENCES

For scanning and parsing we use Jack.

imake is not used in Demeter/Java. Therefore, gen-imake
is not available. To generate the default Makefile, use

j-gen-make

(When Demeter/Java needs a command which is also in Demeter/C++,
it is prefixed by j-.)

In Demeter/Java you need to edit currently the default Makefile
to replace "program" by the file name you have chosen, say x.
Demeter/Java currently expects only two files per directory:
x.cd (class dictionary) and x.beh (adaptive program). 

The class dictionary must contain a class Main = .
unless you change the Makefile.

The parser currently allows only one input file: x.input

In future versions, the Makefile will be generated from a
configuration file so that it no longer needs to be edited.
Several *.beh files will be allowed and input can come from
any file.


TRANSLATION EXAMPLES

propagation pattern:

*operation* int countB() *init* (@ 0 @)
  *traverse* *from* A *to* B
  *wrapper* B 
    *prefix* (@ return_val++; @)

Equivalent Demeter/Java:

// define a traversal with one visitor
A {
  traversal allB(CountingVisitor c){
    to B; // "from A" not needed
  }
}
// CountingVisitor is defined in the class dictionary by
// CountingVisitor is a context class which modifies behavior
// CountingVisitor = <total> Integer.

CountingVisitor {
  // behavior modification
  before B (@ new Integer(total.getValue()+1); @)
}

A {
  int countB() {
    // initalization of counter is done when context object is created
    CountingVisitor c = new CountingVisitor(new Integer(0));
    // traverse with counting visitor
    this.allB(c);
    // return result in context object
    return c.get_total.getValue();
  }
}

More examples of Demeter/Java programs are at
http://www.ccs.neu.edu/research/demeter/sources/DemeterJava/examples