How to Run JBoss Jandex

Jandex is a tool that processes Java annotations within a directory or jar file, and saves the resulting metadata in an index file. This is similar to what a jar file index is to a classloader.

There are 3 ways to run jandex tool:

  1. java -jar command
  2. ant task
  3. jandex maven plugin
In JBoss AS7, jandex jar is located at $JBOSS_HOME/modules/org/jboss/jandex/main/jandex-1.0.3.Final.jar

To display the usage message,
java -jar jandex-1.0.3.Final.jar

Usage: jandex [-v] [-m] [-o file-name] <directory> | <jar>
jandex [-d] <index-file-name>
-v verbose output
-m modify directory or jar instead of creating an external index file
-o name the external index file file-name
-d dump the index file index-file-name

The default behavior, with no options specified, is to autogenerate an external index file

To scan a WAR file, adding the result to WAR's META-INF/jandex.idx (not WEB-INF/jandex.idx):
java -jar jandex-1.0.3.Final.jar -v -m /tmp/test.war

Indexed test.TestBean (2 annotations)
Indexed test.TestIF (0 annotations)
Indexed test.TestServlet (2 annotations)
Wrote META-INF/jandex.idx in 0.0710 seconds (3 classes, 4 annotations, 4 instances, 257 bytes)

To scan a WAR file and put result in the default result file in the same directory as the WAR file:
java -jar jandex-1.0.3.Final.jar /tmp/test.war

Wrote /tmp/test.war.idx in 0.0280 seconds (3 classes, 4 annotations, 4 instances, 257 bytes)

To view the content of an index file:
java -jar jandex-1.0.3.Final.jar -d /tmp/test.war.idx

Class: test.TestBean
Field: test.TestIF test.TestServlet.testBean
Class: test.TestBean
(value = [test.TestIF])
Class: test.TestServlet
(urlPatterns = ["/*"])

Read test.war.idx in 0.0030 seconds

To scan a directory and save the result in a custom output file (-o option currently does not work with jar file input):
java -jar jandex-1.0.3.Final.jar -v -o /tmp/ann.dat $HOME/ws/test/

Indexed test.TestBean (2 annotations)
Indexed test.TestIF (0 annotations)
Indexed test.TestServlet (2 annotations)
Wrote /tmp/ann.dat in 0.0180 seconds (3 classes, 4 annotations, 4 instances, 257 bytes)

jandex.jar comes with an ant task, org/jboss/jandex/JandexAntTask. To run jandex with ant, first create a build.xml:
<?xml version="1.0"?>
<project name="test" default="jandex.modify" basedir=".">
<property environment="env" />
<taskdef name="jandex" classname="org.jboss.jandex.JandexAntTask"
classpath="${env.JBOSS_HOME}/modules/org/jboss/jandex/main/jandex-1.0.3.Final.jar" />

<target name="jandex.modify">
<jandex run="true" verbose="true" modify="true">
<fileset dir="${env.HOME}/ws/test" />

<target name="jandex.newjar">
<jandex run="true" verbose="true" newJar="true">
<fileset dir="${env.HOME}/ws/test" />
To process all "*.jar" files within a directory (recursively, adding the index file to the original jar:

ant jandex.modify

To process all "*.jar" files within a directory (recursively), and create a new index jar file (a jar file that only contains the generated index: META-INF/jandex.idx) for each source jar:

ant jandex.newjar

JandexAntTask (at least this version) filters on file name "*.jar", so any other types of jar files (*.war, *.ear, *.rar, etc) will not be included.

Jandex maven plugin project page has all the source and usages. With this plugin, jandex processes application annotations directly at build time, instead of post-processing the archives as in the 2 other methods. I tried the basic usage by copying the plugin element to one of the quickstart project pom.xml. After running mvn clean install, I can see the console output showing jandex being invoked as part of process-classes phase:
[INFO] --- jandex-maven-plugin:1.0.1:jandex (make-index) @ jboss-as-ejb-in-war ---
[INFO] --- maven-resources-plugin:2.4.3:testResources (default-testResources) @ jboss-as-ejb-in-war ---
[INFO] Using 'UTF-8' encoding to copy filtered resources.
To verify the index has been generated into target/classes and packaged into war file:
ls -l target/classes/META-INF/jandex.idx

jar tvf target/jboss-as-ejb-in-war.war | grep jandex

289 Tue Aug 28 10:09:40 EDT 2012 WEB-INF/classes/META-INF/jandex.idx
In the above output jandex.idx seems to have been packaged into the wrong directory inside the WAR. It should be in META-INF/jandex.idx. Could be a bug in jandex plugin?

Jandex can be used on jars or directories of any java application classes or libraries. For instance, the following command runs jandex on JDK classes.jar:
sudo java -jar jandex-1.0.3.Final.jar $JAVA_HOME/../Classes/classes.jar

Wrote /System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home/../Classes/classes-jar.idx
in 2.4900 seconds (20723 classes, 36 annotations, 1381 instances, 678046 bytes)

ls -l $JAVA_HOME/../Classes/*idx
-rw-r--r-- 1 root wheel 678046 Aug 28 10:45 /System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home/../Classes/classes-jar.idx


My JBoss AS7 jboss-cli Notes

To start standalone server with the default server config (standalone.xml):

To start standalone server on custom, non-default port numbers, using offset=1, 2, 3, etc (negative offset number is invalid).  When starting with offset 1, you will have http port number 8081 (the default 8080+1), CLI port number 10000 (the default 9999+1), admin console port 9991 (the default 9990+1), etc.
standalone.sh -Djboss.socket.binding.port-offset=1

To start standalone server with a specific server config (just the config file name in $JBOSS_HOME/standalone/configuration directory, do not specify its file path):

standalone.sh -c standalone-full.xml
standalone.sh --server-config=standalone-ha.xml
standalone.sh --server-config standalone-full-ha.xml

To avoid/disable "Press any key to continue..." when running JBoss AS7 commands on Windows:
> set NOPAUSE=true
> standalone
> jboss-cli

To start standalone server in debug mode at default debug port 8787, or at a different port, e.g., 6000:
standalone.sh --debug
standalone.sh -d
standalone.sh -d 6000
standalone.sh --debug 6000

To start domain:

To save the PID from AS process, define the environment variable JBOSS_PIDFILE and LAUNCH_JBOSS_IN_BACKGROUND:

To stop the default standalone server or domain, with :shutdown operation request (there is no shutdown command):
jboss-cli.sh --connect --command=:shutdown
jboss-cli.sh -c "/:shutdown()"
jboss-cli.sh -c /:shutdown
jboss-cli.sh -c :shutdown

To restart
jboss-cli.sh -c ":shutdown(restart=true)"

To stop the standalone server right now no matter what. If the server is running, it has the same effect as Ctrl-C. If the server is not running, $JBOSS_PIDFILE is not present and so nothing is done.
/bin/kill -9 `cat $JBOSS_PIDFILE`

To exit from the shell started with jboss-cli.sh, use any of the following (Ctrl-D does not work, though):
[standalone@localhost:9999 /] Ctrl-C
[standalone@localhost:9999 /] exit
[standalone@localhost:9999 /] quit
[standalone@localhost:9999 /] q

To list all deployed applications, with either deploy or undeploy command (-l option gives more details about the deployed applications):
jboss-cli.sh -c deploy
jboss-cli.sh -c undeploy

jboss-cli.sh -c "ls deployment"
jboss-cli.sh -c "deploy -l"
jboss-cli.sh -c "undeploy -l"

To deploy an application:
jboss-cli.sh -c "deploy $HOME/tmp/hello.war"

To redeploy (forcefully overwrite any existing deployed app) an app:
jboss-cli.sh -c "deploy --force $HOME/tmp/hello.war"

To undeploy an application:
jboss-cli.sh -c "undeploy hello.war"

To get CLI help info:
jboss-cli.sh help
jboss-cli.sh -c help

To show help info for deploy command:
jboss-cli.sh -c "deploy --help"

To display the version of the current running JBoss AS, along with $JBOSS_HOME, $JAVA_HOME, java.version, os.name, os.version, etc:
jboss-cli.sh -c version

To create a string or primitive JNDI resource. Do not quote the value attribute, otherwise the quote will become part of the content. Also need to escape whitespace.
jboss-cli.sh -c "/subsystem=naming/binding=java\:global\/env\/flag:add(binding-type=simple, type=boolean, value=true)"

jboss-cli.sh -c "/subsystem=naming/binding=java\:global\/env\/text:add(binding-type=simple, type=java.lang.String, value=This\ is\ a\ text\ value.)"

To create an alias for a JNDI resource (java:global/env/condition is an alias for java:global/env/flag):
jboss-cli.sh -c "/subsystem=naming/binding=java\:global\/env\/condition:add(binding-type=lookup, lookup=java\:global\/env\/flag)"

To list server extensions, profiles, subsystems, network interfaces, or socket-binding-groups:
jboss-cli.sh -c "ls subsystem"
jboss-cli.sh -c "ls extension"
jboss-cli.sh -c "ls profile"
jboss-cli.sh -c "ls interface"
jboss-cli.sh -c "ls socket-binding-group"

To create a datasource witht the default h2 database: 
data-source add --name=test-ds --jndi-name=java\:jboss\/datasources\/test-ds --driver-name=h2 --connection-url=jdbc\:h2\:mem\:test;DB_CLOSE_DELAY\=-1

data-source enable --name=test-ds

To verify a datasource and check if a connection can be obtained: 
data-source test-connection-in-pool --name=test-ds

To disable a datasource: 
data-source disable --name=test-ds 

To delete a datasource: 
data-source remove --name=test-ds