How to run a JAsCo AOP enabled application

There are three ways of running a JAsCo enabled application, either preprocess all beans to insert traps using the beanTransformer tool, or by employing the JAsCo HotSwap 1 or JAsCo HotSwap 2 implementations. The preprocess implementation has the advantage that it is highly portable and quite mature now. The JAsCo HotSwap 2 implementation requires a JVM 1.5+. Using the first generation HotSwap implementation is discouraged. When employing the JAsCo HotSwap 2, it is also possible to activate a third weaving approach, namely a real run-time weaver , inducing a huge performance gain.

Alternatives for running JAsCo:

• Preprocessor
• JAsCo HotSwap 1 (deprecated)
• JAsCo HotSwap 2

Running a JAsCo enabled application is very easy, just run as you would do without jasco, jasco does not require a special script or virtual machine to run! Dont forget to prepocess your application classes by employing the transformBean tool.

Some Hints:

• Make sure all the paths are added to your classpath as described by the installation instructions.
• Make sure . (the current directory) is in your classpath!

The following options can be set when running a jasco application. Just pass them along with your VM, e.g. java -Djasco.debug=true test.Main2.

• -Djasco.debug={true|false} : When true, JAsCo prints debugging information concering joinpoints encountered and which hooks are applicable at these points (default=false)

• -Djasco.output={normal|nowarnings|silent} : Sets the log level of JAsCo. (default=normal) (since version 0.5.0).

• -Djasco.connector.loadinterval=number: Defines the number of milliseconds the system waits for checking whether there are new connectors, or removed connectors. When number is 0, the connector searching disabled, so placing connectors in the classpath (or connectorpath if set) does not work anymore for dynamically adding aspects. The connectors are still loaded at startup time though. When the number is -1, connectors are never loaded automatically by the system. You can however still use the JAsCo API form within the application to register new connectors. (default=1000) (since version 0.4.2)

• -Djasco.connector.loadpriority=number: Defines the priority of the thread that searches for new/deleted connectors. Has to be between Thread.MIN_PRIORITY and Thread.MAX_PRIORITY, which is typically (depends on the OS) between 1 to 10. It is highly recommended to put the priority at least to Thread.NORM_PRIORITY, otherwise when other normal threads are active, the loading thread is not scheduled. The loading thread sleeps between successive searches (see jasco.connector.loadinterval option), so setting it to Thread.MAX_PRIORITY does not interfere with other threads too much. (default=Thread.NORM_PRIORITY) (since version 0.7.4)

• -Djasco.connector.loadpath=paths: Defines the paths where JAsCo searches for connector separated by ; on windows and : on linux, same synatx as classpath (e.g.: /var/test/boe:.. ). You might want to set this path when a large classpath is used in order to limit the paths JAsCo searches and thus decrease the performance overhead. (default=classpath) (since version 0.4.2)

• -Djasco.jutta={true|false} : Enables the experimental Jasco Jutta system that causes a huge performance gain. Still experimental, sometimes caches too much, disable if your application doesn’t seem to work as it should be. (default=true).

• -Djasco.jutta.cachesize=number : Sets the starting cache size for jutta. (default=10000)

• -Djasco.jutta.predefinedcache={true|false} : When true, uses a pre-installed set of combined aspect behavior when applicable. As such, for these combined behaviors no jit compilation is needed, which decreases the startup time. Highly recommended! (default=true)

The JAsCo HotSwap implementation allows to insert traps in only those methods that are subject of aspect application. When new aspects are added at run-time, all methods where the aspects are applicable upon, are hotswapped at run-time for a trapped version. Likewise, the orginal method is again installed when there is no aspect applicable any longer. As such, only those methods where aspects are applied upon are subject of a performance overhead!

Notice that HotSwap is complimentary with inserting traps by the beanTransformer pre-processer. If you’re certain that aspects are always applicable at specific classes, you can preprocess them beforehand, eliminating the HotSwap load-time overhead.

Drawbacks:

• Requires the application to run in debugging mode, causing a global overhead depending on the virtual machine.
• Only available for Sun’s JDK 1.4 or higher. (less portable)

How to run a JAsCo HotSwap application: java <regular java options> jasco.HotSwap <main class> <arguments>

Examples:

• java jasco.HotSwap test.Main2
• java jasco.HotSwap jacbench.Bench 5000 d
• java -Djasco.jutta=true -classpath temp;heteh jasco.HotSwap jacbench.Bench

All options available for running a JAsCo enabled application without HotSwap are also availabe with HotSwap. In addition, some other options are available for configuring hotswap:

• -Djasco.hotswap.replace.classloader={true|false} : When true, JAsCo replaces the standard classloader in order to be notified of class loading events. Otherwise, JAsCo employs the JDI debugging interface. The dedicated class loader is a lot faster (up to 40% overall performance gain), but might not work with some J2EE implementations and is not as stable yet. IF your application does not appaer to function, try disabling this option.(default=true)

• -Djasco.hotswap.tcpport=number: The TCP/IP port JAsCO employs to connect to the running VM, has to be availabe, otherwise the application fails! (default=8898)

• -Djasco.hotswap.suspend={true|false}: Suspends the JVM while hotswapping classes, the advantage is that the applied aspects are directly activated whereas otherwise, the JVM keeps running for a short while without traps (and thus aspects) applied untill the trapped methods are hotswapped. Disadvantage of suspending is that the application hangs for a while. (default=false)

• -Djasco.hotswap.trapall={true|false}: Per default, JAsCo hotswap only hotswaps public methods, which means that aspects cannot be applied at private methods. In order to enable traps at private methods, set the trapall property to true. (default=false) (since version 0.4.6)

• -Djasco.hotswap.optimize.loadtime={true|false}: Per default, JAsCo optimizes the trap insertion algorithm, which leads to +70% load time performance gain. Run-time performance is however descreased by 1-3%. (default=true) (since version 0.5.0)

• -Djasco.hotswap.excludedtypes=listoftypes: A list of types that is never hotswapped for a trapped version. This way, crucial system classes can be protected. Separated by : on linux and ; on windows. Wildcards are also supported, * macthes all symbols, so java.* macthes all classes which name starts with java.. Example listoftypes: java.*;sun.com.*;wsml.* Note: the wildcard (if used) is always at the end. (since version 0.5.0)

• -Djasco.hotswap.replaceexcludedtypes={true|false}: Per default, java.*, com.sun.*, sun.* and javax.* are included in the list of excluded types. If that cannot be the case, define a new set of excluded types using the previous flag and set this variable to true. Discouraged! If a new set of excluded types is defined and this option is false, than both sets are simply merged. (since version 0.5.0)

The troubleshooting guide contains additional information about possible problems and issues with HotSwap.

• Unswapping is only supported for full classes. This means that when aspects are removed, a class is only unswapped for its original when there is no aspect left that is applicable to one or more methods of that class. In the future, unswap on method level will be supported.
• Only the -classpath and -D Java VM arguments are supported with HotSwap.

The JAsCo HotSwap implementation allows to insert traps in only those methods that are subject of aspect application. When new aspects are added at run-time, all methods where the aspects are applicable upon, are hotswapped at run-time for a trapped version. Likewise, the orginal method is again installed when there is no aspect applicable any longer. As such, only those methods where aspects are applied upon are subject of a performance overhead!

The second generation JAsCo HotSwap implementation employs the instrumentation framework available in Java 1.5. This solution is technically superior to the previous HotSwap implementation and is thus the preferred way to run a JAsCo application. Furthermore, HotSwap 2 supports unswap on method level and all regular java VM options!

Notice that HotSwap is complimentary with inserting traps by the beanTransformer pre-processer. If you’re certain that aspects are always applicable at specific classes, you can preprocess them beforehand, eliminating the HotSwap load-time overhead.

Requires:

• JDK 1.5 !

How to run a JAsCo HotSwap 2 application: java -javaagent:<JAsCo installdir/jasco.jar> <regular java options including main class>

The jasco.jar file located in the root JAsCo installation directory has to be passed to the javaagent command switch!

Examples:

• java -javaagent:/home/test/jasco/jasco.jar test.Main2
• java -javaagent:E:\programs\JAsCo\jasco.jar jacbench.Bench 5000 d
• java -javaagent:..\..\jasco.jar -Djasco.jutta=true -classpath temp;/var/www/heteh jacbench.Bench

All options available for running a JAsCo enabled application without HotSwap are also availabe with HotSwap. In addition, some other options are available for configuring hotswap:

• -Djasco.hotswap.trapall={true|false}: Per default, JAsCo hotswap only hotswaps public methods, which means that aspects cannot be applied at private methods. In order to enable traps at private methods, set the trapall property to true. (default=false)

• -Djasco.hotswap.trapaspects={true|false}: Per default, JAsCo does not hotswap JAsCo aspects and as such no aspect on aspect application is possible. When this property is true, aspects are trapped as well and as such they are subject to aspect application. (default=false) (since version 0.8.0)

• -Djasco.hotswap.excludedtypes=listoftypes: A list of types that is never hotswapped for a trapped version. This way, crucial system classes can be protected. Separated by : on linux and ; on windows. Wildcards are also supported, * macthes all symbols, so java.* macthes all classes which name starts with java.. Example listoftypes: java.*;sun.com.*;wsml.* Note: the wildcard (if used) is always at the end.

• -Djasco.hotswap.replaceexcludedtypes={true|false}: Per default, java.*, com.sun.*, sun.* and javax.* are included in the list of excluded types. If that cannot be the case, define a new set of excluded types using the previous flag and set this variable to true. Discouraged! If a new set of excluded types is defined and this option is false, than both sets are simply merged.

• -Djasco.hotswap.inlinecompiler={true|false}: Enables the experimental run-time weaver, which induces a huge performance gain!. Not fully stable yet though. (default=false) (since JAsCo 0.7)

• -Djasco.hotswap.inlinecompiler.heuristics=FullClassNameOfHeuristics: Specifies a heuristics function that decides whether to use the run-time weaver or insert a trap. More info here . (since JAsCo 0.7)

• -Djasco.hotswap.applicationserver={true|false}: When JAsCo is used in a framework where a lot of different disjunct classloaders are employed ( like application servers), the optimized JAsCo system might have problems locating classes. Enable this property to run JAsCo in the slower compatibility mode and class loading should work fine again. Note: the inline compiler (run-time weaver) does not work when this property is enabled. (default=false) (since version 0.8.0)

The troubleshooting guide contains additional information about possible problems and issues with HotSwap.

NONE!