Package edu.neu.ccs.demeterf

Package for transformation/traversals with optional arguments.

See:
Description

Interface Summary

Augmentor	Augmentor interface for traversal argument "updateing".
Builder	Builder Interface (combine).
BuilderAugmentor	Combined Builder and Augmentor interfaces.

Class Summary

AbstTraversal	Abstract Traversal with Control.
Bc	Builder implementation that calls object constructors.
Control	Base Control Class, supports the implementation of immutable (and mutable) traversal Control classes.
ID	Combined ID Builder/Augmentor implementation.
Traversal	Traverses an Object structure using a Builder and an Augmentor.
TUCombiner<T>	A Helper Class to implement something like SYB queries.

Exception Summary

BuilderException	Exception Thrown when Builder methods cannot be found
ValueThrow	Represents a Value that can be tossed out of a traversal.

Package edu.neu.ccs.demeterf Description

Package for transformation/traversals with optional arguments.

Traversals are parametrized by builder and augmentor function objects. Each functional aspect has an empty interface (Builder and Augmentor) that annotates what kinds of methods it implements. There are a combined interface (BuilderAugmentor) and two concrete classes (ID and Bc) that provide default behavior.

Note: The Augmentor is only called when the Traversal traverse(Object o, Object a) method is called; i.e., when the iriginal traversal is passed a starting argument. See Examples for, well... some examples.

• Builder:

  Builders implement

  Ret combine(Target t, ..., Arg a)

  for datatypes to be reconstructed, after the traversal of any subobjects.

  Ret is (of course) the return type, Target should be replaced by the type (or a supertype) at which the method will be called, and Arg should be the expected traversal argument type. The [...] becomes a list of types and bindings (i.e., formal method parameters) that are expected from sub-traversals of the (Target) datatype's fields; no fields? no extra parameters needed.

  All parameters are optional, but order matters: e.g., if a method accepts less than the number of actual parameters available, then it may still be called if the types match. See Dispatch for method matching/dispatch description.



• Augmentor:

  Augmentors implement

  Ret update(Target t, Target.field f, Arg a)

  for datatypes where the traversal argument needs to be modified for subtraversals. Ret should be the new argument type (it can be different), Target is where this method should be called (on the way down), Arg is the type of the previous traversal argument, and Target.field is an encoding of which field of Target we are about to traverse.

  We encode the field to be traversed by using an inner public static class that shares the name of the field. There must be a public path (the outer classes must be public, all the way up) in order for the encoding to work. DemFGen does this automatically... see examples package for some hand-coded examples.

  The Arg and Ret types should generally be the same type (or share a common supertype), but anything is possible.
  e.g., implementing:

  Object update(Object o, Object a){ return o; }

  will give each combine method access to its parent as a traversal argument.

Return types of these methods can be as specific or general as you like. Argument types are used for method execution selection, so they should match expected subtraversal return values. For development safety, during traversal a BuilderException is thrown if no Builder method (combine) with an applicable signature is found. See the individual packages/classes for more info.