| |
Table of Contents
<[email protected]> 29 March 2001
This document provides a concise and easy-to-read set of instructions that will get you up to speed quickly on the basics of installing and using the JBoss J2EE application server suite and the Jetty HTTP Servlet server to develop, deploy and run Enterprise Java applications.
JBoss is the brand name of the leading, Open Source, standards-compliant J2EE application server suite. The suite includes the JBossServer EJB v1.1 container and server (with partial support for the EJB v2.0 standard), the JBossMQ JMS 1.0 implemetation, the JBossNS JNDI implementation, the JBossCMP advanced O/R mapper and JDBC data object storage implementation and, the JAAS-based JBossSX security framework. All the JBoss applications are 100% Pure Java applications and are collectively the most innovative J2EE application server suite available with features including a much admired modular construction and an advanced JMX-based plug-in architecture.
Jetty is an Open Source, 100% Java HTTP Servlet Server. It is designed to be light weight, high performance, embeddable, extensible and flexible, thus making it an ideal platform for serving dynamic HTTP requests from any Java application. Jetty is also standards compliant and implements the HTTP 1.1, Servlet API 2.2 and Java Server Pages 1.1 standards. It also supports SSL as an additional security option for your application.
The JBoss organisation and key figures from Jetty's developer community have collaborated to produce an integrated version of JBoss and Jetty. In this version - called JBoss-Jetty - both JBossServer and Jetty run within the same Java VM instance. The benefit is greatly improved performance as all interactions between JBossServer and Jetty are now within a single VM. Consequently JBoss-Jetty is able to offer the highest performance, Open Source, 100% Pure Java J2EE platform for developing and deploying innovative and critical business systems and applications. Whatever your requirements, JBoss-Jetty together offers you superior return on investment (ROI) and substantially reduced time to market (RTTM) compared to other J2EE development and deployment environments.
Not so fast comrades. You need to obtain a copy of the integrated JBoss-Jetty distribution from the JBoss website. General information about all JBoss products as well as instructions on how to get a copy of JBoss-Jetty for yourself can be found in the JBoss FAQ or on the JBoss website. The rest of this document covers the following tasks:
Now it is important to be aware that both the JBoss application server suite and Jetty are still in active development. They are both evolving as issues are reported, fixed and, new features are identified and added. This means that some of the information contained in this document may be out of date with respect to your copy of JBoss-Jetty. This is even more likely to be the case if you have the latest CVS or developer version of JBoss-Jetty, JBoss or Jetty.
If this is the case with you or, if you have any further comments or suggestions about this document or JBoss-Jetty then please do one or more of the following:
Join the JBoss Mailing List if your comments or suggestions are relevant to JBoss.
Join the Jetty Mailing List if your comments or suggestions are relevant to Jetty.
Before you can use JBoss-Jetty you must ensure that your computer's configuration meets or exceeds the JBoss-Jetty system requirements. To ensure that your computer can run JBoss-Jetty properly we will check the following:
JBoss-Jetty is a suite of enterprise application server applications and, like all such complex software, the physical computer on which JBoss-Jetty is deployed should be configured according to the requirements of the processing load that it will be expected to serve. I don't cover Server Configuration and Capacity Planning any further in this document. A minimum recommended configuration for a computer running JBoss-Jetty is shown below. JBoss-Jetty would work - albeit more slowly - on lesser specified systems:
Table 11.1. Minimum recommended specifications for a JBoss-Jetty computer
| OPERATING SYSTEM | Microsoft Windows 2000 or Linux or Other OS |
| JAVA PLATFORM | JDK 1.3 (or JDK1.2.2 if JDK1.3 is not available) |
| CPU | 233Mhz AMD K6-2 or Intel Pentium II |
| RAM | 64MB (128MB for Windows 2000) |
| DISK INTERFACE TYPE | UDMA/66 |
| HARD DISK SIZE | 6GB |
| NETWORKING | 10/100Mbs Ethernet NIC |
JBoss-Jetty is a 100% Pure Java suite of enterprise application servers and your system must have a Java 2 JDK installed. More specifically, the Java 2 JDK v1.3 (i.e. JDK1.3 or later) is recommended for use with JBoss-Jetty. Although JBoss-Jetty has not been tested an all JDK1.3 platforms, it should run on all JDK1.3 installations regardless of the underlying OS platform. Official JDKs are available to download from Sun at http://java.sun.com/jdk/.
JBoss-Jetty can be used (and has been used) with the Sun Java 2 JDK v1.2.2 but some features - most notably hot deployment - will not work. Since a JDK1.3 distribution is available for most popular OS platforms, JDK v1.2.2 is not recommended for use with JBoss-Jetty. More information is available on the JBoss mailing list archives.
Most installations of JBoss-Jetty will require access to a relational database management system (RDBMS) (or more informally a database server). A database server is used to store and manipulate data by JSP pages, Servlets and EJBeans. This is often the basis of dynamic web sites and web applications.
If you plan to use Entity beans with CMP with your copy of JBoss-Jetty, then you will need to ensure that JBoss-Jetty has access to a database server. Examples of RDBMS that can be used with JBoss-Jetty are Hypersonic SQL(supplied with JBoss-Jetty), MySQL, Oracle 8i/9, Sybase ASE, Microsoft Access and Microsoft SQL Server. The criteria for choosing a database is as complex as those for choosing an OS platform. As a result, JBoss-Jetty doesn't mandate any particular RDBMS and can be configured to work all the popular RDBMS and many other RDBMS not listed here.
You will need an appropriate JDBC driver for your database server before it can be used with JBoss-Jetty (or indeed with any other Java application). On the Microsoft Windows™ platforms, Sun's JDBC-ODBC bridge may be used in lieu of a native JDBC driver but, this is not a recommended solution. You are well advised to obtain a more robust JDBC driver for your chosen RDBMS. For more information see:
??? for basic information on configuring JBoss-Jetty to use a database server.
Chapter 3 for more information on Container Managed Persistence using a database server
Chapter 11 for documents addressing the configuration of specific RDBMS
At this stage you have a system that meets JBoss-Jetty's system requirements. You should also have a copy of the JBoss-Jetty distribution. If you don't have JBoss, see the JBoss FAQ or the JBoss website for instructions on how to obtain it.
Depending on your requirements you would have either chosen to download the JBoss binary distribution or you may have downloaded a snapshot of the JBoss-Jetty source tree via CVS. In the latter case you will need to build both JBoss-Jetty. This document assumes you have the JBoss-Jetty binary distribution but, the process is easy enough that you should still be able to adapt the instructions below if you follow the CVS route.
To install the files from the JBoss distribution archive onto your system do the following:
Create a directory on your system for the JBoss-Jetty application. This directory will thereafter be referred to as the JBoss installation directory or just as JBOSSJETTY_HOME. Below are the commands for creating a JBoss-Jetty installation directory on Windows and Linux/Unix platforms. In the examples, the new directory is also made the current working directory. You might choose a different location for JBoss-Jetty on your system.
Change the current directory to the JBoss installation directory (if you haven't already done so) and extract the files fom the JBoss-Jetty distribution archive to the installation directory. The general form of the command to extract the files is:
jar xvf jBoss-archive-filename
As an example, let's say you have a JBoss-Jetty binary distribution archive named jboss-jetty.zip and it is stored in a directory called C:\Packages or ~/packages on a Windows or Linux/Unix computer respectively. To extract the JBoss-Jetty files from the archive, you would type the following commands on the Windows and Linux/Unix platforms.
| Windows 95/98, Windows NT or Windows 2000 | Linux, Solaris and other Unixes |
chdir C:\JavaApps\jboss-jetty jar xvf C:\Packages\jboss-jetty.zip | cd /usr/bin/jboss-jetty jar xvf ~/packages/jboss-jetty.zip |
For the above command to work, the bin sub-directory of the JDK directory tree must be added to your PATH environment variable. You might also be able to use a compatible de-archiver such as winzip or gzip to extract the files.
You should now have the JBoss-Jetty application's files copied to the installation directory on your system.
Now that you have copied the JBoss-Jetty application files from the JBoss binary distribution archive to the installation directory, the next step is real easy. Jboss-Jetty is supplied with a command file called run.bat jetty (or run.sh jetty on Linux/Unix) that has been carefully designed to start JBoss-Jetty. So, to start the JBoss-Jetty application server suite, use the run jetty command as shown below:
| Windows 95/98, Windows NT or Windows 2000 | Linux, Solaris and other Unixes |
chdir C:\JavaApps\jboss-jetty run jetty | cd /usr/bin/jboss-jetty ./run jetty |
When JBoss-Jetty is started, it should respond with about three to fours screens of console messages. None of the messages should be an error message. This is entirely normal. In addition, JBoss-Jetty is preconfigured with an application that it will automatically deploy when it is started. This is to alert you immediately if, for any reason, the application fails to deploy properly.
As a quick sanity test to ensure that all is well with your copy of JBoss-Jetty, fire up a copy of your favourite web browser and open the following URLs with it. If you are reading this document on the same computer that you have installed JBoss-Jetty, then you may just click the links below (don't forget to use the BACK button to return here!).
http://localhost:8080/jboss/ - this should take you to the sample application that was automatically deployed when JBoss-Jetty was started.
http://localhost:8080/ - this should take you to the HTML documentation for Jetty.
http://localhost:8080/demo/ - this should take you to some sample files that are normally supplied with Jetty.
Now that you've seen how to start JBoss-Jetty and hopefully verified that all is well, you should also know that to stop JBoss-Jetty, you need to press the [CRTL]+[C] key combination. This would trigger a controlled shutdown process within JBoss-Jetty.
[TBD]
The procedure for deploying applications with JBoss-Jetty, the application must be packaged as a JAR, WAR or EAR file. Examples of what-to-do to deploy Jetty-specific application types with JBoss-Jetty?
In this section you will learn the basics of deploying an application composed entirely of .jsp files with JBoss-Jetty. You will create and deploy an application named hello. You will also create a sample.jsp within hello that will be accessible as http://localhost/hello/sample.jsp on the computer running JBoss-Jetty. For other computers, just replace localhost with the computer's IP name or address.
Open the file jetty.xml in %JBOSS_HOME%/jBoss-dir/conf/jetty/ your text editor
Add the following lines before </configure>. These lines create an application called hello and configure it's deployment directory to be helloapp:
<Call name="addWebApplication">
<Arg>/hello/*</Arg>
<Arg><SystemProperty name="jetty.home" default="."/>/webapps/helloapp/</Arg>
<Arg><SystemProperty name="jetty.home" default="."/>/etc/webdefault.xml/</Arg>
</Call>
Create the directory %JBOSS_HOME%/jetty-dir/webapps/helloapp
Create (or copy) a .jsp file inside the newly created directory. Call this file sample.jsp.
On the JBoss-Jetty computer, start jBoss/Jetty and surf to http://localhost/hello/sample.jsp
You should find that the sample.jsp file is automatically compiled and it's output is displayed in your browser.
The sample.jsp file was compiled by default because you used /etc/webdefault.xml as the third argument of the addWebApplication call above. Have a look at the contents of the file %JBOSS_HOME%/jetty-dir/etc/webdefault.xml if you want learn more about how to map calls to a servlet (all .jsp files are processed by a servlet that compiles them first according to webdefault.xml).
If you want to add more jsp-files, just drop them in the helloapp directory and do as you did with sample.jsp previously.
 | |