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 .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 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. Contents Introduction Introduction to Java Application Server Guide 7 Organization of This Document 7 See Also 8 Chapter 1 Application Server Overview 9 JBoss in Mac OS X Server 9 Three Deployment Configurations 10 Chapter 2 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 Chapter 3 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 3 2005-08-11 | © 2003, 2005 Apple Computer, Inc. All Rights Reserved. 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 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 Chapter 5 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 Configuring Applications 11 Figure 2-1 Figure 2-2 Figure 2-3 Figure 2-4 Figure 2-5 Figure 2-6 The Load Application window of the deployment tool 14 The Loaded Application window 15 The deployment-tool main window 16 The Quick Config pane of a component's configuration window 17 A module-settings window 18 The Save Application window of the deployment tool 18 Chapter 3 Configuring and Deploying Sun's Pet Store 21 Table 3-1 Relationship information for the Customer module 27 Chapter 4 Administering Application Servers 37 Figure 4-1 Figure 4-2 Figure 4-3 Figure 4-4 Figure 4-5 Figure 4-6 Figure 4-7 The Configuration window of the management tool 40 The JBoss Management Console window 40 The JBoss Management Console window showing the Security Configuration pane of the log-in configuration service 41 The JBoss Management Console window showing the Statistics pane of the Pet Store ShoppingCart enterprise bean 42 The JBoss Management Console window showing one of the configuration panes for the JMS Directory Service 43 The JBoss Management Console window showing the statistics of the Deploy Service 44 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 Figure 5-2 The WebApp window of the petstore.ear archive 48 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 2005-08-11 | © 2003, 2005 Apple Computer, Inc. All Rights Reserved. 7 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 2005-08-11 | © 2003, 2005 Apple Computer, Inc. All Rights Reserved. 9 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 ...