This tutorial will take you through deployment of the JEXIN web application and development of a simple application that uses JEXIN.
The first step is to deploy jexin.war (Tomcat 6 was used for testing). If deployed to a server on localhost port 8080 then http://localhost:8080/jexin will take you to the nodes page which is the entry point for the application. If you want to use the included example web application you should also deploy jexin-example.war (http://localhost:8080/jexin-example).
To use JEXIN in your application you have to include jexin-[version].jar and aspectjrt.jar. JEXIN uses AspectJ to create stack traces by intercepting method calls. Test builds should use the AspectJ compiler which will weave the TraceAspect aspect into your application. Production builds should use the standard Java compiler to eliminate any impact by JEXIN on production code. There is an alternative to this if you require AspectJ in your production builds for other purposes which will be explained later in this document. If you are using Ant you can use the iajc task instead of javac. The iajc task is defined in aspectjtools.jar. Here is an example excerpt from an Ant build that uses iajc or javac depending on whether the "production" property is set:
<target name="iajc-compile" unless="production" description="Compiles sources using iajc">
<taskdef resource="org/aspectj/tools/ant/taskdefs/aspectjTaskdefs.properties">
<classpath>
<pathelement location="${lib}/aspectjtools.jar" />
</classpath>
</taskdef>
<iajc srcdir="${src}" destdir="${classes}" source="1.5">
<classpath refid="jars" />
</iajc>
</target>
<target name="javac-compile" if="production" description="Compiles sources using javac">
<javac srcdir="${src}" destdir="${classes}">
<classpath refid="jars" />
<classpath refid="nodeploy-jars" />
</javac>
</target>
An instance of TraceServer must be instantiated for the JEXIN web application to communicate with. The example application uses a ServletContextListener (TraceServerLoaderListener) to configure the TraceServer. Details of the configuration options and an example Spring configuration of TraceServer are in the User's Guide. The exceptions that may be injected are defined in the TraceServe configuration. Each exception has an associated ID and description all contained in an InjectableException. The example web application creates 2 InjectableExceptions:
injectableExceptions.add(new InjectableException(
InjectableExceptionConstants.RUNTIME_EXCEPTION,
"A runtime exception",
new RuntimeException()));
injectableExceptions.add(new InjectableException(
InjectableExceptionConstants.SERVICE_EXCEPTION,
"A service exception",
new RuntimeException()));
If you want to have aspects weaved into production builds you may remove the JEXIN overhead by simply not instantiating
the TraceServer. The advice applied to the intercepted methods will be reduced to the equivalent of a single 'if
(traceServer != null)' statement before and after each method invocation.
The methods included in the JEXIN stack trace are identified by the Traceable annotation. Any InjectableException configured in the TraceServer may be injected into any Traceable method. The injectableExceptions property of the Traceable annotation allows the developer to identify those exceptions that are more likely to be thrown by the method. Those exceptions will be identified to the JEXIN web application user.
The example web application is a very simply blog implementation. The user adds an entry and the list of entries is displayed with a time stamp for each entry. To monitor the example application with JEXIN: