- initial api-based tests

- initial J2EE samples (added support for XML/Ant scripts)
author: wisberg <wisberg> 2003-08-07 06:57:57 +0000
committer: wisberg <wisberg> 2003-08-07 06:57:57 +0000
commit: 94cb789115ddbbd149309759711e0e3b6515a36b (patch)
tree: bb4e4fa8768a464424658148a7219d201835035e /docs/sandbox
parent: 9e7ceffb06b794ec4e990e639f33af225e697acf (diff)
download: aspectj-94cb789115ddbbd149309759711e0e3b6515a36b.tar.gz
aspectj-94cb789115ddbbd149309759711e0e3b6515a36b.zip
7 files changed, 366 insertions, 53 deletions
diff --git a/docs/sandbox/readme-sandbox.html b/docs/sandbox/readme-sandbox.html
index d8c874399..4745b98f2 100644
--- a/docs/sandbox/readme-sandbox.html
+++ b/docs/sandbox/readme-sandbox.html
@@ -2,7 +2,7 @@
 <title>README - AspectJ sandbox for sample code and instructions</title>
 <body>
 <h2>README - AspectJ sandbox for sample code and instructions</h2>
-This directory is a place to put some scraps that might end up in the
+This directory is a place to put scraps that might end up in the
 AspectJ documentation or on the web site:
 <ul>
 <li>sample code for AspectJ programs,
@@ -31,7 +31,10 @@ without too much overhead.
 Code in the sandbox is kept in a running state;
 it's tested by running the harness on the sandbox
 test suite file
-  <a href="sandbox-test.xml">sandbox-test.xml</a>.
+  <a href="sandbox-test.xml">sandbox-test.xml</a>
+or 
+  <a href="sandbox-api-test.xml">sandbox-api-test.xml</a>.
+
 To extract the code for documentation, we use a tool 
 that recognizes
 a sample within a source file if it has comments
@@ -41,6 +44,7 @@ and with the test suite specification only takes
 a bit of care with formatting and comments.
 The rest of this document tells how.
 
+<h3>Documenting samples</h3>
 <p><code>org.aspectj.internal.tools.build.SampleGatherer</code>
 (in the build module) extracts samples
 of the following form from any "source" file
@@ -82,11 +86,11 @@ to avoid introducing mistakes.
      	</li>
 	<li>Keep lines short  - 60 characters or less.
      	</li>
-	<li>Code snippets taken out of context of the defining type
+	<li>In Java, code taken out of context of the defining type
         can be indented only once in the source code,
         even though they might normally be indented more.
      	</li>
-	<li>Indent advice pointcuts once beyond the block code:
+	<li>In AspectJ, indent advice pointcuts beyond the block code:
 <pre>
     before() : call(!public * com.company.library..*.*(String,..))
            && within(Runnable+) { // indent once more than code
@@ -114,9 +118,25 @@ as do sets pertaining to particular publications or tutorials.
 An example of this are the sources for the "Test Inoculated" 
 article in the <a href="inoculated">inoculated/</a> directory.
 
-<p>
-When adding code, add a corresponding test case in 
-<a href="sandbox-test.xml">sandbox-test.xml</a>.
+<h3>Testing samples</h3>
+We try to make sure that the samples we present to people
+actually work by testing each kind differently:
+<ul>
+<li>Most Java and AspectJ programs are tested using
+  <a href="sandbox-test.xml">sandbox-test.xml</a>.
+</li>
+<li>API clients are tested using
+  <a href="sandbox-api-test.xml">sandbox-api-test.xml</a>,
+which requires building <code>aspectjtools.jar</code>.
+</li>
+<li>Shell and Ant scripts should be run per instructions.
+</li>
+<li>HTML and text files must be manually reviewed.
+</li>
+</ul>
+
+When adding Java or AspectJ code, add a corresponding test case 
+in <a href="sandbox-test.xml">sandbox-test.xml</a>.
 This file has the same format as other harness test suites;
 for more information,
 see <a href="../../tests/readme-writing-compiler-tests.html"> 
@@ -125,7 +145,7 @@ see <a href="../../tests/readme-writing-compiler-tests.html">
 The test suite should run and pass after new code is added 
 and before samples are extracted.
 
-<p>To keep sample code in sync with the tests:
+<p>To keep Java/AspectJ code in sync with the tests:
 <ul>
 <li>The test title should be prefixed with the anchor name and
     have any suffixes necessary for clarity and to make sure
@@ -183,6 +203,7 @@ and before samples are extracted.
 	</ul>
 	</li>
 </ul>
+
 <p>
 Happy coding!
 <hr>
diff --git a/docs/sandbox/sandbox-api-test.xml b/docs/sandbox/sandbox-api-test.xml
new file mode 100644
index 000000000..959272592
--- /dev/null
+++ b/docs/sandbox/sandbox-api-test.xml
@@ -0,0 +1,26 @@
+<!DOCTYPE suite SYSTEM "../tests/ajcTestSuite.dtd">
+<!-- ../ path when running, ../../ when editing? -->
+
+
+<!-- 
+	This is just like sandbox-test.xml except that it is
+	reserved for code that uses the AspectJ API's because
+	it assumes the build has created the target library,
+	
+	   ../aj-build/dist/tools/lib/aspectjtools.jar
+	
+	and that we run from a peer directory of this one.
+-->
+<suite>
+		
+	<ajc-test dir="api-clients" title="api-ajde-modelWalker"
+		comment="function unvalidated, only that it compiles and runs">
+		<compile files="org/aspectj/samples/JoinPointCollector.java"
+			classpath="../../../aj-build/dist/tools/lib/aspectjtools.jar"/>
+		<run class="org/aspectj/samples/JoinPointCollector"
+			options="-help"/>
+		</ajc-test>
+
+</suite>
+
+	
+\ No newline at end of file
diff --git a/docs/sandbox/sandbox-test.xml b/docs/sandbox/sandbox-test.xml
index 332a4a9d1..fe0eb4110 100644
--- a/docs/sandbox/sandbox-test.xml
+++ b/docs/sandbox/sandbox-test.xml
@@ -13,7 +13,6 @@
 	- verify that RunTime and RuntimeWrites throw Errors	
 	- harness bug: errStreamIsError not false when not forked; fork?
 	- check output/error stream against expected
-	- verify api-clients, using access to aspectjtools.jar...
 	   
 -->
 <suite>
@@ -133,14 +132,4 @@
 
 </suite>
 
-<!--
-	TODO XXX verify api-clients using aspectjtools.jar?
-
-	<ajc-test dir="api-clients" title="api-ajde-modelWalker">
-		<compile files="org/aspectj/samples/JoinPointCollector.java"
-			classpath="../aj-build/dist/tools/lib/aspectjtools.jar;"/>
-		<run ... />
-		</ajc-test>
-
--->
 	
 \ No newline at end of file
diff --git a/docs/sandbox/scripts/precompile-jsp.build.xml b/docs/sandbox/scripts/precompile-jsp.build.xml
new file mode 100644
index 000000000..bdabff97b
--- /dev/null
+++ b/docs/sandbox/scripts/precompile-jsp.build.xml
@@ -0,0 +1,137 @@
+<!-- @author Wes Isberg -->
+<!-- START-SAMPLE j2ee-tomcat4-precompileJsp Precompile JSP's for Tomcat 4.x using AspectJ -->
+<project name="Precompile Tomcat JSPs" default="all" basedir="."> 
+
+    <target name="all" depends="jspc,compile"/>
+
+	<target name="info">
+		<echo>
+This Ant script precompiles deployed .jsp files in Tomcat 
+using AspectJ 1.1.
+
+Usage:
+
+  {ant} -f {this-script} \
+    -Dtomcat.home=/home/tomcat \
+    -Dwebapp.name=launchWeb \
+    -DASPECTJ_HOME=/dev/tools/aspectj-1.1.0
+		
+
+This defines the web application deployment $${webapp.dir} as
+
+   $${tomcat.home}/webapps/$${webapp.name}
+
+, generates the Java source files to 
+
+   $${webapp.dir}/WEB-INF/src
+
+, uses iajc (AspectJ) to compile them to
+
+   $${webapp.dir}/WEB-INF/classes,
+
+, and creates the mappings
+
+   $${webapp.dir}/WEB-INF/generated_web.xml,
+
+which must be manually inserted into 
+
+   $${webapp.dir}/WEB-INF/generated_web.xml,
+
+at which point the web application can be reloaded.
+
+This assumes that aspectjrt.jar is already deployed in 
+any of places on the Tomcat application classpath 
+(the application, shared, or common classpath).
+If ASPECTJ_HOME is not defined, it assumes that
+aspectjtools.jar is in 
+
+   ${CATALINA_HOME}/common/lib
+
+</echo>
+	</target>
+	
+  <target name="init"> 
+	<!-- declare these two on command-line -->
+	<property name="webapp.name"
+		value="launchWeb"/>
+		
+	<property name="tomcat.home"
+		location="i:/home/tomcat"/>
+	
+	<property name="webapp.path"
+		location="${tomcat.home}/webapps/${webapp.name}"/>
+	<property name="webapp.src.dir"
+		location="${webapp.path}/WEB-INF/src"/>
+
+	<property name="ASPECTJ_HOME"
+		location="${tomcat.home}/common"/>
+	
+  </target>
+	
+  <target name="jspc" depends="init"> 
+
+    <taskdef classname="org.apache.jasper.JspC" name="jasper2" > 
+      <classpath id="jspc.classpath"> 
+        <pathelement location="${java.home}/../lib/tools.jar"/> 
+        <fileset dir="${tomcat.home}/server/lib"> 
+          <include name="*.jar"/> 
+        </fileset> 
+        <fileset dir="${tomcat.home}/common/lib"> 
+          <include name="*.jar"/> 
+        </fileset> 
+      </classpath> 
+    </taskdef> 
+
+	<mkdir dir="${webapp.src.dir}"/>
+    <jasper2 
+		 validateXml="true" 
+		 uriroot="${webapp.path}" 
+		 webXmlFragment="${webapp.path}/WEB-INF/generated_web.xml" 
+		 outputDir="${webapp.src.dir}" /> 
+
+  </target> 
+
+  <target name="compile" depends="init">
+
+    <mkdir dir="${webapp.path}/WEB-INF/classes"/>
+    <mkdir dir="${webapp.path}/WEB-INF/lib"/>
+    
+      <path id="iajc.classpath"> 
+        <fileset dir="${ASPECTJ_HOME}/lib"> 
+          <include name="aspectjtools.jar"/> 
+        </fileset> 
+      </path> 
+	<taskdef 
+      resource="org/aspectj/tools/ant/taskdefs/aspectjTaskdefs.properties">
+      <classpath refid="iajc.classpath"/> 
+    </taskdef> 
+
+	<!-- forking compile so it runs in Eclipse -->
+    <iajc destdir="${webapp.path}/WEB-INF/classes"
+           sourceroots="${webapp.src.dir}"
+           debug="on" 
+           verbose="true"
+           fork="true" 
+           forkclasspathRef="iajc.classpath"
+           failonerror="true"
+           >
+      <classpath>
+        <pathelement location="${webapp.path}/WEB-INF/classes"/>
+        <fileset dir="${webapp.path}/WEB-INF/lib">
+          <include name="*.jar"/>
+        </fileset>
+        <pathelement location="${tomcat.home}/common/classes"/>
+        <fileset dir="${tomcat.home}/common/lib">
+          <include name="*.jar"/>
+        </fileset>
+        <pathelement location="${tomcat.home}/shared/classes"/>
+        <fileset dir="${tomcat.home}/shared/lib">
+          <include name="*.jar"/>
+        </fileset>
+      </classpath>
+    </iajc>
+
+  </target>
+
+</project>
+<!-- END-SAMPLE j2ee-tomcat4-precompileJsp -->
diff --git a/docs/sandbox/trails/j2ee.html b/docs/sandbox/trails/j2ee.html
new file mode 100644
index 000000000..dc99e0731
--- /dev/null
+++ b/docs/sandbox/trails/j2ee.html
@@ -0,0 +1,87 @@
+<html>
+<body>
+
+This contains short notes on using AspectJ with various J2EE
+servers and deployment tools.
+
+<!-- @author Wes Isberg -->
+
+<h3>Using AspectJ in servlets</h3>
+<h4>Generally</h4>
+<!-- START-SAMPLE j2ee-servlets-generally Using AspectJ in servlets -->
+AspectJ programs work if run in the same namespace and with aspectjrt.jar.
+Servlet runners and J2EE web containers should run AspectJ programs fine
+if the classes and required libraries are deployed as usual.  
+
+As with any shared library, if more than one application is using AspectJ, 
+then the aspectjrt.jar should be deployed where it will be loaded by a 
+common classloader. The same is true of any shared aspects.
+
+<!-- END-SAMPLE j2ee-servlets-generally  -->
+
+<h4>Running AspectJ servlets in Tomcat 4.x</h4>
+
+<!-- START-SAMPLE j2ee-tomcat4-servlets Running AspectJ servlets in Tomcat 4.x -->
+In Tomcat, you can deploy application servlets in WAR's 
+or in exploded web directories and share code across
+applications.
+<ol>  
+<li>Use <code>ajc</code> to compile the servlets, 
+    and deploy the classes as usual into
+    <code>{WebRoot}/WEB-INF/classes</code>.
+    </li>
+
+<li>If your web applications or aspects do not interact, deploy
+    <code>aspectjrt.jar</code> into
+    <code>{WebRoot}/WEB-INF/lib</code>.
+    </li>
+<li>If your web applications or aspects might interact, deploy
+    them to <code>${CATALINE_BASE}/shared/lib</code>.
+    </li>
+</ol>  
+<!-- END-SAMPLE j2ee-tomcat4-servlets  -->
+
+<!-- START-SAMPLE j2ee-tomcat4-jsp Running AspectJ JSP's in Tomcat 4.x -->
+Tomcat 4.x uses the Jasper engine based on Ant to compile JSP's.
+To set up ajc as the compiler, do the following before starting Tomcat:
+<ol>  
+<li>Put <code>aspectjtools.jar</code> in
+<code>${CATALINA_HOME}/common/lib</code> so that it can be loaded
+by Jasper.
+</li>
+<li>Update Jasper servlet parameters in
+  <code>${CATALINA_HOME}/conf/web.xml</code> to tell Ant to use
+  <code>ajc</code> by setting the compiler property to the
+  AspectJ compiler adapter:
+  <pre>
+    &lt;servlet>
+        &lt;servlet-name>jsp&lt;/servlet-name>
+        &lt;servlet-class>org.apache.jasper.servlet.JspServlet&lt;/servlet-class>
+        ...
+        &lt;init-param>
+            &lt;param-name>compiler&lt;/param-name>
+            &lt;param-value>org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter&lt;/param-value>
+        &lt;/init-param>
+	</pre>
+</li>
+<li>The classpath is dynamically generated from the webapp deployment,
+so <code>aspectjrt.jar</code> should be in 
+<code>{webapp}/WEB-INF/lib</code> or some shared or common
+directory supported by the server.
+</li>
+
+<li>Alternatively, you can precompile JSP's using 
+<a href="#j2ee-tomcat4-precompileJsp">this Ant script</a>.
+That involves manually updating the <code>web.xml</code> file 
+with the <code>Jasper</code>-generated servlet mappings.
+</li>
+</ol>
+<!-- END-SAMPLE j2ee-tomcat4-jsp -->
+
+ 
+<!-- START-SAMPLE j2ee-servlets-tomcat4-myeclipseide Running AspectJ servlets in Tomcat 4.x using MyEclipseIDE -->
+
+<!-- END-SAMPLE j2ee-servlets-tomcat4-myeclipseide  -->
+
+</body>
+</html>
diff --git a/docs/sandbox/trails/j2ee.txt b/docs/sandbox/trails/j2ee.txt
deleted file mode 100644
index 8685939b1..000000000
--- a/docs/sandbox/trails/j2ee.txt
+++ /dev/null
@@ -1,34 +0,0 @@
-
-This contains short notes on using AspectJ with various J2EE
-servers and deployment tools.
-
-// @author Wes Isberg
-
--------- START-SAMPLE j2ee-servlets-generally Using AspectJ in servlets
-AspectJ programs work if run in the same namespace and with aspectjrt.jar.
-Servlet runners and J2EE web containers should run AspectJ programs fine
-if the classes and required libraries are deployed as usual.  The runtime
-classes and shared aspects might need to be deployed into a common 
-directory to work properly across applications, especially in containers 
-that use different class loaders for different applications or use 
-different class-loading schemes.
-
-As with any shared library, if more than one application is using AspectJ, 
-then the aspectjrt.jar should be deployed where it will be loaded by a 
-common classloader. 
-
-Aspects which are used by two applications might be independent or shared.
-Independent aspects can be deployed in each application-specific archive.
-Aspects might be shared explicitly or implicitly, as when they are stateful 
-or staticly bound (however indirectly) to common classes.  When in doubt,
-it is safest to deploy the aspects in the common namespace.
-
--------- END-SAMPLE j2ee-servlets-generally
-
--------- START-SAMPLE j2ee-servlets-tomcat4 Running AspectJ servlets in Tomcat 4.x
-To deploy an AspectJ program as a Tomcat servlet,
-place aspectjrt.jar in shared/lib and deploy the required libraries
-and AspectJ-compiled servlet classes as usual.
-
--------- END-SAMPLE j2ee-servlets-tomcat4 
-
diff --git a/docs/sandbox/trails/myeclipseide.html b/docs/sandbox/trails/myeclipseide.html
new file mode 100644
index 000000000..daff02e49
--- /dev/null
+++ b/docs/sandbox/trails/myeclipseide.html
@@ -0,0 +1,87 @@
+<html>
+<body>
+
+<!-- @author Wes Isberg -->
+<!-- START-SAMPLE j2ee-myeclipseide-generally Using MyEclipseIDE to develop AspectJ programs for J2EE -->
+MyEclipseIde
+(<a href="http://www.myeclipseide.com/">http://www.myeclipseide.com</a>)
+aims to make it easy to develop J2EE applications using Eclipse.
+AJDT 
+(<a href="http://eclipse.org/ajdt">http://eclipse.org/ajdt</a>)
+is an Eclipse plug-in that supports AspectJ. 
+<ul>
+<li>To install AJDT with MyEclipseIDE, direct the Eclipse update manager to
+<a href="http://download.eclipse.org/technology/ajdt/dev/update">
+      http://download.eclipse.org/technology/ajdt/dev/update</a>,
+install the plug-in, and follow any post-install instructions.
+</li>
+
+<li>To enable a project to use aspects, first
+select <code>Convert to AspectJ project</code>
+from the project's context menu (select project, right click).
+(XXX Bug: AJDT reverts perspective to Java; go back to MyEclipseIDE)
+Note that you must convert each project;
+converting the master J2EE project will not affect
+the child components (XXX RFE: option to convert child if parent).
+</li>
+
+<li>To build, select the menu item <code>Project &gt; Rebuild Project</code>.
+AJDT creates <code>default.lst</code> which lists all source files and
+compiles them.  
+You can also recompile by clicking the AJDT build button.
+(XXX Bug:  only available in the Java perspective)
+</li>
+
+<li>To deploy, first add <code>aspectjrt.jar</code> to the project's
+library directory.  
+For servlets and JSP's, that is in <code>{Web Root}/WEB-INF/lib</code>.
+For EJB's, it's XXX todo.
+Then deploy as usual for your application server.
+</li>
+<li>If you are using AspectJ in more than one project,
+you might instead deploy <code>aspectjrt.jar</code>
+whereever shared libraries belong for your server.
+</li>
+</ul>
+
+<!-- END-SAMPLE j2ee-myeclipseide-generally -->
+
+<!-- TODO-SAMPLE j2ee-myeclipseide-tomcat4Servlets Running AspectJ servlets in Tomcat 4.x using MyEclipseIDE -->
+
+<h3>Bugs in MyEclipseIDE</h3>
+<ol>
+<li>After refactoring to rename a servlet, have to manually update web.xml</li>
+<li>Silent failure when unable to delete a duplicate resource during deployment.</li>
+<li>Annoyingly modal UI for deployment.  Use a view.</li>
+<li>Need validation on saving Web.xml.  E.g., servlet mapping names validated with declared servlet names.</li>
+<li>Deployment dirty flag not working; not updated after editing web.xml or rebuilding project.</li>
+<li>Apparantly false JSP error?  using Sun page and template page,
+    got:
+    "Fatal error - The markup in the document preceding the root element 
+     must be well-formed."
+	Error persisted even after replacing the entire contents of the file
+    with the template which worked by default.
+</li>
+<li>When using the exact template page, get no MyEclipseIDE error,
+    but do get compile errors in Tomcat.  Using Javac, get compile-failed
+    stack trace with initial line number.  Using ajc, just get stack trace.
+	But precompiling using Ant seems to work.
+    </li>
+<li>Precompiling JSP's:  
+  <ul> 
+    <li>MyEclipseIDE has a command to compile all JSP's, but
+    I don't see (where or how) the updated servlet mappings
+    get into the deployed web.xml.
+    It would be great to get this working with AJDT.
+	</li>
+	<li>I adapted the Tomcat precompile script to use AspectJ's iajc.
+    This works fine, but like all Jasper2 solutions required the
+    generated servlet mappings be copied manually into the web.xml file.
+	See <a href="#j2ee-tomcat4-precompileJsp">the Ant build script</a>
+	</li>
+  </ul> 
+    </li>
+</ol>
+
+</body>
+</html>
+\ No newline at end of file
author	wisberg <wisberg>	2003-08-07 06:57:57 +0000
committer	wisberg <wisberg>	2003-08-07 06:57:57 +0000
commit	94cb789115ddbbd149309759711e0e3b6515a36b (patch)
tree	bb4e4fa8768a464424658148a7219d201835035e /docs/sandbox
parent	9e7ceffb06b794ec4e990e639f33af225e697acf (diff)
download	aspectj-94cb789115ddbbd149309759711e0e3b6515a36b.tar.gz aspectj-94cb789115ddbbd149309759711e0e3b6515a36b.zip