The JBoss 4 Application Server Guide (JBoss AS 4.0.2)

Table of contents :
The JBoss 4 Application Server Guide……Page 1
Table of Contents……Page 2
What this Book Covers……Page 10
About JBoss……Page 11
About Open Source……Page 12
About Professional Open Source……Page 13
1. J2EE Certification and Standards Compliance……Page 14
2.1. JBoss AS 4.0.1 and above……Page 15
3. New Services Types……Page 16
5. Hibernate Integration……Page 17
6. Clustering and Caching……Page 18
1.2. Directory Structure……Page 19
1.3. The Default Server Configuration File Set……Page 21
1.4.  Basic Installation Testing……Page 26
1.5. Booting from a Network Server……Page 27
2.1. JMX……Page 30
2.1.1. An Introduction to JMX……Page 31
2.1.1.2. Agent Level……Page 32
2.1.1.4. JMX Component Overview……Page 33
2.1.1.4.3. MBean Metadata Classes……Page 34
2.1.1.4.5. Agent Services……Page 35
2.2.2.1. ClassCastExceptions – I’m Not Your Type……Page 36
2.2.2.2. IllegalAccessException – Doing what you should not……Page 41
2.2.2.3. LinkageErrors – Making Sure You Are Who You Say You Are……Page 43
2.2.2.3.1. Debugging Class Loading Issues……Page 47
2.2.2.4. Inside the JBoss Class Loading Architecture……Page 48
2.2.2.4.1. Viewing Classes in the Loader Repository……Page 49
2.2.2.4.2. Scoping Classes……Page 51
2.2.2.4.3. The Complete Class Loading Model……Page 52
2.2.3. JBoss XMBeans……Page 55
2.2.3.1. Descriptors……Page 56
2.2.3.3. The Constructors……Page 58
2.2.3.4. The Attributes……Page 59
2.2.3.5. The Operations……Page 60
2.2.3.6. Notifications……Page 61
2.3.1. Inspecting the Server – the JMX Console Web Application……Page 62
2.3.1.1. Securing the JMX Console……Page 64
2.3.2. Connecting to JMX Using RMI……Page 66
2.3.3.2. Sample twiddle Command Usage……Page 69
2.3.4. Connecting to JMX Using Any Protocol……Page 72
2.4.1. The Startup Process……Page 73
2.4.2. JBoss MBean Services……Page 74
2.4.2.1. The SARDeployer MBean……Page 75
2.4.2.3. The ServiceController MBean……Page 78
2.4.2.3.2. The start(ObjectName) method……Page 79
2.4.2.4. Specifying Service Dependencies……Page 80
2.4.2.5. Identifying Unsatisfied Dependencies……Page 81
2.4.2.6. Hot Deployment of Components, the URLDeploymentScanner……Page 82
2.4.3. Writing JBoss MBean Services……Page 83
2.4.3.1. A Standard MBean Example……Page 84
2.4.3.2.1. Version 1, The Annotated JNDIMap XMBean……Page 87
2.4.3.2.2. Version 2, Adding Persistence to the JNDIMap XMBean……Page 90
2.4.4. Deployment Ordering and Dependencies……Page 94
2.5. JBoss Deployer Architecture……Page 104
2.5.1. Deployers and ClassLoaders……Page 106
2.6.  Exposing MBean Events via SNMP……Page 108
2.7. Remote Access to Services, Detached Invokers……Page 109
2.7.1. A Detached Invoker Example, the MBeanServer Invoker Adaptor Service……Page 112
2.7.2.1. The JRMPInvoker – RMI/JRMP Transport……Page 116
2.7.2.3. The IIOPInvoker – RMI/IIOP Transport……Page 117
2.7.2.5. The HttpInvoker – RMI/HTTP Transport……Page 118
2.7.2.8. HttpProxyFactory – Building Dynamic HTTP Proxies……Page 119
2.7.2.9. Steps to Expose Any RMI Interface via HTTP……Page 120
3.1.1.1. Names……Page 122
3.1.1.2.1. Obtaining a Context using InitialContext……Page 123
3.1.2. J2EE and JNDI – The Application Component Environment……Page 124
3.1.2.1.1. Environment Entries……Page 126
3.1.2.1.2. EJB References……Page 127
3.1.2.1.3. EJB References with jboss.xml and jboss-web.xml……Page 129
3.1.2.1.4. EJB Local References……Page 130
3.1.2.1.5. Resource Manager Connection Factory References……Page 131
3.1.2.1.6. Resource Manager Connection Factory References with jboss.xml and jboss-web.xml……Page 133
3.1.2.1.8. Resource Environment References and jboss.xml, jboss-web.xml……Page 134
3.2. The JBossNS Architecture……Page 135
3.2.1. The Naming InitialContext Factories……Page 138
3.2.1.1. Naming Discovery in Clustered Environments……Page 139
3.2.1.3. The Login InitialContext Factory Implementation……Page 140
3.2.2. Accessing JNDI over HTTP……Page 141
3.2.3. Accessing JNDI over HTTPS……Page 144
3.2.4. Securing Access to JNDI over HTTP……Page 146
3.2.5. Securing Access to JNDI with a Read-Only Unsecured Context……Page 148
3.2.6. Additional Naming MBeans……Page 149
3.2.6.1. org.jboss.naming.ExternalContext MBean……Page 150
3.2.6.2. The org.jboss.naming.NamingAlias MBean……Page 151
3.2.6.3. The org.jboss.naming.JNDIView MBean……Page 152
4.1. Transaction/JTA Overview……Page 156
4.1.2. The components of a distributed transaction……Page 157
4.1.4. Heuristic exceptions……Page 158
4.2. JBoss Transaction Internals……Page 159
4.2.2. The Default Transaction Manager……Page 160
4.2.3. UserTransaction Support……Page 161
5.1. The EJB Client Side View……Page 162
5.1.1. Specifying the EJB Proxy Configuration……Page 165
5.2.1. Detached Invokers – The Transport Middlemen……Page 169
5.2.3. The HA HttpInvoker – Clustered RMI/HTTP Transport……Page 173
5.3.1. EJBDeployer MBean……Page 174
5.3.1.2. Deploying EJBs Into Containers……Page 175
5.3.1.3. Container configuration information……Page 176
5.3.1.3.6. call-ejb-store-on-clean……Page 180
5.3.1.3.9. The container-pool-conf element……Page 181
5.3.1.3.11. The container-cache-conf element……Page 182
5.3.1.3.13. The web-class-loader Element……Page 184
5.3.1.3.15. The commit-option and optiond-refresh-rate elements……Page 185
5.3.1.3.17. cluster-config……Page 186
5.3.2.1. org.jboss.ejb.ContainerPlugin……Page 187
5.3.2.2. org.jboss.ejb.Interceptor……Page 188
5.3.2.3. org.jboss.ejb.InstancePool……Page 189
5.3.2.4. org.jboss.ebj.InstanceCache……Page 190
5.3.2.5. org.jboss.ejb.EntityPersistenceManager……Page 191
5.3.2.6. The org.jboss.ejb.EntityPersistenceStore interface……Page 193
5.3.2.7. org.jboss.ejb.StatefulSessionPersistenceManager……Page 196
5.4.1. Why JBoss Needs Locking……Page 197
5.4.4. Pluggable Interceptors and Locking Policy……Page 198
5.4.5. Deadlock……Page 199
5.4.5.2. Catching ApplicationDeadlockException……Page 200
5.4.6. Advanced Configurations and Optimizations……Page 201
5.4.6.4. Explicitly Defining Read-Only Methods……Page 202
5.4.6.5. Instance Per Transaction Policy……Page 203
5.4.8.3. Hangs and Transaction Timeouts……Page 204
6.1.1. A Point-To-Point Example……Page 205
6.1.2. A Pub-Sub Example……Page 208
6.1.3. A Pub-Sub With Durable Topic Example……Page 212
6.1.4. A Point-To-Point With MDB Example……Page 215
6.2.1. Invocation Layer……Page 221
6.2.6. Persistence Manager……Page 222
6.3. JBoss Messaging Configuration and MBeans……Page 223
6.3.2. org.jboss.mq.il.uil2.UILServerILService……Page 224
6.3.2.1. Configuring UIL2 for SSL……Page 225
6.3.2.2. JMS client properties for the UIL2 transport……Page 226
6.3.4. org.jboss.mq.server.jmx.Invoker……Page 227
6.3.7. org.jboss.mq.security.SecurityManager……Page 228
6.3.8. org.jboss.mq.server.jmx.DestinationManager……Page 229
6.3.9. org.jboss.mq.server.MessageCache……Page 230
6.3.10. org.jboss.mq.pm.jdbc2.PersistenceManager……Page 231
6.3.11.1. org.jboss.mq.server.jmx.Queue……Page 233
6.3.11.2. org.jboss.mq.server.jmx.Topic……Page 235
6.4. Specifying the MDB JMS Provider……Page 236
6.4.1. org.jboss.jms.jndi.JMSProviderLoader MBean……Page 237
6.4.2. org.jboss.jms.asf.ServerSessionPoolLoader MBean……Page 238
6.4.3. Integrating non-JBoss JMS Providers……Page 239
7.1. JCA Overview……Page 240
7.2. An Overview of the JBossCX Architecture……Page 242
7.2.1. BaseConnectionManager2 MBean……Page 243
7.2.2. RARDeployment MBean……Page 244
7.2.3. JBossManagedConnectionPool MBean……Page 245
7.2.5. A Sample Skeleton JCA Resource Adaptor……Page 246
7.3. Configuring JDBC DataSources……Page 252
7.4. Configuring Generic JCA Adaptors……Page 262
8.1.1. Security References……Page 266
8.1.2. Security Identity……Page 268
8.1.3. Security roles……Page 269
8.1.4. EJB method permissions……Page 270
8.1.5. Web Content Security Constraints……Page 274
8.2.1.1. The JAAS Core Classes……Page 277
8.2.1.1.2. Authentication of a Subject……Page 278
8.3. The JBoss Security Model……Page 281
8.3.1. Enabling Declarative Security in JBoss Revisited……Page 283
8.4. The JBoss Security Extension Architecture……Page 287
8.4.1. How the JaasSecurityManager Uses JAAS……Page 289
8.4.2. The JaasSecurityManagerService MBean……Page 292
8.4.3. The JaasSecurityDomain MBean……Page 294
8.4.4. An XML JAAS Login Configuration MBean……Page 295
8.4.5. The JAAS Login Configuration Management MBean……Page 297
8.4.6.1. org.jboss.security.auth.spi.IdentityLoginModule……Page 298
8.4.6.2. org.jboss.security.auth.spi.UsersRolesLoginModule……Page 299
8.4.6.3. org.jboss.security.auth.spi.LdapLoginModule……Page 300
8.4.6.4. org.jboss.security.auth.spi.DatabaseServerLoginModule……Page 304
8.4.6.5. BaseCertLoginModule……Page 305
8.4.6.7. org.jboss.security.ClientLoginModule……Page 307
8.4.7. Writing Custom Login Modules……Page 308
8.4.7.1. Support for the Subject Usage Pattern……Page 309
8.4.7.2. A Custom LoginModule Example……Page 313
8.4.8. The DynamicLoginConfig service……Page 316
8.5. The Secure Remote Password (SRP) Protocol……Page 317
8.5.1. Providing Password Information for SRP……Page 320
8.5.2. Inside of the SRP algorithm……Page 322
8.5.2.1. An SRP example……Page 324
8.6. Running JBoss with a Java 2 security manager……Page 327
8.7. Using SSL with JBoss using JSSE……Page 328
8.8. Configuring JBoss for use Behind a Firewall……Page 332
8.9.3. The http-invoker.sar……Page 333
8.9.4. The jmx-invoker-adaptor-server.sar……Page 334
9.1. The Tomcat Service……Page 335
9.2.1. The Connector element……Page 336
9.2.4. The Valve element……Page 338
9.4. Using SSL with the JBoss/Tomcat bundle……Page 339
9.5. Setting the context root of a web application……Page 342
9.6. Setting up Virtual Hosts……Page 343
9.7. Serving Static Content……Page 344
9.9.1. Configuring session replication……Page 345
9.9.2. Enabling session replication in your application……Page 346
9.9.3. Monitoring session replication……Page 347
9.11.1. The AbstractWebContainer Class……Page 348
9.11.1.1. The AbstractWebContainer Contract……Page 349
9.11.1.2.3. Delegate web container authentication and authorization to JBossSX……Page 354
10.1. System Properties Management……Page 356
10.3. Services Binding Management……Page 357
10.4.1. org.jboss.varia.scheduler.Scheduler……Page 361
10.6. RMI Dynamic Class Loading……Page 364
11.1. Example Code……Page 365
11.1.2. Running the examples……Page 367
11.2. The jbosscmp-jdbc Structure……Page 368
11.3. Entity Beans……Page 370
11.3.1. Entity Mapping……Page 372
11.4. CMP Fields……Page 375
11.4.2. CMP Field Column Mapping……Page 376
11.4.3. Read-only Fields……Page 378
11.4.4. Auditing Entity Access……Page 379
11.4.5. Dependent Value Classes (DVCs)……Page 380
11.5.1. CMR-Field Abstract Accessors……Page 384
11.5.2. Relationship Declaration……Page 385
11.5.3. Relationship Mapping……Page 386
11.5.3.1. Relationship Role Mapping……Page 387
11.5.3.3. Relation table Mapping……Page 390
11.6.1. Finder and select Declaration……Page 392
11.6.2. EJB-QL Declaration……Page 393
11.6.3. Overriding the EJB-QL to SQL Mapping……Page 394
11.6.4. JBossQL……Page 396
11.6.5. DynamicQL……Page 397
11.6.6. DeclaredSQL……Page 398
11.6.7. EJBQL 2.1 and SQL92 queries……Page 401
11.7. Optimized Loading……Page 402
11.7.1. Loading Scenario……Page 403
11.7.2. Load Groups……Page 404
11.7.3.1. on-find……Page 405
11.7.3.1.2. D#findByPrimaryKey……Page 406
11.7.3.1.3. D#findAll……Page 407
11.7.3.1.4. A#findAll……Page 408
11.7.3.2. on-load……Page 409
11.8.1. Commit Options……Page 411
11.8.2. Eager-loading Process……Page 412
11.8.3. Lazy loading Process……Page 413
11.8.3.1. Relationships……Page 414
11.8.4. Lazy loading result sets……Page 416
11.9. Transactions……Page 417
11.10. Optimistic Locking……Page 419
11.11. Entity Commands and Primary Key Generation……Page 422
11.11.1. Existing Entity Commands……Page 423
11.12. Defaults……Page 425
11.12.1. A sample jbosscmp-jdbc.xml defaults declaration……Page 427
11.13. Datasource Customization……Page 428
11.13.1. Type Mapping……Page 429
11.13.2. Function Mapping……Page 432
11.13.3. Mapping……Page 433
11.13.4. User Type Mappings……Page 434
12.1. JAX-RPC Service Endpoints……Page 436
12.2. EJB Endpoints……Page 441
12.3.1. A JAX-RPC client……Page 443
12.3.2. Service references……Page 445
13.1. The Hibernate MBean……Page 449
13.2. Hibernate archives……Page 451
13.4. Using a HAR file inside of an EAR file……Page 453
13.5. The HAR Deployer……Page 454
14.1. Why AOP……Page 455
14.2.2. Advice and Aspect……Page 456
14.2.3.2. Use annotations……Page 457
14.2.3.3. Use Annotation in Application Classes……Page 458
14.2.4. Introduction and Mixin……Page 459
14.3.2. Compile annotation……Page 460
14.4. JBoss AOP Deployer……Page 461
14.4.2. Configure the AOP service……Page 462
14.5. Package and deploy AOP applications to JBoss……Page 463
14.5.1. Use pre-packaged aspects……Page 465
14.5.2. Develop your own aspects……Page 467
14.5.3. Package and deploy custom aspects……Page 469
Appendix A. The GNU Lesser General Public License (LGPL)……Page 472
Appendix B. Book Example Installation……Page 480
C.3. Anonymous CVS Access……Page 481
C.6. Building the JBoss Distribution Using the CVS Source Code……Page 482
C.7. An Overview of the JBoss CVS Source Tree……Page 483
C.8. Using the JBossTest unit testsuite……Page 484