Contents

List of Listings xiii

List of Figures xix

CHAPTER i Preface 15

Forward 15

About the Authors 16

About Open Source 17

About JBoss 18

JBoss: A Full J2EE Implementation with JMX 18

What this Book Covers 19

CHAPTER 1 Installing and Building the JBoss Server 15

Getting the Binary Files 16

Prerequisites 16

Installing the Binary Package 16

Directory Structure 17

The Default Server Configuration File Set 20

conf/jboss-minimal.xml 21

conf/jboss-service.xml 21

conf/jbossmq-state.xml 22

conf/jndi.properties 22

conf/log4j.xml 22

conf/login-config.xml 22

conf/server.policy 22

conf/standardjaws.xml 22

conf/standardjbosscmp-jdbc.xml 22

conf/standardjboss.xml 23

deploy/cache-invalidation-service.xml 23

deploy/client-deployer-service.xml 23

deploy/hsqldb-ds.xml 23

deploy/http-invoker.sar 23

deploy/jboss-jca.sar 23

deploy/jboss-local-jdbc.rar 24

deploy/jboss-xa.rar 24

deploy/jbossweb-tomcat41.sar 24

deploy/jms/jbossmq-destinations-service.xml 24

deploy/jms/jbossmq-httpil.sar 24

deploy/jms/jbossmq-service.xml 24

deploy/jms/jms-ra.rar 24

deploy/jms/jms-ds.xml 25

deploy/jms/jvm-il-service.xml 25

deploy/jms/oil-service.xml 25

deploy/jms/oil2-service.xml 25

deploy/jms/rmi-il-service.xml 25

deploy/jms/uil2-service.xml 25

deploy/jmx-console.war 25

deploy/jmx-invoker-adaptor-server.sar 26

deploy/mail-service.xml 26

deploy/management/console-mgr.sar, web-console.war 26

deploy/properties-service.xml 26

deploy/scheduler-service.xml, schedule-manager-service.xml 26

deploy/snmp-adaptor.sar 27

deploy/sqlexception-service.xml 27

deploy/transaction-service.xml 27

deploy/user-service.xml 27

deploy/uuid-key-generator.sar 27

Basic Installation Testing 27

Booting from a Network Server 30

Building the Server from Source Code 34

Accessing the JBoss CVS Repositories at SourceForge 34

Understanding CVS 34

Anonymous CVS Access 35

Obtaining a CVS Client 35

Building the JBoss-3.2.3 Distribution Using the Source Code 36

Building the JBoss-3.2.3 Distribution Using the CVS Source Code 36

An Overview of the JBoss CVS Source Tree 37

Using the JBossTest unit testsuite 38

CHAPTER 2 The JBoss JMX Microkernel 43

JMX 44

An Introduction to JMX 44

Instrumentation Level 46

Agent Level 46

Distributed Services Level 47

JMX Component Overview 47

Managed Beans or MBeans 47

Notification Model 48

MBean Metadata Classes 49

MBean Server 49

Agent Services 50

JBoss JMX Implementation Architecture 51

The JBoss ClassLoader Architecture 51

Class Loading and Types in Java 51

ClassCastExceptions - I'm Not Your Type 52

IllegalAccessException - Doing what you should not 57

LinkageErrors - Making Sure You Are Who You Say You Are 60

Debugging Class Loading Issues 65

Inside the JBoss Class Loading Architecture 67

Viewing Classes in the Loader Repository 69

Scoping Classes 72

The Complete Class Loading Model 72

JBoss XMBeans 75

Descriptors 76

The Management Class 79

The Constructors 80

The Attributes 80

The Operations 82

Notifications 83

Connecting to the JMX Server 85

Inspecting the Server - the JMX Console Web Application 85

Securing the JMX Console 88

Connecting to JMX Using RMI 90

Command Line Access to JMX 99

Setting the classpath for twiddle 100

Connecting twiddle to a Remote Server 100

Sample twiddle Command Usage 101

Connecting to JMX Using Any Protocol 104

Using JMX as a Microkernel 104

The Startup Process 105

JBoss MBean Services 106

The SARDeployer MBean 107

The Service Life Cycle Interface 110

The ServiceController MBean 111

The create(ObjectName) method 112

The start(ObjectName) method 113

The stop(ObjectName) method 113

The destroy(ObjectName) method 113

Specifying Service Dependencies 113

Identitifying Unsatisfied Dependencies 115

Hot Deployment of Components, the URLDeploymentScanner 115

Writing JBoss MBean Services 117

A Standard MBean Example 118

XMBean Examples 122

Version 1, the Annotated JNDIMap XMBean 123

Version 2, Adding Persistence to the JNDIMap XMBean 128

Version 3, Adding Security and Remote Access to the JNDIMap XMBean 135

Deployment Ordering and Dependencies 147

The JBoss Deployer Architecture 166

Deployers and ClassLoaders 169

Exposing MBean Events via SNMP 171

The SNMP Adaptor Service 172

The Event to Trap Service 173

Remote Access to Services, Detached Invokers 174

A Detached Invoker Example, the MBeanServer Invoker Adaptor Service 179

Detached Invoker Reference 185

The JRMPInvoker - RMI/JRMP Transport 185

The PooledInvoker - RMI/Socket Transport 186

The IIOPInvoker - RMI/IIOP Transport 187

The JRMPProxyFactory Service - Building Dynamic JRMP Proxies 188

The HttpInvoker - RMI/HTTP Transport 188

The HA JRMPInvoker - Clustered RMI/JRMP Transport 189

The HA HttpInvoker - Clustered RMI/HTTP Transport 189

HttpProxyFactory - Building Dynamic HTTP Proxies 190

Steps to Expose Any RMI Interface via HTTP 190

CHAPTER 3 Naming on JBoss - The JNDI Naming Service 193

An Overview of JNDI 194

The JNDI API 194

Names 194

Contexts 195

Obtaining a Context using InitialContext 196

J2EE and JNDI - The Application Component Environment 197

ENC Usage Conventions 198

The ejb-jar.xml ENC Elements 199

The web.xml ENC Elements 200

The jboss.xml ENC Elements 201

The jboss-web.xml ENC Elements 202

Environment Entries 203

EJB References 205

EJB References with jboss.xml and jboss-web.xml 207

EJB Local References 208

Resource Manager Connection Factory References 210

Resource Manager Connection Factory References with jboss.xml and jboss-web.xml 212

Resource Environment References 213

Resource Environment References and jboss.xml, jboss-web.xml 214

The JBossNS Architecture 215

The Naming InitialContext Factories 218

Naming Discovery in Clustered Environments 220

The HTTP InitialContext Factory Implementation 221

The Login InitialContext Factory Implementation 222

Accessing JNDI over HTTP 222

Accessing JNDI over HTTPS 227

Securing Access to JNDI over HTTP 231

Securing Access to JNDI with a Read-Only Unsecured Context 233

Additional Naming MBeans 234

org.jboss.naming.ExternalContext MBean 235

The org.jboss.naming.NamingAlias MBean 237

The org.jboss.naming.JNDIView MBean 237

CHAPTER 4 Transactions on JBoss - The JTA Transaction Service 241

Transaction/JTA Overview 241

Pessimistic and optimistic locking 242

The components of a distributed transaction 243

The two-phase XA protocol 244

Heuristic exceptions 244

Transaction IDs and branches 245

JBoss Transaction Internals 246

Adapting a Transaction Manager to JBoss 246

The Default Transaction Manager 247

org.jboss.tm.XidFactory 247

UserTransaction Support 248

CHAPTER 5 EJBs on JBoss - The EJB Container Configuration and Architecture 249

The EJB Client Side View 249

Specifying the EJB Proxy Configuration 254

The EJB Server Side View 258

Detached Invokers - The Transport Middlemen 259

The HA JRMPInvoker - Clustered RMI/JRMP Transport 264

The HA HttpInvoker - Clustered RMI/HTTP Transport 264

The EJB Container 265

EJBDeployer MBean 266

Verifying EJB deployments 267

Deploying EJBs Into Containers 267

Container configuration information 268

The container-name Element 273

The call-logging Element 273

The invoker-proxy-binding-name Element 273

The container-interceptors Element 273

The instance-pool and container-pool-conf Elements 273

The instance-cache and container-cache-conf Elements 275

The persistence-manager Element 277

The web-class-loader Element 277

The locking-policy Element 277

The commit-option and optiond-refresh-rate Element 278

The security-domain Element 279

cluster-config 279

depends 280

Container Plug-in Framework 280

org.jboss.ejb.ContainerPlugin 281

org.jboss.ejb.Interceptor 282

org.jboss.ejb.InstancePool 283

org.jboss.ebj.InstanceCache 284

org.jboss.ejb.EntityPersistenceManager 286

org.jboss.ejb.StatefulSessionPersistenceManager 292

Entity Bean Locking and Deadlock Detection 294

Why JBoss Needs Locking 294

Entity Bean Lifecycle 294

Default Locking Behavior 295

Method Lock 295

Transaction Lock 295

Pluggable Interceptors and Locking Policy 296

Deadlock 297

Dedlock Detection 297

Catching ApplicationDeadlockException 299

Viewing Lock Information 299

Advanced Configurations and Optimizations 300

Short-lived Transactions 300

Ordered Access 300

Read-Only Beans 301

Explicitly Defining Read-Only Methods 301

Instance Per Transaction Policy 302

Running Within a Cluster 304

Troubleshooting 305

Locking Behavior Not Working 305

IllegalStateException 305

Hangs and Transaction Timeouts 305

CHAPTER 6 Messaging on JBoss - JMS Configuration and Architecture 307

JMS Examples 308

A Point-To-Point Example 308

A Pub-Sub Example 311

A Pub-Sub With Durable Topic Example 319

A Point-To-Point With MDB Example 322

JBoss Messaging Overview 332

Invocation Layer 332

RMI IL (deprecated) 332

OIL IL (deprecated) 332

UIL IL (deprecated) 333

UIL2 IL 333

JVM IL 333

HTTP IL 333

Security Manager 334

Destination Manager 334

Message Cache 334

State Manager 334

Persistence Manager 334

File PM 335

Rolling Logged PM 335

JDBC2 PM 335

Destinations 335

Queues 335

Topics 336

JBoss Messaging Configuration and MBeans 336

org.jboss.mq.il.jvm.JVMServerILService 337

org.jboss.mq.il.rmi.RMIServerILService (deprecated) 338

org.jboss.mq.il.oil.OILServerILService (deprecated) 338

org.jboss.mq.il.uil.UILServerILService (deprecated) 339

org.jboss.mq.il.uil2.UILServerILService 340

Configuring ILs for SSL 341

org.jboss.mq.il.http.HTTPServerILService 342

org.jboss.mq.server.jmx.Invoker 343

org.jboss.mq.server.jmx.InterceptorLoader 343

org.jboss.mq.sm.file.DynamicStateManager 344

org.jboss.mq.security.SecurityManager 345

org.jboss.mq.server.jmx.DestinationManager 348

org.jboss.mq.server.MessageCache 349

org.jboss.mq.pm.file.CacheStore 349

org.jboss.mq.pm.file.PersistenceManager 350

org.jboss.mq.pm.rollinglogged.PersistenceManager 350

org.jboss.mq.pm.jdbc2.PersistenceManager 350

Destination MBeans 352

org.jboss.mq.server.jmx.Queue 353

org.jboss.mq.server.jmx.Topic 354

Administration Via JMX 356

Creating Queues At Runtime 356

Creating Topics At Runtime 356

Managing a JBossMQ User IDs at Runtime 357

Specifying the MDB JMS Provider 357

org.jboss.jms.jndi.JMSProviderLoader MBean 358

org.jboss.jms.asf.ServerSessionPoolLoader MBean 361

Integrating non-JBoss JMS Providers 361

CHAPTER 7 Connectors on JBoss - The JCA Configuration and Architecture 363

JCA Overview 363

An Overview of the JBossCX Architecture 368

BaseConnectionManager2 MBean 370

RARDeployment MBean 371

JBossManagedConnectionPool MBean 372

CachedConnectionManager MBean 373

A Sample Skeleton JCA Resource Adaptor 374

Configuring JCA Adaptors 383

Configuring JDBC DataSources 383

Configuring Generic JCA Adaptors 390

Sample Configurations 394

CHAPTER 8 Security on JBoss - J2EE Security Configuration and Architecture 397

J2EE Declarative Security Overview 397

Security References 401

Security Identity 402

Security roles 403

EJB method permissions 404

Web Content Security Constraints 407

Enabling Declarative Security in JBoss 409

An Introduction to JAAS 409

What is JAAS? 409

The JAAS Core Classes 410

Subject and Principal 410

Authentication of a Subject 411

The JBoss Security Model 415

Enabling Declarative Security in JBoss Revisited 418

The JBoss Security Extension Architecture 424

How the JaasSecurityManager Uses JAAS 426

The JaasSecurityManagerService MBean 429

An Extension to JaasSecurityManager, the JaasSecurityDomain MBean 432

An XML JAAS Login Configuration MBean 433

The JAAS Login Configuration Management MBean 435

Using and Writing JBossSX Login Modules 436

org.jboss.security.auth.spi.IdentityLoginModule 436

org.jboss.security.auth.spi.UsersRolesLoginModule 437

org.jboss.security.auth.spi.LdapLoginModule 440

org.jboss.security.auth.spi.DatabaseServerLoginModule 444

org.jboss.security.auth.spi.ProxyLoginModule 446

org.jboss.security.auth.spi.RunAsLoginModule 447

org.jboss.security.ClientLoginModule 448

Writing Custom Login Modules 449

Support for the Subject Usage Pattern 450

A Custom LoginModule Example 455

The Secure Remote Password (SRP) Protocol 460

Providing Password Information for SRP 465

Inside of the SRP algorithm 467

An SRP example 471

Running JBoss with a Java 2 security manager 474

Using SSL with JBoss using JSSE 478

Configuring JBoss for use Behind a Firewall 485

Howto Secure the JBoss Server 487

The jmx-console.war 488

The web-console.war 488

The http-invoker.sar 488

The jmx-invoker-adaptor-server.sar 488

CHAPTER 9 Integrating Servlet Containers 491

The AbstractWebContainer Class 491

The AbstractWebContainer Contract 493

Creating an AbstractWebContainer Subclass 500

Use the Thread Context Class Loader 500

Integrate Logging Using log4j 500

Delegate web container authentication and authorization to JBossSX 500

JBoss/Tomcat-4.1.x bundle notes 502

The Embedded Tomcat Configuration Elements 504

Server 504

Service 504

Connector 504

The HTTP Connector 505

The Coyote Connector 506

Engine 507

Host 508

Alias 508

DefaultContext 508

Manager 509

Logger 509

Valve 509

Listener 510

Using SSL with the JBoss/Tomcat bundle 510

Setting up Virtual Hosts with the JBoss/Tomcat-4.x bundle 518

Serving External Static Content 521

Using Apache with the JBoss/Tomcat-4.x bundle 523

Using Clustering 524

CHAPTER 10 MBean Services Miscellany 527

System Properties Management 527

Property Editor Management 528

Services Binding Management 529

Running Two JBoss Instances 532

Scheduling Tasks 537

org.jboss.varia.scheduler.Scheduler 538

The JBoss Logging Framework 541

org.jboss.logging.Log4jService 542

RMI Dynamic Class Loading 543

org.jboss.web.WebService 543

CHAPTER 11 The CMP Engine 545

Getting Started 545

Example Code 546

Tests 550

Read-ahead 553

The jbosscmp-jdbc Structure 554

DTD for jbosscmp-jdbc.xml 556

Entity Beans 556

Entity Mapping 560

CMP-Fields 564

CMP-Field Abstract Accessors 564

CMP-Field Declaration 564

CMP-Field Column Mapping 565

Read-only Fields 568

Auditng Entity Access 569

Dependent Value Classes (DVCs) 570

Container Managed Relationships 575

CMR-Field Abstract Accessors 575

Relationship Declaration 576

Relationship Mapping 578

Relationship Role Mapping 580

Foreign Key Mapping 584

Relation-table Mapping 585

Queries 587

Finder and ejbSelect Declaration 588

EJB-QL Declaration 588

Overriding the EJB-QL to SQL Mapping 590

JBossQL 591

DynamicQL 593

DeclaredSQL 594

Parameters 598

BMP Custom Finders 599

Optimized Loading 600

Loading Scenario 600

Load Groups 602

Read-ahead 603

on-find 604

on-load 605

none 608

Loading Process 609

Commit Options 609

Eager-loading Process 610

Lazy-loading Process 611

Relationships 612

Transactions 616

Optimistic Locking 619

Entity Commands and Primary Key Generation 626

Existing Entity Commands 627

Defaults 630

Datasource Customization 634

Function Mapping 637

Type Mapping 637

User Type Mappings 638

CHAPTER 12 Web Services 641

XDoclet 641

Installing XDoclet 642

A Hello World EJB as a Web Service 642

Declaring How to Handle Non-simple Types 645

Writing the Ant build.xml file 646

Creating a Web Service Client with Apache Axis 651

Appendix A The JBoss Group and Our LGPL License 655

About The JBoss Group 655

The GNU Lesser General Public License (LGPL) 655

Appendix B The JBoss DTDs 669

Appendix C Book Example Installation 671


© 2002-2004 JBoss Inc. All rights reserved.