<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,
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
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
</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
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">
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
</ul>
</li>
</ul>
+
<p>
Happy coding!
<hr>
--- /dev/null
+<!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
- 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>
</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
--- /dev/null
+<!-- @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 -->
--- /dev/null
+<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>
+++ /dev/null
-
-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
-
--- /dev/null
+<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
projects / aspectj.git / commitdiff