Chapter 1. Installing and Running JBoss

We volition first past installing JBoss and getting the server up and running. Y'all'll be surprised by how piece of cake it is to work with JBoss. It doesn't thing whether you're on Linux, Mac, or Windows; y'all can get the full JBoss awarding server running in just a few minutes. So, allow's get going.

Installing the Server

Installing JBoss is then easy that new users often recall they are missing something. But don't mistake this simplicity for lack of power or configurability. Before nosotros get started, y'all'll need to make certain y'all have either Java i.4 or Coffee ane.5 installed on your motorcar. That's the simply prerequisite for JBoss 4, and then if you lot are all set nosotros'll go started.

How do I do that?

You can download the latest JBoss version, currently 4.0.2, from the JBoss download folio at http://www.jboss.org/downloads/alphabetize. Once you choose the version of the JBoss awarding server you want, y'all'll be taken to the SourceForge.internet page to practice the actual download. When you get there select one of the prebuilt binary distributions. For JBoss 4.0.2 look for a file named jboss-four.0.ii.naught. You'll likewise see jboss-.4.0.two.tar.gz and jboss-four.0.2.tar.bz2 archives. If either of those formats works better for your platform, feel gratis to use information technology instead.

Note

We apply Java 1.4 in most examples, but in that location should be no differences if yous employ Coffee i.v. JRE install.

Before JBoss 4.0.ii, JBoss required a full JDK installation to compile JSP files. As of Version iv.0.two, Tomcat ships with its ain Java compiler, so JBoss only requires a JRE install.

Many of the releases have service packs, which are marked with the sp designation. Always choose the latest service pack release for the version you are downloading. You might also run into source code releases marked with the -src suffix, as well as RC (release candidate) and DR (programmer release) versions of the server. Ignore those for now and stick to the production binaries. In this book we will work from the jboss-4.0.ii.tar.gz release.

Notation

If you are on a Unix machine, nosotros suggest sticking with the .tar.gz release to make sure file permissions are preserved accurately.

Uncompress the download into the directory where you desire JBoss installed, using the appropriate tool for your platform. We put the server into /Users/samjr/jboss-four.0.2; here'due south the bin directory of the installed server:

                [bin]$                                  pwd                                /Users/samjr/jboss-four.0.two/bin     [bin]$                                  ls                                classpath.sh          jboss_init_suse.sh     run.sh              twiddle.bat     deployer.bat          run.bat                shutdown.bat        twiddle.jar     deployer.sh           run.conf               shutdown.jar        twiddle.sh     jboss_init_redhat.sh  run.jar                shutdown.sh

Note

If you don't accept a good zilch tool, y'all tin can always use the Coffee jar program to expand the zip archive.

What simply happened?

Y'all simply installed one of the nearly powerful application servers bachelor today. Really powerful tools usually demand much more setup and configuration, but not JBoss. Now, y'all're set to start it up.

What nearly...

...if I installed JBoss on another box on my network?

You lot volition want to check the firewall settings on that machine. Specifically, you'll desire to make sure that port 8080 is open and so that y'all'll be able to access the JBoss web server to exam it out. If you lot installed JBoss locally you shouldn't accept to worry about this.

Warning

Exist careful about installing JBoss on a machine that might be visible from the Net. JBoss ships in an insecure country that allows external access to server management features.

Starting Upward JBoss

Y'all might await it to exist complicated and fourth dimension consuming to configure the server and go it running for the first time. JBoss is indeed a complex server, only information technology's elementary to run, configure, and maintain. After in the book nosotros will come across the different kinds of configuration and maintenance options, but for now permit's just get JBoss up and running.

How do I do that?

To start JBoss, you'll need to use the run script in the bin directory of the server. There is a run.sh script for use on Unix machines and a run.bat file for Windows. When you run the script, y'all'll see something like the following output:

Note

If your run.sh file isn't executable, you should chmod the script or invoke information technology using the sh run.sh command. 

                [bin]$                                  ./run.sh                                =========================================================         JBoss Bootstrap Surroundings        JBOSS_HOME: /Users/samjr/jboss-four.0.2RC1        JAVA: coffee        JAVA_OPTS: -server -Xms128m -Xmx128m -Dprogram.name=run.sh        CLASSPATH: /Users/samjr/jboss-4.0.2RC1/bin/run.jar:/lib/tools.jar      =========================================================        05:02:58,197 INFO  [Server] Starting JBoss (MX MicroKernel)...     05:02:58,230 INFO  [Server] Release ID: JBoss [Zion] 4.0.2RC1 (build:     CVSTag=JBoss_4_0_2_RC1 date=200503140913)     05:02:58,232 INFO  [Server] Dwelling Dir: /Users/samjr/jboss-four.0.2RC1     05:02:58,233 INFO  [Server] Home URL: file:/Users/samjr/jboss-4.0.2RC1/     05:02:58,235 INFO  [Server] Library URL: file:/Users/samjr/jboss-4.0.2RC1/lib/     05:02:58,238 INFO  [Server] Patch URL: null     05:02:58,256 INFO  [Server] Server Name: default     05:02:58,258 INFO  [Server] Server Habitation Dir: /Users/samjr/jboss-4.0.2RC1/     server/default     05:02:58,259 INFO  [Server] Server Home URL: file:/Users/samjr/jboss-iv.0.     2RC1/server/default/     05:02:58,261 INFO  [Server] Server Data Dir: /Users/samjr/jboss-4.0.2RC1/     server/default/data     05:02:58,262 INFO  [Server] Server Temp Dir: /Users/samjr/jboss-iv.0.2RC1/     server/default/tmp     05:02:58,264 INFO  [Server] Server Config URL: file:/Users/samjr/jboss-four.0.     2RC1/server/default/conf/     05:02:58,265 INFO  [Server] Server Library URL: file:/Users/samjr/jboss-4.0.     2RC1/server/default/lib/     05:02:58,267 INFO  [Server] Root Deployment Filename: jboss-service.xml     05:02:58,324 INFO  [Server] Starting General Purpose Architecture (GPA)...             [Lots of startup output removed for brevity]         05:04:05,834 INFO  [TomcatDeployer] deploy, ctxPath=/quote, warUrl=file:/     Users/samjr/jboss-iv.0.2RC1/server/default/tmp/deploy/tmp14739quote.war/     05:04:06,348 INFO  [Http11Protocol] Starting Coyote HTTP/i.1 on http-0.0.0.0-8080     05:04:06,868 INFO  [ChannelSocket] JK2: ajp13 listening on /0.0.0.0:8009     05:04:06,956 INFO  [JkMain] Jk running ID=0 time=0/199  config=null     05:04:07,092 INFO  [Server] JBoss (MX MicroKernel) [4.0.2RC1 (build:     CVSTag=JBoss_4_0_2_RC1 date=200503140913)] Started in 1m:7s:977ms

Note

Most of the services in JBoss log output as they start upwardly. Boosted log output is available in the server.log file.

That's it! JBoss is up and running. Right there on that terminal line we accept full confirmation that it's up. But simply to make sure, go to http://localhost:8080/ in your browser. You lot should run across the JBoss welcome page that looks like to Figure 1-one.

JBoss welcome page

Figure 1-one. JBoss welcome page

Congratulations! Your JBoss server is at present running.

Examining the Server (JMX ConsoleJMX Console

The JBoss application server provides a management application that lets y'all see and manage the services that are deployed and running within the server. JBoss itself is implemented as a microkernel composed of managed beans (MBeans). The MBeans that are visible provide yous a way to manage the resources and applications that are deployed on your awarding server. This allows you to monitor and modify applications and their usage. Y'all can see what MBeans you lot have through the JMX Console. The JMX Console organizes the MBeans by the domain, besides by type (service, database, etc.). When you select an MBean you are taken to a page where yous tin can view and edit attributes or invoke the operations of that MBean.

Note

Y'all tin manage all the JBoss services through the JMX Console. If you provide MBeans for your own services, you lot will meet them hither too.

How exercise I practice that?

You tin get to the JBoss JMX Console by going to the chief web page (http://localhost:8080) and choosing the JMX Console link. This will take yous to the jmx-panel web application at http://localhost:8080/jmx-console. When yous're there, you'll run across something like Figure 1-2.

JMX Console

Figure 1-2. JMX Console

JBoss provides an MBean that allows yous to await at your server information. To do that at present, scroll downwards in your browser until you go to the department for the jboss.organisation domain. You should see a link for this: type=ServerInfo. Choose that link and you'll see the ServerInfo MBean page. Information technology volition look something like Figure 1-3.

JMX Console view of ServerInfo

Figure 1-3. JMX Panel view of ServerInfo

You can run across what JVM JBoss is running on top of, what operating system information technology is running on, etc. That's useful information, especially if you are doing remote monitoring.

Note

If yous are feeling adventurous, await at some of the other MBeans and encounter what other types of information are exposed.

What only happened?

You opened the JMX Console on the JBoss server and viewed the ServerInfo MBean. You as well saw that the MBeans are organized co-ordinate to the domain they are in. While this might not seem like much at present, it will come up in handy equally we work our way through the book.

Shutting Downwards the Server

Now that yous know how to start the server and await at it using the JMX Console, yous need to know how to close it down properly. It'southward really pretty simple, so let's become to it.

How exercise I exercise that?

You can close down the server in three ways:

  • Use the JMX Console to go to the jboss.system domain and choose the type=Server MBean link. On the MBean page, coil down to the operations section and click the "Invoke" button for the shutdown() operation.

  • Run the shutdown script for your platform in the same directory where yous institute the run script.

  • Type Ctrl-c in the aforementioned panel window where you lot started JBoss.

When JBoss is stopped, you lot'll see the post-obit bulletin:

                03:fifty:02,412 INFO  [Server] Shutdown complete

Y'all can verify that JBoss has stopped by trying to access the server in your web browser. You won't exist able to connect considering the server is not running anymore.

What just happened?

But as you would expect, the application server shut downwardly. You as well learned iii different ways to terminate JBoss, and you got to see another useful MBean. Of those 3 ways, when should y'all use i or the other?

Annotation

The shutdown script is in the bin directory with the startup script! The twiddle script is a plan for "twiddling" with a remote JBoss server.

In development, the Ctrl-c option is the easiest considering you will likely have an open final window running JBoss. However, if JBoss is running every bit a service, especially on a remote machine, you'll need to use one of the other options. If you have shell admission to the machine, the shutdown script will work fine. You tin besides use the shutdown control to shut downwards a remote JBoss case, merely this requires a local JBoss installation and a few extra command-line arguments. For remote machines, it's often more than user-friendly to just use the JMX Console. If you keep a bookmark set up to the ServerInfo MBean, it can be a very quick process. In the stop, each option serves the needs of unlike types of users, so just choose whatever is most convenient for you.

Specifying a Server Configuration

JBoss is not only powerful, information technology'south also very configurable. At the centre of JBoss is a JMX microkernel that manages the MBeans that command the various services in the server. The JBoss documentation describes the microkernel every bit a spine, and the analogy fits well. JBoss in its minimum configuration is like the brainstem sitting at the top of the spine. It provides all the cadre autonomic features (to steal some thunder from IBM'southward autonomic computing initiative). The spinal column is the attachment point for all the MBeans that want to talk to the brainstem and to each other over the spinal cord. This compages provides a strong backbone to build on, but at the same fourth dimension it tin work at its nearly minimal state and still practise amazing things. It makes JBoss useful for everything from very small, embedded applications all the style up to full-blown enterprise server applications, all on the same spinal cavalcade.

Having a flexible compages is pointless unless y'all can make use of that flexibility. JBoss provides several unlike configurations that range from a barebones server with no J2EE capabilities to a superserver with more than services than whatever single application could possibly employ. Figure ane-4 shows the 3 standard server configurations.

Server configurations

Figure 1-4. Server configurations

Here are descriptions of the server configurations:

Note

There is a huge difference in the size of these configurations. The minimal configuration can start upwards in just a few seconds, whereas it tin accept nearly a infinitesimal for the all configuration to completely start on a typical developer car.

minimal

This configuration provides the bare services you might need in the simplest awarding: logging, JNDI naming services, and URL deployment scanning. You lot'd apply this setup in tight memory situations, or when you want to use JMX to control exactly which MBeans are loaded, and when and how they are loaded. This configuration doesn't provide support for EJBs, web applications, JMS, or any other high-level services. It'due south just a raw microkernel waiting to be molded.

default

This is a lightweight J2EE configuration; it's the ane nearly people use. It provides nigh of the common J2EE services, but it doesn't include IIOP, JAXR, or clustering services, for example. These services can exist added hands to this configuration.

all

This configuration includes everything in JBoss. If you demand whatever actress services non provided in the default configuration, this is the place to start. It's often easier to start from the all configuration and take out unwanted services than to starting time with the default configuration and add together the desired services.

Annotation

The all configuration includes everthing merely proverbial kitchen sink.

How practise I practise that?

Y'all specify a particular configuration using the -c control to the run script. To run the minimal configuration, for example, use -c minimal.

Hither is an example:

Note

You can as well use --configuration = minimal, if you prefer to use long configuration names. 

                [bin]$                                  ./run.sh -c minimal

Creating a New Configuration

You aren't limited to the iii configurations JBoss provides. In fact, instead of having unneeded services loaded, wasting memory and CPU infinite, y'all tin create your own JBoss configuration that has exactly what you lot need. It's actually quite like shooting fish in a barrel to create a custom configuration.

How do I practise that?

The easiest way to create your ain configuration is to copy an existing one and then rename the folder to something that describes your configuration options. Once yous've done that you lot can add whatever new JARs and resources to that new server configuration folder.

Let's say you desire to create a new configuration based on minimal that y'all can add other services to later. You lot can copy the minimal server configuration folder to a new binder in the server folder and telephone call it my_server_config. On Unix this would be cp -R minimal my_server_config.

Yous can run your new configuration like this:

                [bin]$                                  ./run.sh -c my_server_config

The server volition outset upwards using your new configuration, and you'll run into console output that looks like this:

                =========================================================        JBoss Bootstrap Environment        JBOSS_HOME: /Users/samjr/jboss-4.0.2RC1        Coffee: coffee        JAVA_OPTS: -server -Xms128m -Xmx128m -Dprogram.proper name=run.sh        CLASSPATH: /Users/samjr/jboss-iv.0.2RC1/bin/run.jar:/lib/tools.jar      =========================================================         05:49:22,213 INFO  [Server] Starting JBoss (MX MicroKernel)...     05:49:22,217 INFO  [Server] Release ID: JBoss [Zion] four.0.2RC1 (build:     CVSTag=JBoss_4_0_2_RC1 date=200503140913)     05:49:22,220 INFO  [Server] Home Dir: /Users/samjr/jboss-4.0.2RC1     05:49:22,221 INFO  [Server] Home URL: file:/Users/samjr/jboss-4.0.2RC1/     05:49:22,223 INFO  [Server] Library URL: file:/Users/samjr/jboss-4.0.2RC1/lib/     05:49:22,226 INFO  [Server] Patch URL: nil     05:49:22,244 INFO  [Server]                                  Server Name: my_server_config                                05:49:22,246 INFO  [Server] Server Home Dir: /Users/samjr/jboss-four.0.     2RC1/server/my_server_config     05:49:22,247 INFO  [Server] Server Home URL: file:/Users/samjr/jboss-4.0.     2RC1/server/my_server_config/     05:49:22,249 INFO  [Server] Server Data Dir: /Users/samjr/jboss-4.0.2RC1/server/my_     server_config/information     05:49:22,250 INFO  [Server] Server Temp Dir: /Users/samjr/jboss-4.0.2RC1/     server/my_server_config/tmp     05:49:22,251 INFO  [Server] Server Config URL: file:/Users/samjr/jboss-four.0.     2RC1/server/my_server_config/conf/     05:49:22,285 INFO  [Server] Server Library URL: file:/Users/samjr/jboss-4.0.     2RC1/server/my_server_config/lib/     05:49:22,287 INFO  [Server] Root Deployment Filename: jboss-service.xml     05:49:22,294 INFO  [Server] Starting Full general Purpose Architecture (GPA)...          [More startup data]      05:50:44,641 INFO  [Server] JBoss (MX MicroKernel) [4.0.2RC1 (build:     CVSTag=JBoss_4_0_2_RC1 date=200503140913)] Started in 1m:21s:849ms

And with that, the new configuration is started.

What virtually...

...adding or removing services from the configuration?

While new configurations are prissy simply as a way to piece of work in an isolated sandbox, the original premise for creating a new configuration was to customize the fix of services available. We'll need a bit more background to exercise that type of serious customization. But equally we learn how to customize the services throughout this book, you'll exist able to come up back and apply those changes to your own configuration.

We hope you've seen how easy it is to get up and running and how like shooting fish in a barrel it is to create new configurations of the JBoss server. The ability is provided in a simple and configurable fashion. Congratulations for getting this far. At present let's movement on to the next affiliate and see how to package and deploy a simple application.

Go JBoss: A Developer's Notebook now with the O'Reilly learning platform.

O'Reilly members experience live online training, plus books, videos, and digital content from nearly 200 publishers.