Java Application Server Guide
For Version 10.3 or Later
2005-08-11
Apple Inc.
© 2003, 2005 Apple Computer, Inc.
All rights reserved.
No part of this publication may be
reproduced, stored in a retrieval system, or
transmitted, in any form or by any means,
mechanical, electronic, photocopying,
recording, or otherwise, without prior
written permission of Apple Inc., with the
following exceptions: Any person is hereby
authorized to store documentation on a
single computer for personal use only and
to print copies of documentation for
personal use provided that the
documentation contains Apple’s copyright
notice.
The Apple logo is a trademark of Apple Inc.
Use of the “keyboard” Apple logo
(Option-Shift-K) for commercial purposes
without the prior written consent of Apple
may constitute trademark infringement and
unfair competition in violation of federal
and state laws.
No licenses, express or implied, are granted
with respect to any of the technology
described in this document. Apple retains
all intellectual property rights associated
with the technology described in this
document. This document is intended to
assist application developers to develop
applications only for Apple-labeled or
Apple-licensed computers.
Every effort has been made to ensure that
the information in this document is
accurate. Apple is not responsible for
typographical errors.
Apple Inc.
1 Infinite Loop
Cupertino, CA 95014
408-996-1010
Microsystems, Inc. in the U.S. and other
countries.
Simultaneously published in the United
States and Canada.
Even though Apple has reviewed this document,
APPLE MAKES NO WARRANTY OR
REPRESENTATION, EITHER EXPRESS OR
IMPLIED, WITH RESPECT TO THIS
DOCUMENT, ITS QUALITY, ACCURACY,
MERCHANTABILITY, OR FITNESS FOR A
PARTICULAR PURPOSE. AS A RESULT, THIS
DOCUMENT IS PROVIDED “AS IS,” AND
YOU, THE READER, ARE ASSUMING THE
ENTIRE RISK AS TO ITS QUALITY AND
ACCURACY.
IN NO EVENT WILL APPLE BE LIABLE FOR
DIRECT, INDIRECT, SPECIAL, INCIDENTAL,
OR CONSEQUENTIAL DAMAGES
RESULTING FROM ANY DEFECT OR
INACCURACY IN THIS DOCUMENT, even if
advised of the possibility of such damages.
THE WARRANTY AND REMEDIES SET
FORTH ABOVE ARE EXCLUSIVE AND IN
LIEU OF ALL OTHERS, ORAL OR WRITTEN,
EXPRESS OR IMPLIED. No Apple dealer, agent,
or employee is authorized to make any
modification, extension, or addition to this
warranty.
Some states do not allow the exclusion or
limitation of implied warranties or liability for
incidental or consequential damages, so the
above limitation or exclusion may not apply to
you. This warranty gives you specific legal
rights, and you may also have other rights which
vary from state to state.
.Mac is a service mark of Apple Computer,
Inc.
Apple, the Apple logo, Logic, Mac, and Mac
OS are trademarks of Apple Computer, Inc.,
registered in the United States and other
countries.
Finder is a trademark of Apple Computer,
Inc.
Java and all Java-based trademarks are
trademarks or registered trademarks of Sun
Contents
Introduction
Chapter 1
Chapter 2
Chapter 3
Introduction to Java Application Server Guide 7
Organization of This Document 7
See Also 8
Application Server Overview 9
JBoss in Mac OS X Server 9
Three Deployment Configurations 10
Configuring Applications 11
Starting the Application Server 11
Configuring Your Application 13
Starting the JBoss Deployment Tool 14
Loading Your Application 14
Configuring Your Application’s Components 17
Saving a Configured Application 18
Deploying Your Application 19
Configuring and Deploying Sun’s Pet Store 21
Set Up the Environment 21
Configure the Pet Store Enterprise Application 22
Open the petstore.ear File in the Deployment Tool 22
Configure Application-Wide Settings 23
Configure the AsyncSender Enterprise Bean 24
Configure the Catalog Enterprise Bean 24
Configure the Customer Module 25
Configure the PetStore Web Application 29
Configure the SignOn Module 30
Configure the User Enterprise Bean 30
Configure the Counter Enterprise Bean 30
Save the Application 31
Configure the Supplier Enterprise Application 31
Open the supplier.ear file in the Deployment Tool 31
Configure Application-Wide Settings 31
Configure the Supplier Module 32
2005-08-11 | © 2003, 2005 Apple Computer, Inc. All Rights Reserved.
3
CONTENTS
Configure the SupplierPurchaseOrder Module 33
Configure the Supplier Web Application Module 34
Save the Application 35
Deploy and Test the Application 35
Chapter 4
Chapter 5
Administering Application Servers 37
Logging In to the Management Tool 37
Choosing a Task 39
Managing Application Servers 40
Configuring Application Servers 43
Monitoring Application Servers 43
Starting and Stopping Services 44
Creating a Data Source 45
Creating a Topic or a Queue 45
Deploying Applications 46
Balancing User Load and Replicating Sessions 47
Distributable Applications 47
Load Balancing and Clustering 48
Enable Load Balancing in the Web Server 48
Enable Load Balancing in the Application Servers 51
Test the Configuration 52
Document Revision History 53
Glossary 55
4
2005-08-11 | © 2003, 2005 Apple Computer, Inc. All Rights Reserved.
Figures and Tables
Chapter 2
Chapter 3
Chapter 4
Configuring Applications 11
Figure 2-1 The Load Application window of the deployment tool 14
Figure 2-2 The Loaded Application window 15
Figure 2-3 The deployment-tool main window 16
Figure 2-4 The Quick Config pane of a component’s configuration window 17
Figure 2-5 A module-settings window 18
Figure 2-6 The Save Application window of the deployment tool 18
Configuring and Deploying Sun’s Pet Store 21
Table 3-1 Relationship information for the Customer module 27
Administering Application Servers 37
Figure 4-1 The Configuration window of the management tool 40
Figure 4-2 The JBoss Management Console window 40
Figure 4-3 The JBoss Management Console window showing the Security Configuration
pane of the log-in configuration service 41
Figure 4-4 The JBoss Management Console window showing the Statistics pane of the
Pet Store ShoppingCart enterprise bean 42
Figure 4-5 The JBoss Management Console window showing one of the configuration
panes for the JMS Directory Service 43
Figure 4-6 The JBoss Management Console window showing the statistics of the Deploy
Service 44
Figure 4-7 The JBoss Management Console window showing the Start or Stop Services
pane 45
Chapter 5
Balancing User Load and Replicating Sessions 47
Figure 5-1 The WebApp window of the petstore.ear archive 48
Figure 5-2 The workers.properties file in /etc/httpd 50
5
2005-08-11 | © 2003, 2005 Apple Computer, Inc. All Rights Reserved.
FIGURES AND TABLES
6
2005-08-11 | © 2003, 2005 Apple Computer, Inc. All Rights Reserved.
INTRODUCTION
Introduction to Java Application Server
Guide
Note: This document was previously titled Mac OS X Server Java Application Server Administration.
JBoss is a powerful Java-based open-source application server that is very popular among Java 2,
Enterprise Edition (J2EE) application developers. This document describes how to configure and use
the JBoss application server in Mac OS X Server, which lets you deploy J2EE applications easily and
reliably.
This document is intended for system administrators, J2EE application assemblers, and developers.
It assumes you have a solid background in system administration and J2EE technology. You must be
familiar with Mac OS X Server, especially how to use Terminal to issue shell commands. Knowledge
of database engines, such as MySQL, is helpful but not required.
Organization of This Document
This document has the following chapters:
“Application Server Overview” (page 9) provides an overview of JBoss for Mac OS X Server.
■
“Configuring Applications” (page 11) explains how to perform certain tasks with the deployment
■
tool, such as opening, configuring, and saving application archives.
“Configuring and Deploying Sun’s Pet Store” (page 21) walks you through configuring and
■
deploying Sun’s Pet Store application in Mac OS X Server.
“Administering Application Servers” (page 37) teaches you how to manage application servers,
■
which are JBoss instances running on one or more computers.
“Balancing User Load and Replicating Sessions” (page 47) explains how to enable an application
■
to be distributable among cluster nodes and walks you through configuring HTTP load balancing
for Pet Store using three computers.
This document also contains a revision history, a glossary, and an index.
Organization of This Document 7
2005-08-11 | © 2003, 2005 Apple Computer, Inc. All Rights Reserved.
INTRODUCTION
Introduction to Java Application Server Guide
See Also
To use this document to its fullest, you should download its companion files, which are packaged in
Application_Server_companion.zip, located in the same webpage from which you obtained this
document.
For an introduction to J2EE, visit http://java.sun.com/j2ee. You can get detailed information on JBoss
at http://jboss.org.
8
See Also
2005-08-11 | © 2003, 2005 Apple Computer, Inc. All Rights Reserved.
CHAPTER 1
Application Server Overview
JBoss is an open-source highly popular Java-based application server. Based on the Java 2, Enterprise
Edition (J2EE) platform, JBoss provides an affordable delivery system for enterprise applications.
Applications that follow the J2EE standard can be deployed on other application servers, such as
WebLogic, WebSphere, and JRun, with little or no modification. JBoss provides many useful features
in addition those defined in the J2EE standard, including support for clustering, session replication,
mail, and security.
Mac OS X Server includes two easy-to-use, HTML-based tools that facilitate the configuration of J2EE
applications for deployment: The deployment tool and the management tool. The deployment tool
allows you to open application or component archives (EAR files, WAR files, JAR files, SAR files, and
so on) without having to manually decompress the archives. The application lets you view or change
the values of settings specified in the META-INF and WEB-INF directories of the archives. See
“Configuring Applications” (page 11) for more information.
The management tool allows you to manage application servers (JBoss instances) running on one or
more computers. This application lets you start and stop services provided by individual application
servers, configure services, and create data sources, queues, and topics. See “Administering Application
Servers” (page 37) for details.
This chapter provides an overview of JBoss for Mac OS X Server.
JBoss in Mac OS X Server
Mac OS X Server version 10.3 includes JBoss version 3.2.2RC2. To provide a high level of availability,
Mac OS X Server includes a “watchdog” process that ensures that the application server is always
running (if you turn on the application server in Server Admin). If the application server freezes or
crashes, the daemon restarts it automatically.
In addition, Mac OS X Server offers load balancing and session failover through Apache and JBoss:
■
Apache, coupled with the mod_jk plug-in, provides HTTP load balancing with session affinity
(sticky sessions) and connects to JBoss instances through AJP connectors.
JBoss offers session failover through HTTP session state replication in the cluster configuration.
■
JBoss also provides load balancing for enterprise beans, including failover for stateful session
■
beans, and support for session affinity.
JBoss in Mac OS X Server 9
2005-08-11 | © 2003, 2005 Apple Computer, Inc. All Rights Reserved.
CHAPTER 1
Application Server Overview
In Mac OS X Server, JBoss is configured to use Tomcat (using the AJP connector) as its web server
and servlet container. In addition, HTTP and HTTPS (through port 8443) are enabled by default.
You can manage the application server from the Server Admin application. This provides you with
a simple way to start, stop, and monitor the application server. You can use the command line, if you
prefer.
Mac OS X Server includes two applications that allow you to deploy applications on JBoss and monitor
their performance. They are the JBoss deployment tool and the JBoss management tool.
The deployment tool allows you to configure an application or an application component so that, for
example, it accesses the appropriate data sources and database tables when it’s run. This is how
application developers decouple business logic from the database engine that is used to persist data.
That way, you can use the database engine that meets your needs and not the one the developer used
while developing the application. For details on the deployment tool, see “Configuring
Applications” (page 11).
The management tool lets you administer the local (running on the computer you are logged in to)
application server, and monitor local and remote (running on a computer in the local network)
application servers. As part of administering an application server, you may start and stop services,
configure services, deploy applications, and add data sources, queues, and topics. When monitoring
an application server, the management tool lets you access the statistics provided by the resources
and services running on it. For example, a service may indicate its name, its purpose, and when it
was started. For more information on the management tool, see “Administering Application
Servers” (page 37).
Three Deployment Configurations
In Mac OS X Server, all the JBoss configurable settings are set up for maximum J2EE compliance.
There are three standard deployment configurations in JBoss for Mac OS X Server:
The development configuration offers increased logging and also consults schema documents.
■
As a result, an application is not deployed when the configuration files do not adhere to their
respective schemas.
The standalone configuration is set up for high performance on a single server.
■
The cluster configuration is optimized for high performance on a cluster of servers. This includes
■
load balancing as well as session replication among stateful session beans and HTTP sessions.
10
Three Deployment Configurations
2005-08-11 | © 2003, 2005 Apple Computer, Inc. All Rights Reserved.
CHAPTER 2
Configuring Applications
Before you can deploy an application on an application server, you have to start the application server
and then configure or assemble the application. This is the process through which you specify data
sources, database mappings, JNDI resources, and so on.
You configure J2EE applications by modifying XML files in META-INF and WEB-INF directories in
application archives. Performing this task manually is tedious and error prone. The JBoss deployment
tool allows you to configure applications without having to unarchive EAR files, WAR files, or JAR
files, as the tool lets you configure these files directly.
This chapter explains how to start the application server and configure and deploy your application.
Starting the Application Server
To configure an application using the deployment tool, you must connect to a running application
server. Follow these steps to start the application server on a computer.
1.
Launch Server Admin, located in /Applications/Server.
Starting the Application Server 11
2005-08-11 | © 2003, 2005 Apple Computer, Inc. All Rights Reserved.
CHAPTER 2
Configuring Applications
2. In the Computers & Services list, select Application Server.
12
Starting the Application Server
2005-08-11 | © 2003, 2005 Apple Computer, Inc. All Rights Reserved.
CHAPTER 2
Configuring Applications
3. In the configuration pane, click Settings. From Configuration Name pop-up menu, choose the
appropriate configuration.
4. Click the Start Service toolbar button. After a few seconds the application server should be running.
You can confirm that JBoss is running by accessing http://localhost:8080 in your web browser.
You should see a webpage titled Welcome to JBoss/Tomcat.
You can also start JBoss in Terminal with the following command:
$ /Library/JBoss/3.2/bin/run.sh -c deploy-standalone
To get detailed information on JBoss activities, use the develop configuration. This is useful when
you need to make sure JBoss notices when you deploy or undeploy a module, or when you need to
determine whether exceptions are thrown as JBoss starts a deployed application. The develop
configuration produces a detailed log of JBoss activities. It is more useful when you launch the
application server from the command line because you see the results of actions immediately in the
Terminal window from which you launch the application server.
Configuring Your Application
The following sections teach you how to start the deployment tool and configure your application.
Configuring Your Application 13
2005-08-11 | © 2003, 2005 Apple Computer, Inc. All Rights Reserved.
CHAPTER 2
Configuring Applications
Starting the JBoss Deployment Tool
To start the deployment tool, double-click DeploymentTool.woa in /Library/JBoss/Applications
or enter the following command in Terminal:
$ /Library/JBoss/Applications/DeploymentTool.woa/DeploymentTool
After a moment, the Load Application window appears.
Note: Running the JBoss Deployment Tool requires a web browser that supports Frames and Javascript.
Some web browsers may need to have pop-up blocking disabled.
Loading Your Application
The Load Application window is where you specify the location of the application or component you
want to configure. Although the window is titled Load Application, you can also use the deployment
tool to configure EAR files, WAR files, and JAR files.
“Figure 3-1” shows the Load Application window.
Figure 2-1 The Load Application window of the deployment tool
1. Enter the full path to the file in the text field in the Load Application window, and click Load
Application.
Note: The file path you enter in the text field is from the perspective of the server the deployment
tool runs on. That is, if you access the deployment tool from a web browser that runs on a different
computer, the archive you configure must reside on the server, not the computer the web browser
runs on.
14
Normally, you cannot save an application with invalid XML files. That is, you have to configure
all the elements that show up in red in the main window. You can override this by deselecting
Validate XML Files in the Load Application window. However, you may not be able to reload
an application that has been saved in this state.
Configuring Your Application
2005-08-11 | © 2003, 2005 Apple Computer, Inc. All Rights Reserved.
CHAPTER 2
Configuring Applications
After the deployment tool loads the application, it displays the Loaded Application window,
shown in “Figure 3-2”.
Figure 2-2 The Loaded Application window
2. Click “Click here to continue” to move on.
The deployment tool displays the main window (also known as the navigation window). The
main window presents a hierarchy of components generated from the XML files present in the
META-INF and WEB-INF directories of the components contained in the archive you opened. For
example, “Figure 3-3” shows the components present in the petstore.ear file of Sun
Microsystem’ s Pet Store application. You must configure the items in red to save the application.
“Configuring Your Application’s Components” (page 17) shows you how to do this.
Configuring Your Application 15
2005-08-11 | © 2003, 2005 Apple Computer, Inc. All Rights Reserved.
CHAPTER 2
Configuring Applications
Figure 2-3 The deployment-tool main window
16
“Figure 3-3” shows the components of the petstore.ear archive. The following list describes some
of the items in the main window:
PetStoreEAR (Application) Represents the Pet Store enterprise-application archive.
■
Application Settings Clicking this link allows you to configure settings that affect all the modules
■
in the archive when the application is deployed.
AsyncSenderEJB (EJB) Represents the archive (JAR file) that contains the files that define the
■
AsyncSender enterprise bean (the asyncsender-ejb.jar file). Clicking the Module Settings link
lets you configure module-wide settings and set default values for some settings for all the
enterprise beans defined in the module. See “Configure the Customer Module” (page 25) for an
example.
PetStoreWAR (WebApp) Represents the archive (WAR file) that contains the files that define
■
the web module of the Pet Store enterprise application.
Configuring Your Application
2005-08-11 | © 2003, 2005 Apple Computer, Inc. All Rights Reserved.
CHAPTER 2
Configuring Applications
Configuring Your Application’s Components
To configure a component, you choose it from the main window by clicking the appropriate link.
This causes the deployment tool to display the configuration window for the component. As you can
see in “Figure 3-4”, this is a tabbed window that contains one or more panes, which you use to
configure specific aspects of the component. The configuration window also contains a Quick Config
pane, which contains elements of the component that you must configure for the application to be
deployable. “Figure 3-4” shows the Quick Config pane of the CatalogEJB module. It indicates that
the JBoss resource references must be configured. The JBoss resource references also appear in the
JNDI Resource Refs pane. However, you need to configure them in only one of the two panes.
Figure 2-4 The Quick Config pane of a component’s configuration window
Note: For applications with many components, you may want to configure the Quick Config pages
of the invalid components and save the application. Then you can configure each component further
in a piecemeal fashion.
Some settings apply to an entire module, for example, security roles. In addition, some module settings
serve as defaults for settings of individual components in the module. “Figure 3-5” shows some of
the module settings of the CustomerJAR module of the petstore.ear application. Configuring
modules settings can help to speed up the configuration of a module. See “Configure Module-Wide
Settings” (page 25) for an example.
Configuring Your Application 17
2005-08-11 | © 2003, 2005 Apple Computer, Inc. All Rights Reserved.
Loading...