]> source.dussan.org Git - aspectj.git/commitdiff
Finally adding some design docs (after 4 years).
authormkersten <mkersten>
Mon, 14 Jul 2003 12:58:42 +0000 (12:58 +0000)
committermkersten <mkersten>
Mon, 14 Jul 2003 12:58:42 +0000 (12:58 +0000)
docs/developer/language.html [new file with mode: 0644]
docs/developer/modules.html [new file with mode: 0644]
docs/developer/overview.html [new file with mode: 0644]

diff --git a/docs/developer/language.html b/docs/developer/language.html
new file mode 100644 (file)
index 0000000..641353f
--- /dev/null
@@ -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 (file)
index 0000000..14b8e01
--- /dev/null
@@ -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,\85 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 \96 ajde.core and ajde.ui. 
+The core should be independent of the ui component (currently this isn\92t 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\92s 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 (file)
index 0000000..fdd7520
--- /dev/null
@@ -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