Installing the Binary Package

Directory Structure

As mentioned previously, installing the JBoss distribution creates a jboss-4.0.1 directory, which contains server startup scripts, JARs, server configuration sets, and working directories. You need to know your way around the distribution layout to locate JARs for compiling code, updating configurations, deploying code, and so on. Figure 1.1 illustrates the installation directory of the JBoss server.

Figure 1.1. A view of the JBoss server installation directory structure, with the default server configuration file set expanded and overridable locations identified.

[View full size image]

Throughout this book we refer to the top-level jboss-4.0.1 directory as the JBOSS_DIST directory. In Figure 1.1, the default server configuration file set is shown expanded. It contains a number of subdirectories: conf, data, deploy, lib, log, and tmp. In a clean installation, only the conf, deploy, and lib directories will exist. The purposes of these directories are discussed in Table 1.1. In this table, the "ServerConfig Property" column refers to the org.jboss.system.server. ServerConfig interface constant and its corresponding system property string. The ServerConfig constant names and corresponding system property name are displayed in the blue text in Figure 1.1. The XXX_URL names correspond to locations that can be specified by using a URL to access remote locationsfor example, HTTP URLs against a web server. You can use the properties listed in Table 1.1 to override the layout of a JBoss distribution.

Table 1.1. The JBoss Directory Structure

Directory	Description	ServerConfig Property
bin	All the entry-point JARs and start scripts included with the JBoss distribution are located in the bin directory.
client	JARs required for clients are located in the client directory. A typical client requires jbossall-client.jar, concurrent.jar, and log4j.jar.
server	The JBoss server configuration sets are located under the server directory. The default server configuration set is the server/default set. JBoss ships with minimal, default, and all configuration sets. The subdirectories and key configuration files contained in the default configuration set are discussed in more detail later in this chapter, in the section "The Default Server Configuration File Set."	SERVER_BASE_DIR="jboss. server.base.dir" SERVER_BASE_URL="jboss. server.base.url"
lib	The lib directory contains startup JARs used by JBoss. Do not place your own libraries in this directory.	LIBRARY_URL ="jboss.lib.url"
conf	The conf directory contains the boot-strap descriptor filejboss-service.xml by defaultfor a given server configuration. This defines the core services that are fixed for the lifetime of the server.	SERVER_CONFIG_URL ="jboss.server.config.url"
data	The data directory is available for use by services that want to store content in the file system.	SERVER_DATA_DIR ="jboss.server.data.dir"
deploy	The deploy directory is the default location to which the hot deployment service looks for dynamic deployment content. This may be overridden through the URLDeploymentScanner URLs attribute.
lib	The lib directory is the default location referred to by the bootstrap descriptor. All JARs in this directory are loaded into the shared classpath.	SERVER_LIBRARY_URL ="jboss.server.lib.url"
log	The log directory is the default directory into which the bootstrap logging service places its logs. This may be overridden through the conf/log4j.xml configuration file.
tmp	The tmp directory is the location to which deployments are copied for local use.	SERVER_TEMP_DIR="jboss.server. temp.dir"

The Default Server Configuration File Set

The JBOSS_DIST/server directory contains one or more configuration file sets. The default JBoss configuration file set is located in the JBOSS_DIST/server/default directory. JBoss allows you to add more than one configuration set, so a server can easily be run using alternate configurations. Creating a new configuration file set typically starts with copying the default file set into a directory with a new name and then modifying the configuration files as desired. Figure 1.2 shows the contents of the default configuration file set.

Figure 1.2. An expanded view of the default server configuration file set conf and deploy directories.

[View full size image]

conf/jboss-minimal.xml

This is a minimalist example of the jboss-service.xml configuration file. It is the jboss-service.xml file that is used in the minimal configuration file set.

conf/jboss-service.xml

jboss-service.xml defines the core services configurations. The complete DTD and syntax of this file is described, along with the details on integrating custom services, in the next chapter.

conf/jboss.web

This directory is used by Tomcat.

conf/jndi.properties

The jndi.properties file specifies the JNDI InitialContext properties that are used within the JBoss server when an InitialContext is created using the no-arg constructor.

conf/log4j.xml

This file configures the Apache log4j framework category priorities and appenders used by the JBoss server code.

conf/login-config.xml

This file contains sample server-side authentication configurations that are applicable when using JAAS-based security. See Chapter 8, "Security on JBoss," for additional details on the JBoss security framework and the format of this file.

conf/server.policy

The server.policy file is a placeholder for Java2 security permissions. The default file simply grants all permissions to all codebases.

conf/standardjaws.xml

This file provides a default configuration file for the legacy EJB 1.1 JBossCMP engine.

conf/standardjboss.xml

This file provides the default container configurations. Use of this file is covered in Chapter 5, "EJBs on JBoss."

conf/standardjbosscmp-jdbc.xml

This file provides a default configuration file for the JBoss CMP engine. See Chapter 11, "The CMP Engine," for the details of this descriptor.

conf/xmdesc/*-mbean.xml

The xmdesc directory contains XMBean descriptors for several services configured in the jboss-service.xml file.

deploy/bsh-deployer.xml

This file configures the bean shell deployer, which deploys bean shell scripts as JBoss services.

deploy/cache-invalidation-service.xml

This is a service that allows for custom invalidation of the EJB caches via JMS notifications. It is disabled by default.

deploy/client-deployer-service.xml

This is a service that provides support for J2EE application clients. It manages the java:comp/env enterprise naming context for client applications, based on the application-client.xml descriptor.

deploy/ear-deployer.xml

The EAR deployer is the service responsible for deploying J2EE EAR files.

deploy/ejb-deployer.xml

The EJB deployer is the service responsible for deploying J2EE EJB JAR files.

deploy/hsqldb-ds.xml

hsqldb-ds.xml configures the Hypersonic 1.7.1 embedded database service configuration file. It sets up the embedded database and related connection factories. The format of JCA datasource files is discussed in Chapter 7, "Connectors on JBoss."

deploy/http-invoker.sar

http-invoker.sar contains the detached invoker that supports RMI/HTTP. It also sets up bindings of RMI/HTTP proxies for the JNDI naming service; these bindings allow the JBoss JNDI service to be accessed over HTTP. This is discussed in the next chapter.

deploy/jboss-aop.deployer

jboss-aop.deployer configures AspectManagerService and deploys JBoss AOP applications.

deploy/jboss-hibernate.deployer

jboss-hibernate.deployer deploys Hibernate archives (HAR files).

deploy/jboss-local-jdbc.rar

jboss-local-jdbc.rar is a JCA resource adaptor that implements the JCA ManagedConnectionFactory interface for JDBC drivers that support the DataSource interface but not JCA.

deploy/jboss-ws4ee.sar

jboss-ws4ee.sar provides J2EE Web Services support.

deploy/jboss-xa-jdbc.rar

jboss-xa-jdbc.rar is a JCA resource adaptor that implements the JCA ManagedConnectionFactory interface for JDBC drivers that support the XADataSource interface but do not provide the JCA adaptor.

deploy/jbossjca-service.sar

jbossjca-service.sar is the application server implementation of the JCA 1.0 specification. It provides the connection management facilities for integrating resource adaptors into the JBoss server. The JCA layer is discussed in Chapter 7.

deploy/jbossweb-tomcat50.sar

The jbossweb-tomcat50.sar directory is an unpacked MBean service archive for the configuration of the Tomcat 5 servlet engine. The SAR is unpacked rather than deployed as a JAR archive so that the tomcat configuration files can be easily edited. This service is discussed in Chapter 9, "Web Applications."

deploy/jms/hsqldb-jdbc2-service.xml

hsqldb-jdbc2-service.xml configures JMS persistence and caching by using Hypersonic. It also contains the DestinationManager MBean, which is the core service for the JMS implementation.

deploy/jms/jbossmq-destinations-service.xml

jbossmq-destinations-service.xml configures a number of JMS queues and topics used by the JMS unit tests. Configuration of JMS destinations is discussed in Chapter 6, "Messaging on JBoss."

deploy/jms/jbossmq-httpil.sar

jbossmq-httpil.sar provides a JMS invocation layer that allows the use of JMS over HTTP.

deploy/jms/jbossmq-service.xml

The jbossmq-service.xml file configures the core JBossMQ JMS service. JMS services are discussed in Chapter 6.

deploy/jms/jms-ds.xml

The jms-ds.xml file configures the JBossMQ JMS provider for use with the jms-ra.rar JCA resource adaptor.

deploy/jms/jms-ra.rar

jms-ra.rar is a JCA resource adaptor that implements the JCA ManagedConnectionFactory interface for JMS connection factories.

deploy/jms/jvm-il-service.xml

jvm-il-service.xml configures the inter-vm JMS transport invocation layer. This transport layer is described in org.jboss.mq.il.jvm.JVMServerILService.

deploy/jms/uil2-service.xml

uil2-service.xml configures the JMS version 2 unified invocation layer. It is a custom socket-based transport that is the fastest and most reliable and should be used for intervm messaging. This transport layer is described in org.jboss.mq.il.uil2.UILServerILService.

deploy/jmx-console.war

The jmx-console.war directory is an unpackaged web application archive that provides an HTML adaptor for the JMX MBeanServer. The WAR is unpackaged rather than deployed as a JAR archive so that the jmx-console.war/WEB-INF/*.xml descriptors can be edited to easily configure role-based security.

deploy/jmx-invoker-service.sar

jmx-invoker-service.sar is an unpacked MBean service archive that exposes a subset of the JMX MBeanServer interface methods as an RMI interface to enable remote access to the JMX core functionality. This is similar to the legacy jmx-rmi-adaptor.sar, with the difference that the transport is handled by the detached invoker architecture. This service is discussed in Chapter 2, "The JBoss JMX Microkernal."

deploy/mail-ra.rar

mail-ra.rar is a resource adaptor that provides a JavaMail connector.

deploy/mail-service.xml

The mail-service.xml file is an MBean service descriptor that provides JavaMail sessions for use inside the JBoss server.

deploy/management/console-mgr.sar and web-console.war

console-mgr.sar and web-console.war provide the Web Console, which is a web application/applet that provides a richer view of the JMX server management data than the JMX Console. You can view the console at http://localhost:8080/web-console/.

deploy/monitoring-service.xml

The monitoring-service.xml file configures alert monitors like the console listener and email listener used by JMX notifications.

deploy/properties-service.xml

The properties-service.xml file is an MBean service descriptor that allows for customization of the JavaBeans PropertyEditors as well as the definition of system properties. This is discussed further in Chapter 10, "MBean Services Miscellany."

deploy/scheduler-service.xml and schedule-manager-service.xml

The scheduler-service.xml and schedule-manager-service.xml files are MBean service descriptors that provide a scheduling type of service. This is discussed further in Chapter 10.

deploy/sqlexception-service.xml

The sqlexception-service.xml file is an MBean service descriptor for vendor-specific handling of java.sql.SQLExceptions. Its usage is discussed in Chapter 11.

deploy/uuid-key-generator.sar

The uuid-key-generator.sar service provides a UUID-based key-generation facility.