JBoss Enterprise Web Platform 5

Administration And Configuration Guide

for use with JBoss Enterprise Web Platform 5

Edition 5.1.1

JBoss Community

Edited by

JBoss Community

Edited by

Isaac Rooskov

Edited by

Laura Bailey

Legal Notice

Copyright © 2011 Red Hat, Inc.
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack Logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.

Abstract

This book is a guide to the administration and configuration of JBoss Enterprise Web Platform 5 and its patch releases.
Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Getting Help and Giving Feedback
2.1. Do You Need Help?
2.2. Give us Feedback
What this Book Covers
1. Introduction
1.1. JBoss Enterprise Web Platform Use Cases
I. JBoss Enterprise Web Platform Infrastructure
2. JBoss Enterprise Web Platform 5 Architecture
2.1. The JBoss Enterprise Web Platform Bootstrap
2.2. Hot Deployment
II. JBoss Enterprise Web Platform 5 Configuration
3. Network
3.1. IPv6 Support
4. Logging
4.1. Logging Defaults
4.2. Component-Specific Logging
4.2.1. SQL Logging with Hibernate
4.2.2. Transaction Service Logging
5. Deployment
5.1. Deployable Application Types
5.1.1. Exploded Deployment
5.2. Standard Server Profiles
6. Microcontainer
6.1. An overview of the Microcontainer modules
6.2. Configuration
6.3. References
7. The JNDI Naming Service
7.1. An Overview of JNDI
7.1.1. Names
7.1.2. Contexts
7.2. The JBoss Naming Service Architecture
7.3. The Naming InitialContext Factories
7.3.1. The standard naming context factory
7.3.2. The org.jboss.naming.NamingContextFactory
7.3.3. Naming Discovery in Clustered Environments
7.3.4. The HTTP InitialContext Factory Implementation
7.3.5. The Login InitialContext Factory Implementation
7.3.6. The ORBInitialContextFactory
7.4. JNDI over HTTP
7.4.1. Accessing JNDI over HTTP
7.4.2. Accessing JNDI over HTTPS
7.4.3. Securing Access to JNDI over HTTP
7.4.4. Securing Access to JNDI with a Read-Only Unsecured Context
7.5. Additional Naming MBeans
7.5.1. JNDI Binding Manager
7.5.2. The org.jboss.naming.NamingAlias MBean
7.5.3. org.jboss.naming.ExternalContext MBean
7.5.4. The org.jboss.naming.JNDIView MBean
7.6. J2EE and JNDI - The Application Component Environment
7.6.1. ENC Usage Conventions
8. Web Services
8.1. The need for web services
8.2. What web services are not
8.3. Document/Literal
8.4. Document/Literal (Bare)
8.5. Document/Literal (Wrapped)
8.6. RPC/Literal
8.7. RPC/Encoded
8.8. Web Service Endpoints
8.9. Plain old Java Object (POJO)
8.10. The endpoint as a web application
8.11. Packaging the endpoint
8.12. Accessing the generated WSDL
8.13. EJB3 Stateless Session Bean (SLSB)
8.14. Endpoint Provider
8.15. WebServiceContext
8.16. Web Service Clients
8.16.1. Service
8.16.2. Dynamic Proxy
8.16.3. WebServiceRef
8.16.4. Dispatch
8.16.5. Asynchronous Invocations
8.16.6. Oneway Invocations
8.17. Common API
8.17.1. Handler Framework
8.17.2. Message Context
8.17.3. Fault Handling
8.18. DataBinding
8.18.1. Using JAXB with non annotated classes
8.19. Attachments
8.19.1. MTOM/XOP
8.19.2. SwaRef
8.20. Tools
8.20.1. Bottom-Up (Using wsprovide)
8.20.2. Top-Down (Using wsconsume)
8.20.3. Client Side
8.20.4. Command-line & Ant Task Reference
8.20.5. JAX-WS binding customization
8.21. Web Service Extensions
8.21.1. WS-Addressing
8.21.2. WS-Security
8.21.3. XML Registries
8.22. JBossWS Extensions
8.22.1. Proprietary Annotations
8.23. Web Services Appendix
8.24. References
9. JBoss AOP
9.1. Some key terms
9.2. Creating Aspects in JBoss AOP
9.3. Applying Aspects in JBoss AOP
9.4. Packaging AOP Applications
9.5. The JBoss AspectManager Service
9.6. Loadtime transformation in the JBoss Enterprise Web Platform Using Sun JDK
9.7. JRockit
9.8. Improving Loadtime Performance in the JBoss Enterprise Web Platform Environment
9.9. Scoping the AOP to the classloader
9.9.1. Deploying as part of a scoped classloader
9.9.2. Attaching to a scoped deployment
10. Transaction Management
10.1. Overview
10.2. Configuration Essentials
10.3. Transactional Resources
10.4. Last Resource Commit Optimization (LRCO)
10.5. Transaction Timeout Handling
10.6. Recovery Configuration
10.7. Transaction Service FAQ
11. Use Alternative Databases with JBoss Enterprise Platform
11.1. How to Use Alternative Databases
11.2. Install JDBC Drivers
11.2.1. Special Notes on Sybase
11.2.2. Configuring JDBC DataSources
11.3. Common Database-Related Tasks
11.3.1. Security and Pooling
11.3.2. Change Database for the JMS Services
11.3.3. Support Foreign Keys in CMP Services
11.3.4. Specify Database Dialect for Java Persistence API
11.3.5. Change Other JBoss Enterprise Platform Services to use the External Database
11.3.6. A Special Note About Oracle Databases
12. Datasource Configuration
12.1. Types of Datasources
12.2. Datasource Parameters
12.3. Datasource Examples
12.3.1. Generic Datasource Example
12.3.2. Configuring a DataSource for Remote Usage
12.3.3. Configuring a Datasource to Use Login Modules
13. Pooling
13.1. Strategy
13.2. Sticky Transactions
13.3. Workaround for Oracle
13.4. Pool Access
13.5. Pool Filling
13.6. Idle Connections
13.7. Dead connections
13.7.1. Valid connection checking
13.7.2. Errors during SQL queries
13.7.3. Changing/Closing/Flushing the pool
14. Frequently Asked Questions
14.1. I have problems with Oracle XA
III. Clustering Guide
15. Introduction and Quick Start
15.1. Quick Start Guide
15.1.1. Initial Preparation
15.1.2. Launching a JBoss Enterprise Web Platform Cluster
15.1.3. Web Application Clustering Quick Start
16. Clustering Concepts
16.1. Cluster Definition
16.2. Service Architectures
16.2.1. Client-side interceptor architecture
16.2.2. External Load Balancer Architecture
16.3. Load Balancing Policies
16.3.1. Client-side interceptor architecture
16.3.2. External load balancer architecture
17. Clustering Building Blocks
17.1. Group Communication with JGroups
17.1.1. The Channel Factory Service
17.1.2. The JGroups Shared Transport
17.1.3. Distributed Caching with JBoss Cache
17.1.4. The HAPartition Service
18. Clustered JNDI Services
18.1. How it works
18.2. Client configuration
18.2.1. For clients running inside the Enterprise Web Platform
18.2.2. For clients running outside the Enterprise Web Platform
18.3. JBoss configuration
18.3.1. Adding a Second HA-JNDI Service
19. Clustered Session EJBs
19.1. Stateless Session Bean in EJB 3.0
19.2. Stateful Session Beans in EJB 3.0
19.2.1. The EJB application configuration
19.2.2. Optimize state replication
19.2.3. CacheManager service configuration
19.3. Stateless Session Bean in EJB 2.x
19.4. Stateful Session Bean in EJB 2.x
19.4.1. The EJB application configuration
19.4.2. Optimize state replication
19.4.3. The HASessionStateService configuration
19.4.4. Handling Cluster Restart
19.4.5. JNDI Lookup Process
19.4.6. SingleRetryInterceptor
20. Clustered Entity EJBs
20.1. Entity Bean in EJB 3.0
20.1.1. Configure the distributed cache
20.1.2. Configure the entity beans for cache
20.1.3. Query result caching
20.2. Entity Bean in EJB 2.x
21. HTTP Services
21.1. Configuring load balancing using Apache and mod_jk
21.1.1. Download the software
21.1.2. Configure Apache to load mod_jk
21.1.3. Configure worker nodes in mod_jk
21.1.4. Configuring JBoss to work with mod_jk
21.1.5. Configuring the NSAPI connector on Solaris
21.2. Configuring HTTP session state replication
21.2.1. Enabling session replication in your application
21.2.2. HttpSession Passivation and Activation
21.2.3. Configuring the JBoss Cache instance used for session state replication
21.3. Using FIELD-level replication
21.4. Using Clustered Single Sign-on (SSO)
21.4.1. Configuration
21.4.2. SSO Behavior
21.4.3. Limitations
21.4.4. Configuring the Cookie Domain
22. Clustered Deployment Options
22.1. Clustered Singleton Services
22.1.1. HASingleton Deployment Options
22.1.2. Determining the master node
22.2. Farming Deployment
23. JGroups Services
23.1. Configuring a JGroups Channel's Protocol Stack
23.1.1. Common Configuration Properties
23.1.2. Transport Protocols
23.1.3. Discovery Protocols
23.1.4. Failure Detection Protocols
23.1.5. Reliable Delivery Protocols
23.1.6. Group Membership (GMS)
23.1.7. Flow Control (FC)
23.2. Fragmentation (FRAG2)
23.3. State Transfer
23.4. Distributed Garbage Collection (STABLE)
23.5. Merging (MERGE2)
23.6. Other Configuration Issues
23.6.1. Binding JGroups Channels to a Particular Interface
23.6.2. Isolating JGroups Channels
23.6.3. JGroups Troubleshooting
24. JBoss Cache Configuration and Deployment
24.1. Key JBoss Cache Configuration Options
24.1.1. Editing the CacheManager Configuration
24.1.2. Cache Mode
24.1.3. Transaction Handling
24.1.4. Concurrent Access
24.1.5. JGroups Integration
24.1.6. Eviction
24.1.7. Cache Loaders
24.1.8. Buddy Replication
24.2. Deploying Your Own JBoss Cache Instance
24.2.1. Deployment Via the CacheManager Service
24.2.2. Deployment Via a -service.xml File
24.2.3. Deployment Via a -jboss-beans.xml File
IV. Performance Tuning
25. JBoss Enterprise Web Platform 5 Performance Tuning
25.1. Introduction
25.2. Hardware tuning
25.2.1. CPU (Central Processing Unit)
25.2.2. RAM (Random Access Memory)
25.2.3. Hard Disk
25.3. Operating System Performance Tuning
25.3.1. Networking
25.4. Tuning the JVM
25.5. Tuning your applications
25.5.1. Instrumentation
25.6. Tuning JBoss Enterprise Web Platform
25.6.1. Memory usage
25.6.2. Database Connection
25.6.3. Clustering Tuning
25.6.4. Other key configurations
V. Appendices
A. Vendor-Specific Datasource Definitions
A.1. Deployer Location and Naming
A.2. DB2
A.3. Oracle
A.3.1. Changes in Oracle 10g JDBC Driver
A.3.2. Type Mapping for Oracle 10g
A.3.3. Retrieving the Underlying Oracle Connection Object
A.3.4. Limitations of Oracle 11g
A.4. Sybase
A.4.1. Sybase Limitations
A.5. Microsoft SQL Server
A.5.1. Microsoft JDBC Drivers
A.5.2. JSQL Drivers
A.5.3. jTDS JDBC Driver
A.5.4. "Invalid object name 'JMS_SUBSCRIPTIONS' Exception
A.5.5. New dialect for Microsoft SQL Server 2008 with JDBC 3.x drivers
A.6. MySQL Datasource
A.6.1. Installing the Driver
A.6.2. MySQL Local-TX Datasource
A.6.3. MySQL Using a Named Pipe
A.7. PostgreSQL
A.8. Ingres
B. Logging Information and Recipes
B.1. Log Level Descriptions
B.2. Separate Log Files Per Application
B.3. Redirecting Category Output
C. Revision History