[[PageOutline]] = JCop Manual = == Command Line Tools == In the following we describe the usage of the [wiki:JCop] language compiler that is able to compile programs of the JCop and Java programming language. The compiler implements the language as defined in the JCop language specification version 1.0. The language definition has continuously been revised to precisely specify the language including various corner cases and combinations of features. The compiler is an extension to the JastAddJ Java compiler that is implemented based on the [http://jastadd.org/JastAdd JastAdd compiler framework]. === Compile === ==== Synopsis ==== {{{jcopc [Options] [file]}}} ==== Description ==== The jcopc command compiles JCop and Java source, producing .class files compliant with any Java VM (1.1 or later). The argument after the options specifies the source file to compile. Source files are specified by their full qualified name (package name + type name), separated by a dot (".") (rather than a folder delimiter as for javac). ==== Options ==== {{{-classpath }}} Specify where to find user class files and annotation processors. {{{-sourcepath }}} Specify where to find input source files. Only required if the sources aren’t located in the working directory. [[BR]] Example: {{{ jcopc -sourcepath src myPckg.MyMainClass }}} {{{-d }}} Specify where to place generated class files. [[BR]] Example: {{{ jcopc -d bin -sourcepath src myPckg.MyMainClass }}} {{{-sourcedump }}} Dumps Java source files of the compiled classes into the specified folder. [[BR]] Example: {{{ jcopc -sourcedump dump myPckg.MyMainClass }}} {{{-agg }}} Generates a file containing an AGG graph representation of the program’s AST. [[BR]] Example: {{{ jcopc -agg output/agg myPckg.MyMainClass }}} {{{-ctl}}} Output JCop specific messages about what the compiler is doing. [[BR]] Example: {{{ jcopc -ctl myPckg.MyMainClass ... > copying PartialMethod.java > to src\jcop\lang > ..done ... > compiling:...src\de\uni_potsdam\hpi\swa\Widget.jcop ..done > compiling:jcop\lang\Composition.java ..done ... > ..done > compile and weave auxilliary aspect bin\jcop\lang\JCopAspect.aj > ..done > compiled in 3723 millis }}} {{{-rtl}}} Loggs layer activation and composition information at runtime. [[BR]] Example: {{{ jcopc -rtl myPckg.MyMainClass ... > INFO: accessing base method of getBMI > INFO: accessing method getBMI of layer Visualization ... }}} {{{-verbose}}} Output messages about what the compiler is doing {{{-help}}} Print a synopsis of standard options {{{-aspectinfo}}} Output messages about aspect weaving {{{-version}}} Print version information. {{{-xml-outline-path }}} Generate an outline in XML format (useful for development environments) {{{-class-in-layer-outline}}} Generate an outline in XML format (useful for development environments) ==== File Names ==== jcopc accepts source files with either the .java extension or the .jcop extension. ==== Underlying Java Command ==== If you encounter any problems using {{{jcopc}}}, you may use the plain Java command. For instance, the command {{{ jcopc -classpath bin -ctl MyApplication }}} is equivalent to {{{ java -jar -ea "%JCOP_HOME%\jcop.jar" -classpath bin -ctl MyApplication }}} === Launch === ==== Synopsis ==== {{{jcop [Options] class [ argument ]}}} ==== Description ==== The jcop command launches a JCop or Java application. It does this by starting a Java runtime environment (instrumented with the AspectJ weaver), loading a specified class, and invoking that class's main method. The method declaration must look like a plain Java main method: {{{ public static void main(String args[]) {...} }}} The method must be declared public and static, it must not return any value, and it must accept a String array as a parameter. By default, the first non-option argument is the name of the class to be invoked. A fully-qualified class name should be used. The argument after the options specifies the class file to compile and by its full qualified name (package name + type name), separated by a dot ("."). ==== Options ==== As options all standard Java options are allowed. [[BR]] '''If more than one classpath is specified, the entire classpath value must be quotet.''' Specifying one classpath: {{{ jcop -classpath bin Main }}} Specifying several classpaths: {{{ jcop -classpath "bin;lib\MyJar.jar" Main }}} ==== File Names ==== {{{jcop}}} accepts Java bytecode files with the {{{class}}} extension. ==== File Names ==== jcopc accepts source files with either the .java extension or the .jcop extension. ==== Underlying Java Command ==== If you encounter any problems using {{{jcop}}}, you may use the plain {{{java}}}command. For instance, the command {{{ jcop -classpath "bin;lib\mylib\" MyApplication }}} is equivalent to {{{ java -classpath "%JCOP_HOME%\aspectjweaver.jar;bin;lib\mylib\" "-Djava.system.class.loader=org.aspectj.weaver.loadtime.WeavingURLClassLoader" "-Daj.class.path=%ASPECTPATH%;%CLASSPATH%" "-Daj.aspect.path=%ASPECTPATH%" MyApplication }}} == Compiler API == The compiler can be executed programatically by invoking the compile method of jcop.compiler.JCopCompiler in the jcop.jar archive. All compiler arguments — including the name of the class to be compiled — must be passed to the String[] argument of this compile method. Note that key-value pairs are to separate elements of this string array. For example, the following command... {{{ jcopc -sourcepath D:\example\src -d D:\example\bin MyClass }}} ... can be executed calling: {{{ String[] args = new String[] {"-sourcepath", "D:\example\src", "-d", "D:\example\bin", "MyClass"}; jcop.compiler.JCopCompiler.compile(args); }}} == Restrictions and Limitations == === Restrictions to Plain Java Programs === In general, JCop is a superset of Java, thus any Java programs should be compilable and executable using JCop. However, the following limitations need to be considered for plain Java source code. ==== Primitives and Boxing in Java 5 ==== The underlying JastAddJ compiler is not able to perform type boxing in combination with generics. The following listing describes such an scenario. {{{ Vector bytecode = new Vector(); for(byte bc : bytecode) // this will compile but not run ... }}} The above code will compile, however, launching will cause a bytecode verification error similar to the following: {{{ Exception in thread "main" java.lang.VerifyError: (class: Test, method: signature: ()V) Register 2 contains wrong type Could not find the main class: Test. Program will exit. }}} As a workaround, we suggest to consistently use class types instead of primitives in such cases. {{{ Vector bytecode = new Vector();for(Byte bc : bytecode) ... }}} ==== Reserved Keywords ==== In addition to Java’s keywords, the following keywords are introduced by JCop and cannot be used as identifiers. This might require identifier renaming in existing Java programs. {{{after, before, call, context, layer, on, proceed, subject, with, without, when, ".." }}} === Limitations of the JCop Compiler === ==== Default Package ==== Layer declarations in classes of the default package are not supported, thus those classes must contain a package declaration. However, layer import and (de-)activation statements can be used in the default package. ==== Nested Class Support ==== Layers cannot be declared and activated within nested and anonymous classes, yet. {{{ public class MyClass { class MyInnerClass { void m() { ... } layer MyLayer{ ... } // this won’t work } void myMethod() { new MyNestedClass() { layer MyLayer { ... } // this won’t work } } }}} ==== Context Object Methods ==== Due to implementation details, context objects must not contain methods of the folloing signature: * {{{void initLayers()}}} * {{{boolean isActiveFor(String)}}} * {{{String jcop_name()}}} {{{jcop}}} accepts Java bytecode files with the {{{class}}} extension.