Finally adding some design docs (after 4 years).

author: mkersten <mkersten> 2003-07-14 12:58:42 +0000
committer: mkersten <mkersten> 2003-07-14 12:58:42 +0000
commit: cc57abb7456100c16eb009707293d41d1f760db3 (patch)
tree: d8c2915eceda262ceb5808aa7aa8da0f7d9d5d6b /docs
parent: 461bf788adbc4e7740202ea4c1866268f312d4b1 (diff)
download: aspectj-cc57abb7456100c16eb009707293d41d1f760db3.tar.gz
aspectj-cc57abb7456100c16eb009707293d41d1f760db3.zip
3 files changed, 590 insertions, 0 deletions
diff --git a/docs/developer/language.html b/docs/developer/language.html
new file mode 100644
index 000000000..641353f9d
--- /dev/null
+++ b/docs/developer/language.html
@@ -0,0 +1,194 @@
+<html>
+
+<head>
+<meta http-equiv="Content-Language" content="en-us">
+<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
+<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
+<meta name="ProgId" content="FrontPage.Editor.Document">
+<title>AJDT Project Proposal</title>
+<STYLE TYPE="text/css">
+<!--
+ 
+   /* FOR THE SDA PAGE */
+ 
+	/*
+	BODY {margin-top: 15px; margin-left: 15px; margin-right: 15px;}
+	*/
+
+	A:link {
+		color:#4756AC;
+	}
+	A:visited {
+		color:#60657B;
+	}
+	A:hover {
+		color:red
+	}
+	
+	INPUT {font:12px "Courier New", sans-serif;}
+	
+	H2 {
+		font:18px/18px Verdana, Arial, Helvetica, sans-serif; 
+		color:black; 
+		font-weight:bold; 
+		margin-left: 10px;
+		line-height:110%; 
+	}
+	H3 {
+		font:18px/18px Verdana, Arial, Helvetica, sans-serif; 
+		color:black; 
+		font-weight:bold; 
+		margin-left: 10px;
+		line-height:110%; 
+	}
+	H4 {
+		font:15px/16px Verdana, Arial, Helvetica, sans-serif; 
+		color:black; 
+		font-weight:bold; 
+		margin-left: 10px;
+		line-height:140%;
+	}
+	P {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif; 
+		margin-right: 10px;
+		margin-left: 10px;
+		line-height:130%; 
+	}
+	.paragraph {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif; 
+		margin-right: 10px;
+		margin-left: 10px;
+		line-height:130%; 
+	}
+	.smallParagraph {
+		font:11px/11px Verdana, Arial, Helvetica, sans-serif; 
+		margin-right: 10px;
+		margin-left: 10px;
+		line-height:130%; 
+	}
+	LI {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif;
+		text-align:justify; 
+		margin-right: 10px;
+		margin-left: 15px;
+		line-height:120%; 
+	}
+	/*
+	UL {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif;
+		text-align:justify; 
+		margin-right: 10px;
+		margin-left: 15px;
+		line-height:120%; 
+	}*/
+	
+	DL {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif;
+		text-align:justify; 
+		margin-right: 10px;
+		margin-left: 15px;
+		line-height:120%; 
+	}
+	B { font:13px/13px Verdana, Arial, Helvetica, sans-serif; 
+		font-weight:bold; 
+		line-height:140%;
+	}
+	.footer {
+		font:10px/10px Verdana, Arial, Helvetica, sans-serif;  
+		color:#888888; 
+		text-align:left
+	}
+	.figureTitle {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif; 
+		text-align:justify; 
+		text-align:center
+	}
+	.copyrightNotice {
+		font:10px/10px Verdana, Arial, Helvetica, sans-serif; 
+		color:#999999; 
+		line-height:110%;
+	}
+	.smallHeading {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif; 
+		font-weight:bold;
+		line-height:110%;
+	}
+	.tinyHeading {
+		font:11px/11px Verdana, Arial, Helvetica, sans-serif; 
+		font-weight:bold;
+		line-height:120%;
+	}
+	.newsText {
+		font:11px/11px Verdana, Arial, Helvetica, sans-serif; 
+		line-height:130%;
+	}
+	.smallParagraph {
+		font:11px/11px Verdana, Arial, Helvetica, sans-serif; 
+		line-height:130%;
+	}
+	.fancyHeading {
+		font:20px/20px Chantilly, Arial, Helvetica, sans-serif; 
+		margin-right: 10px;
+		color:#6f7a92;
+		margin-left: 10px;
+		line-height:130%;
+	}
+ 
+-->
+</STYLE>
+</head>
+
+<BODY BGCOLOR="white">
+
+<h3 align="center">AspectJ Language Design</h3>
+
+<h4>Key Language Design Properties (from Gregor)</h4>
+<p>(1) Orthogonal join point model - the different kinds of join points, the 
+different primitive pointcuts, and the different kinds of advice can be used in 
+any combination.</p>
+<p>This was one of the hardest parts of the design to get right, because of the 
+&quot;constructor must call super&quot; rule in Java. But we finally got this in 1.0.<br>
+<br>
+(2) Pointcuts support composition and abstraction. Abelson and Sussman say that 
+composition and abstraction are the key elements of a real language. Clearly the 
+pointcut mechanism is the new thing in AspectJ, and so it was critical that it 
+support composition and abstraction. The fact that someone can write:</p>
+<blockquote>
+	<p><font face="Courier">/* define an abstraction called stateChange */<br>
+	pointcut stateChange(): call(void FigureElement+.set*(*));<br>
+	<br>
+	/* compose pointcuts to get other pointcuts */<br>
+	pointcut topLevelStateChange(): stateChange() <br>
+	&amp;&amp; !cflowbelow(stateChange());</font></p>
+</blockquote>
+<p>is what makes it possible for people to really work with crosscutting 
+structure and make their code more clear.<br>
+<br>
+(3) Statically type checked. The efficiency, code quality and programmer 
+productivity arguments for this have been made elsewhere, so I won't repeat 
+them. <br>
+<br>
+(4) Efficient. AspectJ code is as fast as the equivalent functionality, written 
+by hand, in a scattered and tangled way.<br>
+<br>
+(5) Simple kernel. I've heard some people say that AspectJ is too big and too 
+complex. In the most important sense of simple AspectJ is simple. I can reason 
+about any AspectJ program with a simple model. The kernel of AspectJ is simple, 
+and the orthogonality described above means that its easy to start with just the 
+kernel and slowly add to that.</p>
+<p>Its pretty clear to pull out this kernel of AspectJ. I would argue that the 
+right idea for a standard AOP API<br>
+is this kernel, packaged in a way that allows building more sophisticated tools 
+on top of it.<br>
+<br>
+(6) Supports multiple weave times. AspectJ is neutral on whether weaving happens 
+at pre-process, compile, post-process, load, JIT or runtime. This neutrality is 
+critical. Its why there are serious JVM experts who are already thinking about 
+JVM support for AspectJ.</p>
+<p>There's more, but I think these are the most important ones. I think any 
+functionality this group comes up with should also meet these criteria.<br>
+&nbsp;</p>
+
+</body>
+
+</html>
+\ No newline at end of file
diff --git a/docs/developer/modules.html b/docs/developer/modules.html
new file mode 100644
index 000000000..14b8e01b9
--- /dev/null
+++ b/docs/developer/modules.html
@@ -0,0 +1,222 @@
+<html>
+
+<head>
+<meta http-equiv="Content-Language" content="en-us">
+<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
+<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
+<meta name="ProgId" content="FrontPage.Editor.Document">
+<title>AJDT Project Proposal</title>
+<STYLE TYPE="text/css">
+<!--
+ 
+   /* FOR THE SDA PAGE */
+ 
+	/*
+	BODY {margin-top: 15px; margin-left: 15px; margin-right: 15px;}
+	*/
+
+	A:link {
+		color:#4756AC;
+	}
+	A:visited {
+		color:#60657B;
+	}
+	A:hover {
+		color:red
+	}
+	
+	INPUT {font:12px "Courier New", sans-serif;}
+	
+	H2 {
+		font:18px/18px Verdana, Arial, Helvetica, sans-serif; 
+		color:black; 
+		font-weight:bold; 
+		margin-left: 10px;
+		line-height:110%; 
+	}
+	H3 {
+		font:18px/18px Verdana, Arial, Helvetica, sans-serif; 
+		color:black; 
+		font-weight:bold; 
+		margin-left: 10px;
+		line-height:110%; 
+	}
+	H4 {
+		font:15px/16px Verdana, Arial, Helvetica, sans-serif; 
+		color:black; 
+		font-weight:bold; 
+		margin-left: 10px;
+		line-height:140%;
+	}
+	P {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif; 
+		margin-right: 10px;
+		margin-left: 10px;
+		line-height:130%; 
+	}
+	.paragraph {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif; 
+		margin-right: 10px;
+		margin-left: 10px;
+		line-height:130%; 
+	}
+	.smallParagraph {
+		font:11px/11px Verdana, Arial, Helvetica, sans-serif; 
+		margin-right: 10px;
+		margin-left: 10px;
+		line-height:130%; 
+	}
+	LI {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif;
+		text-align:justify; 
+		margin-right: 10px;
+		margin-left: 15px;
+		line-height:120%; 
+	}
+	/*
+	UL {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif;
+		text-align:justify; 
+		margin-right: 10px;
+		margin-left: 15px;
+		line-height:120%; 
+	}*/
+	
+	DL {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif;
+		text-align:justify; 
+		margin-right: 10px;
+		margin-left: 15px;
+		line-height:120%; 
+	}
+	B { font:13px/13px Verdana, Arial, Helvetica, sans-serif; 
+		font-weight:bold; 
+		line-height:140%;
+	}
+	.footer {
+		font:10px/10px Verdana, Arial, Helvetica, sans-serif;  
+		color:#888888; 
+		text-align:left
+	}
+	.figureTitle {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif; 
+		text-align:justify; 
+		text-align:center
+	}
+	.copyrightNotice {
+		font:10px/10px Verdana, Arial, Helvetica, sans-serif; 
+		color:#999999; 
+		line-height:110%;
+	}
+	.smallHeading {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif; 
+		font-weight:bold;
+		line-height:110%;
+	}
+	.tinyHeading {
+		font:11px/11px Verdana, Arial, Helvetica, sans-serif; 
+		font-weight:bold;
+		line-height:120%;
+	}
+	.newsText {
+		font:11px/11px Verdana, Arial, Helvetica, sans-serif; 
+		line-height:130%;
+	}
+	.smallParagraph {
+		font:11px/11px Verdana, Arial, Helvetica, sans-serif; 
+		line-height:130%;
+	}
+	.fancyHeading {
+		font:20px/20px Chantilly, Arial, Helvetica, sans-serif; 
+		margin-right: 10px;
+		color:#6f7a92;
+		margin-left: 10px;
+		line-height:130%;
+	}
+ 
+-->
+</STYLE>
+</head>
+
+<BODY BGCOLOR="white">
+
+<h3 align="center">AspectJ Modules</h3>
+
+<p>There are a number of different structures [Parnas] : the module structure, 
+the uses structure, the runtime structure,� We focus first on the module 
+structure as found in the org.aspectj and org.eclipse.ajdt cvs roots.<br>
+<br>
+The CVS modules are all rooted at dev.eclipse.org:/home/technology. </p>
+<ul>
+	<li>aspectj-home contains the AspectJ project web site on eclipse.org</li>
+	<li>org.aspectj contains the AspectJ project source code</li>
+	<li>org.eclipse.ajdt contains the AJDT project web site and the AJDT source 
+	code</li>
+</ul>
+<h4>Core Modules</h4>
+<h4 class="paragraph"><b>ajbrowser</b></h4>
+<h4 class="paragraph">This module contains the ajbrowser application. It depends on the ajde module 
+for access to the aspectj compiler, and also for the swing user interface 
+components that ajde provides.</h4>
+<h4 class="paragraph"><b>ajde</b></h4>
+<p>This module hides the details of accessing the aspectj compiler and interpreting 
+compilation results (error messages, structure model etc.) from other 
+applications (typically IDEs) that need to invoke it programmatically. <br>
+<br>
+It also contains a library of common swing user interface components that can be 
+used by any swing based IDE. Ajbrowser and the non-eclipse IDE integration 
+projects use this library (except for the emacs support).<br>
+<br>
+Note: we need to separate the ajde component into two � ajde.core and ajde.ui. 
+The core should be independent of the ui component (currently this isn�t quite 
+true). This will allow non-swing based applications that need to integrate with 
+the aspectj compiler to do so without needing to provide a swing environment. 
+The issue is most pressing on Mac OS X where AJDT fails to load due to conflicts 
+between Eclipse�s SWT and swing<br>
+<br>
+Changing any public interface in ajde can break all the IDE integration projects 
+and should be done with care. </p>
+<p><b>asm</b></p>
+<p>This module contains the Abstract Structure Model which represents the result of 
+an aspectj compilation. Clients of ajde are returned an instance of the 
+structure model which allows them to navigate and interpret the structure of a 
+compiled aspectj program.</p>
+<p><b>bridge</b></p>
+<p>...</p>
+<p><b>org.aspectj.ajdt.core</b></p>
+<p>...</p>
+<p><b>org.eclipse.jdt.core</b></p>
+<p>...</p>
+<p><b>runtime</b></p>
+<p>...</p>
+<p><b>taskdefs</b></p>
+<p>...</p>
+<p><b>util</b></p>
+<p>...</p>
+<p><b>weaver</b></p>
+<h4>...<br>
+<br>
+Supporting Modules</h4>
+<p><b>build</b></p>
+<p>...</p>
+<p><b>docs</b></p>
+<p>...</p>
+<p><b>lib</b></p>
+<p>...</p>
+<p><b>releases</b></p>
+<p>...</p>
+<p><b>testing</b></p>
+<p>...</p>
+<p><b>testing-client</b></p>
+<p>...</p>
+<p><b>testing-drivers</b></p>
+<p>...</p>
+<p><b>testing-util</b></p>
+<p>...</p>
+<p><b>tests</b></p>
+<p>...<br>
+&nbsp;</p>
+
+</body>
+
+</html>
+\ No newline at end of file
diff --git a/docs/developer/overview.html b/docs/developer/overview.html
new file mode 100644
index 000000000..fdd7520d6
--- /dev/null
+++ b/docs/developer/overview.html
@@ -0,0 +1,174 @@
+<html>
+
+<head>
+<meta http-equiv="Content-Language" content="en-us">
+<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
+<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
+<meta name="ProgId" content="FrontPage.Editor.Document">
+<title>AJDT Project Proposal</title>
+<STYLE TYPE="text/css">
+<!--
+ 
+   /* FOR THE SDA PAGE */
+ 
+	/*
+	BODY {margin-top: 15px; margin-left: 15px; margin-right: 15px;}
+	*/
+
+	A:link {
+		color:#4756AC;
+	}
+	A:visited {
+		color:#60657B;
+	}
+	A:hover {
+		color:red
+	}
+	
+	INPUT {font:12px "Courier New", sans-serif;}
+	
+	H2 {
+		font:18px/18px Verdana, Arial, Helvetica, sans-serif; 
+		color:black; 
+		font-weight:bold; 
+		margin-left: 10px;
+		line-height:110%; 
+	}
+	H3 {
+		font:18px/18px Verdana, Arial, Helvetica, sans-serif; 
+		color:black; 
+		font-weight:bold; 
+		margin-left: 10px;
+		line-height:110%; 
+	}
+	H4 {
+		font:15px/16px Verdana, Arial, Helvetica, sans-serif; 
+		color:black; 
+		font-weight:bold; 
+		margin-left: 10px;
+		line-height:140%;
+	}
+	P {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif; 
+		margin-right: 10px;
+		margin-left: 10px;
+		line-height:130%; 
+	}
+	.paragraph {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif; 
+		margin-right: 10px;
+		margin-left: 10px;
+		line-height:130%; 
+	}
+	.smallParagraph {
+		font:11px/11px Verdana, Arial, Helvetica, sans-serif; 
+		margin-right: 10px;
+		margin-left: 10px;
+		line-height:130%; 
+	}
+	LI {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif;
+		text-align:justify; 
+		margin-right: 10px;
+		margin-left: 15px;
+		line-height:120%; 
+	}
+	/*
+	UL {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif;
+		text-align:justify; 
+		margin-right: 10px;
+		margin-left: 15px;
+		line-height:120%; 
+	}*/
+	
+	DL {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif;
+		text-align:justify; 
+		margin-right: 10px;
+		margin-left: 15px;
+		line-height:120%; 
+	}
+	B { font:13px/13px Verdana, Arial, Helvetica, sans-serif; 
+		font-weight:bold; 
+		line-height:140%;
+	}
+	.footer {
+		font:10px/10px Verdana, Arial, Helvetica, sans-serif;  
+		color:#888888; 
+		text-align:left
+	}
+	.figureTitle {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif; 
+		text-align:justify; 
+		text-align:center
+	}
+	.copyrightNotice {
+		font:10px/10px Verdana, Arial, Helvetica, sans-serif; 
+		color:#999999; 
+		line-height:110%;
+	}
+	.smallHeading {
+		font:13px/13px Verdana, Arial, Helvetica, sans-serif; 
+		font-weight:bold;
+		line-height:110%;
+	}
+	.tinyHeading {
+		font:11px/11px Verdana, Arial, Helvetica, sans-serif; 
+		font-weight:bold;
+		line-height:120%;
+	}
+	.newsText {
+		font:11px/11px Verdana, Arial, Helvetica, sans-serif; 
+		line-height:130%;
+	}
+	.smallParagraph {
+		font:11px/11px Verdana, Arial, Helvetica, sans-serif; 
+		line-height:130%;
+	}
+	.fancyHeading {
+		font:20px/20px Chantilly, Arial, Helvetica, sans-serif; 
+		margin-right: 10px;
+		color:#6f7a92;
+		margin-left: 10px;
+		line-height:130%;
+	}
+ 
+-->
+</STYLE>
+</head>
+
+<BODY BGCOLOR="white">
+
+<h3 align="center">AspectJ Design Overview</h3>
+
+<h4 class="paragraph">Here are some sobering words from David Parnas on 
+&quot;Ignorant Surgery&quot; in his paper on Software Aging:</h4>
+<h4 class="smallParagraph">&quot;Although it is essential to upgrade software to 
+prevent aging, changing software can cause a different form of aging. The 
+designer of a piece of software usually had a simple concept in mind when 
+writing the program. If the program is large, understanding the concept allows 
+one to find those sections of the program that must be altered when an update or 
+correction is needed. Understanding that concept also implies understanding the 
+interfaces used within the system and between the system and its environment.&nbsp; 
+Changes made by people who do not understand the original design concept almost 
+always cause the structure of the program to degrade. Under those circumstances, 
+changes will be inconsistent with the original concept; in fact, they will 
+invalidate the original concept. Sometimes the damage is small, but often it is 
+quite severe. After those changes, one must know both the original design rules 
+and the newly introduced exceptions to the rules, to understand the product. 
+After many such changes, the original designers no longer understand the 
+product. Those who made the changes, never did. In other words, *nobody* 
+understands the modified product.<br>
+Software that has been repeatedly modified (maintained) in this way becomes very 
+expensive to update. Changes take longer and are more likely to introduce new 
+'bugs'&quot;</h4>
+<h4>Contents</h4>
+<ul>
+	<li><a href="modules.html">Module Structure</a></li>
+	<li><a href="language.html">Language Design</a></li>
+</ul>
+
+</body>
+
+</html>
+\ No newline at end of file
author	mkersten <mkersten>	2003-07-14 12:58:42 +0000
committer	mkersten <mkersten>	2003-07-14 12:58:42 +0000
commit	cc57abb7456100c16eb009707293d41d1f760db3 (patch)
tree	d8c2915eceda262ceb5808aa7aa8da0f7d9d5d6b /docs
parent	461bf788adbc4e7740202ea4c1866268f312d4b1 (diff)
download	aspectj-cc57abb7456100c16eb009707293d41d1f760db3.tar.gz aspectj-cc57abb7456100c16eb009707293d41d1f760db3.zip