- initial J2EE samples (added support for XML/Ant scripts)

21 lat temu · 94cb789115
--- 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>
--- a/docs/sandbox/sandbox-api-test.xml
+++ 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>

 	
--- 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>

 -->
 	
--- a/docs/sandbox/scripts/precompile-jsp.build.xml
+++ 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 -->
--- a/docs/sandbox/trails/j2ee.html
+++ 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>
--- a/docs/sandbox/trails/j2ee.txt
+++ b/docs/sandbox/trails/j2ee.txt
@@ -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 

--- a/docs/sandbox/trails/myeclipseide.html
+++ 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>