JBoss.org Community Documentation

JBoss Application Server 4.2.2

Administration And Development Guide

Authors

Alessio Soldano

Andreadis Dimitris

Bill Burke

Brian Stansberry

Carlo de Wolf

Galder Zamarreno

Heiko Braun

Michael Yuan

Roger Pearse

Shelly Mc Gowan

Thomas Diesler

Edited by

Samson Kittoli

Myriam Malga

Translation of this book to French.

Fabian Decroux

Translation of this book to French.

Jasna Dimanoski

Translation of this book to German.

Yoko Nanamiya

Translation of this book to Japanese.

James Hashida

Translation of this book to Japanese.

Noriko Mizumoto

Translation of this book to Japanese.

Glaucia Freitas

Translation of this book to Portuguese.

Angela Garcia

Translation of this book to Spanish.

Jan 2008

Abstract

This book is a guide to the administration and configuration of the JBoss Application Server.


What this Book Covers
About JBoss
About Open Source
About Professional Open Source
I. Java EE 5 Application Configuration
1. Enterprise Applications with EJB3 Services
1.1. Session Beans
1.2. Entity Beans (a.k.a. Java Persistence API)
1.2.1. The persistence.xml file
1.2.2. Use Alternative Databases
1.2.3. Default Hibernate options
1.3. Message Driven Beans
1.4. Package and Deploy EJB3 Services
1.4.1. Deploy the EJB3 JAR
1.4.2. Deploy EAR with EJB3 JAR
2. Deployment
2.1. Deployable Application Types
2.2. Standard Server Configurations
II. JBoss AS Infrastructure
3. The JBoss JMX Microkernel
3.1. An Introduction to JMX
3.1.1. Instrumentation Level
3.1.2. Agent Level
3.1.3. Distributed Services Level
3.1.4. JMX Component Overview
3.2. JBoss JMX Implementation Architecture
3.2.1. The JBoss ClassLoader Architecture
3.2.2. Class Loading and Types in Java
3.2.3. JBoss XMBeans
3.3. Connecting to the JMX Server
3.3.1. Inspecting the Server - the JMX Console Web Application
3.3.2. Connecting to JMX Using RMI
3.3.3. Command Line Access to JMX
3.3.4. Connecting to JMX Using Any Protocol
3.4. Using JMX as a Microkernel
3.4.1. The Startup Process
3.4.2. JBoss MBean Services
3.4.3. Writing JBoss MBean Services
3.4.4. Deployment Ordering and Dependencies
3.5. JBoss Deployer Architecture
3.5.1. Deployers and ClassLoaders
3.6. Remote Access to Services, Detached Invokers
3.6.1. A Detached Invoker Example, the MBeanServer Invoker Adaptor Service
3.6.2. Detached Invoker Reference
4. Naming on JBoss
4.1. An Overview of JNDI
4.1.1. Names
4.1.2. Contexts
4.2. The JBossNS Architecture
4.3. The Naming InitialContext Factories
4.3.1. The standard naming context factory
4.3.2. The org.jboss.naming.NamingContextFactory
4.3.3. Naming Discovery in Clustered Environments
4.3.4. The HTTP InitialContext Factory Implementation
4.3.5. The Login InitialContext Factory Implementation
4.3.6. The ORBInitialContextFactory
4.4. JNDI over HTTP
4.4.1. Accessing JNDI over HTTP
4.4.2. Accessing JNDI over HTTPS
4.4.3. Securing Access to JNDI over HTTP
4.4.4. Securing Access to JNDI with a Read-Only Unsecured Context
4.5. Additional Naming MBeans
4.5.1. JNDI Binding Manager
4.5.2. The org.jboss.naming.NamingAlias MBean
4.5.3. org.jboss.naming.ExternalContext MBean
4.5.4. The org.jboss.naming.JNDIView MBean
4.6. J2EE and JNDI - The Application Component Environment
4.6.1. ENC Usage Conventions
5. Connectors on JBoss
5.1. JCA Overview
5.2. An Overview of the JBossCX Architecture
5.2.1. BaseConnectionManager2 MBean
5.2.2. RARDeployment MBean
5.2.3. JBossManagedConnectionPool MBean
5.2.4. CachedConnectionManager MBean
5.2.5. A Sample Skeleton JCA Resource Adaptor
5.3. Configuring JDBC DataSources
5.4. Configuring Generic JCA Adaptors
6. Transactions on JBoss
6.1. Transaction/JTA Overview
6.1.1. Pessimistic and optimistic locking
6.1.2. The components of a distributed transaction
6.1.3. The two-phase XA protocol
6.1.4. Heuristic exceptions
6.1.5. Transaction IDs and branches
6.2. JTS support
6.3. Web Services Transactions
6.4. Configuring JBoss Transactions
6.5. Local versus distributed transactions
7. Messaging on JBoss
7.1. JMS Examples
7.1.1. A Point-To-Point Example
7.1.2. A Pub-Sub Example
7.1.3. A Pub-Sub With Durable Topic Example
7.1.4. A Point-To-Point With MDB Example
7.2. JBoss MQ Overview
7.2.1. Invocation Layer
7.2.2. Security Manager
7.2.3. Destination Manager
7.2.4. Message Cache
7.2.5. State Manager
7.2.6. Persistence Manager
7.2.7. Destinations
7.3. JBoss MQ Configuration and MBeans
7.3.1. org.jboss.mq.il.jvm.JVMServerILService
7.3.2. org.jboss.mq.il.uil2.UILServerILService
7.3.3. org.jboss.mq.il.http.HTTPServerILService
7.3.4. org.jboss.mq.server.jmx.Invoker
7.3.5. org.jboss.mq.server.jmx.InterceptorLoader
7.3.6. org.jboss.mq.sm.jdbc.JDBCStateManager
7.3.7. org.jboss.mq.security.SecurityManager
7.3.8. org.jboss.mq.server.jmx.DestinationManager
7.3.9. org.jboss.mq.server.MessageCache
7.3.10. org.jboss.mq.pm.jdbc2.PersistenceManager
7.3.11. Destination MBeans
7.4. Specifying the MDB JMS Provider
7.4.1. org.jboss.jms.jndi.JMSProviderLoader MBean
7.4.2. org.jboss.jms.asf.ServerSessionPoolLoader MBean
7.4.3. Integrating non-JBoss JMS Providers
8. Security on JBoss
8.1. J2EE Declarative Security Overview
8.1.1. Security References
8.1.2. Security Identity
8.1.3. Security roles
8.1.4. EJB method permissions
8.1.5. Web Content Security Constraints
8.1.6. Enabling Declarative Security in JBoss
8.2. An Introduction to JAAS
8.2.1. What is JAAS?
8.3. The JBoss Security Model
8.3.1. Enabling Declarative Security in JBoss Revisited
8.4. The JBoss Security Extension Architecture
8.4.1. How the JaasSecurityManager Uses JAAS
8.4.2. The JaasSecurityManagerService MBean
8.4.3. The JaasSecurityDomain MBean
8.5. Defining Security Domains
8.5.1. Loading Security Domains
8.5.2. The DynamicLoginConfig service
8.5.3. Using JBoss Login Modules
8.5.4. Writing Custom Login Modules
8.6. The Secure Remote Password (SRP) Protocol
8.6.1. Providing Password Information for SRP
8.6.2. Inside of the SRP algorithm
8.7. Running JBoss with a Java 2 security manager
8.8. Using SSL with JBoss using JSSE
8.9. Configuring JBoss for use Behind a Firewall
8.10. How to Secure the JBoss Server
8.10.1. The JMX Console
8.10.2. The Web Console
8.10.3. The HTTP Invokers
8.10.4. The JMX Invoker
9. Web Services
9.1. Document/Literal
9.2. Document/Literal (Bare)
9.3. Document/Literal (Wrapped)
9.4. RPC/Literal
9.5. RPC/Encoded
9.6. Web Service Endpoints
9.7. Plain old Java Object (POJO)
9.8. The endpoint as a web application
9.9. Packaging the endpoint
9.10. Accessing the generated WSDL
9.11. EJB3 Stateless Session Bean (SLSB)
9.12. Endpoint Provider
9.13. WebServiceContext
9.14. Web Service Clients
9.14.1. Service
9.14.2. Dynamic Proxy
9.14.3. WebServiceRef
9.14.4. Dispatch
9.14.5. Asynchronous Invocations
9.14.6. Oneway Invocations
9.15. Common API
9.15.1. Handler Framework
9.15.2. Message Context
9.15.3. Fault Handling
9.16. DataBinding
9.16.1. Using JAXB with non annotated classes
9.17. Attachments
9.17.1. MTOM/XOP
9.17.2. SwaRef
9.18. Tools
9.18.1. Bottom-Up (Using wsprovide)
9.18.2. Top-Down (Using wsconsume)
9.18.3. Client Side
9.18.4. Command-line & Ant Task Reference
9.18.5. JAX-WS binding customization
9.19. Web Service Extensions
9.19.1. WS-Addressing
9.19.2. WS-BPEL
9.19.3. WS-Eventing
9.19.4. WS-Security
9.19.5. WS-Transaction
9.19.6. XML Registries
9.19.7. WS-Policy
9.20. JBossWS Extensions
9.20.1. Proprietary Annotations
9.21. Web Services Appendix
9.22. References
10. Additional Services
10.1. Memory and Thread Monitoring
10.2. The Log4j Service
10.3. System Properties Management
10.4. Property Editor Management
10.5. Services Binding Management
10.5.1. AttributeMappingDelegate
10.5.2. XSLTConfigDelegate
10.5.3. XSLTFileDelegate
10.5.4. The Sample Bindings File
10.6. RMI Dynamic Class Loading
10.7. Scheduling Tasks
10.7.1. org.jboss.varia.scheduler.Scheduler
10.8. The Timer Service
10.9. The BarrierController Service
10.10. Exposing MBean Events via SNMP
III. Legacy EJB Support
11. EJBs on JBoss
11.1. The EJB Client Side View
11.1.1. Specifying the EJB Proxy Configuration
11.2. The EJB Server Side View
11.2.1. Detached Invokers - The Transport Middlemen
11.2.2. The HA JRMPInvoker - Clustered RMI/JRMP Transport
11.2.3. The HA HttpInvoker - Clustered RMI/HTTP Transport
11.3. The EJB Container
11.3.1. EJBDeployer MBean
11.3.2. Container Plug-in Framework
11.4. Entity Bean Locking and Deadlock Detection
11.4.1. Why JBoss Needs Locking
11.4.2. Entity Bean Lifecycle
11.4.3. Default Locking Behavior
11.4.4. Pluggable Interceptors and Locking Policy
11.4.5. Deadlock
11.4.6. Advanced Configurations and Optimizations
11.4.7. Running Within a Cluster
11.4.8. Troubleshooting
11.5. EJB Timer Configuration
12. The CMP Engine
12.1. Example Code
12.1.1. Enabling CMP Debug Logging
12.1.2. Running the examples
12.2. The jbosscmp-jdbc Structure
12.3. Entity Beans
12.3.1. Entity Mapping
12.4. CMP Fields
12.4.1. CMP Field Declaration
12.4.2. CMP Field Column Mapping
12.4.3. Read-only Fields
12.4.4. Auditing Entity Access
12.4.5. Dependent Value Classes (DVCs)
12.5. Container Managed Relationships
12.5.1. CMR-Field Abstract Accessors
12.5.2. Relationship Declaration
12.5.3. Relationship Mapping
12.6. Queries
12.6.1. Finder and select Declaration
12.6.2. EJB-QL Declaration
12.6.3. Overriding the EJB-QL to SQL Mapping
12.6.4. JBossQL
12.6.5. DynamicQL
12.6.6. DeclaredSQL
12.6.7. EJBQL 2.1 and SQL92 queries
12.6.8. BMP Custom Finders
12.7. Optimized Loading
12.7.1. Loading Scenario
12.7.2. Load Groups
12.7.3. Read-ahead
12.8. Loading Process
12.8.1. Commit Options
12.8.2. Eager-loading Process
12.8.3. Lazy loading Process
12.8.4. Lazy loading result sets
12.9. Transactions
12.10. Optimistic Locking
12.11. Entity Commands and Primary Key Generation
12.11.1. Existing Entity Commands
12.12. Defaults
12.12.1. A sample jbosscmp-jdbc.xml defaults declaration
12.13. Datasource Customization
12.13.1. Type Mapping
12.13.2. Function Mapping
12.13.3. Mapping
12.13.4. User Type Mappings
IV. Clustering Guide
13. Clustering
13.1. Introduction
13.2. Cluster Definition
13.3. HAPartition
13.4. JBoss Cache channels
13.4.1. Service Architectures
13.4.2. Load-Balancing Policies
13.4.3. Farming Deployment
13.4.4. Distributed state replication services
14. Clustered JNDI Services
14.1. How it works
14.2. Client configuration
14.2.1. For clients running inside the application server
14.2.2. For clients running outside the application server
14.2.3. JBoss configuration
15. Clustered Session EJBs
15.1. Stateless Session Bean in EJB 2.x
15.2. Stateful Session Bean in EJB 2.x
15.2.1. The EJB application configuration
15.2.2. Optimize state replication
15.2.3. The HASessionState service configuration
15.2.4. Handling Cluster Restart
15.2.5. JNDI Lookup Process
15.2.6. SingleRetryInterceptor
15.3. Stateless Session Bean in EJB 3.0
15.4. Stateful Session Beans in EJB 3.0
16. Clustered Entity EJBs
16.1. Entity Bean in EJB 2.x
16.2. Entity Bean in EJB 3.0
16.2.1. Configure the distributed cache
16.2.2. Configure the entity beans for cache
16.2.3. Query result caching
17. HTTP Services
17.1. Configuring load balancing using Apache and mod_jk
17.2. Download the software
17.3. Configure Apache to load mod_jk
17.4. Configure worker nodes in mod_jk
17.5. Configuring JBoss to work with mod_jk
17.6. Configuring HTTP session state replication
17.7. Enabling session replication in your application
17.8. Using FIELD level replication
17.9. Monitoring session replication
17.10. Using Clustered Single Sign On
17.11. Clustered Singleton Services
17.11.1. HASingletonDeployer service
17.11.2. Mbean deployments using HASingletonController
17.11.3. HASingleton deployments using a Barrier
17.11.4. Determining the master node
18. Clustered JMS Services
18.1. High Availability Singleton Fail-over
18.1.1. Server Side Configuration
18.1.2. Non-MDB HA-JMS Clients
18.1.3. Load Balanced HA-JMS MDBs
19. JBossCache and JGroups Services
19.1. JGroups Configuration
19.2. Common Configuration Properties
19.3. Transport Protocols
19.3.1. UDP configuration
19.3.2. TCP configuration
19.3.3. TUNNEL configuration
19.4. Discovery Protocols
19.4.1. PING
19.4.2. TCPGOSSIP
19.4.3. TCPPING
19.4.4. MPING
19.5. Failure Detection Protocols
19.5.1. FD
19.5.2. FD_SOCK
19.5.3. VERIFY_SUSPECT
19.5.4. FD versus FD_SOCK
19.6. Reliable Delivery Protocols
19.6.1. UNICAST
19.6.2. NAKACK
19.7. Other Configuration Options
19.7.1. Group Membership
19.7.2. Flow Control
19.7.3. Fragmentation
19.7.4. State Transfer
19.7.5. Distributed Garbage Collection
19.7.6. Merging
19.7.7. Binding JGroups Channels to a particular interface
19.7.8. Isolating JGroups Channels
19.7.9. Changing the Group Name
19.7.10. Changing the multicast address and port
19.7.11. JGroups Troubleshooting
19.7.12. Causes of missing heartbeats in FD
A. Book Example Installation
B. Use Alternative Databases with JBoss AS
B.1. How to Use Alternative Databases
B.2. Install JDBC Drivers
B.2.1. Special notes on Sybase
B.3. Creating a DataSource for the External Database
B.4. Change Database for the JMS Services
B.5. Support Foreign Keys in CMP Services
B.6. Specify Database Dialect for Java Persistence API
B.7. Change Other JBoss AS Services to Use the External Database
B.7.1. The Easy Way
B.7.2. The More Flexible Way
B.8. A Special Note About Oracle DataBases