Jboss Admin Tutorial : Directory Structure

4. JBoss Directory Structure

4.1. JBoss AS Directory Structure

JBossORG-EULA.txt       copyright.txt           lib/
bin/                    docs/                   readme.html
client/                 jar-versions.xml        server/
common/                 lgpl.html
  • Root dir known as jboss.home.dir or $JBOSS_HOME
  • Understanding the layout is important:

    • Locating libraries
    • Updating configuration
    • Deploying apps and services

When JBoss AS is installed (uncompressed), the following directories are created:

  • ${jboss.home.dir}/bin
  • ${jboss.home.dir}/client
  • ${jboss.home.dir}/common
  • ${jboss.home.dir}/docs
  • ${jboss.home.dir}/lib
  • ${jboss.home.dir}/server

4.2. The bin Directory

README-service.txt      run.conf                twiddle.sh
classpath.sh            run.conf.bat            wsconsume.bat
jboss_init_hpux.sh      run.jar                 wsconsume.sh
jboss_init_redhat.sh    run.sh                  wsprovide.bat
jboss_init_suse.sh      service.bat             wsprovide.sh
jbosssvc.exe            shutdown.bat            wsrunclient.bat
password_tool.sh        shutdown.jar            wsrunclient.sh
probe.bat               shutdown.sh             wstools.bat
probe.sh                twiddle.bat             wstools.sh
run.bat                 twiddle.jar

JBoss AS ${jboss.home.dir}/bin directory contains startup/shutdown scripts, bootstrap libraries, Web Services and server management utilities:

  • classpath.sh: A tool to determine JBoss classpaths (both client and server)
  • jboss_init_redhat.sh and jboss_init_suse.sh: JBoss system control scripts for RedHat and SuSE systems
  • probe.sh and probe.bat: used for discovering JBoss AS clusters.
  • run.sh and run.bat: Scripts for starting JBoss AS
  • run.jar: Bootstrap code for starting JBoss AS
  • service.bat: Script to manage JBoss as a Windows service.
  • shutdown.sh and shutdown.bat: Scripts for shutting down JBoss AS (including remote instances)
  • shutdown.jar: Bootstrap code for shutting down JBoss AS
  • twiddle.sh and twiddle.bat: Scripts for running JBoss AS command-line management client (based on JMX)
  • twiddle.jar: Bootstrap code for the JMX management (instrumentation) client
  • wsconsume, wsprovide, wsrunclient and wstools are utilities for Web Services. We will see that later on Web Services chapter.

4.3. The client Directory

  • Contains the Java libraries (JARs) required for clients that run outside the JBoss AS containers, such as:

    • WebService clients
    • EJB clients
    • JMX clients
  • Used by external applications that need to access JNDI resources
  • On Unix, to get the client CLASSPATH, run: ${jboss.home.dir}/bin/classpath.sh -c
  • As of JBoss 5, the file client/jbossall-client.jar contains references to other JARs via Class-Path setting in its META-INF/MANIFEST.MF file. This makes it possible for external JBoss clients to just reference this one JAR file as opposed to many of them.
[Note]Note

We will use the client/ directory later with some clients (like JMS) that will run outside the JBoss AS.

4.4. The common directory

  • Contains the lib directory (also known as jboss.common.lib.url).

    • lib folder contains the common libraries shared by all server configurations (more on this later)
    • This directory is new to JBoss 5. In earlier versions of JBoss a number of common libraries were simply duplicated for each configuration set.

4.5. The docs Directory

dtd/            examples/       licenses/       schema/         tests/
  • Examples: sample configuration: JMX, JCA, JMS, NetBoot, etc.

    • Contains excellent examples for many different configurations. For example, the file docs/examples/jca/mysql-ds.xml can serve as a starting point in defining a MySQL-based DataSource (shared database connection-pool) in JBoss AS.
  • DTDs and Schemas for J2EE and JBoss XML files

    • Contain all J2EE-referenced XML DTD and XSD files, making it simple to validate XML files and lookup the relevant "grammar" when making configuration changes. DTDs were employed by J2EE 1.3 and JBoss 4 whereas Schemas are used since J2EE 1.4 and JBoss 5.
  • Licenses for all JBoss components
  • Unit test results
[Note]Note

The actual JBoss AS documentation can be downloaded from http://www.jboss.org/jbossas/docs/5-x.html

4.6. The lib Directory

  • Contains JBoss bootstrap libraries (core libraries)
  • Do not place your own files here or remove any of the existing files
  • As an example, you?ll find here the JBoss Microcontainer and the old JMX kernel.

4.7. The server Directory

all/            minimal/        node2/          web/
default/        node1/          standard/
  • Known in JBoss AS as jboss.server.base.dir
  • Root of server configuration sets
  • JBoss comes with minimal, default and all
  • Version 5.x comes with 2 new configurations: standard and web
  • Defaults to configuration set in server/default
  • Configuration sets contain the actual JBoss services

To change the configuration set that JBoss AS runs with, execute: bin/run.sh -c <configuration-set>

For example:

bin/run.sh -c minimal
bin/run.sh -c all

Configuration sets:

minimal/

  • Includes support for JNDI and logging. It does not contain any other J2EE services like Servlet/JSP container, EJB container, or JMS.
  • Can serve as a starting point when creating your own configuration sets

default/

  • As the name implies, this is the default Java EE 5 configuration. Contains the most used services except JAXR, IIOP and clustering services.

all/

  • This configuration extends the default configuration set and also include JAXR, IIOP and clustering services

standard/

  • Certified Java EE 5 configuration compliant.
[Note]Note

The major differences with the existing configurations is that call-by-value and deployment isolation are enabled by default, along with support for rmiiiop and juddi (taken from the all config).

web/

  • Lightweight web container profile (Java EE 6 web profile). It provides support for JTA/JCA and JPA except for the servlet/JSP container.

4.8. The server Configuration Sets

all/            minimal/        node2/          web/
default/        node1/          standard/
  • The currently running server/<server> dir is known in JBoss AS as jboss.server.home.url
  • The name of the server (e.g. "default") is known as jboss.server.name
  • Configuration sets are independent of each other
[Note]Note

Each configuration set has to have at least the following four directories: conf/, deploy/, deployers/, and lib/. Other (referenced) directories such as data/, log/, tmp/, and work/ are automatically created on JBoss AS startup if they do not exist.

4.9. The default/conf Directory

bindingservice.beans/           jbossts-properties.xml
bootstrap/                      jndi.properties
bootstrap.xml                   login-config.xml
java.policy                     props/
jax-ws-catalog.xml              standardjboss.xml
jboss-log4j.xml                 standardjbosscmp-jdbc.xml
jboss-service.xml               xmdesc/
  • Known in JBoss as jboss.server.config.url
  • Contains a bootstrap descriptor (jboss-service.xml) that defines which services are loaded for the lifetime of the instance

The files in directory ${jboss.server.config.url} :

  • bootstrap/*: Bootstrap descriptors for core microcontainer services defined in bootstrap.xml
  • bootstrap.xml: Defines the core microcontainer beans to load during bootstap
  • jboss-service.xml: Defines the core JMX services configurations
  • jndi.properties: Specifies a set of properties that are passed to JNDI when new InitialDirContext() is called within JBoss
  • jboss-log4j.xml: Configuration file for the logging service (Log4J) defining log filters, priorities, and destinations
  • login-config.xml: Defines security realms used for authentication and authorization (JAAS)
  • props/*.properties: Java property files (usually used for JAAS realms)
  • java.policy: Placeholder for security permissions (Java Security Manager). Grant-All by default
  • standardjboss.xml: Configuration file for the standard EJB container
  • standardjbosscmp-jdbc.xml: Configuration file for the standard JBossCMP engine
  • xmdesc/*-mbean.xml: XMBean descriptors for services configured in the jboss-service.xml file
  • props/*: property files defining users and roles for the jmx-console
[Important]Important

Any changes to files in this directory require a full server restart in order to take effect.

4.10. The default/data Directory

hypersonic/             wsdl/
tx-object-store/        xmbean-attrs/
  • Known in JBoss as jboss.server.data.dir
  • Location where some services store private content on the file system

    • Hypersonic DB - built-in (by default use as the temporary message store by JMS)
    • XMBeans attribute persistence (not enabled by default)
    • Transaction objects (temporary storage of objects during the two-phase commit process)
  • This directory is not directory exposed to the end users (e.g. though the web interface)
[Note]Note

Unless you use Hypersonic DB, the contents of this directory (including the directory itself) can be cleared (deleted) between JBoss restarts.

4.11. The default/deploy Directory

CurrencyConverterApp.ear                jsr88-service.xml
ROOT.war/                               legacy-invokers-service.xml
admin-console.war/                      mail-ra.rar
cache-invalidation-service.xml          mail-service.xml
ejb2-container-jboss-beans.xml          management/
ejb2-timer-service.xml                  messaging/
ejb3-connectors-jboss-beans.xml         monitoring-service.xml
ejb3-container-jboss-beans.xml          my-ws.war
ejb3-interceptors-aop.xml               printservice.sar/
ejb3-timerservice-jboss-beans.xml       profileservice-jboss-beans.xml
fortune.war/                            profileservice-secured.jar/
hdscanner-jboss-beans.xml               properties-service.xml
hsqldb-ds.xml                           quartz-ra.rar
http-invoker.sar/                       remoting-jboss-beans.xml
jboss-local-jdbc.rar                    schedule-manager-service.xml
jboss-xa-jdbc.rar                       scheduler-service.xml
jbossweb.sar/                           security/
jbossws.sar/                            sqlexception-service.xml
jca-jboss-beans.xml                     transaction-jboss-beans.xml
jms-ra.rar                              transaction-service.xml
jmx-console.war/                        uuid-key-generator.sar/
jmx-invoker-service.xml                 vfs-jboss-beans.xml
jmx-remoting.sar/                       xnio-provider.jar/
  • Dynamic deployment content directory
  • This is where applications and services are deployed
  • Default location used by hot deployment service
  • Contains code and configuration files for all services

Some files in the deploy directory include:

  • ROOT.war: is the / root web application
  • cache-invalidation-service.xml - Custom invalidation of EJB caches via JMS
  • ejb2-container-jboss-beans.xml - UserTransaction integration bean for EJB2 container
  • ejb2-timer-service.xml - EJB timer service bean
  • ejb3-connectors-jboss-beans.xml - EJB3 remoting transport bean
  • ejb3-container-jboss-beans.xml - UserTransaction integration bean for EJB3 container
  • ejb3-interceptors-aop.xml - AOP for EJB3
  • ejb3-timer-service.xml - alternate quartz based timer service
  • hdscanner-jboss-beans.xml - hot deployment scanner bean
  • hsqldb-ds.xml - Hypersonic embedded database and related connection factories
  • http-invoker.sar - Detached invoker that supports RMI/HTTP
  • jboss-local-jdbc.rar - JCA to DataSource adaptor for JDBC drivers
  • jboss-xa-jdbc.rar - JCA to XADataSource adaptor for JDBC drivers.
  • jbossweb.sar - Tomcat Servlet/JSP Engine
  • jbossws.sar - The JBoss service that supports web services
  • jca-jboss-beans.xml - Connection management facilities for integrating JCA adaptors into JBoss AS
  • jms-ra.rar - JMS resssource adapter
  • messaging/connection-factories-service.xml - DLQ, ExpiryQueue JMS connection factory
  • messaging/destinations-service.xml - Message persistence store service
  • messaging/jms-ds.xml
  • messaging/legacy-service.xml
  • messaging/messaging-jboss-beans.xml - JMS security and management beans
  • messaging/messaging-service.xml - Core messaging service
  • messaging/remoting-bisocket-service.xml - JMS remoting service layer
  • jmx-console.war - Web application that provides HTML interface to manage MBean server
  • jmx-invoker-service.xml - RMI to JMX adaptor into JBoss
  • jmx-remoting.sar -
  • legacy-invokers-service.xml -
  • jsr-88-service.xml -
  • mail-ra.rar - Resource adaptor that provides a JavaMail connector
  • mail-service.xml - JavaMail session service (SMTP)
  • monitoring-service.xml - Configuration for alert monitors such as email or console listeners
  • properties-service.xml - JavaBeans PropertyEditors and definition of system properties
  • admin-console.war - admin console for JBoss AS
  • scheduler-service.xml - JBoss scheduling service
  • sqlexception-service.xml - Vendor-specific SQL exception handler
  • security/security-jboss-beans.xml - Security domain related beans
  • security/security-policies-jboss-beans.xml - Security authorization for EJB and web authorization
  • transaction-jboss-beans.xml - JTA transaction manager related beans
  • uuid-key-generator.sar - UUID-based key generation facility

4.12. The default/deployers Directory

alias-deployers-jboss-beans.xml         jboss-threads.deployer/
bsh.deployer/                           jbossweb.deployer/
clustering-deployer-jboss-beans.xml     jbossws.deployer/
dependency-deployers-jboss-beans.xml    jsr77-deployers-jboss-beans.xml
directory-deployer-jboss-beans.xml      logbridge-jboss-beans.xml
ear-deployer-jboss-beans.xml            messaging-definitions-jboss-beans.xml
ejb-deployer-jboss-beans.xml            metadata-deployer-jboss-beans.xml
ejb3.deployer/                          seam.deployer/
hibernate-deployer-jboss-beans.xml      security-deployer-jboss-beans.xml
jboss-aop-jboss5.deployer/              webbeans.deployer/
jboss-ejb3-endpoint-deployer.jar        xnio.deployer/
jboss-jca.deployer/
  • Contains all the JBoss AS services that are used to recognize and deploy different application and archive types.

Some files in the deployers directory:

  • hibernate-deployer-jboss-beans.xml - Deployer for Hibernate archives (HAR)
  • ejb-deployer-jboss-beans.xml - Service responsible for deploying EJB JAR files
  • ear-deployer-jboss-beans.xml - Service responsible for deploying EAR files
  • jbossweb.deployer - Service responsible for deploying WAR files
  • jboss-aop-jboss5.deployer - Deployer that sets up Aspect Manager Service and deploys AOP applications
  • etc?
[Note]Note

This directory is new as of JBoss AS 5

4.13. The default/lib Directory

  • Directory referred to by the bootstrap code when loading the configuration set
  • Known within JBoss as jboss.server.lib.url
  • This directory is for Java code (JARs) to be used both by the deployed applications and JBoss AS services
  • If you have Java libraries that you need to be made available to all your applications/services, these can be placed in the ${jboss.server.lib.url} directory.
  • Similarly, you would also use this directory for Java libraries that need to be used by both your applications/services, and JBoss AS services.

    • A typical example of this is a JDBC driver that is needed by JBoss AS to manage a pool of database connections, as well as your code, which implicitly uses it to interact with the database server.
[Note]Note

As of JBoss 5, some JARs that used to reside in this directory have been moved to common/lib in order to share them with other configuration sets.

4.14. The default/log Directory

  • Known within JBoss as jboss.server.log.dir
  • Default destination directory for JBoss AS log files (3 log files)
  • boot.log - logs boot process until logging service starts
  • server.log - takes over once the logging service is initialized from ${jboss.server.config.url}/jboss-log4j.xml
  • audit.log - audit security
  • Default startup log priority: DEBUG
  • STDOUT and STDERR are logged to console

By default:

  • Log file server.log is rolled over daily (with the ".yyyy-MM-dd" extension)
  • Existing logs are overwritten on [re]start
  • Old log files are not automatically cleaned by the server during runtime

Since the logging system is managed by Log4J it can be easily configured to:

  • Roll over logs hourly
  • Roll over logs by size (e.g. 500KB)
  • Automatically remove old logs
  • Log to SMTP, SNMP, Syslog, JMS, etc.

This directory can be cleared (deleted) between JBoss restarts.

4.15. The default/tmp Directory

  • Known in JBoss as jboss.server.temp.dir
  • Used by JBoss AS to store temporary files such as unpacked service and application deployments
  • Deployments are automatically removed on server shutdown

This directory can be cleared (deleted) between JBoss restarts.

[Note]Note

Unpacked deployments (e.g. expanded WAR files) are not copied over. Packed deployments (WAR, EAR, RAR) are uncompressed, whereas JARs and XML-described services are copied over.

4.16. The default/work Directory

  • Directory where compiled JSP .java and .class files reside
  • Also contains cached TLDs
  • Very useful for debugging problems in JSPs

Java ServerPages (.jsp files) are automatically compiled into Java Servlets (.java file) and then into Java byte-code (.class files) by Tomcat (the embedded servlet engine running within JBoss AS).

Many JSP errors are easier to fix when developers are able to look at the compiled .java files and match the line numbers to error/exception messages.

Unless you care to preserve compiled JSPs, this directory can be cleared (deleted) between JBoss restarts.