Visit https://ebookfinal.

com to download the full version and

explore more ebooks

The Java EE 5 Tutorial 2nd ed Edition Eric

Jendrock

_____ Click the link below to download _____

https://ebookfinal.com/download/the-java-
ee-5-tutorial-2nd-ed-edition-eric-jendrock/

Explore and download more ebooks at ebookfinal.com

Here are some suggested products you might be interested in.
Click the link to download

Java EE 5 Development using GlassFish Application Server

1st Ed. Edition David R. Heffelfinger

https://ebookfinal.com/download/java-ee-5-development-using-glassfish-
application-server-1st-ed-edition-david-r-heffelfinger/

Java EE Development with Eclipse 2nd Edition Ram Kulkarni

https://ebookfinal.com/download/java-ee-development-with-eclipse-2nd-
edition-ram-kulkarni/

Java EE 6 Pocket Guide 1st Edition Arun Gupta

https://ebookfinal.com/download/java-ee-6-pocket-guide-1st-edition-
arun-gupta/

Beginning EJB 3 Java EE 7 edition Jonathan Wetherbee

https://ebookfinal.com/download/beginning-ejb-3-java-ee-7-edition-
jonathan-wetherbee/
Java EE 7 Development with NetBeans 8 3rd Edition David R.
Heffelfinger

https://ebookfinal.com/download/java-ee-7-development-with-
netbeans-8-3rd-edition-david-r-heffelfinger/

Java EE 7 Recipes A Problem Solution Approach 1st Edition

Josh Juneau (Auth.)

https://ebookfinal.com/download/java-ee-7-recipes-a-problem-solution-
approach-1st-edition-josh-juneau-auth/

Java 1 5 Tiger A Developer s Notebook 1st ed Edition David

Flanagan

https://ebookfinal.com/download/java-1-5-tiger-a-developer-s-
notebook-1st-ed-edition-david-flanagan/

Java in a nutshell 2nd ed Edition David Flanagan

https://ebookfinal.com/download/java-in-a-nutshell-2nd-ed-edition-
david-flanagan/

Java Concepts Compatible with Java 5 6 and 7 6th Edition

Cay S. Horstmann

https://ebookfinal.com/download/java-concepts-compatible-with-
java-5-6-and-7-6th-edition-cay-s-horstmann/
The Java EE 5 Tutorial 2nd ed Edition Eric Jendrock
Digital Instant Download
Author(s): Eric Jendrock
ISBN(s): 9780321490292, 0321490290
Edition: 2nd ed
File Details: PDF, 8.88 MB
Year: 2006
Language: english
 The Java™ EE 5
Tutorial

For Sun Java System Application Server Platform Edition 9

Jennifer Ball
Debbie Bode Carson
Ian Evans
Kim Haase
Eric Jendrock

May 10, 2006

Copyright © 2006 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A.
All rights reserved.U.S. Government Rights - Commercial software. Government users are subject to the
Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supple-
ments.

This distribution may include materials developed by third parties.

Sun, Sun Microsystems, the Sun logo, Java, JavaBeans, JavaServer, JavaServer Pages, Enterprise Java-
Beans, Java Naming and Directory Interface, JavaMail, JDBC, EJB, JSP, J2EE, J2SE, “Write Once, Run
Anywhere”, and the Java Coffee Cup logo are trademarks or registered trademarks of Sun Microsystems,
Inc. in the U.S. and other countries.
Unless otherwise licensed, software code in all technical materials herein (including articles, FAQs, sam-
ples) is provided under this License.
Products covered by and information contained in this service manual are controlled by U.S. Export Con-
trol laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical
biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly pro-
hibited. Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export
exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is
strictly prohibited.
DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS,
REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MER-
CHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE
DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE
LEGALLY INVALID.

Copyright © 2006 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, États-
Unis. Tous droits réservés.
Droits du gouvernement américain, utlisateurs gouvernmentaux - logiciel commercial. Les utilisateurs
gouvernmentaux sont soumis au contrat de licence standard de Sun Microsystems, Inc., ainsi qu aux dis-
positions en vigueur de la FAR [ (Federal Acquisition Regulations) et des suppléments à celles-ci.
Cette distribution peut comprendre des composants développés pardes tierces parties.
Sun, Sun Microsystems, le logo Sun, Java, JavaBeans, JavaServer, JavaServer Pages, Enterprise Java-
Beans, Java Naming and Directory Interface, JavaMail, JDBC, EJB, JSP, J2EE, J2SE, “Write Once, Run
Anywhere”, et le logo Java Coffee Cup sont des marques de fabrique ou des marques déposées de Sun
Microsystems, Inc. aux États-Unis et dans d’autres pays.
A moins qu’autrement autorisé, le code de logiciel en tous les matériaux techniques dans le présent (arti-
cles y compris, FAQs, échantillons) est fourni sous ce permis.
Les produits qui font l’objet de ce manuel d’entretien et les informations qu’il contient sont régis par la
législation américaine en matière de contrôle des exportations et peuvent être soumis au droit d’autres
pays dans le domaine des exportations et importations. Les utilisations finales, ou utilisateurs finaux, pour
des armes nucléaires, des missiles, des armes biologiques et chimiques ou du nucléaire maritime, directe-
ment ou indirectement, sont strictement interdites. Les exportations ou réexportations vers des pays sous
embargo des États-Unis, ou vers des entités figurant sur les listes d’exclusion d’exportation américaines,
y compris, mais de manière non exclusive, la liste de personnes qui font objet d’un ordre de ne pas partic-
iper, d’une façon directe ou indirecte, aux exportations des produits ou des services qui sont régi par la
législation américaine en matière de contrôle des exportations ("U .S. Commerce Department’s Table of
Denial Orders "et la liste de ressortissants spécifiquement désignés ("U.S. Treasury Department of Spe-
cially Designated Nationals and Blocked Persons "),, sont rigoureusement interdites.

LA DOCUMENTATION EST FOURNIE "EN L’ÉTAT" ET TOUTES AUTRES CONDITIONS, DEC-

LARATIONS ET GARANTIES EXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES,
DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE, Y COMPRIS NOTAMMENT TOUTE
GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L’APTITUDE A UNE
UTILISATION PARTICULIERE OU A L’ABSENCE DE CONTREFAÇON.
 Contents
About This Tutorial. . . . . . . . . . . . . . . . . . . . . . . . . xxvii
Who Should Use This Tutorial xxvii
Prerequisites xxvii
How to Read This Tutorial xxviii
About the Examples xxx
Further Information xxxiv
How to Print This Tutorial xxxiv
Typographical Conventions xxxiv
Feedback xxxv

Chapter 1: Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Java EE Application Model 2
Distributed Multitiered Applications 3
Security 4
Java EE Components 5
Java EE Clients 5
Web Components 7
Business Components 8
Enterprise Information System Tier 9
Java EE Containers 9
Container Services 10
Container Types 11
Web Services Support 12
XML 12
SOAP Transport Protocol 13
WSDL Standard Format 13
UDDI and ebXML Standard Formats 14
Java EE Application Assembly and Deployment 14
Packaging Applications 14
iii
iv CONTENTS

Development Roles 16
Java EE Product Provider 16
Tool Provider 17
Application Component Provider 17
Application Assembler 18
Application Deployer and Administrator 18
Java EE 5 APIs 19
Enterprise JavaBeans Technology 20
Java Servlet Technology 20
JavaServer Pages Technology 20
JavaServer Pages Standard Tag Library 20
JavaServer Faces 21
Java Message Service API 21
Java Transaction API 22
JavaMail API 22
JavaBeans Activation Framework 22
Java API for XML Processing 22
Java API for XML Web Services (JAX-WS) 23
Java Architecture for XML Binding (JAXB) 23
SOAP with Attachments API for Java 23
Java API for XML Registries 24
J2EE Connector Architecture 24
Java Database Connectivity API 24
Java Persistence API 25
Java Naming and Directory Interface 25
Java Authentication and Authorization Service 26
Simplified Systems Integration 26
Sun Java System Application Server Platform Edition 9 27
Tools 27
Starting and Stopping the Application Server 28
Starting the Admin Console 29
Starting and Stopping the Java DB Database Server 30
Debugging Java EE Applications 30

Part One: The Web Tier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33

Chapter 2: Getting Started with Web Applications. . . . . . . . . .35

Web Application Life Cycle 38
Web Modules 40
Packaging Web Modules 42
Deploying a WAR File 43
 CONTENTS v

Testing Deployed Web Modules 44

Listing Deployed Web Modules 44
Updating Web Modules 45
Undeploying Web Modules 47
Configuring Web Applications 48
Mapping URLs to Web Components 48
Declaring Welcome Files 49
Setting Initialization Parameters 50
Mapping Errors to Error Screens 50
Declaring Resource References 51
Duke’s Bookstore Examples 54
Accessing Databases from Web Applications 54
Populating the Example Database 55
Creating a Data Source in the Application Server 55
Further Information 56

Chapter 3: Java Servlet Technology . . . . . . . . . . . . . . . . . . . . . 57

What Is a Servlet? 57
The Example Servlets 58
Troubleshooting 60
Servlet Life Cycle 61
Handling Servlet Life-Cycle Events 61
Handling Errors 64
Sharing Information 64
Using Scope Objects 64
Controlling Concurrent Access to Shared Resources 65
Accessing Databases 67
Initializing a Servlet 68
Writing Service Methods 69
Getting Information from Requests 70
Constructing Responses 72
Filtering Requests and Responses 75
Programming Filters 75
Programming Customized Requests and Responses 77
Specifying Filter Mappings 80
Invoking Other Web Resources 82
Including Other Resources in the Response 82
Transferring Control to Another Web Component 84
Accessing the Web Context 85
Maintaining Client State 86
vi CONTENTS

Accessing a Session 86
Associating Objects with a Session 86
Session Management 87
Session Tracking 88
Finalizing a Servlet 89
Tracking Service Requests 89
Notifying Methods to Shut Down 90
Creating Polite Long-Running Methods 91
Further Information 92

Chapter 4: JavaServer Pages Technology . . . . . . . . . . . . . . . .93

What Is a JSP Page? 93
Example 94
The Example JSP Pages 97
The Life Cycle of a JSP Page 102
Translation and Compilation 102
Execution 103
Creating Static Content 105
Response and Page Encoding 105
Creating Dynamic Content 106
Using Objects within JSP Pages 106
Unified Expression Language 107
Immediate and Deferred Evaluation Syntax 110
Value and Method Expressions 111
Defining a Tag Attribute Type 118
Deactivating Expression Evaluation 119
Literal Expressions 121
Resolving Expressions 122
Implicit Objects 125
Operators 126
Reserved Words 127
Examples 127
Functions 129
JavaBeans Components 130
JavaBeans Component Design Conventions 131
Creating and Using a JavaBeans Component 132
Setting JavaBeans Component Properties 133
Retrieving JavaBeans Component Properties 136
Using Custom Tags 136
Declaring Tag Libraries 137
 CONTENTS vii

Including the Tag Library Implementation 139

Reusing Content in JSP Pages 139
Transferring Control to Another Web Component 140
jsp:param Element 141
Including an Applet 141
Setting Properties for Groups of JSP Pages 144
Further Information 147

Chapter 5: JavaServer Pages Documents . . . . . . . . . . . . . . . 149

The Example JSP Document 150
Creating a JSP Document 152
Declaring Tag Libraries 154
Including Directives in a JSP Document 156
Creating Static and Dynamic Content 158
Using the jsp:root Element 161
Using the jsp:output Element 162
Identifying the JSP Document to the Container 166

Chapter 6: JavaServer Pages Standard Tag Library . . . . . . . 167

The Example JSP Pages 168
Using JSTL 169
Tag Collaboration 170
Core Tag Library 172
Variable Support Tags 172
Flow Control Tags 174
URL Tags 177
Miscellaneous Tags 178
XML Tag Library 180
Core Tags 181
Flow Control Tags 182
Transformation Tags 183
Internationalization Tag Library 184
Setting the Locale 185
Messaging Tags 185
Formatting Tags 186
SQL Tag Library 187
query Tag Result Interface 189
Functions 191
Further Information 192
viii CONTENTS

Chapter 7: Custom Tags in JSP Pages . . . . . . . . . . . . . . . . . . .195

What Is a Custom Tag? 196
The Example JSP Pages 196
Types of Tags 199
Tags with Attributes 199
Tags with Bodies 202
Tags That Define Variables 203
Communication between Tags 203
Encapsulating Reusable Content Using Tag Files 204
Tag File Location 206
Tag File Directives 206
Evaluating Fragments Passed to Tag Files 215
Examples 215
Tag Library Descriptors 220
Top-Level Tag Library Descriptor Elements 221
Declaring Tag Files 222
Declaring Tag Handlers 225
Declaring Tag Attributes for Tag Handlers 227
Declaring Tag Variables for Tag Handlers 229
Programming Simple Tag Handlers 231
Including Tag Handlers in Web Applications 231
How Is a Simple Tag Handler Invoked? 232
Tag Handlers for Basic Tags 232
Tag Handlers for Tags with Attributes 232
Tag Handlers for Tags with Bodies 236
Tag Handlers for Tags That Define Variables 237
Cooperating Tags 240
Examples 242

Chapter 8: Scripting in JSP Pages . . . . . . . . . . . . . . . . . . . . . .251

The Example JSP Pages 252
Using Scripting 253
Disabling Scripting 253
Declarations 254
Initializing and Finalizing a JSP Page 254
Scriptlets 255
Expressions 256
Programming Tags That Accept Scripting Elements 257
TLD Elements 257
Tag Handlers 257
 CONTENTS ix

Tags with Bodies 260

Cooperating Tags 261
Tags That Define Variables 263

Chapter 9: JavaServer Faces Technology . . . . . . . . . . . . . . . 265

JavaServer Faces Technology Benefits 267
What is a JavaServer Faces Application? 268
A Simple JavaServer Faces Application 268
Steps in the Development Process 269
Mapping the FacesServlet Instance 270
Creating the Pages 271
Defining Page Navigation 278
Configuring Error Messages 279
Developing the Beans 279
Adding Managed Bean Declarations 280
User Interface Component Model 281
User Interface Component Classes 282
Component Rendering Model 284
Conversion Model 289
Event and Listener Model 290
Validation Model 291
Navigation Model 292
Backing Beans 295
The Life Cycle of a JavaServer Faces Page 300
Further Information 306

Chapter 10: Using JavaServer Faces Technology in JSP Pages . .

307
The Example JavaServer Faces Application 308
Setting Up a Page 310
Using the Core Tags 313
Using the HTML Component Tags 316
UI Component Tag Attributes 317
The UIForm Component 319
The UIColumn Component 320
The UICommand Component 321
The UIData Component 323
The UIGraphic Component 326
The UIInput and UIOutput Components 327
x CONTENTS

The UIPanel Component 332

The UISelectBoolean Component 335
The UISelectMany Component 335
The UIMessage and UIMessages Components 337
The UISelectOne Component 338
The UISelectItem, UISelectItems, and UISelectItemGroup Components
339
Using Localized Data 343
Loading a Resource Bundle 343
Referencing Localized Static Data 344
Referencing Error Messages 345
Using the Standard Converters 347
Converting a Component’s Value 348
Using DateTimeConverter 349
Using NumberConverter 351
Registering Listeners on Components 353
Registering a Value-Change Listener on a Component 354
Registering an Action Listener on a Component 355
Using the Standard Validators 356
Requiring a Value 358
Using the LongRangeValidator 359
Binding Component Values and Instances to External Data Sources
359
Binding a Component Value to a Property 361
Binding a Component Value to an Implicit Object 363
Binding a Component Instance to a Bean Property 364
Binding Converters, Listeners, and Validators to Backing Bean Prop-
erties 365
Referencing a Backing Bean Method 367
Referencing a Method That Performs Navigation 368
Referencing a Method That Handles an Action Event 369
Referencing a Method That Performs Validation 370
Referencing a Method That Handles a Value-change Event 370
Using Custom Objects 371
Using a Custom Converter 372
Using a Custom Validator 373
Using a Custom Component 374

Chapter 11: Developing with JavaServer Faces Technology .377

Writing Bean Properties 378
 CONTENTS xi

Writing Properties Bound to Component Values 379

Writing Properties Bound to Component Instances 387
Writing Properties Bound to Converters, Listeners, or Validators 389
Performing Localization 390
Creating a Resource Bundle 390
Localizing Dynamic Data 391
Localizing Messages 391
Creating a Custom Converter 393
Implementing an Event Listener 396
Implementing Value-Change Listeners 397
Implementing Action Listeners 398
Creating a Custom Validator 399
Implementing the Validator Interface 400
Creating a Custom Tag 404
Writing Backing Bean Methods 406
Writing a Method to Handle Navigation 407
Writing a Method to Handle an Action Event 409
Writing a Method to Perform Validation 409
Writing a Method to Handle a Value-Change Event 410

Chapter 12: Creating Custom UI Components . . . . . . . . . . . . 413

Determining Whether You Need a Custom Component or Renderer
414
When to Use a Custom Component 414
When to Use a Custom Renderer 415
Component, Renderer, and Tag Combinations 416
Understanding the Image Map Example 417
Why Use JavaServer Faces Technology to Implement an Image Map?
418
Understanding the Rendered HTML 418
Understanding the JSP Page 419
Configuring Model Data 421
Summary of the Application Classes 423
Steps for Creating a Custom Component 424
Creating Custom Component Classes 425
Specifying the Component Family 428
Performing Encoding 428
Performing Decoding 430
Enabling Component Properties to Accept Expressions 431
Saving and Restoring State 433
xii CONTENTS

Delegating Rendering to a Renderer 434

Creating the Renderer Class 435
Identifying the Renderer Type 436
Handling Events for Custom Components 437
Creating the Component Tag Handler 438
Retrieving the Component Type 439
Setting Component Property Values 439
Providing the Renderer Type 442
Releasing Resources 443
Defining the Custom Component Tag in a Tag Library Descriptor 443

Chapter 13: Configuring JavaServer Faces Applications . . . .447

Application Configuration Resource File 448
Configuring Beans 449
Using the managed-bean Element 450
Initializing Properties using the managed-property Element 451
Initializing Maps and Lists 458
Registering Custom Error Messages 459
Registering Custom Localized Static Text 460
Registering a Custom Validator 461
Registering a Custom Converter 462
Configuring Navigation Rules 463
Registering a Custom Renderer with a Render Kit 466
Registering a Custom Component 469
Basic Requirements of a JavaServer Faces Application 470
Configuring an Application with a Deployment Descriptor 471
Including the Required JAR Files 478
Including the Classes, Pages, and Other Resources 478

Chapter 14: Internationalizing and Localizing Web Applications .

481
Java Platform Localization Classes 481
Providing Localized Messages and Labels 482
Establishing the Locale 483
Setting the Resource Bundle 484
Retrieving Localized Messages 485
Date and Number Formatting 486
Character Sets and Encodings 487
Character Sets 487
 CONTENTS xiii

Character Encoding 488

Further Information 491

Part Two: Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493

Chapter 15: Building Web Services with JAX-WS . . . . . . . . . . . 495

Setting the Port 496
Creating a Simple Web Service and Client with JAX-WS 496
Requirements of a JAX-WS Endpoint 498
Coding the Service Endpoint Implementation Class 498
Building and Packaging the Service 499
Deploying the Service 499
A Simple JAX-WS Client 501
Types Supported by JAX-WS 503
Web Services Interoperability and JAX-WS 503
Further Information 503

Chapter 16: Binding between XML Schema and Java Classes . .

505
JAXB Architecture 506
Architectural Overview 506
The JAXB Binding Process 507
More About Unmarshalling 508
More About Marshalling 508
More About Validation 508
Representing XML Content 509
Java Representation of XML Schema 509
Binding XML Schemas 509
Simple Type Definitions 509
Default Data Type Bindings 510
Customizing JAXB Bindings 512
Schema-to-Java 512
Java-to-Schema 513
Examples 518
General Usage Instructions 519
Description 520
Using the Examples 523
Configuring and Running the Samples 523
JAXB Compiler Options 523
JAXB Schema Generator Options 525
xiv CONTENTS

About the Schema-to-Java Bindings 526

Schema-Derived JAXB Classes 529
Basic Examples 537
Modify Marshal Example 537
Unmarshal Validate Example 539
Customizing JAXB Bindings 540
Why Customize? 541
Customization Overview 542
Customize Inline Example 555
Datatype Converter Example 560
External Customize Example 561
Java-toSchema Examples 565
j2s-create-marshal Example 565
j2s-xmlAccessorOrder Example 565
j2s-xmlAdapter-field Example 568
j2s-xmlAttribute-field Example 571
j2s-xmlRootElement Example 572
j2s-xmlSchemaType-class Example 572
j2s-xmlType Example 573

Chapter 17: Streaming API for XML . . . . . . . . . . . . . . . . . . . . . .575

Why StAX? 575
Streaming Versus DOM 576
Pull Parsing Versus Push Parsing 577
StAX Use Cases 577
Comparing StAX to Other JAXP APIs 578
StAX API 579
Cursor API 579
Iterator API 580
Choosing Between Cursor and Iterator APIs 585
Using StAX 587
StAX Factory Classes 587
Resources, Namespaces, and Errors 589
Reading XML Streams 590
Writing XML Streams 593
Sun’s Streaming Parser Implementation 595
Reporting CDATA Events 595
SJSXP Factories Implementation 596
Sample Code 597
Sample Code Organization 597
 CONTENTS xv

Configuring Your Environment for Running the Samples 598

Running the Samples 599
Sample XML Document 600
cursor Sample – CursorParse.java 600
cursor2event Sample – CursorApproachEventObject.java 603
event Sample – EventParse.java 604
filter Sample – MyStreamFilter.java 606
readnwrite Sample – EventProducerConsumer.java 609
writer Sample – CursorWriter.java 611
Further Information 613

Chapter 18: SOAP with Attachments API for Java . . . . . . . . . . 615

Overview of SAAJ 616
Messages 616
Connections 620
Tutorial 621
Creating and Sending a Simple Message 622
Adding Content to the Header 631
Adding Content to the SOAPPart Object 632
Adding a Document to the SOAP Body 634
Manipulating Message Content Using SAAJ or DOM APIs 634
Adding Attachments 635
Adding Attributes 637
Using SOAP Faults 643
Code Examples 649
Request.java 650
MyUddiPing.java 651
HeaderExample.java 658
DOMExample.java and DOMSrcExample.java 660
Attachments.java 664
SOAPFaultTest.java 666
Further Information 668

Chapter 19: Java API for XML Registries . . . . . . . . . . . . . . . . . . 671

Overview of JAXR 671
What Is a Registry? 671
What Is JAXR? 672
JAXR Architecture 673
Implementing a JAXR Client 674
xvi CONTENTS

Establishing a Connection 675

Querying a Registry 681
Managing Registry Data 686
Using Taxonomies in JAXR Clients 694
Running the Client Examples 699
Before You Compile the Examples 700
Compiling the Examples 701
Running the Examples 702
Using JAXR Clients in Java EE Applications 707
Coding the Application Client: MyAppClient.java 707
Coding the PubQuery Session Bean 708
Editing the Properties File 708
Starting the Application Server 708
Creating JAXR Resources 709
Compiling the Source Files and Packaging the Application 710
Deploying the Application 710
Running the Application Client 710
Further Information 711

Part Three: Enterprise Beans. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .713

Chapter 20: Enterprise Beans . . . . . . . . . . . . . . . . . . . . . . . . . . .715

What Is an Enterprise Bean? 715
Benefits of Enterprise Beans 715
When to Use Enterprise Beans 716
Types of Enterprise Beans 717
What Is a Session Bean? 717
State Management Modes 717
When to Use Session Beans 718
What Is a Message-Driven Bean? 719
What Makes Message-Driven Beans Different from Session and Entity
Beans? 719
When to Use Message-Driven Beans 721
Defining Client Access with Interfaces 721
Remote Clients 722
Local Clients 722
Deciding on Remote or Local Access 723
Web Service Clients 724
Method Parameters and Access 724
The Contents of an Enterprise Bean 725
Naming Conventions for Enterprise Beans 726
 CONTENTS xvii

The Life Cycles of Enterprise Beans 727

The Life Cycle of a Stateful Session Bean 727
The Life Cycle of a Stateless Session Bean 728
The Life Cycle of a Message-Driven Bean 729
Further Information 729

Chapter 21: Getting Started with Enterprise Beans . . . . . . . . . 731

Creating the Enterprise Bean 732
Coding the Enterprise Bean 732
Compiling and Packaging converter 733
Creating the Application Client 734
Coding the Application Client 735
Compiling the Application Client 736
Creating the Web Client 737
Coding the Web Client 737
Compiling the Web Client 738
Deploying the Java EE Application 739
Running the Application Client 739
Running the Web Client 739
Modifying the Java EE Application 740
Modifying a Class File 740

Chapter 22: Session Bean Examples . . . . . . . . . . . . . . . . . . . . . 743

The cart Example 743
Session Bean Class 745
The Remove Method 748
Helper Classes 749
Building and Packaging the CartBean Example 749
Undeploying cart 750
A Web Service Example: HelloServiceBean 751
The Web Service Endpoint Implementation Class 751
Stateless Session Bean Implementation Class 752
Building and Packaging helloservice 753
Deploying helloservice 753
Using the Timer Service 754
The Timeout Method 754
Creating Timers 754
Canceling and Saving Timers 755
Getting Timer Information 756
xviii CONTENTS

Transactions and Timers 756

The timersession Example 756
Building and Packaging timersession 757
Deploying timersession 758
Handling Exceptions 759

Chapter 23: A Message-Driven Bean Example . . . . . . . . . . . .761

Example Application Overview 761
The Application Client 762
The Message-Driven Bean Class 763
The onMessage Method 764
Packaging, Deploying, and Running SimpleMessage 765
Creating the Administered Objects 765
Creating and Packaging the Application 766
Deploying the Application 766
Running the Client 767
Removing the Administered Objects 767
Creating Deployment Descriptors for Message-Driven Beans 768

Part Four: Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .769

Chapter 24: Introduction to the Java Persistence API . . . . . . .771

Entities 771
Requirements for Entity Classes 772
Persistent Fields and Properties in Entity Classes 772
Primary Keys in Entities 774
Multiplicity in Entity Relationships 776
Direction in Entity Relationships 777
Managing Entities 779
The Persistence Context 779
The EntityManager 779
Persistence Units 785

Chapter 25: Persistence in the Web Tier . . . . . . . . . . . . . . . . . .787

Accessing Databases from Web Applications 787
Populating the Example Database 789
Creating a Data Source in the Application Server 789
Defining the Persistence Unit 790
Creating an Entity Class 790
 CONTENTS xix

Obtaining Access to an Entity Manager 792

Accessing Data From the Database 794
Updating Data in the Database 795

Chapter 26: Persistence in the EJB Tier . . . . . . . . . . . . . . . . . . . 797

Overview of the order Application 797
Entity Relationships in order 798
Primary Keys in order 800
Entity Mapped to More Than One Database Table 804
Cascade Operations in order 805
BLOB and CLOB Database Types in order 805
Temporal Types in order 806
Managing order’s Entities 807
Building and Running order 810
Creating the Database Tables 810
Building and Packaging the Application 810
Deploying the Application 810
Running the Application 811
Undeploying order 812
The roster Application 812
Relationships in the roster Application 813
Automatic Table Generation in roster 814
Building and Running roster 814
Building and Packaging the roster Application 815
Deploying the Application 815
Running the Application 815
Undeploying order 816

Chapter 27: The Java Persistence Query Language . . . . . . . . 817

Terminology 817
Simplified Syntax 818
Select Statements 818
Update and Delete Statements 819
Example Queries 819
Simple Queries 820
Queries That Navigate to Related Entities 821
Queries with Other Conditional Expressions 823
Bulk Updates and Deletes 825
Full Syntax 826
xx CONTENTS

BNF Symbols 826

BNF Grammar of the Java Persistence Query Language 827
FROM Clause 832
Path Expressions 836
WHERE Clause 837
SELECT Clause 848
ORDER BY Clause 851
The GROUP BY Clause 851

Part Five: Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .853

Chapter 28: Introduction to Security in Java EE . . . . . . . . . . . .855

Overview 856
A Simple Example 857
Security Functions 860
Characteristics of Application Security 861
Security Implementation Mechanisms 862
Java SE Security Implementation Mechanisms 862
Java EE Security Implementation Mechanisms 863
Securing Containers 866
Using Deployment Descriptors for Declarative Security 867
Using Annotations 868
Using Programmatic Security 869
Securing the Application Server 869
Working with Realms, Users, Groups, and Roles 871
What is a Realm, User, Group, and Role? 871
Managing Users and Groups on the Application Server 875
Setting Up Security Roles 876
Mapping Roles to Users and Groups 878
Establishing a Secure Connection Using SSL 879
Installing and Configuring SSL Support 880
Specifying a Secure Connection in Your Application Deployment De-
scriptor 880
Verifying SSL Support 881
Working with Digital Certificates 883
Enabling Mutual Authentication over SSL 888
Further Information 891

Chapter 29: Securing Java EE Applications . . . . . . . . . . . . . . .893

Securing Enterprise Beans 894
 CONTENTS xxi

Accessing an Enterprise Bean Caller’s Security Context 896

Declaring Security Role Names Referenced from Enterprise Bean Code
898
Defining a Security View of Enterprise Beans 901
Using Enterprise Bean Security Annotations 913
Using Enterprise Bean Security Deployment Descriptor Elements 914
Configuring IOR Security 915
Deploying Secure Enterprise Beans 918
Enterprise Bean Example Applications 919
Example: Securing an Enterprise Bean 919
Discussion: Securing the Duke’s Bank Example 925
Securing Application Clients 926
Using Login Modules 926
Using Programmatic Login 927
Securing EIS Applications 928
Container-Managed Sign-On 928
Component-Managed Sign-On 929
Configuring Resource Adapter Security 929
Mapping an Application Principal to EIS Principals 931
Further Information 932

Chapter 30: Securing Web Applications. . . . . . . . . . . . . . . . . . 933

Overview 934
Working with Security Roles 936
Declaring Security Roles 937
Mapping Security Roles to Application Server Groups 940
Checking Caller Identity Programmatically 941
Declaring and Linking Role References 943
Defining Security Requirements for Web Applications 945
Declaring Security Requirements Using Annotations 946
Declaring Security Requirements in a Deployment Descriptor 948
Specifying a Secure Connection 955
Specifying an Authentication Mechanism 957
Examples: Securing Web Applications 963
Example: Basic Authentication with JAX-WS 964
Further Information 970

Chapter 31: Securing Web Services . . . . . . . . . . . . . . . . . . . . . 971

Securing Web Service Endpoints 972
xxii CONTENTS

Overview of Message Security 972

Advantages of Message Security 973
Message Security Mechanisms 975
Web Services Security Initiatives and Organizations 976
W3C Specifications 976
OASIS Specifications 977
JCP Specifications 978
WS-I Specifications 979
Using Message Security with Java EE 981
Using the Application Server Message Security Implementation 982
Using the Java WSDP XWSS Security Implementation 987
Further Information 991

Chapter 32: The Java Message Service API . . . . . . . . . . . . . . .993

Overview 993
What Is Messaging? 994
What Is the JMS API? 994
When Can You Use the JMS API? 995
How Does the JMS API Work with the Java EE Platform? 996
Basic JMS API Concepts 997
JMS API Architecture 998
Messaging Domains 999
Message Consumption 1001
The JMS API Programming Model 1001
Administered Objects 1002
Connections 1004
Sessions 1005
Message Producers 1006
Message Consumers 1007
Messages 1009
Queue Browsers 1012
Exception Handling 1013
Writing Simple JMS Client Applications 1013
A Simple Example of Synchronous Message Receives 1014
A Simple Example of Asynchronous Message Consumption 1021
A Simple Example of Browsing Messages in a Queue 1025
Running JMS Client Programs on Multiple Systems 1028
Creating Robust JMS Applications 1033
Using Basic Reliability Mechanisms 1034
Using Advanced Reliability Mechanisms 1041
 CONTENTS xxiii

Using the JMS API in a Java EE Application 1052

Using @Resource Annotations in Java EE Components 1053
Using Session Beans to Produce and to Synchronously Receive Messages
1053
Using Message-Driven Beans 1054
Managing Distributed Transactions 1057
Using the JMS API with Application Clients and Web Components1059
Further Information 1060

Chapter 33: Java EE Examples Using the JMS API . . . . . . . . . 1061

A Java EE Application That Uses the JMS API with a Session Bean
1062
Writing the Application Components 1062
Creating and Packaging the Application 1065
Deploying the Application 1066
Running the Application Client 1067
A Java EE Application That Uses the JMS API with an Entity 1067
Overview of the Human Resources Application 1068
Writing the Application Components 1070
Creating and Packaging the Application 1072
Deploying the Application 1073
Running the Application Client 1074
An Application Example That Consumes Messages from a Remote
Java EE Server 1075
Overview of the Modules 1076
Writing the Components 1077
Creating and Packaging the Modules 1077
Deploying the EJB Module and Copying the Client 1079
Running the Application Client 1079
An Application Example That Deploys a Message-Driven Bean on Two
Java EE Servers 1080
Overview of the Modules 1081
Writing the Module Components 1082
Creating and Packaging the Modules 1084
Deploying the Modules 1084
Running the Application Client 1085

Chapter 34: Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1089

What Is a Transaction? 1089
xxiv CONTENTS

Container-Managed Transactions 1090

Transaction Attributes 1091
Rolling Back a Container-Managed Transaction 1095
Synchronizing a Session Bean’s Instance Variables 1096
Methods Not Allowed in Container-Managed Transactions 1096
Bean-Managed Transactions 1097
JTA Transactions 1097
Returning without Committing 1098
Methods Not Allowed in Bean-Managed Transactions 1098
Transaction Timeouts 1098
Updating Multiple Databases 1099
Transactions in Web Components 1101

Chapter 35: Resource Connections . . . . . . . . . . . . . . . . . . . . .1103

Resources and JNDI Naming 1103
DataSource Objects and Connection Pools 1105
Resource Injection 1106
Field-Based Injection 1107
Method-Based Injection 1108
Class-Based Injection 1109
Further Information 1110

Chapter 36: Connector Architecture . . . . . . . . . . . . . . . . . . . .1111

About Resource Adapters 1111
Resource Adapter Contracts 1113
Management Contracts 1113
Outbound Contracts 1115
Inbound Contracts 1116
Common Client Interface 1116
Further Information 1118

Part Six: Case Studies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1119

Chapter 37: The Coffee Break Application . . . . . . . . . . . . . . .1121

Common Code 1122
JAX-WS Coffee Supplier Service 1122
Service Implementation 1123
SAAJ Coffee Supplier Service 1124
SAAJ Client 1125
 CONTENTS xxv

SAAJ Service 1133

Coffee Break Server 1139
JSP Pages 1140
JavaBeans Components 1143
RetailPriceListServlet 1145
Resource Configuration 1145
Building, Packaging, Deploying, and Running the Application 1146
Setting the Port 1146
Building the Common Classes 1147
Building, Packaging, and Deploying the JAX-WS Service 1147
Building, Packaging, and Deploying the SAAJ Service 1148
Building, Packaging, and Deploying the Coffee Break Server 1148
Running the Coffee Break Client 1148
Removing the Coffee Break Application 1150

Chapter 38: The Duke’s Bank Application . . . . . . . . . . . . . . . 1151

Enterprise Beans 1152
Session Beans 1153
Java Persistence Entities 1155
Helper Classes 1156
Database Tables 1156
Protecting the Enterprise Beans 1157
Application Client 1158
The Classes and Their Relationships 1160
BankAdmin Class 1160
Web Client 1161
Design Strategies 1163
Client Components 1164
Request Processing 1167
Protecting the Web Client Resources 1170
Building, Packaging, Deploying, and Running the Application 1171
Setting Up the Servers 1172
Building the Duke’s Bank Application 1173
Running the Clients 1173
Running the Application Client 1173
Running the Web Client 1174

Appendix A: Java Encoding Schemes. . . . . . . . . . . . . . . . . . . 1177

Further Information 1178
xxvi CONTENTS

About the Authors . . . . . . . . . . . . . . . . . . . . . . . . .1179

Current Writers 1179

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1181
 About This Tutorial

THE Java™ EE 5 Tutorial is a guide to developing enterprise applications for

the Java Platform, Enterprise Edition 5 (Java EE 5). Here we cover all the things
you need to know to make the best use of this tutorial.

Who Should Use This Tutorial

This tutorial is intended for programmers who are interested in developing and
deploying Java EE 5 applications on the Sun Java System Application Server
Platform Edition 9.

Prerequisites
Before proceeding with this tutorial you should have a good knowledge of the
Java programming language. A good way to get to that point is to work through
all the basic and some of the specialized trails in The Java™ Tutorial, Mary
Campione et al., (Addison-Wesley, 2000). In particular, you should be familiar
with relational database and security features described in the trails listed in
Table 1.

Table 1 Prerequisite Trails in The Java™ Tutorial

Trail URL

JDBC http://java.sun.com/docs/books/tutorial/jdbc

Security http://java.sun.com/docs/books/tutorial/security1.2

xxvii
xxviii

How to Read This Tutorial

The Java EE 5 platform is quite large, and this tutorial reflects this. However,
you don’t have to digest everything in it at once. The tutorial has been divided
into parts to help you navigate the content more easily.
This tutorial opens with an introductory chapter, which you should read before
proceeding to any specific technology area. Chapter 1 covers the Java EE 5 plat-
form architecture and APIs along with the Sun Java System Application Server
Platform Edition 9.
When you have digested the basics, you can delve into one or more of the five
main technology areas listed next. Because there are dependencies between
some of the chapters, Figure 1 contains a roadmap for navigating through the
tutorial.
• The web-tier technology chapters cover the components used in develop-
ing the presentation layer of a Java EE 5 or stand-alone web application:
• Java Servlet
• JavaServer Pages (JSP)
• JavaServer Pages Standard Tag Library (JSTL)
• JavaServer Faces
• Web application internationalization and localization
• The web services technology chapters cover the APIs used in developing
standard web services:
• The Java API for XML-based Web Services (JAX-WS)
• The Java API for XML Binding (JAXB)
• The Streaming API for XML (StAX)
• The SOAP with Attachments API for Java (SAAJ)
• The Java API for XML Registries (JAXR)
• The Enterprise JavaBeans (EJB) technology chapters cover the compo-
nents used in developing the business logic of a Java EE 5 application:
• Session beans
• Message-driven beans
• The Persistence technology chapters cover the Java Persistence API, which
is used for accessing databases from Java EE applications:
• Introduction to the Java Persistence API
 xxix

• Persistence in the Web Tier

• Persistence in the EJB Tier
• The Java Persistence Query Language
• The platform services chapters cover the system services used by all the
Java EE 5 component technologies:
• Transactions
• Resource connections
• Security
• Java Message Service
• The Connector architecture

Figure 1 Roadmap to This Tutorial

After you have become familiar with some of the technology areas, you are
ready to tackle the case studies, which tie together several of the technologies
discussed in the tutorial. The Coffee Break Application (Chapter 37) describes
an application that uses the web application and web services APIs. The Duke’s
xxx

Bank Application (Chapter 38) describes an application that employs web appli-
cation technologies, enterprise beans, and the Java Persistence API.
Finally, the appendix contains auxiliary information helpful to the Java EE 5
application developer:
• Java encoding schemes (Appendix A)

About the Examples

This section tells you everything you need to know to install, build, and run the
examples.

Required Software
The following software is required to run the examples.

Tutorial Bundle
The tutorial example source is contained in the tutorial bundle. If you are view-
ing this online, you need to click on the “Download” link at the top of any page.
After you have installed the tutorial bundle, the example source code is in the
<INSTALL>/javaee5tutorial/examples/ directory, with subdirectories for
each of the technologies discussed in the tutorial.

Application Server
The Sun Java System Application Server Platform Edition 9 is targeted as the
build and runtime environment for the tutorial examples. To build, deploy, and
run the examples, you need a copy of the Application Server and Java 2 Plat-
form, Standard Edition 5.0 (J2SE 5.0). If you already have a copy of the J2SE
SDK, you can download the Application Server from:

http://java.sun.com/javaee/downloads/index.html

You can also download the Java EE 5 SDK—which contains the Application
Server and the J2SE SDK—from the same site.
 xxxi

Application Server Installation Tips

In the Admin configuration pane of the Application Server installer,
• Select the Don’t Prompt for Admin User Name radio button. This will save
the user name and password so that you won’t need to provide them when
performing administrative operations with asadmin. You will still have to
provide the user name and password to log in to the Admin Console.
• Note the HTTP port at which the server is installed. This tutorial assumes
that you are accepting the default port of 8080. If 8080 is in use during
installation and the installer chooses another port or if you decide to
change it yourself, you will need to update the common build properties
file (described in the next section) and the configuration files for some of
the tutorial examples to reflect the correct port.
In the Installation Options pane, check the Add Bin Directory to PATH checkbox
so that Application Server scripts (asadmin, asant, wsimport, wsgen, xjc, and
schemagen) override other installations.

Apache Ant
Ant is a Java technology-based build tool developed by the Apache Software
Foundation (http://ant.apache.org), and is used to build, package, and
deploy the tutorial examples. Ant is included with the Application Server. To use
the ant command-line tool add <JAVAEE_HOME>/lib/ant/bin to your PATH
environment variable.

Registry Server
You need a registry server to run the examples discussed in Chapter 19. Instruc-
tions for obtaining and setting up a registry server are provided in Chapter 19.

Building the Examples

The tutorial examples are distributed with a configuration file for ant or asant, a
portable build tool contained in the Application Server. This tool is an extension
of the Ant tool developed by the Apache Software Foundation
(http://ant.apache.org). The asant utility contains additional tasks that
invoke the Application Server administration utility asadmin. Directions for
building the examples are provided in each chapter. Either ant or asant may be
used to build, package, and deploy the examples.
xxxii

Build properties common to all the examples are specified in the

<INSTALL>/javaeetutorial5/examples/bp-project/build.properties
file. This file must be created before you run the examples. We’ve included a
sample file <INSTALL>/javaeetutorial5/examples/bp-
project/build.properties.sample that you should rename to
<INSTALL>/javaeetutorial5/examples/bp-project/build.properties and
edit to reflect your environment. The tutorial examples use the Java BluePrints
(http://java.sun.com/reference/blueprints/) build system and applica-
tion layout structure.
To run the ant scripts, you must set common build properties in the file
<INSTALL>/javaeetutorial5/examples/bp-project/build.properties as
follows:
• Set the javaee.home property to the location of your Application Server
installation. The build process uses the javaee.home property to include
the libraries in <JAVAEE_HOME>/lib/ in the classpath. All examples that
run on the Application Server include the Java EE library archive—
<JAVAEE_HOME>/lib/javaee.jar—in the build classpath. Some exam-
ples use additional libraries in <JAVAEE_HOME>/lib/; the required libraries
are enumerated in the individual technology chapters. <JAVAEE_HOME>
refers to the directory where you have installed the Application Server.

Note: On Windows, you must escape any backslashes in the javaee.home property
with another backslash or use forward slashes as a path separator. So, if your Appli-
cation Server installation is C:\Sun\AppServer, you must set javaee.home as fol-
lows:

javaee.home = C:\\Sun\\AppServer

or

javaee.home=C:/Sun/AppServer

• Set the javaee.tutorial.home property to the location of your tutorial.

This property is used for asant deployment and undeployment.
For example, on UNIX:
javaee.tutorial.home=/home/username/javaeetutorial5
On Windows:
javaee.tutorial.home=C:/javaeetutorial5
 xxxiii

Do not install the tutorial to a location with spaces in the path.

• If you did not use the default value (admin) for the admin user, set the
admin.user property to the value you specified when you installed the
Application Server.
• If you did not use port 8080, set the domain.resources.port property to
the value specified when you installed the Application Server.
• Set the admin user’s password in
<INSTALL>/javaeetutorial5/examples/common/admin-pass-
word.txt to the value you specified when you installed the Application
Server. The format of this file is AS_ADMIN_PASSWORD=password. For
example:
AS_ADMIN_PASSWORD=mypassword

Tutorial Example Directory Structure

To facilitate iterative development and keep application source separate from
compiled files the tutorial examples use the Java BluePrints application directory
structure.
Each application module has the following structure:
• build.xml: Ant build file
• src/java: Java source files for the module
• src/conf: configuration files for the module, with the exception of web
applications
• web: JSP and HTML pages, style sheets, tag files, and images
• web/WEB-INF: configuration files for web applications
• nbproject: NetBeans project files
Examples that have multiple application modules packaged into an enterprise
application archive (or EAR) have submodule directories that use the following
naming conventions:
• <EXAMPLE_NAME>-app-client: Application clients
• <EXAMPLE_NAME>-ejb: Enterprise bean JARs
• <EXAMPLE_NAME>-war: web applications
The Ant build files (build.xml) distributed with the examples contain targets to
create a build subdirectory and to copy and compile files into that directory; a
xxxiv

dist subdirectory, which holds the packaged module file; and a client-jar
directory, which holds the retrieved application client JAR.

Further Information
This tutorial includes the basic information that you need to deploy applications
on and administer the Application Server.
See the Sun Java™ System Application Server Platform Edition 9 Developer’s
Guide at http://docs.sun.com/app/docs/doc/819-3659 for information
about developer features of the Application Server.
See the Sun Java™ System Application Server Platform Edition 9 Administra-
tion Guide at http://docs.sun.com/app/docs/doc/819-3658 for information
about administering the Application Server.
For information about the Java DB database included with the Application
Server see the Apache web site at http://db.apache.org/derby.

How to Print This Tutorial

To print this tutorial, follow these steps:
1. Ensure that Adobe Acrobat Reader is installed on your system.
2. Open the PDF version of this book.
3. Click the printer icon in Adobe Acrobat Reader.

Typographical Conventions
Table 2 lists the typographical conventions used in this tutorial.

Table 2 Typographical Conventions

Font Style Uses

italic Emphasis, titles, first occurrence of terms

 xxxv

Table 2 Typographical Conventions

Font Style Uses

URLs, code examples, file names, path names, tool names,

monospace application names, programming language keywords, tag,
interface, class, method, and field names, properties

italic monospace Variables in code, file paths, and URLs

<italic monospace> User-selected file path components

Menu selections indicated with the right-arrow character →, for example,

First→Second, should be interpreted as: select the First menu, then choose Sec-
ond from the First submenu.

Feedback
To send comments, broken link reports, errors, suggestions, and questions about
this tutorial to the tutorial team, please use the feedback form at
http://java.sun.com/javaee/5/docs/tutorial/information/sendus-
mail.html.
xxxvi
 1
Overview

Developers today increasingly recognize the need for distributed, transac-

tional, and portable applications that leverage the speed, security, and reliability
of server-side technology. In the world of information technology, enterprise
applications must be designed, built, and produced for less money, with greater
speed, and with fewer resources.
With the Java™ Platform, Enterprise Edition (Java EE), development of Java
enterprise applications has never been easier or faster. The aim of the Java EE 5
platform is to provide developers a powerful set of APIs while reducing develop-
ment time, reducing application complexity, and improving application perfor-
mance.
The Java EE 5 platform introduces a simplified programming model. With Java
EE 5 technology, XML deployment descriptors are now optional. Instead, a
developer can simply enter the information as an annotation directly into a Java
source file, and the Java EE server will configure the component at deployment
and run-time. These annotations are generally used to embed in a program data
that would otherwise be furnished in a deployment descriptor. With annotations,
the specification information is put directly in your code next to the program ele-
ment that it affects.
In the Java EE platform, dependency injection can be applied to all resources
that a component needs, effectively hiding the creation and lookup of resources
from application code. Dependency injection can be used in EJB containers, web
containers, and application clients. Dependency injection allows the Java EE
container to automatically insert references to other required components or
resources using annotations.
1
2 OVERVIEW

The Java™ Persistence API is new to the Java EE 5 platform. The Java Persis-
tence API provides an object/relational mapping for managing relational data in
enterprise beans, web components, and application clients. It can also be used in
Java SE applications, outside of the Java EE environment.
This tutorial uses examples to describe the features and functionalities available
in the Java EE 5 platform for developing enterprise applications. Whether you
are a new or experienced Enterprise developer, you should find the examples and
accompanying text a valuable and accessible knowledge base for creating your
own solutions.
If you are new to Java EE enterprise application development, this chapter is a
good place to start. Here you will review development basics, learn about the
Java EE architecture and APIs, become acquainted with important terms and
concepts, and find out how to approach Java EE application programming,
assembly, and deployment.

Java EE Application Model

The Java EE application model begins with the Java programming language and
the Java virtual machine. The proven portability, security, and developer produc-
tivity they provide forms the basis of the application model. Java EE is designed
to support applications that implement enterprise services for customers,
employees, suppliers, partners, and others who make demands on or contribu-
tions to the enterprise. Such applications are inherently complex, potentially
accessing data from a variety of sources and distributing applications to a variety
of clients.
To better control and manage these applications, the business functions to sup-
port these various users are conducted in the middle tier. The middle tier repre-
sents an environment that is closely controlled by an enterprise’s information
technology department. The middle tier is typically run on dedicated server
hardware and has access to the full services of the enterprise.
The Java EE application model defines an architecture for implementing services
as multi-tier applications that deliver the scalability, accessibility, and manage-
ability needed by enterprise-level applications. This model partitions the work
needed to implement a multi-tier service into two parts: the business and presen-
tation logic to be implemented by the developer, and the standard system ser-
vices provided by the Java EE platform. The developer can rely on the platform
to provide solutions for the hard systems-level problems of developing a multi-
tier service.
 DISTRIBUTED MULTITIERED APPLICATIONS 3

Distributed Multitiered Applications

The Java EE platform uses a distributed multitiered application model for enter-
prise applications. Application logic is divided into components according to
function, and the various application components that make up a Java EE appli-
cation are installed on different machines depending on the tier in the multitiered
Java EE environment to which the application component belongs. Figure 1–1
shows two multitiered Java EE applications divided into the tiers described in the
following list. The Java EE application parts shown in Figure 1–1 are presented
in Java EE Components (page 5).
• Client-tier components run on the client machine.
• Web-tier components run on the Java EE server.
• Business-tier components run on the Java EE server.
• Enterprise information system (EIS)-tier software runs on the EIS server.
Although a Java EE application can consist of the three or four tiers shown in
Figure 1–1, Java EE multitiered applications are generally considered to be
three-tiered applications because they are distributed over three locations: client
machines, the Java EE server machine, and the database or legacy machines at
the back end. Three-tiered applications that run in this way extend the standard
two-tiered client and server model by placing a multithreaded application server
between the client application and back-end storage.
4 OVERVIEW

Figure 1–1 Multitiered Applications

Security
While other enterprise application models require platform-specific security
measures in each application, the Java EE security environment enables security
constraints to be defined at deployment time. The Java EE platform makes appli-
cations portable to a wide variety of security implementations by shielding appli-
cation developers from the complexity of implementing security features.
The Java EE platform provides standard declarative access control rules that are
defined by the developer and interpreted when the application is deployed on the
server. Java EE also provides standard login mechanisms so application develop-
ers do not have to implement these mechanisms in their applications. The same
application works in a variety of different security environments without chang-
ing the source code.
Exploring the Variety of Random
Documents with Different Content
 The hours went slowly, and to those who were shut up in the forest hut,
compelled to be idle, they seemed interminable. They talked over the
possibilities at which Otto Engel had hinted so confidently, but in the slow
passing of the hours they began to grow hopeless over Tyndale's affairs.
They speculated as to what the forester might be able to do, but their own
memory of the drawbridge and portcullis, and the armed men on the walls,
drove them to the conclusion that his scheme was a wild and impossible
one.

Again and again Herman went to the window, and looked out to the
forest, hoping to see the forester, but there was no sign of his coming. He
saw the giant trees rearing their proud heads to the sun, which at some spots
found its way on the pathways and undergrowth. Some wild boars rushed
by at odd intervals, and a dark-grey, grizzled lynx chased a poor creature
among the branches, or dropped to the earth on an unsuspecting victim. It
served to pass the time to watch from the window all that went on in the
forest—the wolves that passed, or a bear that shambled along, but halted at
an ant-hill to scrape out the nests and lap up the eggs.

But the all-absorbing matters were those two—the rescue of William

Tyndale, and Margaret, who in less than a week was to be his wife. He
shivered at the thought of her journey through the cavern, with its loneliness
and those tokens of death from which she had shrunk even in his company.
What must she have felt when she was moving in the cavern alone?

The hours went on—the longest he had ever spent. The morning passed.
The sun changed his position, and cast long, slanting shadows, and
presently the afternoon began to grow old. Then evening came, and the
forester had not returned.

They began to be anxious for his safety, and fears of many sorts were
talked about. Had he shot some wild creature, and in the brute's agony had
he been mauled and torn? The anxiety became so great, when the shadows
grew dense and night was falling, that Herman drew the bolt, intending to
go out and search for the absent man; but Roye, as much distressed, but
cautious, dissuaded him.
 At last they heard the heavy stamp of feet on the path outside, and then
the scratch of a dog's paws on the door. Herman's hand went to the bolt, but
he waited for another sign, and when Engel spoke quietly and lifted the
latch he opened the door.

"I put the horse back in the meadow!" the forester exclaimed, lowering
himself stiffly on a stool, but he had barely done so when he straightened
himself and went to the cupboard to get food for himself and the dog.

"Sit down," cried Herman. "I'll do that."

"I've got to the bottom of my scheme," said the tired man, glad to be
seated. "I'll tell you all about it as soon as I find myself in front of food. But
we'll see to the dog first," he added, the moment Herman set the meat on the
table.

"I've found a way for getting William Tyndale out of that robber's den,
so that we shall surprise both Schouts and Cochlaeus, and spoil their plans!"
Otto Engel exclaimed, his mouth full. He was eating ravenously, for he and
the dog had gone all the day without food. In his wanderings he had
threshed out that difficult problem of deliverance. "I can see my way, and
we'll have him out of it before I'm very much older," he added, when he had
swallowed a draught of water and had given the dog another great helping.

"You can?" the others cried, startled by the forester's words, and
impressed with his confidence.

"Yes, I can!" mumbled Engel, who seemed to grow hungrier as the

moments sped.

"And what's your plan?" asked Roye, drawing his stool up to the table,
where he leant forward and gazed at the ranger. "Is it sure?" he went on,
laying his hand on the other's arm. "Or is it possible that you may fail and
leave us to our disappointment, and my master to his death?"

His face was pale and his voice eager and tremulous, while his eyes
gleamed as though they were not far from tears.
 The ranger swallowed his mouthful, and then he answered as earnestly
as Roye:

"Neither of you shall be disappointed, please God, if you choose to

throw in your lot with me and make this venture. You will possibly say 'tis a
desperate thing to do. You may even deem me mad. I know not what you
may say or think when I tell you what I mean to do. God only knows what
you may say about it—that it is like putting one's head into a noose if by
any means the plan should fail."

Engel's meal was ended now, and, getting up from the table, he carried
his stool with him and sat before the fire, and sprawled his crossed feet to
catch the warmth of the burning logs.

"I suppose nine out of ten, not knowing what I know, would say it was a
madman's venture, but I'll tell you exactly what is at the back of my mind,
and you shall say 'yes' or 'no,' according to what you think, when I have had
my say."

The others pulled their stools to the fireside and listened; but while he
unfolded his plan they thought he must be mad. Yet when they looked at his
face they felt they were mistaken. He had evidently planned the whole thing
out, basing this desperate scheme on his knowledge of the castle and not on
mere supposition.

They shrank from the venture which the forester proposed, for there
could be but one ending to it, without benefiting William Tyndale in the
slightest degree. On the very face of it, it was doomed to failure, and it
might end in death for them all.

"You are only telling us of the bare possibilities, Otto!" Herman

exclaimed, when the ranger had ended. "You surely do not mean that we
shall make such a wild attempt?"

The ranger swung round on his stool and faced Herman, but did not
speak until he once more turned to gaze into the midst of the burning logs,
leaning forward as though he saw pictures among them.
 "I am telling you of something more than possibilities," he said
presently. "I count what I propose as a certainty, and I mean to try my plan.
I shall be glad to have you with me, but if you are afraid—and it's not to be
wondered at if you are—I will do the thing alone; only the task will be so
much the harder, and the risks will be greater because it will take so much
longer time. God helping me, the man on whom so much depends shall be
freed!"

Engel sprang to his feet, overturning the stool, and paced the floor,
walking round by the wall and past the door and window like a caged beast,
back and forth again, as though to walk off his excitement.

"I mean to try it!" he exclaimed. "I've been kneeling a lot to-day in the
forest to pray about it, and I believe God has shown me the way. It would
be woe to me if I did not do my best for the good man after that."

He was moving about restlessly, not pausing while he spoke.

"I can't imagine how you mean to get inside the castle," Herman said,
incredulous. The scheme was such a preposterous one.

Engel went to a cupboard on the farther side of the room, and, feeling
about in the darkness, he brought out a sheet of paper, which he smoothed
out on the table.

"I'll get a light," he said, and when the candle was burning he spoke
again. "You are both able to lay some claim to scholarship, I suppose; so
you will understand this plan with a bit of explanation. It's a plan of
Schouts' castle, but he doesn't know I've got it, or he might hang me over
his gate."

He bent over the sheet when he had covered the window, so that none
might look in from outside. Then, with his forefinger, while the others bent
over, he opened out the scheme more fully. He showed them the point
where he would go in, where he would go when he was once inside, and
how he meant to get out with William Tyndale, and the others, with the plan
so plainly before them, saw that the scheme was possible, provided there
were no accidents to mar it.
 But it was a desperate venture, to say the least, for three men to pit
themselves against the robber lord, and expect to snatch their friend from
the clutches of one who had scores of servitors, every one a trained fighting
man who had no fear of God or man, and, like the Norse warriors who had
in them the Berserker spirit, would go to the battle when the call came, and
fight with frenzied and merciless fury. The bare suggestion was little less
than madness.

After bending over the table so long, the forester straightened himself
and gazed down at the crumpled sheet of paper which was resting on the
table among the crumbs and broken bread which had not been swept away.
Herman and Roye glanced up at him, and saw the resolute look on his face
and the total absence of fear. The first to speak was Herman.

"Otto Engel."

"Well?"

"I shall go with you."

"So will I!" Roye exclaimed. His pale face showed that he did not speak
lightly.

The ranger put out his hands and gripped those which were stretched
out to him.

"I counted on you both," he said quietly.

"When shall we start?" Herman asked.

"Now."

Roye turned his back on the others and gazed into the fire, but a few
moments later he swung round again.

"I said I would go, and so I will. But 'tis too great a venture without
asking God's help before we start," he said, dropping on his knees at the
table. The others did the same, and buried their faces in their hands while
the elder man prayed concerning this dangerous enterprise, and asked that
William Tyndale might have a safe deliverance.

"Now I can go in double strength," cried the ranger, still on his knees;
and there was something exalted in his tone and a look on his face that is
rare with men. "Please God, we'll have that dear man here before the dawn
comes!"

He rose to his feet, and, looking to his weapons, bade the others do the
same. Telling the dog to keep safe watch, however long they were away,
giving him a big bone to wile away the hours and placing food within his
reach in case the creature should grow hungry, he blew out the light, threw
open the door, and walked into the night.

The moon was already showing her face in fitful gleams where the leafy
canopy of the forest was broken here and there; but even thus it seemed
dark at first. They moved in stealth, not knowing who might be abroad.
Once they saw a pair of shining eyes in the thicket, but at a sharp word from
the ranger and a menacing movement on his part, the beast moved off,
snarling, yet frightened, for three men were too many to meet in fight.

"'Twas a wolf, and he's a desperate coward when you get him in a
corner," Engel said carelessly.

The slow going in the forest took more than half an hour of their time,
but at last they reached the open, where the green slope swept, up which
William Tyndale had been taken, as a prisoner.

All was silent now, and the moonlit sweep of grass had neither man nor
beast on it.

Away to the left were the silver-shining waters of the river, but it was
clear. No craft moved up or down, and nothing tempted the bandit lord from
his warm banquet-hall. Presently, however, Herman and his companions
caught the glint of steel, and then they saw a soldier come from behind a
bush and pace the bank, doubtless on the look out for any vessel that gave
promise of plunder.
 "Were it not for the trouble that would come, I would go on my knees
here and pray that some craft might pass which would bring Schouts and his
cut-throat soldiers out to-night," the ranger muttered. "'Twould go some
way towards lessening our own danger."

"Many a poor man would lose his life to-night if we prayed like that,"
said Roye seriously.

"Yes. That's the worst part of it. One benefits so often at the price of
another's irremediable loss," came the ranger's grave response. "Ah, well!
We'll take it as God sends it!"

He led the way along the edge of the ascending slope, but well within
the shadows of the trees.

The castle stood on the brow of the hill, and those who were on this
desperate errand saw the massive towers and wondered how an enemy
could hope to scale the walls and capture the place. Standing for a while,
since there was ample time, Engel told his companions what the castle was
like inside, so that they might not be altogether unprepared for what they
would see during their venture.

"You pass the gateway which those two towers defend. Then you are in
the first or lower ward, which is defended by as many as eight strong
towers, and separated from the second ward by another gateway with a
portcullis.

"In the second ward is a dungeon tower and a prison chapel, but
William Tyndale is not in that part of the castle. I found out so much when I
was abroad to-day. You go out of the second ward by a long flight of steps
to the third and fourth wards, which are surrounded by a steep rampart and
a wall, I know not how many feet thick, nor how many high. Then you
come to the very heart of things. There is the King's Tower, where Schouts
is lodged. There's the Queen's Tower, where his lady has her quarters. The
kitchen and the chapel and other places are near. Well, it's in the King's
Tower we have to go, for Master Tyndale is lodged there, and because I
have a friend in court, I know just where."
 The ranger stopped talking abruptly. They were approaching a broad
and open path which ran through the forest, and they caught the sound of
men's voices.

Standing back where none could see them, they waited, wondering at
the meaning of these unexpected sounds. A minute or two later the lights of
lanterns appeared on their right in a dense part of the forest. These came
nearer and nearer, and not only were there the sounds of men's voices, but
of horses' hoofs, their snortings, and the jingle of their trappings.

Before long a dozen horsemen moved past those who were standing in
the shelter of the bushes—two men, fully armed, going first, their drawn
swords glancing as they rode out to the grassy slope. Then two others at
whose sides swords hung in their scabbards, and behind them a number of
well-armed men.

None of the watchers could tell who they were, for the heavy foliage hid
their faces; but when the cavalcade swept round towards the castle, Herman
gripped Roye's arm.

"Do you know who they are?" he whispered eagerly.

"Ay, I know," Roye muttered. "One is Captain Berndorff of the City

Guard, and the man riding at his side is Cochlaeus!"

CHAPTER XVI

WITHIN THE CASTLE

The cavalcade halted at the drawbridge, and a horseman sounded a

trumpet which brought a soldier to one of the towers over the gate.
 The watchers had gone forward among the trees, keeping pace with the
horses, and now saw and heard all that passed. The soldier demanded their
business, and the response came from Cochlaeus.

"Tell my lord of Schouts that the Deacon of the Church of the Blessed
Virgin wishes to confer with him on a matter of the first importance. Say
that I have ridden out from the city for that purpose."

"Bad hours for a Churchman to keep," the soldier remarked insolently,

and laughing. He waited, to know whether Cochlaeus had more to say, but,
when he found that no answer came, he turned away. More than a quarter of
an hour passed, and then the gate opened slowly, the portcullis was raised,
and the drawbridge dropped over the moat noisily.

"My lord says that the Deacon of the Church of the Blessed Virgin may
enter," said the warden surlily.

Berndorff, hearing what the soldier said, gave an order, and the
horsemen moved forward. Already the feet of the first two horses were on
the bridge, but the soldier caught at the bridles.

"Nay!" he cried. "I told you that my lord said that the Deacon might
enter. I ought to have said, 'and no other'! All else must stay outside and
cool their toes, or ride away, just as they please. But as for going in, no!"
the soldier exclaimed roughly.

"An insolent varlet!" cried Cochlaeus, riding forward. "Is that how you
speak to a dignitary of the Church?" he asked angrily.

"I speak as my master bids me, and, whether it be insolent or not, I

stand by my orders," was the sharp retort. "These must wait until your
business is done and you come forth again."

Cochlaeus was irresolute. In his own mind there was the fear that he
might be detained by the bandit lord, and held for heavy ransom, since it
was known that the treasure coffer of the Church of the Blessed Virgin was
a full one. Schouts was known among the Churchmen to care nothing for
the maledictions of the Church; and while he may have thought seriously of
armed men standing at his gate in considerable numbers, he had no fear
from such as were in the community to which Cochlaeus belonged.

"'Tis an insult," he cried angrily.

"That's for my lord to say, not for me," the soldier answered, with
indifference.

"'Tis inhospitable as well," the Inquisitor exclaimed, "not to allow my

attendants shelter at such an hour, but they must stay outside!"

"Where lies the lack of hospitality?" came the curt rejoinder. "You come
hither at your own suggestion, and not as my master's guest. Would you
suppose that he would suffer any to enter his stronghold who chose to pass
this way? He can surely say whom he will see, and refuse if he cares?"

The soldiers behind Cochlaeus sat grimly in their saddles, but they
understood. Schouts was not likely to admit any armed men who might
prove awkward if once they got across the bridge and held the gate, keeping
it wide open for hundreds to come who might be lurking in the forest for
surprise. And as for Cochlaeus, were it not for their own honour as soldiers
in the service of the Burgomaster of the city, they would have been well
content to see this heretic hunter lying stark and still on this same bridge to
which he had come to parley with the robber lord.

"What must I do?" Cochlaeus cried angrily, irritated by this undisguised

insolence. It was an intrusion on his dignity which he would not have
brooked elsewhere. But here was a lawless lord's stronghold, and the master
of it was known up and down the river as one who was a law unto himself,
and dictated terms, especially within his own domain.

"What must you do?" the warden responded in surprise at the question.
"Come in alone, or go away again, just as you may please. I have my lord's
orders, and I won't go from them. Nor dare I. None of these soldiers,
therefore, may enter. My lord will have none of them inside of his castle.
He said so when I took your message to him."
 The soldiers on the drawbridge moved their horses back, and stood with
the others, while Cochlaeus, going forward in an ill-humour, rode in at the
dark gateway. Then his temper gave place to fear, for it dawned upon him
that he was placing himself in the power of a man who might retort on the
Church to which he was an inveterate enemy, and hold this heretic hunter
for ransom. His face paled, and his hand trembled on the rein when the
drawbridge began to rise and the portcullis rushed down, the sound of the
loud rattle of chains coming as a reminder of the helplessness of his
position, and how completely he was in the power of the bandit lord.

"Caught like a rat in a trap, I'll be bound," muttered Otto Engel, who,
like his companions, was watching all that passed, and trying to gauge how
far this night visit of Cochlaeus was likely to affect the prisoner in the
castle. "Ay, like a rat in a trap! God grant he may never come out alive!" he
said, when the gates clanged together. "But come, friends. Let us be on the
move, lest that Inquisitor has come to buy William Tyndale, and will pay
Schouts' price. Then there is no saving the poor man."

The ranger moved away at a run, winding in and out among the bushes,
leaping over little runlets and brushing through thick undergrowth; but his
comrades kept pace with him, so that when he halted under a gnarled oak,
whose great branches hung so heavily that he had to stoop to pass beneath
them, the others were but a little way behind.

"Is this the place?" Herman asked, bending low to look for Engel, who
was completely hidden.

"Yes. We'll waste no time now we are here," said the ranger. "Stand
there awhile and get your breath," he said to Roye, who was panting with
his run. "I will go first, and what I do you must copy."

Getting a foothold on the trunk of the tree, he climbed among the

foliage and disappeared. Herman could hear him mounting, the rustle of the
branches telling how he was moving.

"Art coming?" Engel asked presently, in a tone which warned the others
to be cautious.
 "I'm coming," Herman whispered back, but he turned to Roye. "You had
better go next, then I shall know that you are safe. I am used to climbing
trees, but possibly you are not."

"'Tis true," said the elder man, but he followed Engel, and before long
word came in the darkness that he was safe.

When Herman stood with the others in the great fork, which formed a
natural platform, the ranger dropped on his knees, and felt about in the
darkness with his hand.

When he had found what he wanted, he began to descend into the body
of the tree, the trunk proving to be hollow. The others could hear the sound
of his feet, as though he stepped on iron. The fancy became reality when
Engel produced a light, and while he held a lantern in his hand, they saw
him below, waiting for them to follow.

"Put your feet on those irons, and hold tight with your hands, or you
may get a nasty fall," he whispered, pointing to some iron loops which had
been driven into the inside of the tree, forming what was equivalent to a
ladder. Herman descended, feeling with his feet for footing as he went,
Roye following closely.

Looking around them curiously when they stood in a group, they saw all
manner of insects crawling about, startled by the light and this unwonted
invasion of their domain. Many of them left shiny tracks behind them,
while some insects, attracted by the lantern, flew against its horny sides.

It was an unpleasant sight, but they had other business on hand, and
they went about it with that quick glance at their surroundings.

Handing the lantern to Herman, the ranger bent down and prodded the
floor with his hunting-knife. At every prod there was an answering metallic
sound.

"That's iron," said Herman, who was watching eagerly.

 "Yes. Don't you remember what the plan showed you?" Engel replied.
"Ha! This seems to be what I want."

He had driven his knife into a crevice, and, scraping the earth away, as
he moved along, with the point, he marked out a square space. Driving in
the point of the tempered steel, he raised an iron plate which worked on
hinges, and, getting his hands to it when it had come a little way, he threw it
back against the tree's side, and looked into a hole, the bottom of which was
lost in blackness.

Here, again, were iron clamps by which Engel descended carefully, for
some distance, until his foot touched solid ground. Herman followed and
found himself in a cavernous space.

Gazing around, they found that it was what they expected according to
the plan. Here was a great chamber, low-roofed, and narrowing down on
one side to a passage whose walls gleamed in the light of the lantern.

The walls were veined in all directions, and the yellow colour suggested
gold; but this was no time for close examination. The matter in hand was
the finding of William Tyndale, to wrest him from Schouts' harsh keeping
before he had time to sell him into the hands of those for whom Cochlaeus
was acting.

"Yonder is the passage," said the ranger, walking the next moment
across the floor with the others so close at his heels that, when he halted
unexpectedly, they bundled against him.

For some distance the passage ran level, narrowing down occasionally,
so that Engel had to turn his burly form sideways and squeeze himself
through; but after a time the floor sloped downwards, and so steeply at
some points that the footing was treacherous. It was made more so by the
moisture which oozed through the rocky ceiling and trickled down the walls
to the ground on which they trod.

"We are under the moat," whispered the ranger, who stumbled while he
carelessly turned to speak, and barely saved himself from a heavy fall.
 Having passed this slimy, moss-covered floor, they found themselves on
an ascending path, and there they paused; for at this point the real danger of
their daring venture began.

"We are inside the castle," whispered Engel. "What say you? Shall we
all go forward, or will you both stay here while I go forward to see how the
land lies?"

"Let us go on farther," Herman proposed. "We ought not to be so far

separated if one of us should choose to stand back. As far as I remember the
plan we have fifty yards or more to go before we reach the corridor. There
is, moreover, a door at the end of the passage, if the plan is true."

"It's true enough, so far," said Engel, "and why not be correct all the
way through? I've heard my father say so, and he knew, for he had tried it
more than once."

The ranger was moving forward while he spoke, throwing light on the
treacherous path with the lantern.

For more than fifty yards they went their way, touching the slimy walls
at times, and treading on softness they would have shuddered at, but for this
matter on their minds, and of such supreme importance.

Suddenly they came to a full stop, for a wall was in front of them, to all
appearance solid rock, and impassable. But instead of dismay there was a
stifled sound of satisfaction. It was what the plan had marked.

Herman began to look about this rocky face, smoothing his hand over it
lightly, but for a time he failed to find what he was searching for. Then he
exclaimed in a tone of satisfaction, just as the fear was coming that they had
been misled:

"I have it!"

He felt a tiny knob of rock, and, pressing on it, the wall began to move
away slowly and heavily, but without a sound. The moment he took his
hand away, the rocky door stood still, leaving a crevice sufficiently wide for
them to peep through.

Hiding the lantern's light so that it should not betray them, they saw a
long passage, three or four feet wide, but almost in darkness. The only light
it contained was that of a smoking lamp hanging on the wall far down the
corridor.

"Shall we venture?" asked the ranger.

"What use was it to come so far, and not go farther?" Roye asked almost
testily. "We have to get my master out of this."

While he spoke he put out his hand and pressed the door farther open.
Then, brushing past the others, he stood in the passage. Engel and Herman
followed. Thrusting the door back into its place, careful not to send it too
far, for the latch to catch, they looked at it in such dim light as there was,
and saw that it fitted into the roughly built wall so well that none would
suspect the presence of a door when thrust back completely. It was clear to
them that it was a secret entrance and exit, the existence of which had
probably been forgotten.

"Now for the next thing," said the ranger, glancing up and down the
passage anxiously. "Put your minds on that plan in my home, and you will
remember we had to take the first turning to the left. It comes half-way
between us here and that light yonder."

He led the way, going softly and cautiously, ready for advance or
retreat, as things might chance. Ere many yards had been traversed they
came to an opening on the left, and it led up some winding steps, past
doorways from none of which came any sound or sign of life or light on the
other sides. The stairway opened on a long corridor, broad and pretentious.
Some of the doorways had heavy curtains hanging over them, and one into
which they peered, since the door was wide open, showed the great
banqueting-hall, with tapestries on the walls, casques and bucklers, antlers,
and many other relics of the chase in the forest. Across the hall at the upper
end ranged the high table at which the lord of the castle sat, and the other
tables ran down by the walls, leaving the central space clear.
 To linger was dangerous, and yet the nearer way to Tyndale's cell lay
through the hall.

"I'll not venture," Engel muttered, listening intently for any sound of
approaching voices or footsteps, and realising, like the others, that in this
escapade they were almost challenging death. "We'll go round, for who can
tell what men may come into the place when we are half-way across the
floor of that hall? We should never get to yonder door, nor any other door,
except a dungeon one."

He turned away, hugging the wall as he went, and always keeping an

eye on the hanging curtains at the doors. His idea was that, if someone
came into the passage, he and his comrades in this deadly venture might get
into hiding until the danger had passed.

Every sound thrilled them, for the peril was so great. And yet they
moved onwards, bent on getting Tyndale away, if it were possible. After a
time they came to a corner, and glanced along another corridor shut off with
heavy hangings.

Should they venture? There was no hiding-place nearer than a doorway

a dozen yards farther on. And here Engel knew his way thoroughly, for,
being hail-fellow-well-met with many of the retainers, he had often been
there, and was always welcome. He knew that if he could pass that door in
safety he had but one more to go beyond, and he would be at the steps
which descended to the place where, so Sprenkel had told him when they
met in the forest in the afternoon, the prisoner had been placed.

The danger centred at that door, and Engel half wished he had come
alone, so that his movements should not be hampered. One could move
where three would find it impossible and dangerous.

"Roye," he whispered, while they were hidden in the curtain, "one can
move freely, and perhaps two; but three are too many. It adds so greatly to
the fear of discovery. What say you to going back to the secret door and
staying in the passage, keeping everything in readiness when we bring
William Tyndale with us?"
 "Is there likely to be any fighting? for, if so, I can do my share," said
Roye readily.

"There will be no fighting. It's a matter of stealth, and three are too
many. One may blunder and spoil everything. We shall all be waiting for
each other."

"I'll go back, but not willingly," came the reluctant response. "I wanted
greatly to be one of those to go to my master, but I see the difficulty."

Roye turned on his heel.

"Can you find the way?" Engel whispered; and Roye, answering
quickly, went back softly. They watched him until he disappeared at the
steps.

"He's brave enough," the ranger said sincerely, "and I like the man's
spirit. There's no doubt as to the love he has for his master, and he's sore at
heart at turning back. But three are too many."

Engel and Herman made a hurried progress down the dimly-lit corridor,
making for one of the doors, but they hid themselves among some curtains
almost in panic, for a page-boy came into view at one of the corners,
whistling gaily as he walked along carelessly. He passed on, unsuspecting,
not even looking at the heavy curtains.

As for those in hiding, they almost forgot the boy in the intensity of
their surprise at what they saw. From among the folds in which they stood,
they looked into a gorgeous chamber, and at the table, in the centre, so
seated that the flaming logs upon the hearth lit up their faces, making the
lights of the candles dim with the red glow, were two men.

One was Schouts, the robber lord. The other was Cochlaeus. Both had
wine goblets by their hand, and were talking seriously.
 CHAPTER XVII

THE MAN IN THE DUNGEON

"What will you give me, Deacon, if I hand you over this prisoner of
mine, whose name, you say, is William Tyndale?"

Schouts lifted the silver flagon while he spoke, and filled his goblet.

"Two hundred and fifty golden crowns, my lord—the price that is set on
that fellow's head," Cochlaeus answered.

"What!" cried Schouts, in sharp surprise, with the goblet half-way to his
lips. "You would make a crafty bargain with me, and pay me as much as
you would pay one of my retainers if they chanced to find this lean-faced
Englishman?"

Schouts laughed scornfully, and instead of drinking he brought down

the goblet heavily to the table, spilling the wine on his hand.

"'Tis a big sum, my lord. Two hundred and fifty golden crowns."

"It may be, Deacon, but I should get as much from this fellow's friends
in Hamburg, for since I got hold of him I am told that some English
merchants there have some regard for him, and are finding him money for
this enterprise of his, this writing of pestilent papers. I shall go to them,
perhaps to-morrow—perhaps to-night—and tell them how anxious the
Churchmen are to burn their friend, but they only value him for fuel to an
Inquisition fire at two hundred and fifty crowns. They will give me five
hundred without a word, I'll warrant you, and think they got this Tyndale
cheaply. But I'll not take five hundred from them, nor from you. The price
for that Englishman in my dungeon is a thousand crowns, down here on this
table, if you are the purchaser. Then you may torture him to your heart's
content, or burn him, just as you are disposed."

"A thousand crowns!" cried Cochlaeus, gazing at the robber lord in

blank amazement, and in his movement of surprise unwittingly overturning
the wine goblet near his hand. "Who would give you such a preposterous
sum? No one!"

He brought his clenched fist heavily on the table while he spoke.

Schouts laughed, then drank off his wine, draining his goblet and filling
it again before he answered.

"I said a thousand crowns, and golden ones. And if nobody will give me
that much, no one has him but myself, and I shall keep him. He won't cost
much for his food, and I shall get a bit of satisfaction out of it all. I shall
know, for instance, that you and your torturing crew in those Holy House
cellars where you keep your racks and your thumbscrews are consumed
with anger because you cannot work your will on that man you want so
badly, and won't buy at my price."

Schouts sipped at his wine two or three times, staring at Cochlaeus, half
amused at the look on the Churchman's face.

"I shall keep him for a time, and he may bring me in a good sum before
I have done with him. His friends may go beyond the thousand when they
know where he is."

"I can't believe it!" exclaimed Cochlaeus, in a tone of incredulity.

"Can you not?" cried Schouts. "Look you, Deacon Cochlaeus! If this
man goes out of my hands, whether to his friends or to his foes, he will not
go until I see a thousand crowns of gold on this table. Now you have my
answer. I won't take nine hundred and ninety-nine. It shall be a thousand;
and when you have brought me that many you may do as you please with
him, for then he is yours, body and soul."

The robber had stood up, and, pushing back his chair, so that it fell to
the floor with a noisy clatter, he went to the hearth, and, having kicked the
logs together with his boot, stood with his back to the fire and looked to see
how this emissary of the Inquisition received his ultimatum.
 "Say seven hundred and fifty, my lord," exclaimed Cochlaeus, now
standing. "A thousand crowns is such an enormous sum for a penniless
man."

"'Tis William Tyndale's price, whether he is penniless or rolls in

wealth," came the dogged answer. "And, as I said, I won't take a golden
crown less, not even nine hundred and ninety-nine."

Cochlaeus paced the floor to and fro, his feet treading on some
magnificent carpets which must have come from Turkish looms. He had no
thought for all the luxury that was round him—the spoils of many a piracy.
His thoughts were on the man for whose purchase he was bargaining, whom
he longed to see crouching in one of the dungeons of the Inquisition,
presently to be bound on the wheel and broken, or put to some other torture,
and, if he had his own way, burnt in the open market-place of the city which
he had dared to pollute with his shameless sheets!

But the price! This robber lord had the audacity to ask a thousand
golden crowns, and as he had already protested, the sum was preposterous.
Yet, before he came away to hunt down the arch-heretic, who was dealing
such deadly blows at Mother Church, and spreading far and wide his
pestiferous books, his fellow-Inquisitors had told him that a thousand, or
even two thousand, golden crowns would not be too much if it would bring
Tyndale into their power. They would be able to silence him for ever, and he
would not then seduce the people to heresy.

Schouts stood with his back to the blazing logs, and watched the
Churchman with a sinister look on his face, as he moved backwards and
forwards, debating this question of payment to the bandit lord. As for the
lord of the castle, he was smiling to himself, although his face was stern, to
think that he was wringing out a thousand golden crowns from a Church for
which, in his godless way, he had the most profound contempt.

"Well, Deacon, what decision?" he asked abruptly, when Cochlaeus

seemed no nearer to it.

"I cannot decide," the Churchman protested. "The terms are so

exorbitant. Who ever heard of such a sum—a thousand crowns—for one of
Tyndale's stamp?"

Schouts laughed.

"I've more to add, and that, too, may prove preposterous!" he exclaimed.
"I forgot, when I fixed the price for my prisoner, that I must have a full
pardon for every sin of which I stand convicted—my robberies, what you
and many another call my murders, my wanton insults—to quote you again
—to some of the Church's high dignitaries—for everything that you and
yours may count a sin! That and the thousand crowns! So now decide, and
quickly, for I want to be gone."

He was going to say more, but there were quick steps on the stones of
the corridor, and then a man came in without ceremony, and, breathless with
haste, strode to where Schouts was standing.
 "MY LORD, THERE IS A SHIP COMING ROUND THE BEND," THE
MAN CRIED, BREATHLESSLY.

"My lord," he cried, not heeding the Churchman, who had paused in his
restless walk to hear what Schouts had to say, "there is a ship coming round
the bend. She is the same you bade me keep a sharp look out for."
 The man held his hands to his sides, and sought to regain his
squandered breath, but Schouts, filling his goblet with wine, gave it to the
soldier, told him to drink, and follow him quickly.

"I will talk with you later, Deacon Cochlaeus," Schouts exclaimed,
facing his visitor; "but I must see to this business at once. But bethink you
of what I said. A thousand crowns and absolution, or nothing." He halted at
the door, and the confusion on the face of the Churchman so amused him
that he burst into loud laughter. "By the way, twelve hours hence my price
will be raised. Maybe I'll ask for fifteen hundred crowns."

He pulled the door after him, and walked swiftly along the corridor,
looking to his weapons as he went.

The great bell of the castle clanged a few moments later. The sound of it
travelled to the building's farthest depths, and away beyond the walls, into
the forest itself, for, as Otto Engel whispered, he had often heard it in his
hut, and knew that there was murder afoot.

Those who hid behind the curtain heard the tramp of men, and before
long they came by in haste. They were taking the shortest cuts to be in time
to form up and receive the commands from their lord, who was bawling out
his orders in the courtyard, Some, to save time, rushed through the room in
which Cochlaeus stood—in at one door and out at that where Herman and
the forester were hiding. They were buckling on their swords as they went,
and, careless of the Churchman's dignity, brushed past him, almost
overturning him in their haste. Cochlaeus' jaw dropped when the last to pass
through the chamber was a priest, who did not look his way, but hurried on
with noisy cries and oaths and drunken laughter.

Before long the clatter of men's feet was heard outside, and a horse's
hoofs beat on the stones, then thundered on the drawbridge when it was
lowered. Herman and his companion knew what it meant, for the robber
lord and his retainers were on the way to another daring act of piracy.

"God be praised!" exclaimed Engel, in a low tone. "'Tis our opportunity.

That prayer in my hut is going to be answered," he whispered, but even then
the voice thrilled with exultation.
 Gripping Herman by the arm, he drew him from the curtains, and
hurried with him down the passage they had traversed before, to the open
door of the banqueting-hall. There they paused to look in cautiously, to
discover whether it was empty. No one was there, and, taking the risks, they
went through it at a run and out by the door at the other end.

When they passed the kitchens they, too, were empty. Not a sound was
heard, save what was distant, for the bell was no longer clanging, and every
man within the castle, throwing aside his task, whatever its nature, was
gone, either to take his stand on guard at the drawbridge or above the gate,
or to descend the slope to the river, to deal with the doomed vessel that had
been daring enough to venture past in the dark night hours. She was going
to pay the price of her mad audacity, and the robber lord was there to extort
it to the last penny.

Going along the deserted corridor, Herman and the ranger came to some
steps, down which they went swiftly after Engel had snatched at one of the
few lamps that were hanging on the wall. The steps were black as night, but
with the lamp's aid now they went down and down, until they came to a
sudden stop at a blank wall. But here they saw that on the left were other
steps, breaking off at right angles, and descending they came to a door
studded with nails and sheeted with iron, crossed with bolts and bars.

"'Tis here," whispered Engel. "And here's the key, just as Sprenkel said."

A great key hung on a nail near by the door, and the ranger, taking it
down, thrust it into the lock. When he twisted it, the bolt went back with a
scream which seemed dangerously loud in the quietness of the castle
depths. Herman, meanwhile, was busy, for they both knew well how
precious the moments were, and what they were to do they must do quickly.
He pulled back the bolts and dropped the bars, and, thus free to move, the
door was thrust open into darkness.

"Are you there, Master Tyndale?" Herman whispered, stepping down

into the dungeon.

"I am here. Who are you?"

 The question came in tremulous tones, which gave the two strong men
at the door the impression that the voice was that of a weakened man.

"'Tis Herman and a friend. Come at once. We want to get you away
from this robber's castle, and the moments are precious."

Engel stood with the lamp lifted high, to see where the prisoner lay in
this dank dungeon. The uneven floor was full of pools, and the walls ran
with moisture, while, in the momentary silence, before any more was said, a
drop of water fell with a musical note into one of the pools, and made the
broken surface shimmer in the lamplight. Herman's eyes were quick to see
the misery of the place. There were crawling creatures on the floor and the
walls, and dull green moss coated the floor.

That, at first, was all he saw; but presently he saw William Tyndale
kneeling on a spread of damp straw in a corner behind the door.

He was looking their way, uncertain as to those who had come to this
fetid cell; half wondering whether it was reality, or that he was dreaming
that he had really heard Herman's voice. Herman caught the gleam in his
eyes from the lamp's light, and went forward. And still it seemed to the
prisoner such an incredible thing, till Herman was really near him, scuffling
his feet among the straw, and flinging a strong arm about his shoulder,
kissing the cold cheek, and telling him that he and his comrade had been
searching for him, meaning to get him away.

Tyndale put out his manacled hands to grasp those of the young man
who had been tender and loving as a son for the past months.

"'Tis wonderful!" the prisoner exclaimed, trying to rise from his

kneeling posture. "You might almost have heard the words of my prayer
when you came to the door. 'Out of the depths have I cried unto Thee, o
Lord. Bring my soul out of prison, that I may praise Thy name.' And think
of it! The Lord heard my supplication, and made haste to help me!"

Herman bent down, and, throwing his strong arms about the kneeling
prisoner, lifted him to his feet; but Tyndale could not stand without the
young man's aid.
 "I am very weak," Tyndale said, in a trembling tone. "Since I left your
home I have not touched a morsel of food, and none has been brought to
me."

For the first time they heard the clank of chains, and when Engel
lowered the lamp he saw that Tyndale's feet were in irons.

"The cowardly hounds!" he exclaimed, his anger blazing forth when he

saw what had been done. "God do so to me, and more also——"

But Tyndale checked him.

"Say it not, friend. God can best requite what has been done to me. But
can we not go away, since, as you said, the moments are very precious? I
should feel the stroke of my misfortune in double measure if you met with
trouble in your desire to help me."

The forester looked carefully at Tyndale, at his hands and feet, and then,
to his confusion, saw that there was a chain about his body which fastened
the prisoner to the wall, so that at the farthest he could not get more than a
yard or two across the floor.

"Herman, hold this lamp!" he cried. Then, passing closer to the wall, his
lips shut tightly in his frenzy of determination, he gripped the chain with his
strong hands and strove to wrench away the iron ring at the wall.

It was a task beyond his power, and Herman, understanding his purpose,
set the lamp down on the floor and went to his side, to grip the chain as
well. Then, with their strength combined, they tugged and tugged at what
seemed a hopeless task. They pulled and strained, planting their feet against
the wall, until the veins in their fore-heads seemed to stand out like
whipcord.

"It's coming!" said Engel exultantly. "See! The iron is moving in the
wall. Again! with all your might, Herman! We won't be done!"

The pull was the supreme effort of their strength, and the iron ring broke
open, and the chain was set free, so suddenly that the two men fell
backwards heavily on the floor among the pools.

Scrambling to their feet, scarcely waiting to rub their bruises, they went
forward to where Tyndale sat in his weakness.

"Take up the lamp, Herman," said the forester, "and show the way. Tell
me where the risky places are, so that I take no false step at all."

Herman asked no questions, and Engel, bending low, took Tyndale up in

his strong arms as a woman might take a child. Making light of his burden,
he followed at the younger man's heels, and, although the steps were
treacherous with slime, he almost pressed Herman forward. For the younger
man was going cautiously, not knowing what danger might suddenly
confront them.

The castle seemed to be silent, and no sound was heard save that of their
own hurried footsteps in the passage and the faint and occasional clinking
of Tyndale's fetters.

"Make for the secret passage," Engel whispered, panting a little with his
burden after having climbed the treacherous steps so quickly. "Go ahead,
and see whether the way is clear. Put the lantern down, anywhere, for if
anyone saw a moving light it would awaken suspicion, and we don't want to
run the risk of being challenged. If you hear any sound, stand by and see if
it means danger."

Herman blew out the light, and, setting the lantern on the floor in a dark
place, he went forward at a run, on his toes, alert and urgent; but no one
crossed his path. When he peeped into the banqueting-hall it was empty. For
any sound or sight in that dangerous venture the great castle might have
been deserted by everything living except himself and his companions. It
was so wherever he went, and at last he came to the door in the wall.

Roye had drawn it after him, just as closely as he found it, to prevent
suspicion in the mind of a possible passer-by and Herman stood by, without
opening it, waiting for Otto Engel to come up with his burden. He turned
the corner sooner than Herman expected, but in the dim light it was easy to
see that the load he carried was growing heavy, as much almost with
nervous strain as with the actual weight; for this daring enterprise was so
beset with danger that the forester had lived what seemed to be hours of
anxious thought in those brief minutes which passed between the dungeon
and the secret door.

He knew that if they were seen by any of the castle soldiers or servitors,
and caught red-handed, as it were, and with a helpless man in chains, he and
Herman would have a desperate fight to wage against overwhelming odds.
What, he asked himself, as he carried William Tyndale, worn down with
weakness and privation, and feeling him growing heavier with every yard
he covered—what if one of the page-boys or some of the women should be
moving about and, seeing them, run away, screaming out an alarm! Only
God could tell the consequences, and it might well end in death for each of
the three.

The forester was within three or four yards of the place where Herman
was awaiting him, when he caught the gleam of steel in the younger man's
hand, and saw by the light of one of the lamps on the wall that he was
bending forward and gazing along the passage. He went even more softly
than before, and with his intensely quickened hearing he heard the sound of
someone singing—a boyish voice shouting out the robber's song.

Although he had been feeling overborne with his burden, and the
sweatdrops were on his brow, the forester hurried forward. He might have
had no burden in his arms at all, so swiftly did he bound over those last few
yards.

"Open the door!" he exclaimed, reckless now; for if he could pass

through the doorway with his burden and the door could be pulled into its
place again, he thought their safety was assured.

It was not necessary to say so much, for Herman dug his finger nails
into what little edge there was, and pulled the door open, so that he looked
into the dark, forbidding gap. Dark though it was, the forester did not
hesitate, but hurried in.

Waiting for the moment when he could follow, Herman kept his gaze
fixed on the distant end where there was a possible corner which the boy
would turn at any moment. The passage was still empty, although the sound
of stamping feet grew plainer, rattling to the rhythm of the song. The relief
was intense, to know that William Tyndale was carried into the secret way
without being seen. It was now his own turn to enter, and it must be at once.

He stepped into the blackness, careful as to where he placed his feet,

and began to draw the door after him. At that moment Roye came near to
him with his lantern, and in the swift glance he took along the passage,
Herman saw that a sharp line of light from the lantern fell across the floor
of the passage, and on the opposite wall. At that same moment the boy
turned the corner and came into view. He must have seen the line of light,
for he halted suddenly, and the song gave place to an exclamation of
wonder and half of alarm. In his own keen thought Herman pictured the boy
gazing along the passage with startled eyes; but he did not wait to see what
happened. The opening in the wall closed up with a soft thud, and as he
looked, Herman saw that the latch had caught, and the entrance was
securely blocked.

How much had the boy seen? Herman asked himself, wiping the
dampness from his forehead, for this narrow escape had startled him.
Surely, only the flash of the line of light, for he had entered so speedily,
urged on by the dread of discovery.

"Where are the others, Roye?" he asked, only seeing him, as he turned
his back on the door.

"We're all right," said Engel, and Herman saw him close by in the
passage, and, having set his burden gently on the floor, he was wiping his
face and neck with his cap. "Did anyone see you?"

"No. The boy swung round the corner into the passage, a long way off,
but he could not have seen more than the flash of this lantern across the
floor just as I had stepped in and was pulling the door into its place."

Herman said it bravely, but this experience had tried him greatly, and
now he stood with his back against the wall, in something like helplessness,
and his knees were trembling, while he felt his lips quivering.
 They turned their attention to Tyndale, and going on their knees beside
him they sought to discover how much he was in need of help, and what
likelihood there was of getting him away. The man for whom they had
dared so greatly sat on the rocky floor, fettered heavily, his back set against
the wall of rock, and his head bowed so that his chin rested on his bosom.
But his thin hand was lifted to take theirs, while he thanked them for their
splendid service.

Herman held him by the hand, while all three watched him anxiously. In
that uncertain light he looked to them like a dying man, and he seemed to
guess their thoughts.

"I am very weak and ill, Herman," he said quietly; "but you came in
time. I shall not die, but live, for God has brought me out of the depths to
give me the opportunity to complete His work."

Weak though he was, on life's borderland, as it seemed to his

companions, there was a thrill of exultation in his voice. He spoke as one
would speak who had unshaken confidence in the success of his mission.

Still watching him, they felt that his condition was serious. They saw in
him a man capable of high and prolonged endurance, but the strain of the
past few months, when he was compelled to remain in the house in hiding,
foregoing exercise and recreation, and especially during these last few days,
when he was seeking to get away from his would-be tormentors, had borne
him down, and he had come to the end of his reserve strength. Yet, to their
amazement, he was exultant and confident, and they realised in those
moments of watching that William Tyndale was a man whose character had
been matured in the hardest of all schools, annealed in the furnace, and not
forgetful, although the chains were about his hands and feet, of the Hand
that was strong beyond that of men, and had brought him out of the
dungeon depths.

"Is my wallet all right, Herman?" Tyndale asked anxiously, too weak to
look for himself; too weak, indeed, to lift his hand to feel for the strap
across his breast.
Welcome to our website – the ideal destination for book lovers and
knowledge seekers. With a mission to inspire endlessly, we offer a
vast collection of books, ranging from classic literary works to
specialized publications, self-development books, and children's
literature. Each book is a new journey of discovery, expanding
knowledge and enriching the soul of the reade

Our website is not just a platform for buying books, but a bridge
connecting readers to the timeless values of culture and wisdom. With
an elegant, user-friendly interface and an intelligent search system,
we are committed to providing a quick and convenient shopping
experience. Additionally, our special promotions and home delivery
services ensure that you save time and fully enjoy the joy of reading.

Let us accompany you on the journey of exploring knowledge and

personal growth!

ebookfinal.com