JBoss Installation
Before we start I would like to make one note and that is when you install software try and rename the installation directory (not to use any spaces) because in some environments (Windows) it likes to place JBoss in a pathname that has spaces (c:\program files\...), when you develop applications later, spaces in pathnames will cause you major headaches.
The first task we need to do is to obtain the JDK from Sun (http://java.sun.com), I used version 1.6.0 and JBoss runs perfectly but you might want to try with the latest version, download the JDK and install into your environment following Sun's instructions. Once installed don't forgot to set a JAVA_HOME environment variable that points to your JDK.
| JAVA_HOME | set JAVA_HOME=c:/jdk1.6.0_12 |
Installing JBoss is simple and there are a number of ways that you can install it
The fastest way to install JBoss is to download the binary version from http://www.jboss.org, unzip it and copy it to directory and that's it, it is ready to go, no installation. If you are going to install it straight into Production, then you need to make some changes to the default configuration to secure it, I have a topic on Production configurations. JBoss will work straight out of the box and is ideal for a development environment, the other route is to use JEMS installer which is a GUI based installer that allows you to configure the services that JBoss will use, you need to download the jems-installer file (http://labs.jboss.com/jeminstaller) which is an executable JAR file (90MB), looking at the web site the JEMS installer does not appear to supported very well as the link did not work but you can obtain the file from SourceForge.
It appears that the binary installation is the preferred way to go, one note is that there is no installation and everything that you need is contained in one directory (no registry settings or package stuff), this means you just copy the directory and put onto any server (Windows or Unix) and it should start up, the only difference is the way you start JBoss
There is a file called "service" in the bin directory which can create a windows JBoss service for you, I had problems when using this, it gave a file error message, this was because of the "jbosssvc" wrapper file was either corrupt or the wrong type, search for a newer version on the web and replace the one in the original install (I have a link below to the one I used)
| create a windows JBoss service | c:\jboss6\bin\service install Note: downloaded jbosssvc file |
When you have finished installing JBoss you should have a top level directory structure like below (Yes. I know its JBoss 4 but its the same layout)
| bin | This directory contains all the scripts (both Unix and Windows) that you will need to start and stop JBoss. There are a number of others files here
|
| client | This directory contains many Java libraries that are used to communicate with JBoss server from a client application. These client applications are called standalone client or remote clients and could be Swing applications, remote Web services, JMS clients. If for what ever reason you need to use these libraries use the jbossall-client.jar file, this jar file contains a META-INF/Manifest.mf file that contains a class path reference to all the jar files in this directory. |
| common | This directory I believe is from the version 4 JBoss implemention, where all common Java libraries were placed so that all web application could use them, I now believe that all common libraries should be placed in the <server config>/lib directory (see below). |
| docs | There are no user manuals in this directory, but it contains the following
|
| lib | This directory contains all the libraries that need to start the core JBoss server. Do not put any libraries that you want to use across all web applications, these need to go in <server config>/lib (see below) |
| server | This directory only has the server configurations in it, each directory represents a different server configuration that JBoss can be started in (see above). Normally you copy a particular directory that suits you and rename to what ever you want and then configure this directory for your environment, then use the -c option to start your server configuration |
The server directory holds the server configuration, see above for the layout of this directory
| conf | Each server configuration has a conf directory that holds files used for servlet-wide configuration. This directory is only scanned once during the boot sequence so any changes that yo make are not picked up until you restart the server. The import files in this directory are
|
| deploy | this is where applications and services are deployed. You can deploy any application packages here for example JAR, WAR or EAR that you create. By copying them into this directory JBoss will automatically deploy them to the application server. |
| deployers | contains all the JBoss AS services that are used to recognize and deploy different applications and archive types, for example the ejb3.deployer directory contains libraries and configuration files necessary for starting the service that deploys EJB3 applications that you deploy into the deploy directory. |
| lib | this directory holds all the Java libraries that can be accessed by all web applications. |
| Generated Directories | JBoss creates additional directories when first started
|
JBoss is designed to be modular, this means that you add or remove services very easily, by removing unwanted services you can decrease the memory allocation and increase performance, it also reduces security risks. The picture below shows how the microcontainer runs on top of the JVM and how various application-server services plug into the microcontainer. When you start JBoss you are always starting a server configuration which is a directory structure under the server's server directory, it contains code, libraries and configuration files for a set of services and applications that run when the server starts.
Typically you copy one of the already supplied configurations and adapt it to your environment, then start this configuration using the -c option with run.bat or run.sh, or you can just use one of the supplied configurations.
| start a different configuration | run.bat -c minimal run.bat -c <your configuration> |
Pre-Configurations |
|
| all | Includes everything - clustering, RMI/IIOP support |
| default | this is the default configuration if you do not specify anything, it does not include a web container, no ejb or JMS support |
| minimal | Includes only JNDI, logging services an a URL deployment scanner to find new deployments |
| standard | |
| web | Used to contain services which will allow simple web applications (servlet, jsp) to be deployed. |
I have read a number of JBoss books and none of them detailed the JBoss boot sequence, searching the web and using the JBoss log file, I will put a quick summary of the boot sequence below, it may not be to accurate but there is no document that explains this well, I will update this as and when I get more information.
| bootstrap.xml | Defines the core microcontainer services that start when the server first starts. |
bootstrap.xml file |
|
| vfs.xml | This configures the Virtual filesystem, which is a simple read-only framework abstracting the way we look at the the filesystem. It uses virtual files which can be accessed by a URI/URL (uses a URI/URL:MBean link pairing) |
| classloader.xml | This configures the core classloading system and classpath |
| aop.xml | Aspect-oriented programming is a programming paradigm that increases modularity by allowing the separation of cross-cutting concerns. (its a post OOP programming paradigm) |
| jmx.xml | This configures the JMX Kernel Mbeans |
| deployers.xml | This configures the MainDeployer, Structure Deployers, the bootstrap MC and the JMX deployer |
| binding.xml | This configures the ServiceBindingManager bean and configuration |
| profile-repository.xml | This configures the ProfileService beans which includes management and deployment support. |
To start JBoss using the default configuration, you open a console window and go to the bin directory, then run "run.sh" or "run.bat", you can also use the -c option to change the default server configuration, I have already discussed this above. To stop JBoss use the "shutdown" command
| Starting JBoss | # cd <JBoss dir>/bin # run.sh c:\> run.bat # run.sh -c all |
| Stopping JBoss | # shutdown.sh c:\> shutdown.bat |
When JBoss has started you should see the below line in the log file, you can also check that JBoss has started by using the following URL http://localhost:8080
| JBoss has started | 2009-04-03 12:05:12,125 INFO [org.jboss.bootstrap.microcontainer.ServerImpl] (main) JBoss (Microcontainer) [5.0.1.GA (build: SVNTag=JBoss_5_0_1_GA date=200902231221)] Started in 1m:907ms |
JBoss uses log4j an open source logging framework, the configuration file is located at server/xxx/conf/jboss-log4j.xml. I have already discussed log4j in my Tomcat tutorial, so have a look there first then continue back here. JBoss be default has two appenders configured, one for the console and for the server/xxx/log/server.log file. Most configuration setups use a rolling log file, it is created each time JBoss is stopped and restarted and at midnight it is rolled over, you can also specify a size for it to rollover.
| Rolling logfile | <log4j: ...> <appender name="FILE" class="org.jboss.logging.appender.RollingFileAppender"> <errorHandler ../> <param name="File" value="${jboss.server.log.dir}/server.log"/> <param name="Append" value="true"/> <param name="MaxFileSize" value="10MB"/> <param name="MaxBackupIndex" value="20"/> <layout ../> </appender> ... </log4j> |
| Limiting logging | <log4j:...> ... <category name="org.jboss.jms"> <priority value="WARN"/> </category> </log4j> |
There are a number of system properties that define default directory locations
| jboss.home.dir | c:\jboss-5.0.0.GA /opt/jboss-5.0.0.GA |
| jboss.home.url | file:/c:\jboss-5.0.0.GA file://opt/jboss-5.0.0.GA |
| jboss.lib.url | <jboss.home.url>lib/ |
| jboss.patch.url | -none- |
| jboss.server.base.dir | <jboss.home.dir>/server |
| jboss.server.base.url | <jboss.home.url>server/ |
| jboss.server.home.dir | <jboss.server.base.dir>/default |
| jboss.server.home.url | <jboss.server.base.url>default/ |
| jboss.server.config.url | <jboss.server.home.url>conf/ |
| jboss.server.data.dir | <jboss.server.home.dir>/data |
| jboss.server.lib.url | <jboss.server.home.url>lib/ |
| jboss.server.log.dir | <jboss.server.home.dir>/log |
| jboss.server.temp.dir | <jboss.server.home.dir>/tmp |
You can also provide system properties on the commandline by using the "-D" option
| supplying commandline properties | c:\> run.bat -Djboss.server.log.dir=d:/log |
There are two more systems properties which are of interest
| jboss.server.name | default |
| jboss.bind.address | 127.0.0.1 |
System properties are used in a number of configuration XML files and as stated above you can add your own properties using the "-D" option
| Using your own system properties | c:\> run.bat -Dtrading.database.login=trader1 -Dtrading.database.password=traderpw // In your oracle-ds.xml file <user-name>${trading.database.login}</user-name> |