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.