| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>ajc</title><link rel="stylesheet" href="aspectj-docs.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.44"><link rel="home" href="index.html" title="The AspectJtm Development Environment Guide"><link rel="up" href="command-line-tools.html#ajc-ref-top" title="ajc, the AspectJ compiler/weaver"><link rel="previous" href="command-line-tools.html" title="Chapter 2. AspectJ command-line tools"><link rel="next" href="ajdoc-ref-top.html" title="ajdoc, the AspectJ documentation tool"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">ajc</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="command-line-tools.html">Prev</a> </td><th width="60%" align="center"><tt>ajc</tt>, the AspectJ compiler/weaver</th><td width="20%" align="right"> <a accesskey="n" href="ajdoc-ref-top.html">Next</a></td></tr></table><hr></div><div class="refentry"><h1 class="title"><a name="ajc-ref"></a>ajc</h1><div class="refnamediv"><a name="d0e122"></a><h2>Name</h2>ajc — compiler and bytecode weaver for the AspectJ and Java languages</div><div class="refsynopsisdiv"><a name="d0e127"></a><h2>Synopsis</h2><div class="cmdsynopsis" id="d0e128"><a name="d0e128"></a><tt>ajc</tt> [<i><tt>Options</tt></i>] [<i><tt>file...</tt></i> | @<i><tt>file...</tt></i> | -argfile <i><tt>file...</tt></i>]</div></div><div class="refsect1"><a name="ajc"></a><h2>Description</h2><p>The <b>ajc</b> command compiles and weaves AspectJ and |
| Java source and .class files, producing .class files compliant with any |
| Java VM (1.1 or later). It combines compilation and bytecode weaving |
| and supports incremental builds; you can also weave bytecode |
| at run-time using <a href="ltw.html">Load-Time Weaving</a>. |
| </p><p> The arguments after the options specify the source file(s) to compile. |
| To specify source classes, use <i><tt>-inpath</tt></i> (below). |
| Files may be listed directly on the command line or in a file. |
| The <i><tt>-argfile <i><tt>file</tt></i></tt></i> |
| and <i><tt>@<i><tt>file</tt></i></tt></i> forms |
| are equivalent, and are interpreted as meaning all the arguments |
| listed in the specified file. |
| </p><p> |
| <b>Note:</b> |
| You must explicitly pass <b>ajc</b> all necessary sources. |
| Be sure to include the source not only for the |
| aspects or pointcuts but also for any affected types. |
| Specifying all sources is necessary because, unlike javac, ajc does not |
| search the sourcepath for classes. |
| (For a discussion of what affected types might be required, |
| see <a href="../progguide/implementation.html" target="_top">The AspectJ |
| Programming Guide, Implementation Appendix</a>.) |
| <p> |
| </p> |
| To specify sources, you can list source files as arguments or use the |
| options <i><tt>-sourceroots</tt></i> or <i><tt>-inpath</tt></i>. |
| If there are multiple sources for any type, the result is undefined |
| since ajc has no way to determine which source is correct. (This |
| happens most often when users include the destination directory |
| on the inpath and rebuild.) |
| </p><div class="refsect2"><a name="ajc_options"></a><h3>Options</h3><div class="variablelist"><dl><dt><a name="d0e195"></a><span class="term">-injars <i><tt>JarList</tt></i></span></dt><dd><p><a name="d0e200"></a> |
| deprecated: since 1.2, use -inpath, which also takes |
| directories. |
| </p></dd><dt><a name="d0e203"></a><span class="term">-inpath <i><tt>Path</tt></i></span></dt><dd><p><a name="d0e208"></a> |
| Accept as source bytecode any .class files in the |
| .jar files or directories on Path. |
| The output will include these |
| classes, possibly as woven with any applicable aspects. |
| Path is a single argument containing |
| a list of paths to zip files or directories, |
| delimited by the platform-specific path delimiter. |
| </p></dd><dt><a name="d0e211"></a><span class="term">-aspectpath <i><tt>Path</tt></i></span></dt><dd><p><a name="d0e216"></a> |
| Weave binary aspects from jar files and directories on path into all sources. |
| The aspects should have been output by the same version |
| of the compiler. |
| When running the output classes, the run classpath should contain |
| all aspectpath entries. |
| Path, like classpath, is a single argument containing |
| a list of paths to jar files, delimited by the platform- |
| specific classpath delimiter. |
| </p></dd><dt><a name="d0e219"></a><span class="term">-argfile <i><tt>File</tt></i></span></dt><dd><p><a name="d0e224"></a> |
| The file contains a line-delimited list of arguments. |
| Each line in the file should contain one option, filename, or |
| argument string (e.g., a classpath or inpath). |
| Arguments read from the file are inserted into the argument list |
| for the command. Relative paths in the file are calculated from |
| the directory containing the file (not the current working directory). |
| Comments, as in Java, start with <tt>//</tt> and |
| extend to the end of the line. Options specified in argument |
| files may override rather than extending existing option values, |
| so avoid specifying options like <i><tt>-classpath</tt></i> |
| in argument files unlike the argument file is the only build |
| specification. The form <i><tt>@file</tt></i> is the same |
| as specifying <i><tt>-argfile file</tt></i>. |
| </p></dd><dt><a name="d0e239"></a><span class="term">-outjar <i><tt>output.jar</tt></i></span></dt><dd><p><a name="d0e244"></a>Put output classes in zip file output.jar. |
| </p></dd><dt><a name="d0e247"></a><span class="term">-outxml</span></dt><dd><p><a name="d0e250"></a>Generate aop.xml file for load-time weaving with default name. |
| </p></dd><dt><a name="d0e253"></a><span class="term">-outxmlfile <i><tt>custom/aop.xml</tt></i></span></dt><dd><p><a name="d0e258"></a>Generate aop.xml file for load-time weaving with custom name. |
| </p></dd><dt><a name="d0e261"></a><span class="term">-incremental</span></dt><dd><p><a name="d0e264"></a>Run the compiler continuously. |
| After the initial compilation, the compiler will |
| wait to recompile until it reads a newline from the standard |
| input, and will quit when it reads a 'q'. |
| It will only recompile necessary components, so a recompile |
| should be much faster than doing a second compile. |
| This requires -sourceroots. |
| </p></dd><dt><a name="d0e267"></a><span class="term">-sourceroots <i><tt>DirPaths</tt></i></span></dt><dd><p><a name="d0e272"></a>Find and build all .java or .aj source files under |
| any directory listed in DirPaths. |
| DirPaths, like classpath, is a single argument containing |
| a list of paths to directories, delimited by the platform- |
| specific classpath delimiter. |
| Required by -incremental. |
| </p></dd><dt><a name="d0e275"></a><span class="term">-crossrefs</span></dt><dd><p><a name="d0e278"></a> |
| Generate a build .ajsym file into the output directory. Used for |
| viewing crosscutting references by tools like the AspectJ |
| Browser. |
| </p></dd><dt><a name="d0e281"></a><span class="term">-emacssym</span></dt><dd><p><a name="d0e284"></a> |
| Generate .ajesym symbol files for emacs support (deprecated). |
| </p></dd><dt><a name="d0e287"></a><span class="term">-Xlint</span></dt><dd><p><a name="d0e290"></a>Same as -Xlint:warning (enabled by default) |
| </p></dd><dt><a name="d0e293"></a><span class="term">-Xlint:{level}</span></dt><dd><p><a name="d0e296"></a>Set default level for messages about potential |
| programming mistakes in crosscutting code. |
| {level} may be ignore, warning, or error. |
| This overrides entries in |
| org/aspectj/weaver/XlintDefault.properties |
| from aspectjtools.jar, but does not override levels set |
| using the -Xlintfile option. |
| </p></dd><dt><a name="d0e299"></a><span class="term">-Xlintfile <i><tt>PropertyFile</tt></i></span></dt><dd><p><a name="d0e304"></a>Specify properties file to set levels for |
| specific crosscutting messages. |
| PropertyFile is a path to a Java .properties file that |
| takes the same property names and values as |
| org/aspectj/weaver/XlintDefault.properties |
| from aspectjtools.jar, which it also overrides. |
| </p></dd><dt><a name="d0e307"></a><span class="term">-help</span></dt><dd><p><a name="d0e310"></a> |
| Emit information on compiler options and usage |
| </p></dd><dt><a name="d0e313"></a><span class="term">-version</span></dt><dd><p><a name="d0e316"></a> |
| Emit the version of the AspectJ compiler |
| </p></dd><dt><a name="d0e319"></a><span class="term">-classpath <i><tt>Path</tt></i></span></dt><dd><p><a name="d0e324"></a> |
| Specify where to find user class files. |
| Path is a single argument containing |
| a list of paths to zip files or directories, |
| delimited by the platform-specific path delimiter. |
| </p></dd><dt><a name="d0e327"></a><span class="term">-bootclasspath <i><tt>Path</tt></i></span></dt><dd><p><a name="d0e332"></a> |
| Override location of VM's bootclasspath |
| for purposes of evaluating types when compiling. |
| Path is a single argument containing |
| a list of paths to zip files or directories, |
| delimited by the platform-specific path delimiter. |
| </p></dd><dt><a name="d0e335"></a><span class="term">-extdirs <i><tt>Path</tt></i></span></dt><dd><p><a name="d0e340"></a> |
| Override location of VM's extension directories |
| for purposes of evaluating types when compiling. |
| Path is a single argument containing |
| a list of paths to directories, |
| delimited by the platform-specific path delimiter. |
| </p></dd><dt><a name="d0e343"></a><span class="term">-d <i><tt>Directory</tt></i></span></dt><dd><p><a name="d0e348"></a> |
| Specify where to place generated .class files. |
| If not specified, <i><tt>Directory</tt></i> |
| defaults to the current working dir. |
| </p></dd><dt><a name="d0e354"></a><span class="term">-target <i><tt>[1.1 to 1.5]</tt></i></span></dt><dd><p><a name="d0e359"></a>Specify classfile target setting (1.1 to 1.5, default is 1.2) |
| </p></dd><dt><a name="d0e362"></a><span class="term">-1.3</span></dt><dd><p><a name="d0e365"></a>Set compliance level to 1.3 |
| This implies -source 1.3 and -target 1.1. |
| </p></dd><dt><a name="d0e368"></a><span class="term">-1.4</span></dt><dd><p><a name="d0e371"></a>Set compliance level to 1.4 (default) |
| This implies -source 1.4 and -target 1.2. |
| </p></dd><dt><a name="d0e374"></a><span class="term">-1.5</span></dt><dd><p><a name="d0e377"></a>Set compliance level to 1.5. |
| This implies -source 1.5 and -target 1.5. |
| </p></dd><dt><a name="d0e380"></a><span class="term">-source <i><tt>[1.3|1.4|1.5]</tt></i></span></dt><dd><p><a name="d0e385"></a>Toggle assertions (1.3, 1.4, or 1.5 - default is 1.4). |
| When using -source 1.3, an assert() statement valid under |
| Java 1.4 will result in a compiler error. |
| When using -source 1.4, |
| treat <tt>assert</tt> as a keyword and |
| implement assertions according to the 1.4 language spec. |
| When using -source 1.5, |
| Java 5 language features are permitted. |
| </p></dd><dt><a name="d0e391"></a><span class="term">-nowarn</span></dt><dd><p><a name="d0e394"></a>Emit no warnings (equivalent to '-warn:none') |
| This does not suppress messages |
| generated by <tt>declare warning</tt> or |
| <tt>Xlint</tt>. |
| </p></dd><dt><a name="d0e403"></a><span class="term">-warn: <i><tt>items</tt></i></span></dt><dd><p><a name="d0e408"></a>Emit warnings for any instances of |
| the comma-delimited list of questionable code |
| (eg '-warn:unusedLocals,deprecation'): |
| <pre class="programlisting"> |
| constructorName method with constructor name |
| packageDefaultMethod attempt to override package-default method |
| deprecation usage of deprecated type or member |
| maskedCatchBlocks hidden catch block |
| unusedLocals local variable never read |
| unusedArguments method argument never read |
| unusedImports import statement not used by code in file |
| none suppress all compiler warnings |
| </pre> |
| <tt>-warn:none</tt> does not suppress messages |
| generated by <tt>declare warning</tt> or |
| <tt>Xlint</tt>. |
| |
| </p></dd><dt><a name="d0e424"></a><span class="term">-deprecation</span></dt><dd><p><a name="d0e427"></a>Same as -warn:deprecation |
| </p></dd><dt><a name="d0e430"></a><span class="term">-noImportError</span></dt><dd><p><a name="d0e433"></a>Emit no errors for unresolved imports |
| </p></dd><dt><a name="d0e436"></a><span class="term">-proceedOnError</span></dt><dd><p><a name="d0e439"></a>Keep compiling after error, |
| dumping class files with problem methods |
| </p></dd><dt><a name="d0e442"></a><span class="term">-g<i><tt>:[lines,vars,source]</tt></i></span></dt><dd><p><a name="d0e447"></a>debug attributes level, that may take three forms: |
| <pre class="programlisting"> |
| -g all debug info ('-g:lines,vars,source') |
| -g:none no debug info |
| -g:{items} debug info for any/all of [lines, vars, source], e.g., |
| -g:lines,source |
| </pre> |
| |
| </p></dd><dt><a name="d0e453"></a><span class="term">-preserveAllLocals</span></dt><dd><p><a name="d0e456"></a>Preserve all local variables during code generation |
| (to facilitate debugging). |
| </p></dd><dt><a name="d0e459"></a><span class="term">-referenceInfo</span></dt><dd><p><a name="d0e462"></a>Compute reference information. |
| </p></dd><dt><a name="d0e465"></a><span class="term">-encoding <i><tt>format</tt></i></span></dt><dd><p><a name="d0e470"></a>Specify default source encoding format. |
| Specify custom encoding on a per file basis by suffixing |
| each input source file/folder name with '[encoding]'. |
| </p></dd><dt><a name="d0e473"></a><span class="term">-verbose</span></dt><dd><p><a name="d0e476"></a>Emit messages about accessed/processed compilation units |
| </p></dd><dt><a name="d0e479"></a><span class="term">-showWeaveInfo</span></dt><dd><p><a name="d0e482"></a>Emit messages about weaving |
| </p></dd><dt><a name="d0e485"></a><span class="term">-log <i><tt>file</tt></i></span></dt><dd><p><a name="d0e490"></a>Specify a log file for compiler messages. |
| </p></dd><dt><a name="d0e493"></a><span class="term">-progress</span></dt><dd><p><a name="d0e496"></a>Show progress (requires -log mode). |
| </p></dd><dt><a name="d0e499"></a><span class="term">-time</span></dt><dd><p><a name="d0e502"></a>Display speed information. |
| </p></dd><dt><a name="d0e505"></a><span class="term">-noExit</span></dt><dd><p><a name="d0e508"></a>Do not call System.exit(n) at end of compilation |
| (n=0 if no error) |
| </p></dd><dt><a name="d0e511"></a><span class="term">-repeat <i><tt>N</tt></i></span></dt><dd><p><a name="d0e516"></a>Repeat compilation process N times |
| (typically to do performance analysis). |
| </p></dd><dt><a name="d0e519"></a><span class="term">-XterminateAfterCompilation</span></dt><dd><p><a name="d0e522"></a>Causes compiler to terminate before weaving |
| </p></dd><dt><a name="d0e525"></a><span class="term">-XaddSerialVersionUID</span></dt><dd><p><a name="d0e528"></a>Causes the compiler to calculate and add |
| the SerialVersionUID field to any type implementing |
| Serializable that is affected by an aspect. The field |
| is calculated based on the class before weaving has |
| taken place. |
| </p></dd><dt><a name="d0e531"></a><span class="term">-Xreweavable[:compress]</span></dt><dd><p><a name="d0e534"></a>(Experimental - deprecated as now default) |
| Runs weaver in reweavable mode which causes |
| it to create woven classes that can be rewoven, subject to the restriction that |
| on attempting a reweave all the types that advised the woven type must be accessible. |
| </p></dd><dt><a name="d0e537"></a><span class="term">-XnoInline</span></dt><dd><p><a name="d0e540"></a>(Experimental) do not inline around advice |
| </p></dd><dt><a name="d0e543"></a><span class="term">-XincrementalFile <i><tt>file</tt></i></span></dt><dd><p><a name="d0e548"></a>(Experimental) This works like incremental mode, |
| but using a file rather than standard input to control the compiler. |
| It will recompile each time file is changed and |
| and halt when file is deleted. |
| </p></dd><dt><a name="d0e551"></a><span class="term">-XserializableAspects</span></dt><dd><p><a name="d0e554"></a> |
| (Experimental) Normally it is an error to declare |
| aspects Serializable. This option removes that restriction. |
| </p></dd><dt><a name="d0e557"></a><span class="term">-XnotReweavable</span></dt><dd><p><a name="d0e560"></a> |
| (Experimental) Create class files that can't be subsequently rewoven by AspectJ. |
| </p></dd><dt><a name="d0e565"></a><span class="term">-Xajruntimelevel:1.2, ajruntimelevel:1.5</span></dt><dd><p><a name="d0e568"></a> |
| (Experimental) Allows code to be generated that targets a 1.2 or a 1.5 level AspectJ runtime (default 1.5) |
| </p></dd></dl></div></div><div class="refsect2"><a name="d0e571"></a><h3>File names</h3><p>ajc accepts source files with either the <tt>.java</tt> |
| extension or the <tt>.aj</tt> extension. We normally use |
| <tt>.java</tt> for all of our files in an AspectJ system -- files |
| that contain aspects as well as files that contain classes. However, if |
| you have a need to mechanically distinguish files that use AspectJ's |
| additional functionality from those that are pure Java we recommend using |
| the <tt>.aj</tt> extension for those files.</p><p>We'd like to discourage other means of mechanical distinction such as |
| naming conventions or sub-packages in favor of the <tt>.aj</tt> |
| extension.</p><div class="itemizedlist"><ul><li><p><a name="d0e594"></a>Filename conventions are hard to enforce and lead to awkward names |
| for your aspects. Instead of <tt>TracingAspect.java</tt> we |
| recommend using <tt>Tracing.aj</tt> (or just |
| <tt>Tracing.java</tt>) instead.</p></li><li><p><a name="d0e606"></a>Sub-packages move aspects out of their natural place in a system |
| and can create an artificial need for privileged aspects. Instead of |
| adding a sub-package like <tt>aspects</tt> we recommend using the |
| <tt>.aj</tt> extension and including these files in your existing |
| packages instead.</p></li></ul></div></div><div class="refsect2"><a name="d0e615"></a><h3>Compatibility</h3><p> |
| AspectJ is a compatible extension to the Java programming language. The |
| AspectJ compiler adheres to the <a href="http://java.sun.com/docs/books/jls/index.html" target="_top"> <i>The Java Language Specfication, Second |
| Edition</i></a> and to the <a href="http://java.sun.com/docs/books/vmspec/index.html" target="_top"><i>The Java Virtual Machine Specification, Second |
| Edition</i></a> and runs on any Java 2 compatible |
| platform. The code it generates runs on any Java 1.1 or later |
| compatible platform. |
| For more information on compatibility with |
| Java and with previous releases of AspectJ, |
| see |
| <a href="compatibility.html#versionCompatibility">AspectJ Version Compatibility</a>. |
| </p></div><div class="refsect2"><a name="d0e631"></a><h3>Examples</h3><div class="example"><p><a name="simpleexample"></a><b>Example 2.1. A simple example</b></p><p>Compile two files:</p><pre class="programlisting"> |
| ajc HelloWorld.java Trace.java |
| </pre></div><div class="example"><p><a name="exampleusingargfile"></a><b>Example 2.2. An example using -argfile/@</b></p><p> |
| To avoid specifying file names on the command line, |
| list source files in a line-delimited text argfile. |
| Source file paths may be absolute or relative to the argfile, |
| and may include other argfiles by @-reference. |
| The following file <tt>sources.lst</tt> |
| contains absolute and relative files and @-references: |
| </p><pre class="programlisting"> |
| Gui.java |
| /home/user/src/Library.java |
| data/Repository.java |
| data/Access.java |
| @../../common/common.lst |
| @/home/user/src/lib.lst |
| view/body/ArrayView.java</pre><p>Compile the files using either the -argfile or @ form:</p><pre class="programlisting"> |
| ajc -argfile sources.lst |
| ajc @sources.lst</pre><p> |
| Argfiles are also supported by jikes and javac, so you |
| can use the files in hybrid builds. However, the support varies: |
| </p><div class="itemizedlist"><ul><li><p><a name="d0e658"></a>Only ajc accepts command-line options</p></li><li><p><a name="d0e661"></a>Jikes and Javac do not accept internal @argfile references. |
| </p></li><li><p><a name="d0e664"></a>Jikes and Javac only accept the @file form on the command line.</p></li></ul></div></div><div class="example"><p><a name="examplebytecode"></a><b>Example 2.3. An example using -inpath and -aspectpath</b></p><p>Bytecode weaving using -inpath: |
| AspectJ 1.2 supports weaving .class files in input zip/jar files |
| and directories. |
| Using input jars is like compiling the corresponding |
| source files, and all binaries are emitted to output. Although |
| Java-compliant compilers may differ in their output, ajc should |
| take as input any class files produced by javac, jikes, eclipse, |
| and, of course, ajc. Aspects included in -inpath will be woven into |
| like other .class files, and they will affect other types as usual. |
| </p><p>Aspect libraries using -aspectpath: |
| AspectJ 1.1 supports weaving from read-only libraries containing |
| aspects. Like input jars, they affect all input; unlike input |
| jars, they themselves are not affected or emitted as output. |
| Sources compiled with aspect libraries must be run with the same |
| aspect libraries on their classpath. |
| </p><p>The following example builds the tracing example in a |
| command-line environment; it creates a read-only aspect library, |
| compiles some classes for use as input bytecode, and |
| compiles the classes and other sources with the aspect library. |
| </p><p>The tracing example is in the AspectJ distribution |
| ({aspectj}/doc/examples/tracing). This uses the following files: |
| </p><p><pre class="programlisting"> |
| aspectj1.1/ |
| bin/ |
| ajc |
| lib/ |
| aspectjrt.jar |
| examples/ |
| tracing/ |
| Circle.java |
| ExampleMain.java |
| lib/ |
| AbstractTrace.java |
| TraceMyClasses.java |
| notrace.lst |
| Square.java |
| tracelib.lst |
| tracev3.lst |
| TwoDShape.java |
| version3/ |
| Trace.java |
| TraceMyClasses.java |
| </pre></p><p>Below, the path separator is taken as ";", but file separators |
| are "/". All commands are on one line. Adjust paths and |
| commands to your environment as needed. |
| |
| </p><p>Setup the path, classpath, and current directory:</p><pre class="programlisting"> |
| cd examples |
| export ajrt=../lib/aspectjrt.jar |
| export CLASSPATH="$ajrt" |
| export PATH="../bin:$PATH" |
| </pre><p>Build a read-only tracing library:</p><pre class="programlisting"> |
| ajc -argfile tracing/tracelib.lst -outjar tracelib.jar |
| </pre><p>Build the application with tracing in one step:</p><pre class="programlisting"> |
| ajc -aspectpath tracelib.jar -argfile tracing/notrace.lst -outjar tracedapp.jar |
| </pre><p>Run the application with tracing:</p><pre class="programlisting"> |
| java -classpath "$ajrt;tracedapp.jar;tracelib.jar" tracing.ExampleMain |
| </pre><p>Build the application with tracing from binaries in two steps:</p><div class="itemizedlist"><ul><li><p><a name="d0e702"></a> |
| (a) Build the application classes (using javac for demonstration's sake):</p><pre class="programlisting"> |
| mkdir classes |
| javac -d classes tracing/*.java |
| jar cfM app.jar -C classes . |
| </pre></li><li><p><a name="d0e707"></a> |
| (b) Build the application with tracing:</p><pre class="programlisting"> |
| ajc -inpath app.jar -aspectpath tracelib.jar -outjar tracedapp.jar |
| </pre></li></ul></div><p>Run the application with tracing (same as above):</p><pre class="programlisting"> |
| java -classpath "$ajrt;tracedapp.jar;tracelib.jar" tracing.ExampleMain |
| </pre><p>Run the application without tracing:</p><pre class="programlisting"> |
| java -classpath "app.jar" tracing.ExampleMain |
| </pre></div></div><div class="refsect2"><a name="d0e720"></a><h3>The AspectJ compiler API</h3><p>The AspectJ compiler is implemented completely in Java and can be |
| called as a Java class. The only interface that should be considered |
| public are the public methods in <tt>org.aspectj.tools.ajc.Main</tt>. |
| E.g., <tt>main(String[] args)</tt> takes the |
| the standard <b>ajc</b> command line arguments. |
| This means that an alternative way to run the |
| compiler is </p><div class="cmdsynopsis" id="d0e734"><a name="d0e734"></a><tt><tt>java org.aspectj.tools.ajc.Main</tt></tt> [<i><tt>option...</tt></i>] [<i><tt>file...</tt></i>]</div><p>To access compiler messages programmatically, use the methods |
| <tt>setHolder(IMessageHolder holder)</tt> and/or |
| <tt>run(String[] args, IMessageHolder holder)</tt>. |
| <tt>ajc</tt> reports each message to the holder |
| using <tt>IMessageHolder.handleMessage(..)</tt>. |
| If you just want to collect the messages, use |
| <tt>MessageHandler</tt> as your |
| <tt>IMessageHolder</tt>. |
| For example, compile and run the following with |
| <tt>aspectjtools.jar</tt> on the classpath: |
| </p><pre class="programlisting"> |
| import org.aspectj.bridge.*; |
| import org.aspectj.tools.ajc.Main; |
| import java.util.Arrays; |
| |
| public class WrapAjc { |
| public static void main(String[] args) { |
| Main compiler = new Main(); |
| MessageHandler m = new MessageHandler(); |
| compiler.run(args, m); |
| IMessage[] ms = m.getMessages(null, true); |
| System.out.println("messages: " + Arrays.asList(ms)); |
| } |
| } |
| </pre></div><div class="refsect2"><a name="d0e769"></a><h3>Stack Traces and the SourceFile attribute</h3><p>Unlike traditional java compilers, the AspectJ compiler may in |
| certain cases generate classfiles from multiple source files. |
| Unfortunately, the original Java class file format does not support |
| multiple |
| SourceFile attributes. In order to make sure all source file |
| information is available, the AspectJ compiler may in some cases |
| encode multiple filenames in the SourceFile attribute. |
| When the Java VM generates stack traces, it uses this attribute |
| to specify the source file. |
| </p><p>(The AspectJ 1.0 compiler also supports the .class file extensions of JSR-45. |
| These permit compliant debuggers (such as jdb in Java 1.4.1) to identify |
| the right file and line even given many source files for a single class. |
| JSR-45 support is planned for ajc in AspectJ 1.1, but is not in the initial |
| release. To get fully debuggable .class files, use the -XnoInline option.) |
| </p><p>Probably the only time you may see this format is when you view |
| stack traces, where you may encounter traces of the format |
| </p><pre class="programlisting"> |
| java.lang.NullPointerException |
| at Main.new$constructor_call37(Main.java;SynchAspect.java[1k]:1030) |
| </pre><p>where instead of the usual |
| </p><pre class="programlisting"> |
| File:LineNumber |
| </pre><p>format, you see |
| </p><pre class="programlisting"> |
| File0;File1[Number1];File2[Number2] ... :LineNumber |
| </pre><p>In this case, LineNumber is the usual offset in lines plus the |
| "start line" of the actual source file. That means you use LineNumber |
| both to identify the source file and to find the line at issue. |
| The number in [brackets] after each file tells you the |
| virtual "start line" for that file (the first file has a start of 0). |
| </p><p> In our example from the null pointer exception trace, |
| the virtual start line is 1030. Since the file SynchAspect.java |
| "starts" at line 1000 [1k], the LineNumber points to line 30 of |
| SynchAspect.java. |
| </p><p> So, when faced with such stack traces, the way to find the actual |
| source location is to look through the list of "start line" numbers to |
| find the one just under the shown line number. That is the file where |
| the source location can actually be found. Then, subtract that "start |
| line" from the shown line number to find the actual line number within |
| that file. |
| </p><p>In a class file that comes from only a single source file, the AspectJ |
| compiler generates SourceFile attributes consistent with |
| traditional Java compilers. |
| </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="command-line-tools.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="ajdoc-ref-top.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 2. AspectJ command-line tools </td><td width="20%" align="center"><a accesskey="u" href="command-line-tools.html#ajc-ref-top">Up</a></td><td width="40%" align="right"> <tt>ajdoc</tt>, the AspectJ documentation tool</td></tr></table></div></body></html> |
