diff options
| -rw-r--r-- | docs/sandbox/readme-sandbox.html | 37 | ||||
| -rw-r--r-- | docs/sandbox/sandbox-api-test.xml | 26 | ||||
| -rw-r--r-- | docs/sandbox/sandbox-test.xml | 11 | ||||
| -rw-r--r-- | docs/sandbox/scripts/precompile-jsp.build.xml | 137 | ||||
| -rw-r--r-- | docs/sandbox/trails/j2ee.html | 87 | ||||
| -rw-r--r-- | docs/sandbox/trails/j2ee.txt | 34 | ||||
| -rw-r--r-- | docs/sandbox/trails/myeclipseide.html | 87 |
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> + <servlet> + <servlet-name>jsp</servlet-name> + <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class> + ... + <init-param> + <param-name>compiler</param-name> + <param-value>org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter</param-value> + </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 > 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 |