The JBoss 4 Application Server Guide
		Next

The JBoss 4 Application Server Guide

JBoss AS 4.0.4

Release 5

Table of Contents

What this Book Covers

About JBoss

About Open Source

About Professional Open Source

What's new in JBoss 4

1. J2EE Certification and Standards Compliance
2. New Services Types
3. JBoss AOP Support
4. Hibernate Integration
5. Clustering and Caching

1. Installing and running JBoss

1.1. Installing JBoss
1.2. Directory Structure
1.3. The Default Server Configuration File Set
1.4. Starting and Stopping JBoss

2. The JBoss JMX Microkernel

2.1. An Introduction to JMX

2.1.1. Instrumentation Level

2.1.2. Agent Level

2.1.3. Distributed Services Level

2.1.4. JMX Component Overview

2.1.4.1. Managed Beans or MBeans
2.1.4.2. Notification Model
2.1.4.3. MBean Metadata Classes
2.1.4.4. MBean Server
2.1.4.5. Agent Services

2.2. JBoss JMX Implementation Architecture

2.2.1. The JBoss ClassLoader Architecture

2.2.2. Class Loading and Types in Java

2.2.2.1. ClassCastExceptions - I'm Not Your Type
2.2.2.2. IllegalAccessException - Doing what you should not
2.2.2.3. LinkageErrors - Making Sure You Are Who You Say You Are
2.2.2.4. Inside the JBoss Class Loading Architecture

2.2.3. JBoss XMBeans

2.2.3.1. Descriptors
2.2.3.2. The Management Class
2.2.3.3. The Constructors
2.2.3.4. The Attributes
2.2.3.5. The Operations
2.2.3.6. Notifications

2.3. Connecting to the JMX Server

2.3.1. Inspecting the Server - the JMX Console Web Application

2.3.1.1. Securing the JMX Console

2.3.2. Connecting to JMX Using RMI

2.3.3. Command Line Access to JMX

2.3.3.1. Connecting twiddle to a Remote Server
2.3.3.2. Sample twiddle Command Usage

2.3.4. Connecting to JMX Using Any Protocol

2.4. Using JMX as a Microkernel

2.4.1. The Startup Process

2.4.2. JBoss MBean Services

2.4.2.1. The SARDeployer MBean
2.4.2.2. The Service Life Cycle Interface
2.4.2.3. The ServiceController MBean
2.4.2.4. Specifying Service Dependencies
2.4.2.5. Identifying Unsatisfied Dependencies
2.4.2.6. Hot Deployment of Components, the URLDeploymentScanner

2.4.3. Writing JBoss MBean Services

2.4.3.1. A Standard MBean Example
2.4.3.2. XMBean Examples

2.4.4. Deployment Ordering and Dependencies

2.5. JBoss Deployer Architecture

2.5.1. Deployers and ClassLoaders

2.6. Remote Access to Services, Detached Invokers

2.6.1. A Detached Invoker Example, the MBeanServer Invoker Adaptor Service

2.6.2. Detached Invoker Reference

2.6.2.1. The JRMPInvoker - RMI/JRMP Transport
2.6.2.2. The PooledInvoker - RMI/Socket Transport
2.6.2.3. The IIOPInvoker - RMI/IIOP Transport
2.6.2.4. The JRMPProxyFactory Service - Building Dynamic JRMP Proxies
2.6.2.5. The HttpInvoker - RMI/HTTP Transport
2.6.2.6. The HA JRMPInvoker - Clustered RMI/JRMP Transport
2.6.2.7. The HA HttpInvoker - Clustered RMI/HTTP Transport
2.6.2.8. HttpProxyFactory - Building Dynamic HTTP Proxies
2.6.2.9. Steps to Expose Any RMI Interface via HTTP

3. Naming on JBoss

3.1. An Overview of JNDI

3.1.1. Names

3.1.2. Contexts

3.1.2.1. Obtaining a Context using InitialContext

3.2. The JBossNS Architecture

3.3. The Naming InitialContext Factories

3.3.1. The standard naming context factory
3.3.2. The org.jboss.naming.NamingContextFactory
3.3.3. Naming Discovery in Clustered Environments
3.3.4. The HTTP InitialContext Factory Implementation
3.3.5. The Login InitialContext Factory Implementation
3.3.6. The ORBInitialContextFactory

3.4. JNDI over HTTP

3.4.1. Accessing JNDI over HTTP
3.4.2. Accessing JNDI over HTTPS
3.4.3. Securing Access to JNDI over HTTP
3.4.4. Securing Access to JNDI with a Read-Only Unsecured Context

3.5. Additional Naming MBeans

3.5.1. JNDI Binding Manager
3.5.2. The org.jboss.naming.NamingAlias MBean
3.5.3. org.jboss.naming.ExternalContext MBean
3.5.4. The org.jboss.naming.JNDIView MBean

3.6. J2EE and JNDI - The Application Component Environment

3.6.1. ENC Usage Conventions

3.6.1.1. Environment Entries
3.6.1.2. EJB References
3.6.1.3. EJB References with jboss.xml and jboss-web.xml
3.6.1.4. EJB Local References
3.6.1.5. Resource Manager Connection Factory References
3.6.1.6. Resource Manager Connection Factory References with jboss.xml and jboss-web.xml
3.6.1.7. Resource Environment References
3.6.1.8. Resource Environment References and jboss.xml, jboss-web.xml

4. Transactions on JBoss

4.1. Transaction/JTA Overview

4.1.1. Pessimistic and optimistic locking
4.1.2. The components of a distributed transaction
4.1.3. The two-phase XA protocol
4.1.4. Heuristic exceptions
4.1.5. Transaction IDs and branches

4.2. JBoss Transaction Internals

4.2.1. Adapting a Transaction Manager to JBoss

4.2.2. The Default Transaction Manager

4.2.2.1. org.jboss.tm.XidFactory

4.2.3. UserTransaction Support

5. EJBs on JBoss

5.1. The EJB Client Side View

5.1.1. Specifying the EJB Proxy Configuration

5.2. The EJB Server Side View

5.2.1. Detached Invokers - The Transport Middlemen
5.2.2. The HA JRMPInvoker - Clustered RMI/JRMP Transport
5.2.3. The HA HttpInvoker - Clustered RMI/HTTP Transport

5.3. The EJB Container

5.3.1. EJBDeployer MBean

5.3.1.1. Verifying EJB deployments
5.3.1.2. Deploying EJBs Into Containers
5.3.1.3. Container configuration information

5.3.2. Container Plug-in Framework

5.3.2.1. org.jboss.ejb.ContainerPlugin
5.3.2.2. org.jboss.ejb.Interceptor
5.3.2.3. org.jboss.ejb.InstancePool
5.3.2.4. org.jboss.ebj.InstanceCache
5.3.2.5. org.jboss.ejb.EntityPersistenceManager
5.3.2.6. The org.jboss.ejb.EntityPersistenceStore interface
5.3.2.7. org.jboss.ejb.StatefulSessionPersistenceManager

5.4. Entity Bean Locking and Deadlock Detection

5.4.1. Why JBoss Needs Locking

5.4.2. Entity Bean Lifecycle

5.4.3. Default Locking Behavior

5.4.4. Pluggable Interceptors and Locking Policy

5.4.5. Deadlock

5.4.5.1. Deadlock Detection
5.4.5.2. Catching ApplicationDeadlockException
5.4.5.3. Viewing Lock Information

5.4.6. Advanced Configurations and Optimizations

5.4.6.1. Short-lived Transactions
5.4.6.2. Ordered Access
5.4.6.3. Read-Only Beans
5.4.6.4. Explicitly Defining Read-Only Methods
5.4.6.5. Instance Per Transaction Policy

5.4.7. Running Within a Cluster

5.4.8. Troubleshooting

5.4.8.1. Locking Behavior Not Working
5.4.8.2. IllegalStateException
5.4.8.3. Hangs and Transaction Timeouts

5.5. EJB Timer Configuration

6. Messaging on JBoss

6.1. JMS Examples

6.1.1. A Point-To-Point Example
6.1.2. A Pub-Sub Example
6.1.3. A Pub-Sub With Durable Topic Example
6.1.4. A Point-To-Point With MDB Example

6.2. JBoss Messaging Overview

6.2.1. Invocation Layer

6.2.2. Security Manager

6.2.3. Destination Manager

6.2.4. Message Cache

6.2.5. State Manager

6.2.6. Persistence Manager

6.2.7. Destinations

6.2.7.1. Queues
6.2.7.2. Topics

6.3. JBoss Messaging Configuration and MBeans

6.3.1. org.jboss.mq.il.jvm.JVMServerILService

6.3.2. org.jboss.mq.il.uil2.UILServerILService

6.3.2.1. Configuring UIL2 for SSL
6.3.2.2. JMS client properties for the UIL2 transport

6.3.3. org.jboss.mq.il.http.HTTPServerILService

6.3.4. org.jboss.mq.server.jmx.Invoker

6.3.5. org.jboss.mq.server.jmx.InterceptorLoader

6.3.6. org.jboss.mq.sm.jdbc.JDBCStateManager

6.3.7. org.jboss.mq.security.SecurityManager

6.3.8. org.jboss.mq.server.jmx.DestinationManager

6.3.9. org.jboss.mq.server.MessageCache

6.3.10. org.jboss.mq.pm.jdbc2.PersistenceManager

6.3.11. Destination MBeans

6.3.11.1. org.jboss.mq.server.jmx.Queue
6.3.11.2. org.jboss.mq.server.jmx.Topic

6.4. Specifying the MDB JMS Provider

6.4.1. org.jboss.jms.jndi.JMSProviderLoader MBean
6.4.2. org.jboss.jms.asf.ServerSessionPoolLoader MBean
6.4.3. Integrating non-JBoss JMS Providers

7. Connectors on JBoss

7.1. JCA Overview

7.2. An Overview of the JBossCX Architecture

7.2.1. BaseConnectionManager2 MBean
7.2.2. RARDeployment MBean
7.2.3. JBossManagedConnectionPool MBean
7.2.4. CachedConnectionManager MBean
7.2.5. A Sample Skeleton JCA Resource Adaptor

7.3. Configuring JDBC DataSources

7.4. Configuring Generic JCA Adaptors

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.2.1.1. The JAAS Core Classes

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.3.1. Password Stacking
8.5.3.2. Password Hashing
8.5.3.3. Unauthenticated Identity
8.5.3.4. UsersRolesLoginModule
8.5.3.5. LdapLoginModule
8.5.3.6. DatabaseServerLoginModule
8.5.3.7. BaseCertLoginModule
8.5.3.8. IdentityLoginModule
8.5.3.9. RunAsLoginModule
8.5.3.10. ClientLoginModule

8.5.4. Writing Custom Login Modules

8.5.4.1. Support for the Subject Usage Pattern
8.5.4.2. A Custom LoginModule Example

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.6.2.1. An SRP example

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 Applications

9.1. The Tomcat Service

9.2. The server.xml file

9.2.1. The Connector element
9.2.2. The Engine element
9.2.3. The Host element
9.2.4. The Valve element

9.3. The context.xml file

9.4. Using HTTPS

9.5. Using DIGEST Authentication

9.6. Setting the context root of a web application

9.7. Setting up Virtual Hosts

9.8. Serving Static Content

9.9. Using Apache with Tomcat

9.10. Using JavaServer Faces

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

11. The CMP Engine

11.1. Example Code

11.1.1. Enabling CMP Debug Logging
11.1.2. Running the examples

11.2. The jbosscmp-jdbc Structure

11.3. Entity Beans

11.3.1. Entity Mapping

11.4. CMP Fields

11.4.1. CMP Field Declaration
11.4.2. CMP Field Column Mapping
11.4.3. Read-only Fields
11.4.4. Auditing Entity Access
11.4.5. Dependent Value Classes (DVCs)

11.5. Container Managed Relationships

11.5.1. CMR-Field Abstract Accessors

11.5.2. Relationship Declaration

11.5.3. Relationship Mapping

11.5.3.1. Relationship Role Mapping
11.5.3.2. Foreign Key Mapping
11.5.3.3. Relation table Mapping

11.6. Queries

11.6.1. Finder and select Declaration

11.6.2. EJB-QL Declaration

11.6.3. Overriding the EJB-QL to SQL Mapping

11.6.4. JBossQL

11.6.5. DynamicQL

11.6.6. DeclaredSQL

11.6.6.1. Parameters

11.6.7. EJBQL 2.1 and SQL92 queries

11.6.8. BMP Custom Finders

11.7. Optimized Loading

11.7.1. Loading Scenario

11.7.2. Load Groups

11.7.3. Read-ahead

11.7.3.1. on-find
11.7.3.2. on-load
11.7.3.3. none

11.8. Loading Process

11.8.1. Commit Options

11.8.2. Eager-loading Process

11.8.3. Lazy loading Process

11.8.3.1. Relationships

11.8.4. Lazy loading result sets

11.9. Transactions

11.10. Optimistic Locking

11.11. Entity Commands and Primary Key Generation

11.11.1. Existing Entity Commands

11.12. Defaults

11.12.1. A sample jbosscmp-jdbc.xml defaults declaration

11.13. Datasource Customization

11.13.1. Type Mapping
11.13.2. Function Mapping
11.13.3. Mapping
11.13.4. User Type Mappings

12. Web Services

12.1. JAX-RPC Service Endpoints

12.2. EJB Endpoints

12.3. Web Services Clients

12.3.1. A JAX-RPC client
12.3.2. Service references

13. Hibernate

13.1. The Hibernate MBean

13.2. Deploying Hibernate applications

13.2.1. Deploying as a Hibernate archive
13.2.2. Scanning the deployment

13.3. Using the Hibernate objects

14. The JBoss microcontainer

14.1. Introduction to the JBoss Microcontainer

14.2. Bean archives

14.3. Basic Configuration

14.3.1. Deployment
14.3.2. Bean
14.3.3. Construction
14.3.4. Factories
14.3.5. Properties
14.3.6. String Values
14.3.7. Injections
14.3.8. Collections
14.3.9. Lifecycle

14.4. Conclusion

15. Aspect Oriented Programming (AOP) Support

15.1. Why AOP

15.2. AOP Basic Concepts

15.2.1. Joinpoint and Invocation

15.2.2. Advice and Aspect

15.2.3. Pointcut

15.2.3.1. Use XML configuration file
15.2.3.2. Use annotations
15.2.3.3. Use Annotation in Application Classes

15.2.4. Introduction and Mixin

15.3. Build JBoss AOP Applications

15.3.1. Compile to bytecode
15.3.2. Compile annotation
15.3.3. AOP Intrumentation

15.4. JBoss AOP Deployer

15.4.1. Install the latest jboss-aop.deployer
15.4.2. Configure the AOP service
15.4.3. Pre-packaged aspects library

15.5. Package and deploy AOP applications to JBoss

15.5.1. Use pre-packaged aspects
15.5.2. Develop your own aspects
15.5.3. Package and deploy custom aspects

16. Clustering

16.1. Introduction

16.1.1. Cluster Definition

16.1.2. Service Architectures

16.1.2.1. Client-side interceptor
16.1.2.2. Load balancer

16.1.3. Load-Balancing Policies

16.1.3.1. JBoss AS 3.0.x
16.1.3.2. JBoss AS 3.2+

16.1.4. Farming Deployment

16.1.5. Distributed state replication services

16.2. Clustered JNDI Services

16.2.1. How it works
16.2.2. Client configuration
16.2.3. JBoss configuration

16.3. Clustered Session EJBs

16.3.1. Stateless Session Bean in EJB 2.x

16.3.1.1. Handle Cluster Restart

16.3.2. Stateful Session Bean in EJB 2.x

16.3.2.1. The EJB application configuration
16.3.2.2. Optimize state replication
16.3.2.3. The HASessionState service configuration

16.3.3. Stateless Session Bean in EJB 3.0

16.3.4. Stateful Session Bean in EJB 3.0

16.4. Clustered Entity EJBs

16.4.1. Entity Bean in EJB 2.x

16.4.2. Entity Bean in EJB 3.0

16.4.2.1. Configure the distributed cache
16.4.2.2. Configure the entity beans for cache

16.5. HTTP Services

16.5.1. Download the software
16.5.2. Configure Apache to load mod_jk
16.5.3. Configure worker nodes in mod_jk
16.5.4. Configure JBoss
16.5.5. Configure HTTP session state replication
16.5.6. Enabling session replication in your application
16.5.7. Use FIELD level replication
16.5.8. Monitoring session replication
16.5.9. Using Single Sign On

16.6. Clustered JMS Services

16.6.1. High Availability Singleton Fail-over

16.6.1.1. Server Side Configuration
16.6.1.2. HA-JMS Client
16.6.1.3. Load Balanced HA-JMS MDBs

17. JBossCache and JGroups Services

17.1. JGroups Configuration

17.1.1. Transport Protocols

17.1.1.1. UDP configuration
17.1.1.2. TCP configuration
17.1.1.3. TUNNEL configuration

17.1.2. Discovery Protocols

17.1.2.1. PING
17.1.2.2. TCPGOSSIP
17.1.2.3. TCPPING
17.1.2.4. MPING

17.1.3. Failure Detection Protocols

17.1.3.1. FD
17.1.3.2. FD_SOCK
17.1.3.3. FD_SIMPLE

17.1.4. Reliable Delivery Protocols

17.1.4.1. UNICAST
17.1.4.2. NAKACK

17.1.5. Other Configuration Options

17.1.5.1. Group Membership
17.1.5.2. Flow Control
17.1.5.3. State Transfer
17.1.5.4. Distributed Garbage Collection
17.1.5.5. Merging

17.2. JBossCache Configuration

A. The GNU Lesser General Public License (LGPL)

B. Book Example Installation

C. Building the Server from Source Code

C.1. Downloading JBoss Source
C.2. Anonymous CVS Access
C.3. Building JBoss AS
C.4. Using the JBossTest unit testsuite