3. Contents
Preface ...................................................................................................................................................31
Part I
1
Introduction .........................................................................................................................................35
Overview ...............................................................................................................................................37
Java EE 6 Platform Highlights ............................................................................................................ 38
Java EE Application Model ................................................................................................................. 39
Distributed Multitiered Applications ............................................................................................... 39
Security .......................................................................................................................................... 41
Java EE Components ................................................................................................................... 42
Java EE Clients .............................................................................................................................. 42
Web Components ........................................................................................................................ 44
Business Components ................................................................................................................. 45
Enterprise Information System Tier .......................................................................................... 46
Java EE Containers .............................................................................................................................. 47
Container Services ....................................................................................................................... 47
Container Types ........................................................................................................................... 48
Web Services Support ......................................................................................................................... 49
XML ............................................................................................................................................... 49
SOAP Transport Protocol ........................................................................................................... 50
WSDL Standard Format .............................................................................................................. 50
Java EE Application Assembly and Deployment ............................................................................. 50
Packaging Applications ...................................................................................................................... 51
Development Roles ............................................................................................................................. 52
Java EE Product Provider ............................................................................................................ 53
Tool Provider ................................................................................................................................ 53
Application Component Provider ............................................................................................. 53
3
4. Contents
Application Assembler ................................................................................................................ 54
Application Deployer and Administrator ................................................................................. 54
Java EE 6 APIs ...................................................................................................................................... 55
Enterprise JavaBeans Technology .............................................................................................. 58
Java Servlet Technology .............................................................................................................. 59
JavaServer Faces Technology ...................................................................................................... 59
JavaServer Pages Technology ..................................................................................................... 60
JavaServer Pages Standard Tag Library ..................................................................................... 60
Java Persistence API ..................................................................................................................... 61
Java Transaction API ................................................................................................................... 61
Java API for RESTful Web Services ........................................................................................... 61
Managed Beans ............................................................................................................................ 61
Contexts and Dependency Injection for the Java EE Platform (JSR 299) ............................. 62
Dependency Injection for Java (JSR 330) .................................................................................. 62
Bean Validation ............................................................................................................................ 62
Java Message Service API ............................................................................................................ 63
Java EE Connector Architecture ................................................................................................ 63
JavaMail API ................................................................................................................................. 63
Java Authorization Contract for Containers ............................................................................ 63
Java Authentication Service Provider Interface for Containers ............................................. 64
Java EE 6 APIs in the Java Platform, Standard Edition 6 and 7 ...................................................... 64
Java Database Connectivity API ................................................................................................. 64
Java Naming and Directory Interface API ................................................................................ 65
JavaBeans Activation Framework .............................................................................................. 65
Java API for XML Processing ..................................................................................................... 65
Java Architecture for XML Binding ........................................................................................... 66
SOAP with Attachments API for Java ........................................................................................ 66
Java API for XML Web Services ................................................................................................. 66
Java Authentication and Authorization Service ....................................................................... 67
GlassFish Server Tools ........................................................................................................................ 67
2
Using the Tutorial Examples .............................................................................................................. 69
Required Software ............................................................................................................................... 69
Java Platform, Standard Edition ................................................................................................. 69
Java EE 6 Software Development Kit ......................................................................................... 70
4
The Java EE 6 Tutorial • January 2013
5. Contents
Java EE 6 Tutorial Component ................................................................................................... 70
NetBeans IDE ............................................................................................................................... 71
Apache Ant ................................................................................................................................... 72
Starting and Stopping the GlassFish Server ...................................................................................... 73
▼ To Start the GlassFish Server Using NetBeans IDE ................................................................. 74
Starting the Administration Console ................................................................................................ 74
▼ To Start the Administration Console Using NetBeans IDE ................................................... 74
Starting and Stopping the Java DB Server ......................................................................................... 75
▼ To Start the Database Server Using NetBeans IDE .................................................................. 75
Building the Examples ........................................................................................................................ 75
Tutorial Example Directory Structure .............................................................................................. 76
Getting the Latest Updates to the Tutorial ....................................................................................... 77
▼ To Update the Tutorial through the Update Center ................................................................ 77
Debugging Java EE Applications ....................................................................................................... 77
Using the Server Log .................................................................................................................... 77
Using a Debugger ......................................................................................................................... 78
Part II
The Web Tier ......................................................................................................................................... 79
3
Getting Started with Web Applications ........................................................................................... 81
Web Applications ................................................................................................................................ 81
Web Application Lifecycle ................................................................................................................. 83
Web Modules: The hello1 Example ................................................................................................. 84
Examining the hello1 Web Module ......................................................................................... 85
Packaging a Web Module ............................................................................................................ 88
Deploying a Web Module ........................................................................................................... 90
Running a Deployed Web Module ............................................................................................ 90
Listing Deployed Web Modules ................................................................................................. 91
Updating a Web Module ............................................................................................................. 91
Dynamic Reloading ..................................................................................................................... 91
Undeploying Web Modules ........................................................................................................ 92
Configuring Web Applications: The hello2 Example ................................................................... 93
Mapping URLs to Web Components ........................................................................................ 93
Examining the hello2 Web Module ......................................................................................... 94
Running the hello2 Example ..................................................................................................... 95
5
6. Contents
Declaring Welcome Files ............................................................................................................ 97
Setting Context Parameters ........................................................................................................ 97
Mapping Errors to Error Screens ............................................................................................... 98
Declaring Resource References .................................................................................................. 99
Further Information about Web Applications ............................................................................... 101
4
JavaServer Faces Technology ..........................................................................................................103
What Is a JavaServer Faces Application? ......................................................................................... 104
JavaServer Faces Technology Benefits ............................................................................................ 105
Creating a Simple JavaServer Faces Application ............................................................................ 106
Developing the Managed Bean ................................................................................................. 106
Creating the Web Page .............................................................................................................. 107
Mapping the FacesServlet Instance ...................................................................................... 108
The Lifecycle of the hello Application ................................................................................... 108
Running the hello Application ............................................................................................... 109
Further Information about JavaServer Faces Technology ............................................................ 110
5
Introduction to Facelets ...................................................................................................................111
What Is Facelets? ................................................................................................................................ 111
Developing a Simple Facelets Application ..................................................................................... 113
Creating a Facelets Application ................................................................................................ 113
Configuring the Application ..................................................................................................... 116
Running the guessnumber Facelets Example ......................................................................... 117
Using Facelets Templates ................................................................................................................. 119
Composite Components .................................................................................................................. 121
Web Resources ................................................................................................................................... 123
6
Expression Language ........................................................................................................................125
Overview of the EL ............................................................................................................................ 125
Immediate and Deferred Evaluation Syntax .................................................................................. 126
Immediate Evaluation ............................................................................................................... 127
Deferred Evaluation ................................................................................................................... 127
Value and Method Expressions ....................................................................................................... 128
Value Expressions ...................................................................................................................... 128
6
The Java EE 6 Tutorial • January 2013
7. Contents
Method Expressions .................................................................................................................. 132
Defining a Tag Attribute Type ......................................................................................................... 134
Literal Expressions ............................................................................................................................ 135
Operators ............................................................................................................................................ 136
Reserved Words ................................................................................................................................. 136
Examples of EL Expressions ............................................................................................................. 137
7
Using JavaServer Faces Technology in Web Pages ...................................................................... 139
Setting Up a Page ............................................................................................................................... 139
Adding Components to a Page Using HTML Tags ....................................................................... 140
Common Component Tag Attributes ..................................................................................... 142
Adding HTML Head and Body Tags ....................................................................................... 145
Adding a Form Component ..................................................................................................... 146
Using Text Components ........................................................................................................... 147
Using Command Component Tags for Performing Actions and Navigation ................... 152
Adding Graphics and Images with the h:graphicImage Tag ............................................... 153
Laying Out Components with the h:panelGrid and h:panelGroup Tags ......................... 154
Displaying Components for Selecting One Value ................................................................. 156
Displaying Components for Selecting Multiple Values ........................................................ 158
Using the f:selectItem and f:selectItems Tags .............................................................. 159
Displaying the Results from Selection Components ............................................................. 161
Using Data-Bound Table Components .................................................................................. 161
Displaying Error Messages with the h:message and h:messages Tags .............................. 164
Creating Bookmarkable URLs with the h:button and h:link Tags ................................... 165
Using View Parameters to Configure Bookmarkable URLs ................................................. 166
The bookmarks Example Application ...................................................................................... 167
Resource Relocation Using h:outputScript and h:outputStylesheet Tags ................. 169
Using Core Tags ................................................................................................................................ 171
8
Using Converters, Listeners, and Validators ................................................................................. 175
Using the Standard Converters ........................................................................................................ 175
Converting a Component’s Value ............................................................................................ 176
Using DateTimeConverter ....................................................................................................... 177
Using NumberConverter ........................................................................................................... 179
Registering Listeners on Components ............................................................................................ 180
7
8. Contents
Registering a Value-Change Listener on a Component ........................................................ 181
Registering an Action Listener on a Component ................................................................... 182
Using the Standard Validators ......................................................................................................... 183
Validating a Component’s Value ............................................................................................. 185
Using LongRangeValidator ..................................................................................................... 185
Referencing a Managed Bean Method ............................................................................................ 186
Referencing a Method That Performs Navigation ................................................................. 187
Referencing a Method That Handles an Action Event .......................................................... 187
Referencing a Method That Performs Validation .................................................................. 187
Referencing a Method That Handles a Value-Change Event ............................................... 188
9
10
8
Developing with JavaServer Faces Technology ........................................................................... 189
Managed Beans in JavaServer Faces Technology .......................................................................... 189
Creating a Managed Bean ......................................................................................................... 190
Using the EL to Reference Managed Beans ............................................................................. 191
Writing Bean Properties ................................................................................................................... 192
Writing Properties Bound to Component Values ................................................................. 193
Writing Properties Bound to Component Instances ............................................................. 198
Writing Properties Bound to Converters, Listeners, or Validators ..................................... 199
Writing Managed Bean Methods .................................................................................................... 200
Writing a Method to Handle Navigation ................................................................................ 201
Writing a Method to Handle an Action Event ........................................................................ 202
Writing a Method to Perform Validation ............................................................................... 202
Writing a Method to Handle a Value-Change Event ............................................................. 203
Using Bean Validation ...................................................................................................................... 204
Validating Null and Empty Strings .......................................................................................... 207
JavaServer Faces Technology: Advanced Concepts ..................................................................... 209
The Lifecycle of a JavaServer Faces Application ............................................................................ 210
Overview of the JavaServer Faces Lifecycle ............................................................................. 210
Restore View Phase .................................................................................................................... 213
Apply Request Values Phase ..................................................................................................... 213
Process Validations Phase ......................................................................................................... 214
Update Model Values Phase ..................................................................................................... 214
Invoke Application Phase ......................................................................................................... 215
The Java EE 6 Tutorial • January 2013
9. Contents
Render Response Phase ............................................................................................................. 215
Partial Processing and Partial Rendering ....................................................................................... 216
The Lifecycle of a Facelets Application ........................................................................................... 216
User Interface Component Model .................................................................................................. 217
User Interface Component Classes .......................................................................................... 217
Component Rendering Model ................................................................................................. 219
Conversion Model ..................................................................................................................... 220
Event and Listener Model ......................................................................................................... 221
Validation Model ....................................................................................................................... 222
Navigation Model ...................................................................................................................... 223
11
Using Ajax with JavaServer Faces Technology ............................................................................. 227
Overview of Ajax ............................................................................................................................... 228
Using Ajax Functionality with JavaServer Faces Technology ...................................................... 228
Using Ajax with Facelets ................................................................................................................... 229
Using the f:ajax Tag ................................................................................................................ 229
Sending an Ajax Request ................................................................................................................... 231
Using the event Attribute ......................................................................................................... 231
Using the execute Attribute ..................................................................................................... 232
Using the immediate Attribute ................................................................................................. 232
Using the listener Attribute ................................................................................................... 233
Monitoring Events on the Client ..................................................................................................... 233
Handling Errors ................................................................................................................................. 234
Receiving an Ajax Response ............................................................................................................. 234
Ajax Request Lifecycle ...................................................................................................................... 235
Grouping of Components ................................................................................................................ 236
Loading JavaScript as a Resource ..................................................................................................... 236
Using JavaScript API in a Facelets Application ...................................................................... 237
Using the @ResourceDependency Annotation in a Bean Class ............................................ 238
The ajaxguessnumber Example Application ................................................................................ 238
The ajaxguessnumber Source Files ......................................................................................... 239
Running the ajaxguessnumber Example ................................................................................ 240
Further Information about Ajax in JavaServer Faces Technology ............................................... 242
9
10. Contents
12
Composite Components: Advanced Topics and Example ........................................................... 243
Attributes of a Composite Component .......................................................................................... 243
Invoking a Managed Bean ................................................................................................................ 244
Validating Composite Component Values .................................................................................... 245
The compositecomponentlogin Example Application ................................................................ 245
The Composite Component File .............................................................................................. 245
The Using Page ........................................................................................................................... 246
The Managed Bean .................................................................................................................... 247
Running the compositecomponentlogin Example ............................................................... 248
13
Creating Custom UI Components and Other Custom Objects ................................................... 251
Determining Whether You Need a Custom Component or Renderer ....................................... 253
When to Use a Custom Component ........................................................................................ 253
When to Use a Custom Renderer ............................................................................................. 254
Component, Renderer, and Tag Combinations ..................................................................... 255
Understanding the Image Map Example ........................................................................................ 256
Why Use JavaServer Faces Technology to Implement an Image Map? ............................... 256
Understanding the Rendered HTML ...................................................................................... 257
Understanding the Facelets Page ............................................................................................. 258
Configuring Model Data ........................................................................................................... 259
Summary of the Image Map Application Classes ................................................................... 260
Steps for Creating a Custom Component ....................................................................................... 261
Creating Custom Component Classes ............................................................................................ 262
Specifying the Component Family .......................................................................................... 264
Performing Encoding ................................................................................................................ 265
Performing Decoding ................................................................................................................ 267
Enabling Component Properties to Accept Expressions ...................................................... 268
Saving and Restoring State ........................................................................................................ 269
Delegating Rendering to a Renderer ............................................................................................... 270
Creating the Renderer Class ..................................................................................................... 270
Identifying the Renderer Type ................................................................................................. 272
Implementing an Event Listener ..................................................................................................... 273
Implementing Value-Change Listeners .................................................................................. 273
Implementing Action Listeners ............................................................................................... 274
Handling Events for Custom Components .................................................................................... 275
10
The Java EE 6 Tutorial • January 2013
11. Contents
Defining the Custom Component Tag in a Tag Library Descriptor ........................................... 276
Using a Custom Component ........................................................................................................... 277
Creating and Using a Custom Converter ....................................................................................... 279
Creating a Custom Converter .................................................................................................. 279
Using a Custom Converter ....................................................................................................... 282
Creating and Using a Custom Validator ........................................................................................ 283
Implementing the Validator Interface ..................................................................................... 284
Specifying a Custom Tag ........................................................................................................... 286
Using a Custom Validator ......................................................................................................... 287
Binding Component Values and Instances to Managed Bean Properties .................................. 288
Binding a Component Value to a Property ............................................................................. 289
Binding a Component Value to an Implicit Object ............................................................... 291
Binding a Component Instance to a Bean Property .............................................................. 292
Binding Converters, Listeners, and Validators to Managed Bean Properties ............................ 293
14
Configuring JavaServer Faces Applications ..................................................................................295
Using Annotations to Configure Managed Beans ......................................................................... 296
Using Managed Bean Scopes .................................................................................................... 296
Application Configuration Resource File ....................................................................................... 297
Ordering of Application Configuration Resource Files ........................................................ 298
Configuring Managed Beans ........................................................................................................... 300
Using the managed-bean Element ............................................................................................ 300
Initializing Properties Using the managed-property Element ............................................ 303
Initializing Maps and Lists ........................................................................................................ 308
Registering Application Messages ................................................................................................... 308
Using FacesMessage to Create a Message .............................................................................. 310
Referencing Error Messages ..................................................................................................... 310
Using Default Validators .................................................................................................................. 311
Registering a Custom Validator ....................................................................................................... 312
Registering a Custom Converter ..................................................................................................... 313
Configuring Navigation Rules ......................................................................................................... 313
▼ To Configure a Navigation Rule ............................................................................................... 315
Implicit Navigation Rules ......................................................................................................... 316
Registering a Custom Renderer with a Render Kit ........................................................................ 317
Registering a Custom Component .................................................................................................. 319
11
12. Contents
Basic Requirements of a JavaServer Faces Application ................................................................. 320
Configuring an Application with a Web Deployment Descriptor ....................................... 321
Configuring Project Stage ......................................................................................................... 324
Including the Classes, Pages, and Other Resources ............................................................... 324
15
Java Servlet Technology ...................................................................................................................327
What Is a Servlet? ............................................................................................................................... 328
Servlet Lifecycle ................................................................................................................................. 328
Handling Servlet Lifecycle Events ............................................................................................ 328
Handling Servlet Errors ............................................................................................................. 330
Sharing Information ......................................................................................................................... 330
Using Scope Objects .................................................................................................................. 330
Controlling Concurrent Access to Shared Resources ........................................................... 331
Creating and Initializing a Servlet ................................................................................................... 331
Writing Service Methods .................................................................................................................. 332
Getting Information from Requests ........................................................................................ 332
Constructing Responses ............................................................................................................ 333
Filtering Requests and Responses .................................................................................................... 334
Programming Filters .................................................................................................................. 335
Programming Customized Requests and Responses ............................................................ 336
Specifying Filter Mappings ....................................................................................................... 336
Invoking Other Web Resources ....................................................................................................... 338
Including Other Resources in the Response ........................................................................... 339
Transferring Control to Another Web Component .............................................................. 339
Accessing the Web Context .............................................................................................................. 339
Maintaining Client State ................................................................................................................... 340
Accessing a Session .................................................................................................................... 340
Associating Objects with a Session .......................................................................................... 340
Session Management ................................................................................................................. 341
Session Tracking ........................................................................................................................ 341
Finalizing a Servlet ............................................................................................................................. 342
Tracking Service Requests ........................................................................................................ 342
Notifying Methods to Shut Down ............................................................................................ 343
Creating Polite Long-Running Methods ................................................................................. 343
The mood Example Application ........................................................................................................ 344
12
The Java EE 6 Tutorial • January 2013
13. Contents
Components of the mood Example Application ..................................................................... 344
Running the mood Example ....................................................................................................... 344
Further Information about Java Servlet Technology .................................................................... 346
16
Uploading Files with Java Servlet Technology ............................................................................. 347
The @MultipartConfig Annotation ............................................................................................... 347
The getParts and getPart Methods .............................................................................................. 348
The fileupload Example Application ........................................................................................... 349
Architecture of the fileupload Example Application .......................................................... 349
Running the fileupload Example .......................................................................................... 352
17
Internationalizing and Localizing Web Applications .................................................................. 355
Java Platform Localization Classes .................................................................................................. 355
Providing Localized Messages and Labels ...................................................................................... 356
Establishing the Locale .............................................................................................................. 356
Setting the Resource Bundle ..................................................................................................... 357
Retrieving Localized Messages ................................................................................................. 358
Date and Number Formatting ......................................................................................................... 359
Character Sets and Encodings .......................................................................................................... 359
Character Sets ............................................................................................................................. 359
Character Encoding ................................................................................................................... 360
Part III
Web Services ......................................................................................................................................361
18
Introduction to Web Services ..........................................................................................................363
What Are Web Services? ................................................................................................................... 363
Types of Web Services ....................................................................................................................... 363
“Big” Web Services ..................................................................................................................... 364
RESTful Web Services ............................................................................................................... 364
Deciding Which Type of Web Service to Use ................................................................................ 366
19
Building Web Services with JAX-WS ............................................................................................... 367
Creating a Simple Web Service and Clients with JAX-WS ........................................................... 368
Requirements of a JAX-WS Endpoint ..................................................................................... 369
13
14. Contents
Coding the Service Endpoint Implementation Class ............................................................ 370
Building, Packaging, and Deploying the Service .................................................................... 370
Testing the Methods of a Web Service Endpoint ................................................................... 371
A Simple JAX-WS Application Client ..................................................................................... 372
A Simple JAX-WS Web Client ................................................................................................. 374
Types Supported by JAX-WS ........................................................................................................... 377
Schema-to-Java Mapping .......................................................................................................... 377
Java-to-Schema Mapping .......................................................................................................... 378
Web Services Interoperability and JAX-WS .................................................................................. 379
Further Information about JAX-WS ............................................................................................... 379
20
21
14
Building RESTful Web Services with JAX-RS ................................................................................. 381
What Are RESTful Web Services? ................................................................................................... 381
Creating a RESTful Root Resource Class ........................................................................................ 382
Developing RESTful Web Services with JAX-RS ................................................................... 382
Overview of a JAX-RS Application .......................................................................................... 384
The @Path Annotation and URI Path Templates ................................................................... 385
Responding to HTTP Methods and Requests ........................................................................ 387
Using @Consumes and @Produces to Customize Requests and Responses .......................... 390
Extracting Request Parameters ................................................................................................ 392
Example Applications for JAX-RS ................................................................................................... 396
A RESTful Web Service ............................................................................................................. 396
The rsvp Example Application ................................................................................................ 398
Real-World Examples ............................................................................................................... 400
Further Information about JAX-RS ................................................................................................ 401
JAX-RS: Advanced Topics and Example .......................................................................................... 403
Annotations for Field and Bean Properties of Resource Classes ................................................. 403
Extracting Path Parameters ...................................................................................................... 404
Extracting Query Parameters ................................................................................................... 405
Extracting Form Data ................................................................................................................ 405
Extracting the Java Type of a Request or Response ................................................................ 406
Subresources and Runtime Resource Resolution .......................................................................... 407
Subresource Methods ................................................................................................................ 407
Subresource Locators ................................................................................................................ 407
The Java EE 6 Tutorial • January 2013
15. Contents
Integrating JAX-RS with EJB Technology and CDI ...................................................................... 408
Conditional HTTP Requests ............................................................................................................ 409
Runtime Content Negotiation ......................................................................................................... 410
Using JAX-RS With JAXB ................................................................................................................ 412
Using Java Objects to Model Your Data .................................................................................. 414
Starting from an Existing XML Schema Definition ............................................................... 415
Using JSON with JAX-RS and JAXB ........................................................................................ 417
The customer Example Application ............................................................................................... 418
Overview of the customer Example Application ................................................................... 419
The Customer and Address Entity Classes ............................................................................. 419
The CustomerService Class ..................................................................................................... 422
The CustomerClientXML and CustomerClientJSON Classes ............................................... 424
Modifying the Example to Generate Entity Classes from an Existing Schema .................. 426
Running the customer Example .............................................................................................. 428
Part IV
Enterprise Beans ................................................................................................................................433
22
Enterprise Beans ................................................................................................................................435
What Is an Enterprise Bean? ............................................................................................................ 435
Benefits of Enterprise Beans ..................................................................................................... 436
When to Use Enterprise Beans ................................................................................................. 436
Types of Enterprise Beans ......................................................................................................... 436
What Is a Session Bean? .................................................................................................................... 437
Types of Session Beans .............................................................................................................. 437
When to Use Session Beans ...................................................................................................... 438
What Is a Message-Driven Bean? .................................................................................................... 439
What Makes Message-Driven Beans Different from Session Beans? .................................. 439
When to Use Message-Driven Beans ....................................................................................... 440
Accessing Enterprise Beans .............................................................................................................. 441
Using Enterprise Beans in Clients ............................................................................................ 441
Deciding on Remote or Local Access ....................................................................................... 442
Local Clients ............................................................................................................................... 443
Remote Clients ........................................................................................................................... 445
Web Service Clients ................................................................................................................... 446
Method Parameters and Access ................................................................................................ 447
15
16. Contents
The Contents of an Enterprise Bean ............................................................................................... 447
Packaging Enterprise Beans in EJB JAR Modules .................................................................. 447
Packaging Enterprise Beans in WAR Modules ...................................................................... 448
Naming Conventions for Enterprise Beans ................................................................................... 449
The Lifecycles of Enterprise Beans .................................................................................................. 450
The Lifecycle of a Stateful Session Bean .................................................................................. 450
The Lifecycle of a Stateless Session Bean ................................................................................. 451
The Lifecycle of a Singleton Session Bean ............................................................................... 451
The Lifecycle of a Message-Driven Bean ................................................................................. 452
Further Information about Enterprise Beans ................................................................................ 453
23
24
16
Getting Started with Enterprise Beans .......................................................................................... 455
Creating the Enterprise Bean ........................................................................................................... 455
Coding the Enterprise Bean Class ............................................................................................ 456
Creating the converter Web Client ........................................................................................ 456
Running the converter Example ............................................................................................ 457
Modifying the Java EE Application ................................................................................................. 458
▼ To Modify a Class File ................................................................................................................ 458
Running the Enterprise Bean Examples ........................................................................................ 461
The cart Example ............................................................................................................................. 461
The Business Interface ............................................................................................................... 462
Session Bean Class ..................................................................................................................... 463
The @Remove Method ................................................................................................................. 466
Helper Classes ............................................................................................................................. 466
Running the cart Example ....................................................................................................... 466
A Singleton Session Bean Example: counter ................................................................................. 468
Creating a Singleton Session Bean ........................................................................................... 468
The Architecture of the counter Example .............................................................................. 472
Running the counter Example ................................................................................................ 475
A Web Service Example: helloservice ......................................................................................... 476
The Web Service Endpoint Implementation Class ................................................................ 476
Stateless Session Bean Implementation Class ........................................................................ 477
Running the helloservice Example ...................................................................................... 477
Using the Timer Service .................................................................................................................... 479
The Java EE 6 Tutorial • January 2013
17. Contents
Creating Calendar-Based Timer Expressions ........................................................................ 479
Programmatic Timers ............................................................................................................... 482
Automatic Timers ...................................................................................................................... 483
Canceling and Saving Timers ................................................................................................... 484
Getting Timer Information ...................................................................................................... 485
Transactions and Timers .......................................................................................................... 485
The timersession Example ..................................................................................................... 485
Running the timersession Example ...................................................................................... 488
Handling Exceptions ......................................................................................................................... 489
25
A Message-Driven Bean Example ...................................................................................................491
Overview of the simplemessage Example ..................................................................................... 491
The simplemessage Application Client ......................................................................................... 492
The Message-Driven Bean Class ..................................................................................................... 493
The onMessage Method ............................................................................................................. 494
Running the simplemessage Example ........................................................................................... 495
Administered Objects for the simplemessage Example ....................................................... 495
▼ To Run the simplemessage Application Using NetBeans IDE ............................................ 496
▼ To Run the simplemessage Application Using Ant .............................................................. 496
Removing the Administered Objects for the simplemessage Example .............................. 497
26
Using the Embedded Enterprise Bean Container ........................................................................ 499
Overview of the Embedded Enterprise Bean Container ............................................................... 499
Developing Embeddable Enterprise Bean Applications ............................................................... 499
Running Embedded Applications ............................................................................................ 500
Creating the Enterprise Bean Container ................................................................................. 500
Looking Up Session Bean References ...................................................................................... 502
Shutting Down the Enterprise Bean Container ..................................................................... 502
The standalone Example Application ........................................................................................... 502
▼ To Run the standalone Example Application ....................................................................... 503
27
Using Asynchronous Method Invocation in Session Beans ....................................................... 505
Asynchronous Method Invocation ................................................................................................. 505
Creating an Asynchronous Business Method ......................................................................... 506
17
18. Contents
Calling Asynchronous Methods from Enterprise Bean Clients ........................................... 507
The async Example Application ...................................................................................................... 508
Architecture of the async Example Application .................................................................... 508
Running the async Example ..................................................................................................... 509
Part V
28
Introduction to Contexts and Dependency Injection for the Java EE Platform .......................515
Overview of CDI ................................................................................................................................ 516
About Beans ....................................................................................................................................... 517
About CDI Managed Beans .............................................................................................................. 517
Beans as Injectable Objects ............................................................................................................... 518
Using Qualifiers ................................................................................................................................. 519
Injecting Beans ................................................................................................................................... 520
Using Scopes ...................................................................................................................................... 520
Overriding the Scope of a Bean at the Point of Injection .............................................................. 522
Giving Beans EL Names .................................................................................................................... 522
Adding Setter and Getter Methods .................................................................................................. 523
Using a Managed Bean in a Facelets Page ....................................................................................... 524
Injecting Objects by Using Producer Methods .............................................................................. 524
Configuring a CDI Application ....................................................................................................... 525
Using the @PostConstruct and @PreDestroy Annotations With CDI Managed Bean
Classes ................................................................................................................................................. 525
▼ To Initialize a Managed Bean Using the @PostConstruct Annotation .............................. 525
▼ To Prepare for the Destruction of a Managed Bean Using the @PreDestroy Annotation 526
Further Information about CDI ...................................................................................................... 526
29
18
Contexts and Dependency Injection for the Java EE Platform ...................................................513
Running the Basic Contexts and Dependency Injection Examples .......................................... 527
The simplegreeting CDI Example ................................................................................................ 527
The simplegreeting Source Files ........................................................................................... 528
The Facelets Template and Page ............................................................................................... 528
Configuration Files .................................................................................................................... 529
Running the simplegreeting Example .................................................................................. 530
The guessnumber CDI Example ...................................................................................................... 531
The guessnumber Source Files ................................................................................................. 532
The Java EE 6 Tutorial • January 2013
19. Contents
The Facelets Page ....................................................................................................................... 536
Running the guessnumber Example ........................................................................................ 537
30
Contexts and Dependency Injection for the Java EE Platform: Advanced Topics ...................539
Using Alternatives in CDI Applications ......................................................................................... 539
Using Specialization .................................................................................................................. 540
Using Producer Methods, Producer Fields, and Disposer Methods in CDI Applications ....... 541
Using Producer Methods .......................................................................................................... 542
Using Producer Fields to Generate Resources ........................................................................ 543
Using a Disposer Method .......................................................................................................... 543
Using Predefined Beans in CDI Applications ................................................................................ 544
Using Events in CDI Applications ................................................................................................... 545
Defining Events .......................................................................................................................... 545
Using Observer Methods to Handle Events ............................................................................ 545
Firing Events ............................................................................................................................... 546
Using Interceptors in CDI Applications ......................................................................................... 547
Using Decorators in CDI Applications ........................................................................................... 549
Using Stereotypes in CDI Applications .......................................................................................... 550
31
Running the Advanced Contexts and Dependency Injection Examples ................................. 553
The encoder Example: Using Alternatives .................................................................................... 553
The Coder Interface and Implementations ............................................................................. 554
The encoder Facelets Page and Managed Bean ...................................................................... 554
Running the encoder Example ................................................................................................ 556
The producermethods Example: Using a Producer Method To Choose a Bean
Implementation ................................................................................................................................. 558
Components of the producermethods Example .................................................................... 559
Running the producermethods Example ................................................................................ 560
The producerfields Example: Using Producer Fields to Generate Resources ........................ 561
The Producer Field for the producerfields Example .......................................................... 561
The producerfields Entity and Session Bean ...................................................................... 563
The producerfields Facelets Pages and Managed Bean ..................................................... 564
Running the producerfields Example .................................................................................. 566
The billpayment Example: Using Events and Interceptors ........................................................ 568
The PaymentEvent Event Class ................................................................................................ 568
19
20. Contents
The PaymentHandler Event Listener ....................................................................................... 568
The billpayment Facelets Pages and Managed Bean ............................................................ 569
The LoggedInterceptor Interceptor Class ............................................................................ 572
Running the billpayment Example ........................................................................................ 573
The decorators Example: Decorating a Bean ............................................................................... 574
Components of the decorators Example .............................................................................. 574
Running the decorators Example .......................................................................................... 575
Part VI
Persistence ..........................................................................................................................................577
32
Introduction to the Java Persistence API ...................................................................................... 579
Entities ................................................................................................................................................ 579
Requirements for Entity Classes .............................................................................................. 580
Persistent Fields and Properties in Entity Classes .................................................................. 580
Primary Keys in Entities ............................................................................................................ 585
Multiplicity in Entity Relationships ......................................................................................... 587
Direction in Entity Relationships ............................................................................................. 587
Embeddable Classes in Entities ................................................................................................ 590
Entity Inheritance .............................................................................................................................. 591
Abstract Entities ......................................................................................................................... 591
Mapped Superclasses ................................................................................................................. 591
Non-Entity Superclasses ........................................................................................................... 592
Entity Inheritance Mapping Strategies .................................................................................... 592
Managing Entities .............................................................................................................................. 595
The EntityManager Interface .................................................................................................. 595
Persistence Units ........................................................................................................................ 599
Querying Entities ............................................................................................................................... 600
Further Information about Persistence .......................................................................................... 601
33
Running the Persistence Examples ................................................................................................603
The order Application ...................................................................................................................... 603
Entity Relationships in the order Application ....................................................................... 604
Primary Keys in the order Application ................................................................................... 606
Entity Mapped to More Than One Database Table ............................................................... 610
20
The Java EE 6 Tutorial • January 2013
21. Contents
Cascade Operations in the order Application ....................................................................... 610
BLOB and CLOB Database Types in the order Application ................................................ 611
Temporal Types in the order Application .............................................................................. 612
Managing the order Application’s Entities ............................................................................. 612
Running the order Example ..................................................................................................... 614
The roster Application .................................................................................................................... 615
Relationships in the roster Application ................................................................................. 616
Entity Inheritance in the roster Application ......................................................................... 617
Criteria Queries in the roster Application ............................................................................ 619
Automatic Table Generation in the roster Application ...................................................... 620
Running the roster Example ................................................................................................... 621
The address-book Application ....................................................................................................... 623
Bean Validation Constraints in address-book ...................................................................... 623
Specifying Error Messages for Constraints in address-book .............................................. 624
Validating Contact Input from a JavaServer Faces Application .......................................... 625
Running the address-book Example ...................................................................................... 625
34
The Java Persistence Query Language .......................................................................................... 629
Query Language Terminology ......................................................................................................... 630
Creating Queries Using the Java Persistence Query Language .................................................... 630
Named Parameters in Queries .................................................................................................. 631
Positional Parameters in Queries ............................................................................................. 631
Simplified Query Language Syntax ................................................................................................. 632
Select Statements ........................................................................................................................ 632
Update and Delete Statements ................................................................................................. 632
Example Queries ................................................................................................................................ 633
Simple Queries ........................................................................................................................... 633
Queries That Navigate to Related Entities .............................................................................. 634
Queries with Other Conditional Expressions ........................................................................ 635
Bulk Updates and Deletes ......................................................................................................... 637
Full Query Language Syntax ............................................................................................................ 637
BNF Symbols .............................................................................................................................. 637
BNF Grammar of the Java Persistence Query Language ....................................................... 638
FROM Clause ................................................................................................................................. 642
Path Expressions ........................................................................................................................ 646
21
22. Contents
WHERE Clause ............................................................................................................................... 647
SELECT Clause ............................................................................................................................. 657
ORDER BY Clause ......................................................................................................................... 659
GROUP BY and HAVING Clauses .................................................................................................. 659
35
36
Creating and Using String-Based Criteria Queries ...................................................................... 673
Overview of String-Based Criteria API Queries ............................................................................ 673
Creating String-Based Queries ........................................................................................................ 674
Executing String-Based Queries ...................................................................................................... 675
37
Controlling Concurrent Access to Entity Data with Locking ...................................................... 677
Overview of Entity Locking and Concurrency .............................................................................. 677
Using Optimistic Locking ......................................................................................................... 678
Lock Modes ........................................................................................................................................ 679
Setting the Lock Mode ............................................................................................................... 680
Using Pessimistic Locking ........................................................................................................ 680
38
22
Using the Criteria API to Create Queries ........................................................................................ 661
Overview of the Criteria and Metamodel APIs .............................................................................. 661
Using the Metamodel API to Model Entity Classes ....................................................................... 663
Using Metamodel Classes ......................................................................................................... 664
Using the Criteria API and Metamodel API to Create Basic Typesafe Queries ......................... 664
Creating a Criteria Query .......................................................................................................... 665
Query Roots ................................................................................................................................ 665
Querying Relationships Using Joins ........................................................................................ 666
Path Navigation in Criteria Queries ........................................................................................ 667
Restricting Criteria Query Results ........................................................................................... 667
Managing Criteria Query Results ............................................................................................ 669
Executing Queries ...................................................................................................................... 671
Using a Second-Level Cache with Java Persistence API Applications .......................................683
Overview of the Second-Level Cache .............................................................................................. 683
Controlling Whether Entities May Be Cached ....................................................................... 684
Specifying the Cache Mode Settings to Improve Performance .................................................... 685
The Java EE 6 Tutorial • January 2013
23. Contents
Setting the Cache Retrieval and Store Modes ......................................................................... 686
Controlling the Second-Level Cache Programmatically ....................................................... 687
Part VII
Security ...............................................................................................................................................689
39
Introduction to Security in the Java EE Platform ......................................................................... 691
Overview of Java EE Security ........................................................................................................... 692
A Simple Application Security Walkthrough ......................................................................... 692
Features of a Security Mechanism ............................................................................................ 695
Characteristics of Application Security ................................................................................... 696
Security Mechanisms ........................................................................................................................ 697
Java SE Security Mechanisms ................................................................................................... 697
Java EE Security Mechanisms ................................................................................................... 698
Securing Containers .......................................................................................................................... 700
Using Annotations to Specify Security Information ............................................................. 700
Using Deployment Descriptors for Declarative Security ...................................................... 701
Using Programmatic Security .................................................................................................. 701
Securing the GlassFish Server .......................................................................................................... 702
Working with Realms, Users, Groups, and Roles .......................................................................... 702
What Are Realms, Users, Groups, and Roles? ........................................................................ 703
Managing Users and Groups on the GlassFish Server ........................................................... 706
Setting Up Security Roles .......................................................................................................... 707
Mapping Roles to Users and Groups ....................................................................................... 709
Establishing a Secure Connection Using SSL ................................................................................. 710
Verifying and Configuring SSL Support ................................................................................. 711
Further Information about Security ................................................................................................ 711
40
Getting Started Securing Web Applications ................................................................................. 713
Overview of Web Application Security .......................................................................................... 713
Securing Web Applications .............................................................................................................. 715
Specifying Security Constraints ............................................................................................... 715
Specifying Authentication Mechanisms ................................................................................. 719
Specifying an Authentication Mechanism in the Deployment Descriptor ......................... 722
Declaring Security Roles ........................................................................................................... 723
23
24. Contents
Using Programmatic Security with Web Applications ................................................................. 724
Authenticating Users Programmatically ................................................................................. 724
Checking Caller Identity Programmatically ........................................................................... 726
Example Code for Programmatic Security ............................................................................. 727
Declaring and Linking Role References .................................................................................. 728
Examples: Securing Web Applications ........................................................................................... 729
▼ To Set Up Your System for Running the Security Examples ................................................ 729
The hello2_basicauth Example: Basic Authentication with a Servlet .............................. 730
The hello1_formauth Example: Form-Based Authentication with a JavaServer Faces
Application ................................................................................................................................. 734
41
Getting Started Securing Enterprise Applications ...................................................................... 739
Securing Enterprise Beans ................................................................................................................ 739
Securing an Enterprise Bean Using Declarative Security ...................................................... 742
Securing an Enterprise Bean Programmatically .................................................................... 746
Propagating a Security Identity (Run-As) ............................................................................... 747
Deploying Secure Enterprise Beans ......................................................................................... 749
Examples: Securing Enterprise Beans ............................................................................................. 749
The cart-secure Example: Securing an Enterprise Bean with Declarative Security ....... 750
The converter-secure Example: Securing an Enterprise Bean with Programmatic
Security ........................................................................................................................................ 754
42
Java EE Security: Advanced Topics .................................................................................................. 759
Working with Digital Certificates ................................................................................................... 759
Creating a Server Certificate ..................................................................................................... 760
Adding Users to the Certificate Realm .................................................................................... 762
Using a Different Server Certificate with the GlassFish Server ............................................. 763
Authentication Mechanisms ............................................................................................................ 764
Client Authentication ................................................................................................................ 764
Mutual Authentication .............................................................................................................. 764
Using Form-Based Login in JavaServer Faces Web Applications ................................................ 769
Using j_security_check in JavaServer Faces Forms ........................................................... 769
Using a Managed Bean for Authentication in JavaServer Faces Applications .................... 770
Using the JDBC Realm for User Authentication ........................................................................... 771
▼ To Configure a JDBC Authentication Realm ......................................................................... 772
24
The Java EE 6 Tutorial • January 2013
25. Contents
Securing HTTP Resources ................................................................................................................ 775
Securing Application Clients ........................................................................................................... 778
Using Login Modules ................................................................................................................ 779
Using Programmatic Login ...................................................................................................... 779
Securing Enterprise Information Systems Applications ............................................................... 780
Container-Managed Sign-On .................................................................................................. 780
Component-Managed Sign-On ............................................................................................... 780
Configuring Resource Adapter Security ................................................................................. 781
▼ To Map an Application Principal to EIS Principals ............................................................... 782
Configuring Security Using Deployment Descriptors ................................................................. 783
Specifying Security for Basic Authentication in the Deployment Descriptor .................... 783
Specifying Non-Default Principal-to-Role Mapping in the Deployment Descriptor ....... 784
Further Information about Security ................................................................................................ 785
Part VIII
Java EE Supporting Technologies ................................................................................................... 787
43
Introduction to Java EE Supporting Technologies ....................................................................... 789
Transactions in Java EE Applications ............................................................................................. 789
Resources in Java EE Applications ................................................................................................... 790
The Java EE Connector Architecture and Resource Adapters ............................................. 790
Java Database Connectivity Software ...................................................................................... 790
Java Message Service ......................................................................................................................... 791
44
Transactions ...................................................................................................................................... 793
What Is a Transaction? ..................................................................................................................... 793
Container-Managed Transactions .................................................................................................. 794
Transaction Attributes .............................................................................................................. 795
Rolling Back a Container-Managed Transaction .................................................................. 799
Synchronizing a Session Bean’s Instance Variables ............................................................... 799
Methods Not Allowed in Container-Managed Transactions ............................................... 799
Bean-Managed Transactions ........................................................................................................... 800
JTA Transactions ....................................................................................................................... 800
Returning without Committing ............................................................................................... 801
Methods Not Allowed in Bean-Managed Transactions ........................................................ 801
25