carfield.com.hk

README.txt

2008-03-17T17:25:16Z

Implementations of GoF Design Patterns in Java and AspectJ
Code base documentation

Overview
========

The goal was to provide parallel implementations in AspectJ and Java that
allow for direct comparisons. It has to be noted that most patterns offer
variability in the implementation approach. We choose the one that appeared
to be the most general. Sometimes, the AspectJ version implements a slightly
different (or additional) case(s). This is because AJ sometimes
allows for additional functionality. Please refer to the web page for a
detailed description of this work.

Example Setup
=============

All pattern examples have a class called Main. This class is the test driver
for the particular example. The Main classes are extensively documented using
ajdoc, usually describing the experimental setup and the assignment of roles
to participants. In most cases, the differences between Java and AspectJ
implementations are also mentioned.

Documentation (ajdoc)
=====================

It is possible to generate the ajdoc documentation for either all examples,
for only the reusable library aspects, or for one particular example. Since
ajdoc shows type names without their package (on the left hand side), multiple
types with the same name (but residing in different packages) may be confused
when the documentation for all examples is generated.
==> Generate documentation for all examples: use the makeDocs batch file.
(1) Change to the directory that you extracted the ZIP archive into. (2)
Type "makeDocs" to generate the HTML documentation in the docs
subdirectory.
==> Generate Documentation for the reusable library aspects: use the provided
makeLibraryDocs batch file. (1) Change to the directory that you extracted
the downloaded ZIP file into. (2) Type "makeLibraryDocs" to generate the
HTML documentation in the docs subdirectory.
==> Generate docs for a single example: use the makeSingleExampleDocs batch
file. (1) Change to the directory that you extracted the downloaded ZIP
file into. (2) Call the batch file. It needs two arguments: the name of
the pattern and the language used. For example, type:
"makeSingleExampleDocs singleton aspectj" or type:
"makeSingleExampleDocs templateMethod java".
Within the ajdoc documentation, we tried to separate type names from our
examples and role names (as presented in GoF). We show roles names in italics
and actual type names in code font. This is reflected in the ajdoc
documentation.

Questions, feedback, suggestions, etc.
The AODP web page is http://www.cs.ubc.ca/labs/spl/aodp.html
Please send all questions, feedback, and suggestions to Jan Hannemann
(jan@cs.ubc.ca). We are very much interested in improving our code.
Please do not hesitate to drop us a line.

Appendix
========

This appendix outlines how to compile and run the examples provided, and how
to generate ajdoc documentation. A number of DOS batch files exist that
automate these tasks somewhat. Note that they only work in Windows
environments. The following is a list of tasks and a description of what
commands accomplish them. For compiling, running and generating documentation,
two options are given. The first one is using a provided script; the second is
the standard command-line option (longer, but will work on all operation
systems).

Set up your system:
1. Install Java and AspectJ
2. Make sure your CLASSPATH contains the current directory (denoted by a
period), e.g. CLASSPATH=.;C:\...
3. Extract the ZIP file into a directory of your choice
4. Change to that directory

Compile Java and AspectJ versions of a design pattern example (e.g. observer).
Choose one:
� makePattern observer
� ajc @examples\observer\files.lst

Run a compiled example (e.g. observer). Choose one:
� testPattern observer (this runs both Java and AspectJ versions)
� java examples.observer.java.Main (for the Java version),
java examples.observer.java.Main (for the AspectJ version)

Generate documentation for all examples. Choose one:
� makeDocs
� ajdoc -private -d docs @allPatterns.lst

Generate documentation for the library aspects. Choose one:
� makeLibraryDocs
� ajdoc -private -d docs ca.ubc.cs.spl.pattern.library

Generate documentation for a single example (e.g. the AspectJ version of the
observer example). Choose one:
� makeSingleExampleDocs observer aspectj
� ajdoc -private -d docs examples.observer.aspectj

View the generated documentation:
� Open the file index.html (located in the docs/ subdirectory) with your
favorite browser.

Command.java

2004-03-24T16:00:00Z

CommandInvoker.java

2004-03-24T16:00:00Z

CommandProtocol.java

2004-03-24T16:00:00Z

package ca.ubc.cs.spl.pattern.library;

/* -*- Mode: Java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * This file is part of the design patterns project at UBC
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.1 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * either http://www.mozilla.org/MPL/ or http://aspectj.org/MPL/.
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is ca.ubc.cs.spl.patterns.
 *
 * Contributor(s): 
 */
 
import java.util.WeakHashMap;
import java.util.Collection;
import java.util.LinkedList;
import java.util.Iterator; 

import ca.ubc.cs.spl.pattern.library.Command;
import ca.ubc.cs.spl.pattern.library.CommandInvoker;
import ca.ubc.cs.spl.pattern.library.CommandReceiver;

// TODO: This implementation allows only for exactly one command per invoker. 
// That can either stay this way or be replaced with composite (macro) 
// commands, either with or without defined order. [Jan, Oct 29, 2002]

/**
 * This is the abstract Command protocol.
 * 
 * @author Jan Hannemann
 * @author Gregor Kiczales
 * @version 1.1, 10/29/02
 * 
 * @see Command
 */

public abstract aspect CommandProtocol { 
 
////////////////////////////////
// Invoker -> Command mapping //
////////////////////////////////

 /**
 * stores the mapping between CommandInvokers and Commands
 */
 
 private WeakHashMap mappingInvokerToCommand = new WeakHashMap();
 
 /**
 * Sets a new command for an invoker
 *
 * @param invoker the object which will invoke the command
 * @param command the command to be set
 * @returns the former command
 */ 
 
 public Object setCommand(CommandInvoker invoker, Command command) { 
 	return mappingInvokerToCommand.put(invoker, command); 
 }
 
 /**
 * Removes a command from an invoker
 *
 * @param invoker the object which will no longer invoke the command
 * @param command the command to be removed
 * @returns the former command
 */ 
 
 public Object removeCommand(CommandInvoker invoker) { 
 	return setCommand(invoker, null); 
 }


 /**
 * Returns the command for an invoker
 *
 * @param invoker the object for which to return the command 
 * @returns the current command for the invoker
 */ 
 
 public Command getCommand(CommandInvoker invoker) { 
 	return (Command) mappingInvokerToCommand.get(invoker); 
 }


/////////////////////////////////
// Command -> Receiver mapping //
/////////////////////////////////

 /**
 * stores the mapping between Coammnds and Receivers
 */
 
 private WeakHashMap mappingCommandToReceiver = new WeakHashMap();
 
 /**
 * Sets a new receiver for a command
 *
 * @param command the command to be set
 * @param receiver the object to be manipulated by the command's 
 * execute() method
 * @returns the former receiver
 */ 
 
 public Object setReceiver(Command command, CommandReceiver receiver) { 
 	return mappingCommandToReceiver.put(command, receiver); 
 }
 
 /**
 * Returns the receiver for a particular command
 *
 * @param invoker the object for which to return the command 
 * @returns the current command for the invoker
 */ 
 
 public CommandReceiver getReceiver(Command command) { 
 	return (CommandReceiver) mappingCommandToReceiver.get(command); 
 }


///////////////////////////////////////
// Command Execution via PC & advice //
///////////////////////////////////////


 /**
 * The join points after which to execute the command.
 * This replaces the normally scattered myCommand.execute() calls.
 *
 * @param invoker the object invoking the command
 */

 protected abstract pointcut commandTrigger(CommandInvoker invoker);


 /**
 * Calls <code>executeCommand()</code> when the command is triggered. 
 *
 * @param invoker the object invoking the command
 */ 
 
 after(CommandInvoker invoker): commandTrigger(invoker) { 
 Command command = getCommand(invoker);
 	if (command != null) {
 	 CommandReceiver receiver = getReceiver(command);
 	command.executeCommand(receiver);
 } else {
 // Do nothing: This Invoker has no associated command
 }
 }
 

//////////////////////////////////
// setCommand() via PC & advice //
//////////////////////////////////

 /**
 * The join points after which to set a command for an invoker.
 * This replaces the normally scattered myInvoker.add(Command) calls.
 * The pointcut is provided in addition to the setCommand() method above,
 * to allow all pattern code to be removed from concrete invokers. 
 *
 * This PC is non-abstract, to make it optional for sub-aspcects to define
 * it.
 *
 * @param invoker the invoker to attach the command to
 * @param command the command to be attached to the invoker
 */

 protected pointcut setCommandTrigger(CommandInvoker invoker, Command command); 


 /**
 * Calls <code>addCommand()</code> when a command should be set. 
 *
 * @param invoker the invoker to attach the command to
 * @param command the command to be attached to the invoker
 */ 
 
 after(CommandInvoker invoker, Command command): setCommandTrigger(invoker, command) { // TODO: is "before" a better choice? 
 	if (invoker != null)
 	setCommand(invoker, command); 
 // TODO: throw exception in else case?
 }

/////////////////////////////////////
// removeCommand() via PC & advice //
/////////////////////////////////////

 /**
 * The join points after which to remove a command from an invoker.
 * This replaces the normally scattered myInvoker.remove(Command) calls.
 * The pointcut is provided in addition to the removeCommand() method 
 * above, to allow all pattern code to be removed from concrete invokers.
 *
 * This PC is non-abstract, to make it optional for sub-aspcects to define
 * it.
 *
 * @param invoker the invoker to remove the command from
 */

 protected pointcut removeCommandTrigger(CommandInvoker invoker); 
 
 /**
 * Calls <code>removeCommand()</code> when a command should be removed. 
 *
 * @param invoker the invoker to remove the command from
 */ 
 
 after(CommandInvoker invoker): removeCommandTrigger(invoker) { // TODO: is "before" a better choice? 
 	if (invoker != null)
 	removeCommand(invoker); 
 // TODO: throw exception in else case?
 }

////////////////////////////////////////////
// Command default method implementations //
////////////////////////////////////////////

 /**
 * Provides a deault implementation for the isExecutable method defined
 * in the Command interface. 
 *
 * @returns true (default implementation). Can be overwritten by concrete
 * aspects or even concrete commands.
 */ 

 public boolean ca.ubc.cs.spl.pattern.library.Command.isExecutable() {
 return true;
 } 
 
////////////////////////////////////////////////////////////////
// Calling specialized execute() instead of generic execute() //
////////////////////////////////////////////////////////////////

 public final void Command.execute() {} // this prevents anyone from implementing this method instead of the specialized version. Invokers can call it though

 protected pointcut callGenericExecute(Command command): 
 ( call(void Command+.execute())) && target(command);

 after(Command command): callGenericExecute(command) { // TODO: around?
 command.executeCommand(getReceiver(command));
 }
}

CommandReceiver.java

2004-03-24T16:00:00Z

Leaf.java

2004-03-24T16:00:00Z

Main.java

2004-03-24T16:00:00Z

package examples.visitor.java;

/* -*- Mode: Java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * This file is part of the design patterns project at UBC
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.1 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * either http:*www.mozilla.org/MPL/ or http:*aspectj.org/MPL/.
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is ca.ubc.cs.spl.pattern.
 *
 * Contributor(s): 
 */

/**
 * Implements the driver for the Visitor design pattern example. 
 *
 * Intent: Represents an operation to be performed on the elements of an 
 * object structure. Visitor lets you define a new operation without changing
 * the classes of the elements on which it operates
 *
 * Participating classes are <code>SumVisitor</code> and 
 * <code>TraversalVisitor</code> as ConcreteVisitors, implementing the 
 * <code>NodeVisitor</code> interface. 
 * <code>RegularNode</code> and <code>Leaf</code> are ConcreteElements, 
 * implementing the <code>Node</code> interface. 
 *
 * In this example, Node, RegularNode and Leaf build up a binary tree that has 
 * int values as leafs. SumVisitor is a NodeVisitor that collects the sum of 
 * elements in the leafs (should be 6). TraversalVisitor is a visitor that 
 * collects a description of the tree like {{1,2},3}
 *
 * This is the Java version.
 *
 * Note that <UL>
 * <LI> Every visitor (even the inteface) has to know of each possible element 
 * type in the object structure. 
 * <LI> Nodes need to know of the visitor interface; they have to implement the 
 * accept(NodeVisitor) method.
 * </UL>
 *
 * @author Jan Hannemann
 * @author Gregor Kiczales
 * @version 1.0, 06/13/02
 * 
 * @see Node
 * @see RegularNode
 * @see Leaf
 * @see NodeVisitor
 * @see SumVisitor
 * @see TraversalVisitor
 */

public class Main { 
	
 /**
 * Implements the driver for the Visitor design pattern example. 
 *
 * In this example, Node, RegularNode and Leaf build up a binary tree that has 
 * int values as leafs. SumVisitor is a NodeVisitor that collects the sum of 
 * elements in the leafs (should be 6). TraversalVisitor is a visitor that 
 * collects a description of the tree like {{1,2},3} 
 *
 * @param args the command-line parameters, unused
 */


	public static void main(String[] args) { 
	 
	 System.out.println("Building the tree (1): leaves");
		
		Leaf one = new Leaf(1);
		Leaf two = new Leaf(2);
		Leaf three = new Leaf(3);
		
	 System.out.println("Building the tree (1): regular nodes");
		
		RegularNode regN = new RegularNode(one, two);
		RegularNode root = new RegularNode(regN, three);
		
 System.out.println("The tree now looks like this: ");
 System.out.println(" regN ");
 System.out.println(" / \\ ");
 System.out.println(" regN 3 ");
 System.out.println(" / \\ ");
 System.out.println(" 1 2 ");
		 
 System.out.println("Visitor 1: SumVisitor, collects the sum of leaf");
 System.out.println("values. Result should be 6.");
				 
		SumVisitor sumVisitor = new SumVisitor(); 
		root.accept(sumVisitor);
		System.out.println(sumVisitor.report()); 
		
 System.out.println("Visitor 2: TraversalVisitor, collects a tree");
 System.out.println("representation. Result should be {{1,2},3}.");
		
		TraversalVisitor traversalVisitor = new TraversalVisitor(); 
		root.accept(traversalVisitor);
		System.out.println(traversalVisitor.report()); 
	}
}

MyVisitor.java

2004-03-24T16:00:00Z

package examples.visitor.aspectj;

/* -*- Mode: Java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * This file is part of the design patterns project at UBC
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.1 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * either http:*www.mozilla.org/MPL/ or http:*aspectj.org/MPL/.
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is ca.ubc.cs.spl.pattern.
 *
 * Contributor(s): 
 */

import ca.ubc.cs.spl.pattern.library.VisitorProtocol;

/**
 * Implements a concrete visitor pattern instance. This aspect assings
 * the roles to the participants.
 *
 * @author Jan Hannemann
 * @author Gregor Kiczales
 * @version 1.0, 06/13/02
 */

public aspect MyVisitor extends VisitorProtocol { 
 
 /** 
 * Assigns the <code>VisitorNode</code> role to <code>Node</code>
 */

 declare parents: Node implements VisitorNode;

 /** 
 * Assigns the <code>VRegularNode</code> role to <code>RegularNode</code>
 */

 declare parents: RegularNode implements VRegularNode;

 /** 
 * Assigns the <code>VLeaf</code> role to <code>Leaf</code>
 */

 declare parents: Leaf implements VLeaf;
}

Node.java

2004-03-24T16:00:00Z

NodeVisitor.java

2004-03-24T16:00:00Z

RegularNode.java

2004-03-24T16:00:00Z

SampleComposite.java

2004-03-24T16:00:00Z

package examples.testcomposite.aspectj;

/* -*- Mode: Java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * This file is part of the design patterns project at UBC
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.1 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * either http://www.mozilla.org/MPL/ or http://aspectj.org/MPL/.
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is ca.ubc.cs.spl.pattern.
 *
 * Contributor(s): 
 */
 
import java.io.PrintStream; 
import java.util.Enumeration; 
import ca.ubc.cs.spl.pattern.library.CompositeProtocol;

/**
 * Implements a concrete instance of the composite design pattern. 
 * 
 * It maintains the mapping between composites and their children, defines the
 * component, composite, and leaf roles, and implements facilities to
 * implements methods that work on the whole aggregate structure.
 *
 * This is the AspectJ version. 
 *
 * Each concrete subaspect does the following things: <UL>
 * <LI> Define which classes are Components and Leafs
 * <LI> (optional) Define methods that operate on the whole aggregate
 * structure (using visitors)
 * </UL>
 *
 * @author Jan Hannemann
 * @author Gregor Kiczales
 * @version 1.0, 05/13/02
 * 
 * @see Component
 * @see CompositeA 
 * @see LeafB
 */

public aspect SampleComposite extends CompositeProtocol {

 /** 
 * Assigns the Composite role to <code>CompositeA</code>
 */
 
 declare parents: Directory implements Composite; // Role Pattern: Assigning Roles

 /** 
 * Assigns the Leaf role to <code>LeafB</code>
 */

 declare parents: File implements Leaf; // Role Pattern: Assigning Roles 
 


 // Test1: Attaching an operation with arguments
 
	/**
	 * helper variable to store recursion depth for pretty printing
	 */

 private static int indent = 0;

 /**
 * Print a number of spaces according to the current recursion depth
 */

 private static void indent() {
		for (int i=0; i<indent; i++)
			System.out.print(" ");
	} 
	
/*
	public int sizeOnDisk(Component c) {
	 return c.sizeOnDisk();
	}
	
	private int Component.sizeOnDisk() {
	 Enumeration e = SampleComposite.aspectOf().recurseFunction(this, new FunctionVisitor() {
	 public Object doFunction(Component c) {
	 return new Integer(c.sizeOnDisk());
	 }
	 });
	 
	 int sum =0;
	 while (e.hasMoreElements()) {
	 sum += ((Integer)e.nextElement()).intValue();
	 }
	 return sum;
	
 }

 private int File.sizeOnDisk() {return id;}
*/

 public int sizeOnDisk(Component c) { // Does not work
 return c.sizeOnDisk();
 }

 private int Component.sizeOnDisk() {return 0;}
 
 private int Directory.sizeOnDisk() { 
 int sum = 0; 
 java.util.Enumeration children;
 for (children = SampleComposite.aspectOf().getAllChildren(this); children.hasMoreElements(); ) {
 sum += ((Component)children.nextElement()).sizeOnDisk();
 }
 return sum;
 }
 
 private int File.sizeOnDisk() { return id; }


/* public int sizeOnDisk(Component c) { // Works
 int sum = 0;
 if (c instanceof File) {
 sum = ((File)c).id;
 } else if (c instanceof Directory) {
 java.util.Enumeration children;
 for (children = SampleComposite.aspectOf().getAllChildren(c); children.hasMoreElements(); ) {
 sum += sizeOnDisk((Component)children.nextElement());
 } 
 }
 return sum;
 }
*/

 /**
 * Provides a client-accessible method that pretty-prints the 
 * structure of the aggregate structure using a Visitor
 *
 * @param s the PrintStram to print to
 */

 public void Component.printStructure(PrintStream s) {
 indent();
 s.println("<Component>"+this);
 } 
 
 /**
 * Implements <code>printStructure</code> for Composites: The indent 
 * is appropriately updated and the method call is forwarded to all 
 * children.
 *
 * @param s the PrintStram to print to
 */

 public void Composite.printStructure(final PrintStream s) {
 indent();
 s.println("<Composite>"+this);
 indent +=4;
 SampleComposite.aspectOf().recurseOperation(this, new Visitor() { public void doOperation(Component c) { c.printStructure(s); } } );
 indent -=4;
 }

 /**
 * Implements <code>printStructure</code> for Leafs.
 *
 * @param s the PrintStram to print to
 */

 public void Leaf.printStructure(PrintStream s) {
 indent();
 s.println("<Leaf>"+this);
 }
 
 
 
 
 
 // Test2: Collecting statistics on the structure (aggregation)
 
 /**
 * Provides a client-accessible method that pretty-prints the 
 * structure of the aggregate structure using a FunctionVisitor. 
 * Calculates the sum of all Leaf IDs in the structure 
 *
 * @returns the sum of leaf ids of all elements in this structure
 */ 
 
 public int Component.subSum() {
 return 0;
 }

 /**
 * Implements <code>subSum()</code> for Composites: The method call 
 * is forwarded to all children, then the results are summed up.
 *
 * @returns the sum of leaf ids of all elements in this structure
 */

 public int Composite.subSum() { // Collects the sum of all Leaves in the structure
 Enumeration enum = SampleComposite.aspectOf().recurseFunction(this, new FunctionVisitor() { 
 public Object doFunction(Component c) { 
 return new Integer(c.subSum()); 
 }
 }); 
 
 int sum = 0;
 while (enum.hasMoreElements()) {
 sum += ((Integer) enum.nextElement()).intValue();
 System.out.println("Sum = "+sum);
 }
 return sum;
 }
 
 /**
 * Implements <code>subSum()</code> for Leafs: Simply returns
 * the Leaf's ID.
 *
 * @returns the leaf id
 */

 public int File.subSum() {
 return id;
 }
}

SumVisitor.java

2004-03-24T16:00:00Z

TraversalVisitor.java

2004-03-24T16:00:00Z

Visitor.java

2004-03-24T16:00:00Z

files.lst

2004-03-24T16:00:00Z