Java EE 7精粹 (Java EE 7 Essentials)

Arun Gupta Java EE 7 Essentials Java EE 7 Essentials by Arun Gupta Copyright © 2013 Arun Gupta. All rights reserved. Printed in the United States of America. Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472. O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles ( For more information, contact our corporate/ institutional sales department: 800-998-9938 or Editors: Mike Loukides and Meghan Blanchette Production Editor: Kara Ebrahim Copyeditor: Rachel Monaghan Proofreader: Linley Dolby Indexer: Angela Howard Cover Designer: Randy Comer Interior Designer: David Futato Illustrator: Rebecca Demarest August 2013: First Edition Revision History for the First Edition: 2013-08-08: First release See for release details. Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of O’Reilly Media, Inc. Java EE 7 Essentials, the image of glassfish, and related trade dress are trademarks of O’Reilly Media, Inc. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O’Reilly Media, Inc., was aware of a trade‐ mark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this book, the publisher and author assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. ISBN: 978-1-449-37017-6 [LSI] To Menka, the eternal sunshine in my life. You make my days shine and life upbeat. To Aditya and Mihir, your stories and games are invaluable to me. Table of Contents Foreword. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii 1. Java Platform, Enterprise Edition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Introduction 1 Deliverables 3 What’s New in Java EE 7 6 2. Servlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 WebServlet 11 Servlet Filters 16 Event Listeners 17 Asynchronous Support 20 Nonblocking I/O 22 Web Fragments 24 Security 25 Resource Packaging 28 Error Mapping 29 Handling Multipart Requests 30 Upgrade Processing 31 3. JavaServer Faces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Facelets 34 Resource Handling 37 Composite Components 38 Request Processing Life-Cycle Phases 41 Ajax 43 HTTP GET 46 Server and Client Extension Points 47 v Validating Data 50 Navigation Rules 51 Faces Flow 51 Resource Library Contracts 57 Passthrough Attributes and HTML5-Friendly Markup 59 Component Tags 60 4. RESTful Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Resources 73 Binding HTTP Methods 77 Multiple Resource Representations 79 Binding a Request to a Resource 81 Entity Providers 82 Client API 84 Mapping Exceptions 87 Filters and Entity Interceptors 88 Validation of Resources 94 5. SOAP-Based Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Web Service Endpoints 98 Provider-Based Dynamic Endpoints 101 Endpoint-Based Endpoints 102 Web Service Client 103 Dispatch-Based Dynamic Client 105 Handlers 107 6. JSON Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Streaming API 112 Consuming JSON Using the Streaming API 112 Producing JSON Using the Streaming API 114 Object Model API 116 Consuming JSON Using the Object Model API 116 Producing JSON Using the Object Model API 117 7. WebSocket. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Annotated Server Endpoint 122 Programmatic Server Endpoint 128 Annotated Client Endpoint 132 Programmatic Client Endpoint 135 JavaScript WebSocket Client 137 Encoders and Decoders 138 vi | Table of Contents Integration with Java EE Security 142 8. Enterprise JavaBeans. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 Stateful Session Beans 145 Stateless Session Beans 148 Singleton Session Beans 150 Life-Cycle Event Callbacks 151 Message-Driven Beans 154 Portable Global JNDI Names 156 Transactions 157 Asynchronous Invocation 159 Timers 160 Embeddable API 164 EJB Lite 165 9. Contexts and Dependency Injection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Discovery of Beans 167 Injection Points 170 Qualifier and Alternative 171 Producer and Disposer 173 Interceptors 174 Decorators 178 Scopes and Contexts 179 Stereotypes 181 Events 182 Portable Extensions 183 Built-in Beans 185 Life-Cycle Callbacks 186 10. Concurrency Utilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Asynchronous Tasks 189 Schedule Tasks 194 Managed Threads 197 Dynamic Contextual Objects 198 11. Bean Validation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 Built-in Constraints 203 Defining a Custom Constraint 207 Validation Groups 210 Method and Constructor Constraint 212 12. Java Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 Table of Contents | vii User-Managed Transactions 215 Container-Managed Transactions 216 @TransactionScoped 218 13. Java Persistence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 Entities 219 Persistence Unit, Persistence Context, and Entity Manager 222 Schema Generation 226 Create, Read, Update, and Delete Entities 229 Entity Listeners 232 Stored Procedures 235 Validating the Entities 237 Transactions and Locking 239 Caching 241 14. Java Message Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 Sending a Message 247 Receiving a Message Synchronously 251 Receiving a Message Asynchronously 253 Quality of Service 254 Temporary Destinations 255 15. Batch Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 Chunk-Oriented Processing 258 Custom Checkpointing 263 Exception Handling 264 Batchlet Processing 265 Listeners 266 Job Sequence 267 Flow 268 Split 269 Decision 269 Partitioning the Job 271 16. Build an End-to-End Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 Introduction 275 Software Requirements 275 Problem Statement 276 Lab Flow 277 Walkthrough of a Sample Application 278 Show Booking (JavaServer Faces) 283 Chat Room (Java API for WebSocket) 292 viii | Table of Contents View and Delete Movies (Java API for RESTful Web Services) 299 Add Movie (Java API for JSON Processing) 304 Ticket Sales (Batch Applications for the Java Platform) 310 Movie Points (Java Message Service 2) 318 Conclusion 326 Troubleshooting 327 Completed Solution 327 A. Further Reading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 Table of Contents | ix Foreword As Java EE platform specification lead, I’ve been guiding the path of Java EE since its introduction in 1999. Arun has been a key member of the Java EE team from the be‐ ginning. The Java EE platform has evolved significantly over the last 13 years. The release of Java EE 5 in 2006 was just the beginning of a theme that continues today: making it easier to develop Java EE applications. Java EE 6 in 2009 contributed significantly to this theme with the inclusion of CDI. Java EE 7 is the latest release continuing this theme of focusing on developer productivity. Arun has been involved in several different areas of Java EE, but the common thread of his involvement has been understanding real developers and real applications. His background with Java EE, and his current role as technology evangelist for Java EE, make him uniquely qualified to introduce developers to the latest Java EE technology. In this book, Arun surveys all the key technologies of the latest version of Java EE, giving developers a taste for these many new capabilities, and showing just how easy it is to write Java EE applications. Arun expands on his popular Java EE 6 Pocket Guide to cover more technologies in more depth. Particular attention is paid to technologies new to Java EE 7, and to new features of existing technologies. Developers with some Java EE experience, as well as developers new to Java EE, will find this a very helpful overview of Java EE 7. Each chapter covers a Java EE technology in just enough depth to help you understand what the technology does, what it’s best used for, and how to get started using it. While it’s not a complete tutorial, an experienced developer will find that it provides just the right level of detail to understand the technology. The chapters are full of short code fragments that developers will appreciate. After describing the key technologies of Java EE, in the last chapter of the book, Arun pulls it all together with a hands-on lab that walks you through the process of developing a real application that uses most of these technologies. This is where Arun’s experience really shines. There’s nothing like seeing the code for a running application to show you how these technologies actually work in practice. xi Java EE is a rich platform that we’ve been developing over many years. It can be daunting to sort through all the old and new versions of technologies to find the best way to write Java EE applications. We’ve made it much easier to write Java EE applications in recent years, but sometimes that message doesn’t come through when reading our many Java EE specifications. Arun’s years of experience in working with application developers, teaching hands-on labs, and evangelizing Java EE put him in a unique position to pro‐ vide all the key information at just the right depth. This book is a great way for developers to get an overview of the Java EE platform, and especially the new features in Java EE 7. —Bill Shannon Architect Java EE Platform Specification Lead, Oracle June 2013 xii | Foreword Preface The Java EE 7 platform builds upon previous versions of the platform and focuses on higher productivity and embracing HTML5. This book is directed toward readers who want to get a quick overview of the platform and to keep coming back to review the basics. This book provides an overview of the key specifications in the Java EE 7 platform (one specification per chapter). This book is by no means intended to be an exhaustive guide or tutorial that explains each and every concept of different specifications. However, the main concepts from the different specifications are explained using simple code samples. No prior knowledge of earlier versions of the platform is required, but you’ll need some basic understanding of Java to understand the code. A significant part of this book is derived from Java EE 6 Pocket Guide (O’Reilly). New chapters have been added to cover the new technologies in the platform. New sections have been added or existing sections updated to reflect the changes in the platform. If you have read the Java EE 6 Pocket Guide, then you can read this book at a much faster pace; otherwise, you can read this book from beginning to end. Alternatively, you can read specific chapters based upon your interest. I also provide self-paced instructions on how to build an end-to-end application using most of the technologies described. This allows developers to understand the design patterns they can apply to build a real-life application using Java EE 7. I hope you will enjoy the book! Conventions Used in This Book The following typographical conventions are used in this book: Italic Indicates new terms, URLs, email addresses, filenames, and file extensions. xiii Constant width Used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords. Constant width italic Shows text that should be replaced with user-supplied values or by values deter‐ mined by context. Using Code Examples Supplemental material (code examples, exercises, etc.) is available for download at This book is here to help you get your job done. In general, if this book includes code examples, you may use the code in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of ex‐ ample code from this book into your product’s documentation does require permission. We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Java EE 7 Essentials by Arun Gupta (O’Reil‐ ly). Copyright 2013 Arun Gupta, 978-1-449-37017-6.” If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at Safari® Books Online Safari Books Online ( is an on- demand digital library that delivers expert content in both book and video form from the world’s leading authors in technology and business. Technology professionals, software developers, web designers, and business and crea‐ tive professionals use Safari Books Online as their primary resource for research, prob‐ lem solving, learning, and certification training. Safari Books Online offers a range of product mixes and pricing programs for organi‐ zations, government agencies, and individuals. Subscribers have access to thousands of books, training videos, and prepublication manuscripts in one fully searchable database from publishers like O’Reilly Media, Prentice Hall Professional, Addison-Wesley xiv | Preface Professional, Microsoft Press, Sams, Que, Peachpit Press, Focal Press, Cisco Press, John Wiley & Sons, Syngress, Morgan Kaufmann, IBM Redbooks, Packt, Adobe Press, FT Press, Apress, Manning, New Riders, McGraw-Hill, Jones & Bartlett, Course Technol‐ ogy, and dozens more. For more information about Safari Books Online, please visit us online. How to Contact Us Please address comments and questions concerning this book to the publisher: O’Reilly Media, Inc. 1005 Gravenstein Highway North Sebastopol, CA 95472 800-998-9938 (in the United States or Canada) 707-829-0515 (international or local) 707-829-0104 (fax) We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at To comment or ask technical questions about this book, send email to bookques For more information about our books, courses, conferences, and news, see our website at Find us on Facebook: Follow us on Twitter: Watch us on YouTube: Acknowledgments This book would not have been possible without support from a multitude of people. First and foremost, many thanks to O’Reilly for trusting in me and providing an op‐ portunity to write this book. Their team provided excellent support throughout the editing, reviewing, proofreading, and publishing process. At O’Reilly, Meghan Blanchette provided excellent editorial help throughout all the stages, helping with interim reviews, providing feedback on styling, arranging technical reviews, and connecting me with the rest of the team when required. Rachel Monaghan and Kara Ebrahim helped with copyediting and making sure to pro‐ vide the finishing touches. And thanks to the rest of the O’Reilly team with whom I did not interact directly, but who were helping in many other ways. Preface | xv The detailed proofreading and technical review by Markus Eisele (@myfear, http://, John Yeary (@jyeary,, and Bert Ert‐ man (@BertErtman, ensured that the relevant con‐ tent was covered accurately. Their vast experience and knowledge showed in the depth of their comments. I am grateful for the numerous discussions with developers around the world that helped me understand the technology better. Thanks to my colleagues at Oracle and the dif‐ ferent JSR specification leads for explaining the intended use cases of different tech‐ nologies. And thanks to everybody else in my life, who provided much-needed breaks from book writing. xvi | Preface CHAPTER 1 Java Platform, Enterprise Edition Introduction The Java Platform, Enterprise Edition (Java EE), provides a standards-based platform for developing web and enterprise applications. These applications are typically de‐ signed as multitier applications, with a frontend tier consisting of a web framework, a middle tier providing security and transactions, and a backend tier providing connec‐ tivity to a database or a legacy system. These applications should be responsive and capable of scaling to accommodate the growth in user demand. The Java EE platform defines APIs for different components in each tier, and also pro‐ vides some additional services such as naming, injection, and resource management that span across the platform. These components are deployed in containers that provide runtime support. Containers provide a federated view of the underlying Java EE APIs to the application components. Java EE application components never interact directly with other Java EE application components. They use the protocols and methods of the container for interacting with each other and with platform services. Interposing a container between the application components and the Java EE services allows the con‐ tainer to transparently inject the services required by the component, such as declarative transaction management, security checks, resource pooling, and state management. This container-based model and abstraction of resource access allows the platform to offload the developer from common infrastructure tasks. Each component of the platform is defined in a separate specification that also describes the API, javadocs, and expected runtime behavior. Java EE 7 was released in June 2013 and provides a simple, easy-to-use, and complete stack for building such web and enterprise applications. The previous versions of the platform, starting with Java EE 5 and continuing with Java EE 6, took the first steps in providing a simplified developer experience. 1 The Java EE 7 platform built upon the previous version with three main goals: Embracing HTML5 The WebSocket protocol, developed as part of the collection of technologies that make up HTML5, brings a new level of ease of development and network efficiency to modern, interactive web applications. It provides a two-way, full-duplex com‐ munication channel between a client and a server over a single TCP (transmission control protocol) channel. Java EE 7 defines a new standard API to develop and deploy WebSocket clients and endpoints. JSON is the lingua franca of the Web for lightweight data exchange. Until now, developers were required to bundle third-party libraries for JSON processing. Java EE 7 defines a new portable API to parse, generate, transform, and query JSON using a Streaming API or Object Model API. JavaServer Faces (JSF) introduces pass-through attributes and elements that allow near-total control over the user experience of each individual element in the view. This allows HTML5-friendly markup to be easily embedded in a page. Higher productivity The JMS API has been greatly simplified. JMSContext provides the unified func‐ tionality of Connection and Session objects. In addition, several JMS interfaces implement Autocloseable and thus are automatically closed after use. Finally, correct error handling, runtime exceptions instead of checked exceptions, method chaining on JMSProducer, and simplified message sending are further examples of features that the JMS API has simplified. Without the Client API (introduced in JAX-RS 2), developers are required to use basic HttpUrlConnection APIs and write all the surrounding code. More defaults for the application’s use—such as a preconfigured DataSource for accessing databases in operational environments, a preconfigured JMS Connec tionFactory for accessing a JMS provider, and a preconfigured ManagedExecutor Service—provide a seamless out-of-the-box experience for new developers start‐ ing with the platform. The Contexts and Dependency Injection (CDI) specification is now a core com‐ ponent model, and is enabled by default. This makes the platform a lot more co‐ hesive and integrated. CDI interceptors are now more widely applicable to beans. @Transactional annotation brings transactional semantics to POJOs (plain old Java objects), outside of an EJB (Enterprise JavaBean). Bean Validation allows au‐ tomatic validation of method arguments and results using interceptors. Less boilerplate text, more defaults, and a cohesive integrated platform together boost developers’ productivity when building applications using the latest version of the platform. 2 | Chapter 1: Java Platform, Enterprise Edition Enterprise demands Batch Applications for the Java Platform is a new functionality in the platform and very important for enterprise customers. It allows developers to easily define non‐ interactive, bulk-oriented, long-running jobs in an item- or task-oriented way. Concurrency Utilities for Java EE, another functionality new to the platform, is an extension of the Java SE Concurrency Utilities API, for use in the Java EE container- managed environment so that the proper container-managed runtime context can be made available for the execution of these tasks. This functionality in the platform allows the developer to leverage the standard APIs and reduces the dependency on third-party frameworks. Prior to Java EE 7, the Java EE 6 platform improved upon the developer productivity features and added a lot more functionality. Deliverables The Java EE 7 platform was developed as Java Specification Request (JSR) 342 following JCP 2.9. The JCP process defines three key deliverables for any JSR: Specification A formal document that describes the proposed component and its features. Reference Implementation (RI) Binary implementation of the proposed specification. The RI helps to ensure that the proposed specifications can be implemented in a binary form and provides constant feedback to the specification process. The RI of Java EE is built in the GlassFish community. Technology Compliance Kit (TCK) A set of tests that verify that the RI is in compliance with the specification. This allows multiple vendors to provide compliant implementations. Java EE 7 consists of the platform specification that defines requirements across the platform. It also consists of the following component specifications: Web technologies • JSR 45: Debugging Support for Other Languages 1.0 • JSR 52: Standard Tag Library for JavaServer Pages (JSTL) 1.2 • JSR 245: JavaServer Pages (JSP) 2.3 • JSR 340: Servlet 3.1 • JSR 341: Expression Language 3.0 • JSR 344: JavaServer Faces (JSF) 2.2 Deliverables | 3 • JSR 353: Java API for JSON Processing (JSON-P) 1.0 • JSR 356: Java API for WebSocket 1.0 Enterprise technologies • JSR 236: Concurrency Utilities for Java EE 1.0 • JSR 250: Common Annotations for the Java Platform 1.2 • JSR 316: Managed Beans 1.0 • JSR 318: Interceptors 1.2 • JSR 322: Java EE Connector Architecture (JCA) 1.7 • JSR 330: Dependency Injection for Java 1.0 • JSR 338: Java Persistence API (JPA) 2.1 • JSR 343: Java Message Service (JMS) 2.0 • JSR 345: Enterprise JavaBeans (EJB) 3.2 • JSR 346: Contexts and Dependency Injection (CDI) for the Java EE Platform 1.1 • JSR 349: Bean Validation 1.1 • JSR 352: Batch Applications for Java Platform 1.0 • JSR 907: Java Transaction API (JTA) 1.2 • JSR 919: JavaMail 1.5 Web service technologies • JSR 93: Java API for XML Registries (JAXR) 1.0 (optional for Java EE 7) • JSR 101: Java API for XML-based RPC (JAX-RPC) 1.1 (optional for Java EE 7) • JSR 109: Implementing Enterprise Web Services 1.4 • JSR 181: Web Services Metadata for the Java Platform 2.1 • JSR 222: Java Architecture for XML Binding (JAXB) 2.2 • JSR 224: Java API for XML Web Services (JAX-WS) 2.2 • JSR 339: Java API for RESTful Web Services (JAX-RS) 2.0 Management and security technologies • JSR 77: J2EE Management API 1.1 • JSR 88: Java Platform EE Application Deployment API 1.2 (optional for Java EE 7) • JSR 115: Java Authorization Contract and Containers (JACC) 1.5 4 | Chapter 1: Java Platform, Enterprise Edition • JSR 196: Java Authentication Service Provider Inteface for Containers (JASPIC) 1.1 The different components work together to provide an integrated stack, as shown in Figure 1-1. Figure 1-1. Java EE 7 architecture In Figure 1-1: • Different components can be logically divided into three tiers: backend tier, middle tier, and web tier. This is only a logical representation, and the components can be restricted to a different tier based upon the application’s requirements. • JPA and JMS provide the basic services such as database access and messaging. JCA allows connection to legacy systems. Batch is used for performing noninteractive, bulk-oriented tasks. • Managed Beans and EJB provide a simplified programming model using POJOs to use the basic services. • CDI, Interceptors, and Common Annotations provide concepts that are applicable to a wide variety of components, such as type-safe dependency injection, addressing cross-cutting concerns using interceptors, and a common set of annotations. Con‐ currency Utilities can be used to run tasks in a managed thread. JTA enables Trans‐ actional Interceptors that can be applied to any POJO. • CDI Extensions allow you to extend the platform beyond its existing capabilities in a standard way. Deliverables | 5 • Web Services using JAX-RS and JAX-WS, JSF, JSP, and EL define the programming model for web applications. Web Fragments allow automatic registration of third- party web frameworks in a very natural way. JSON provides a way to parse and generate JSON structures in the web tier. WebSocket allows the setup of a bidirec‐ tional, full-duplex communication channel over a single TCP connection. • Bean Validation provides a standard means to declare constraints and validate them across different technologies. JAX-RPC (JSR 101), JAXR (JSR 93), EJB Entity Beans (part of JSR 153), and Java EE Application Deployment (JSR 88) are pruned in this version of the platform. The RI of Java EE 7 is built in the GlassFish Community. The GlassFish Server Open Source Edition 4.0 provides a full Java EE 7–compliant, free, and open source application server. It is also available in a Web Profile distribution and can be downloaded from The application server is easy to use (ZIP installer and NetBeans/ Eclipse/IntelliJ integration), lightweight (downloads starting at 37 MB, small disk/ memory footprint), and modular (OSGi-based, containers start on demand). Prior to Java EE 7, GlassFish Server Open Source Edition provides a Java EE 6−compliant version application server. It also provides clustering with high availability and centralized administration using CLI, Web-based administration console, and REST management/monitoring APIs. The Oracle GlassFish Server is Oracle’s com‐ mercially supported GlassFish server distribution and can be downloaded from http:// As of this writing, there are 18 Java EE 6–compliant applica‐ tion servers. The TCK is available to all Java EE licensees for testing their respective implementations. What’s New in Java EE 7 Some new specifications have been added to improve the functionality and richness of the platform. Several existing component specifications were revised to make them simpler and easier to use. The main features of the new specifications are described as follows: Java API for WebSocket • Enables a WebSocket client and server endpoint to be defined declaratively via annotations on a POJO, or programmatically via interface implementation. • Provides server-specific configuration, such as mapping that identifies a Web‐ Socket endpoint in the URI space of the container, subprotocols supported by the endpoint, and extensions required by the applications. • Offers client-specific configurations such as providing custom configuration algorithms. 6 | Chapter 1: Java Platform, Enterprise Edition • Enables packaging and deployment on JDK or web containers. • Allows for integration with existing Java EE technologies. Java API for JSON Processing • The streaming API provides a way to parse and generate JSON in a streaming fashion. • The Object Model API creates a random-access, tree-like structure that rep‐ resents the JSON data in memory. Batch Applications for Java Platform • Allows for description of a Batch Job using Job Specification Language defined by an XML schema. It defines a complete execution sequence of the jobs. • Features the Batch Programming Model using interfaces, abstract classes, and field annotations. • Offers the Chunked and Batchlet job-processing styles. Concurrency Utilities for Java EE • Provides concurrency capabilities to Java EE application components, without compromising container integrity. • Defines managed objects: ManagedExecutorService, ManagedScheduledExe cutorService, ContextService, and ManagedThreadFactory. The main features of the updated specifications are described as follows: Java API for RESTful Web Services • Offers a new Client API that can be used to access web resources and provides integration with JAX-RS providers. • Supports asynchronous processing in both the Client API and the Server API. • Defines Message Filters and Entity Interceptors as extension points to cus‐ tomize the request/response processing on the client and server side. • Supports new server-side content negotiation using qs factor. • Enables declarative validation of fields, properties, and parameters injected using @HeaderParam, @QueryParam, etc. Resource classes may be annotated with constraint annotations. Java Message Service • Several changes have been made to make the API simpler and easier to use. For example, Connection, Session, and other objects with a close method now implement the java.lang.Autocloseable interface to allow them to be used in a Java SE 7 try-with-resources statement. New methods have been added to create a session without the need to supply redundant arguments. A new What’s New in Java EE 7 | 7 method, getBody, has been added to allow an application to extract the body directly from a Message without the need to cast it first to an appropriate sub‐ type. • A message producer can now specify that a message must not be delivered until after a specified time interval. • New send methods have been added to allow an application to send messages asynchronously. • JMS providers must now set the JMSXDeliveryCount message property. Expression Language • Expression Language (EL) is a specification of its own. It can be configured and used outside of a Java EE container using ELProcessor. • The lambda syntax is now included in EL. Using lambdas, a complete set of collection operations, such as map and filter is now supported. • In addition to the usual arithmetic and comparison operators, new operators —such as an assignment operator and string concatenation operator—have been added to make EL more expressive. Enterprise JavaBeans • Support for EJB 2.1, EJB QL, and JAX-RPC-based Web Service endpoints and client view is now optional. • Enhanced message-driven beans (MDBs) contract with a no-method message listener interface to expose all public methods as message listener methods. This will allow custom Resource Adapters for future MDBs. • EJB API Groups have been defined with clear rules for an EJB Lite Container to support other API groups. This will help define how EJB features beyond EJB Lite can be officially added to a product that does not support full Java EE Profile. • Asynchronous session bean invocations and nonpersistent EJB Timer Service are included in EJB Lite. • An option has been added to disable passivation of stateful session beans. Servlets • Defines a standard mechanism to upgrade existing HTTP connection to a dif‐ ferent protocol using HttpUpgradeHandler. • Offers nonblocking request and response processing for async servlets. • Defines rules for which HTTP methods are covered by . 8 | Chapter 1: Java Platform, Enterprise Edition JavaServer Faces • Faces Flow provides an encapsulation of related views/pages with application- defined entry and exit points. • Resource Library Contracts enable developers to apply facelet templates to an entire application in a reusable and interchangeable manner. • HTML5-friendly markup allows near-total control over the user experience of each individual element in the view. • Stateless Views mean developers no longer have to save the UIComponent state. This allows applications with JavaScript components to manage the state in‐ stead of JSF doing it for them. Java Persistence • Database schema and tables may be generated by using javax.persistence.schema-generation.* properties. • Unsynchronized Persistence Contexts mean a persistence context does not have to be enlisted in a transaction. Such persistence contexts can explicitly join a transaction. • Bulk update/delete is supported via Criteria API. • Predefined and user-defined functions can be invoked using FUNCTION. • Stored procedures can be invoked using StoredProcedureQuery and @NamedStoredProcedureQuery. Interceptors • Associating interceptors using InterceptorBinding is now part of this speci‐ fication, instead of CDI. • @AroundConstruct designates an interceptor method that receives a callback when the target class constructor is invoked. • Method-level interceptors can be extended to life-cycle callbacks, adding constructor-level interceptors. • Priority ranges can be dedicated for ordering interceptors using interceptor binding. Contexts and Dependency Injection • Allows for automatic enabling of CDI for beans with a scope annotation, and EJBs, in Java EE. • Supports global ordering and enabling of interceptors, decorators, and alter‐ natives using the @Priority annotation. • Adds the @Vetoed annotation, allowing easy programmatic disabling of classes. What’s New in Java EE 7 | 9 Bean Validation • Validation constraints can be applied to the parameters and return values of arbitrary methods and constructors. • Integration points with CDI have been increased and reworked. • The targeted group can be altered when validation cascading is happening. Java Transaction • @Transactional provides the application to declaratively control transaction boundaries on CDI-managed beans, as well as classes defined as managed beans by the Java EE specification, at both the class and method level where method-level annotations override those at the class level. • @TransactionScoped is a new CDI scope that defines bean instances whose life cycle is scoped to the currently active JTA transaction. JavaMail • @MailSessionDefinition and @MailSessionDefintions defines MailSes sion to be registered with JNDI. Java EE Connector Architecture • Provides @AdministeredObjectDefinition, @AdministeredObjectDefin tions, @ConnectorFactoryDefinition, and @ConnectorFactoryDefini tions to define a connector-administered object and factory to be registered in JNDI. 10 | Chapter 1: Java Platform, Enterprise Edition CHAPTER 2 Servlets Servlets are defined as JSR 340, and the complete specification can be downloaded. A servlet is a web component hosted in a servlet container and generates dynamic content. The web clients interact with a servlet using a request/response pattern. The servlet container is responsible for the life cycle of the servlet, receives requests and sends responses, and performs any other encoding/decoding required as part of that. WebServlet A servlet is defined using the @WebServlet annotation on a POJO, and must extend the javax.servlet.http.HttpServlet class. Here is a sample servlet definition: @WebServlet("/account") public class AccountServlet extends javax.servlet.http.HttpServlet { //. . . } The fully qualified class name is the default servlet name, and may be overridden using the name attribute of the annotation. The servlet may be deployed at multiple URLs: @WebServlet(urlPatterns={"/account", "/accountServlet"}) public class AccountServlet extends javax.servlet.http.HttpServlet { //. . . } The @WebInitParam can be used to specify an initialization parameter: @WebServlet(urlPatterns="/account", initParams={ @WebInitParam(name="type", value="checking") } ) 11 public class AccountServlet extends javax.servlet.http.HttpServlet { //. . . } The HttpServlet interface has one doXXX method to handle each of HTTP GET, POST, PUT, DELETE, HEAD, OPTIONS, and TRACE requests. Typically the developer is concerned with overriding the doGet and doPost methods. The following code shows a servlet handling the GET request: @WebServlet("/account") public class AccountServlet extends javax.servlet.http.HttpServlet { @Override protected void doGet( HttpServletRequest request, HttpServletResponse response) { //. . . } } In this code: • The HttpServletRequest and HttpServletResponse capture the request/response with the web client. • The request parameters; HTTP headers; different parts of the path such as host, port, and context; and much more information is available from HttpServletRe quest. The HTTP cookies can be sent and retrieved as well. The developer is responsible for populating the HttpServletResponse, and the container then transmits the captured HTTP headers and/or the message body to the client. This code shows how an HTTP GET request received by a servlet displays a simple response to the client: protected void doGet(HttpServletRequest request, HttpServletResponse response) { try (PrintWriter out = response.getWriter()) { out.println(""); out.println("MyServlet"); out.println(""); out.println("

My First Servlet

"); //. . . out.println(""); } finally { //. . . } } 12 | Chapter 2: Servlets Request parameters may be passed in GET and POST requests. In a GET request, these parameters are passed in the query string as name/value pairs. Here is a sample URL to invoke the servlet explained earlier with request parameters: . . ./account?tx=10 In a POST request, the request parameters can also be passed in the posted data that is encoded in the body of the request. In both GET and POST requests, these parameters can be obtained from HttpServletRequest: protected void doGet(HttpServletRequest request, HttpServletResponse response) { String txValue = request.getParameter("tx"); //. . . } Request parameters can differ for each request. Initialization parameters, also known as init params, may be defined on a servlet to store startup and configuration information. As explained earlier, @WebInitParam is used to specify init params for a servlet: String type = null; @Override public void init(ServletConfig config) throws ServletException { type = config.getInitParameter("type"); //. . . } You can manipulate the default behavior of the servlet’s life-cycle call methods by over‐ riding the init, service, and destroy methods of the javax.servlet.Servlet inter‐ face. Typically, database connections are initialized in init and released in destroy. You can also define a servlet using the servlet and servlet-mapping elements in the deployment descriptor of the web application, web.xml. You can define the Account Servlet using web.xml: AccountServlet org.sample.AccountServlet AccountServlet /account WebServlet | 13 The annotations cover most of the common cases, so web.xml is not required in those cases. But some cases, such as ordering of servlets, can only be done using web.xml. If the metadata-complete element in web.xml is true, then the annotations in the class are not processed: //. . . The values defined in the deployment descriptor override the values defined using annotations. A servlet is packaged in a web application in a .war file. Multiple servlets may be pack‐ aged together, and they all share a servlet context. The ServletContext provides detail about the execution environment of the servlets and is used to communicate with the container—for example, by reading a resource packaged in the web application, writing to a logfile, or dispatching a request. The ServletContext can be obtained from HttpServletRequest: protected void doGet(HttpServletRequest request, HttpServletResponse response) { ServletContext context = request.getServletContext(); //. . . } A servlet can send an HTTP cookie, named JSESSIONID, to the client for session track‐ ing. This cookie may be marked as HttpOnly, which ensures that the cookie is not exposed to client-side scripting code, and thus helps mitigate certains kinds of cross- site scripting attacks: SessionCookieConfig config = request.getServletContext(). getSessionCookieConfig(); config.setHttpOnly(true); Alternatively, URL rewriting may be used by the servlet as a basis for session tracking. The ServletContext.getSessionCookieConfig method returns SessionCookieCon fig, which can be used to configure different properties of the cookie. The HttpSession interface can be used to view and manipulate information about a session such as the session identifier and creation time, and to bind objects to the session. A new session object may be created: 14 | Chapter 2: Servlets protected void doGet(HttpServletRequest request, HttpServletResponse response) { HttpSession session = request.getSession(true); //. . . } The session.setAttribute and session.getAttribute methods are used to bind objects to the session. A servlet may forward a request to another servlet if further processing is required. You can achieve this by dispatching the request to a different resource using Reques tDispatcher, which can be obtained from HttpServletRequest.getRequestDispatch er or ServletContext.getRequestDispatcher. The former can accept a relative path, whereas the latter can accept a path relative to the current context only: protected void doGet(HttpServletRequest request, HttpServletResponse response) { request.getRequestDispatcher("bank").forward(request, response); //. . . } In this code, bank is another servlet deployed in the same context. The ServletContext.getContext method can be used to obtain ServletContext for foreign contexts. It can then be used to obtain a RequestDispatcher, which can dispatch requests in that context. You can redirect a servlet response to another resource by calling the HttpServletRes ponse.sendRedirect method. This sends a temporary redirect response to the client, and the client issues a new request to the specified URL. Note that in this case, the original request object is not available to the redirected URL. The redirect may also be marginally slower because it entails two requests from the client, whereas forward is performed within the container: protected void doGet(HttpServletRequest request, HttpServletResponse response) { //. . . response.sendRedirect(""); } Here the response is redirected to the URL. Note that this URL could be on a different host/port and may be relative or absolute to the container. In addition to declaring servlets using @WebServlet and web.xml, you can define them programmatically using ServletContext.addServlet methods. You can do this from the ServletContainerInitializer.onStartup or ServletContextListener.contex tInitialized method. You can read more about this in “Event Listeners” on page 17. WebServlet | 15 The ServletContainerInitializer.onStartup method is invoked when the applica‐ tion is starting up for the given ServletContext. The addServlet method returns ServletRegistration.Dynamic, which can then be used to create URL mappings, set security roles, set initialization parameters, and manage other configuration items: public class MyInitializer implements ServletContainerInitializer { @Override public void onStartup (Set> clazz, ServletContext context) { ServletRegistration.Dynamic reg = context.addServlet("MyServlet", "org.example.MyServlet"); reg.addMapping("/myServlet"); } } Servlet Filters A servlet filter may be used to update the request and response payload and header information from and to the servlet. It is important to realize that filters do not create the response—they only modify or adapt the requests and responses. Authentication, logging, data compression, and encryption are some typical use cases for filters. The filters are packaged along with a servlet and act upon the dynamic or static content. You can associate filters with a servlet or with a group of servlets and static content by specifying a URL pattern. You define a filter using the @WebFilter annotation: @WebFilter("/*") public class LoggingFilter implements javax.servlet.Filter { public void doFilter(HttpServletRequest request, HttpServletResponse response) { //. . . } } In the code shown, the LoggingFilter is applied to all the servlets and static content pages in the web application. The @WebInitParam may be used to specify initialization parameters here as well. A filter and the target servlet always execute in the same invocation thread. Multiple filters may be arranged in a filter chain. You can also define a filter using and elements in the deployment descriptor: LoggingFilter org.sample.LoggingFilter . . . LoggingFilter 16 | Chapter 2: Servlets /* In addition to declaring filters using @WebFilter and web.xml, you can define them programmatically using ServletContext.addFilter methods. You can do this from the ServletContainerInitializer.onStartup method or the ServletContextLis tener.contextInitialized method. The addFilter method returns ServletRegis tration.Dynamic, which can then be used to add mapping for URL patterns, set initi‐ alization parameters, and handle other configuration items: public class MyInitializer implements ServletContainerInitializer { public void onStartup (Set> clazz, ServletContext context) { FilterRegistration.Dynamic reg = context.addFilter("LoggingFilter", "org.example.LoggingFilter"); reg.addMappingForUrlPatterns(null, false, "/"); } } Event Listeners Event listeners provide life-cycle callback events for ServletContext, HttpSession, and ServletRequest objects. These listeners are classes that implement an interface that supports event notifications for state changes in these objects. Each class is annotated with @WebListener, declared in web.xml, or registered via one of the ServletCon text.addListener methods. A typical example of these listeners is where an additional servlet is registered programmatically without an explicit need for the programmer to do so, or a database connection is initialized and restored back at the application level. There may be multiple listener classes listening to each event type, and they may be specified in the order in which the container invokes the listener beans for each event type. The listeners are notified in the reverse order during application shutdown. Servlet context listeners listen to the events from resources in that context: @WebListener public class MyContextListener implements ServletContextListener { @Override public void contextInitialized(ServletContextEvent sce) { ServletContext context = sce.getServletContext(); //. . . } @Override public void contextDestroyed(ServletContextEvent sce) { //. . . } } Event Listeners | 17 The ServletContextAttributeListener is used to listen for attribute changes in the context: public class MyServletContextAttributeListener implements ServletContextAttributeListener { @Override public void attributeAdded(ServletContextAttributeEvent event) { //. . . event.getName(); //. . . event.getValue(); } @Override public void attributeRemoved(ServletContextAttributeEvent event) { //. . . } @Override public void attributeReplaced(ServletContextAttributeEvent event) { //. . . } } The HttpSessionListener listens to events from resources in that session: @WebListener public class MySessionListener implements HttpSessionListener { @Override public void sessionCreated(HttpSessionEvent hse) { HttpSession session = hse.getSession(); //. . . } @Override public void sessionDestroyed(HttpSessionEvent hse) { //. . . } } The HttpSessionActivationListener is used to listen for events when the session is passivated or activated: public class MyHttpSessionActivationListener implements HttpSessionActivationListener { @Override public void sessionWillPassivate(HttpSessionEvent hse) { // ... hse.getSession(); } @Override 18 | Chapter 2: Servlets public void sessionDidActivate(HttpSessionEvent hse) { // ... } } The HttpSessionAttributeListener is used to listen for attribute changes in the session: public class MyHttpSessionAttributeListener implements HttpSessionAttributeListener { @Override public void attributeAdded(HttpSessionBindingEvent event) { HttpSession session = event.getSession(); //. . . event.getName(); //. . . event.getValue(); } @Override public void attributeRemoved(HttpSessionBindingEvent event) { //. . . } @Override public void attributeReplaced(HttpSessionBindingEvent event) { //. . . } } The HttpSessionBindingListener is used to listen to events when an object is bound to or unbound from a session: public class MyHttpSessionBindingListener implements HttpSessionBindingListener { @Override public void valueBound(HttpSessionBindingEvent event) { HttpSession session = event.getSession(); //. . . event.getName(); //. . . event.getValue(); } @Override public void valueUnbound(HttpSessionBindingEvent event) { //. . . } } The ServletRequestListener listens to the events from resources in that request: @WebListener public class MyRequestListener implements ServletRequestListener { @Override public void requestDestroyed(ServletRequestEvent sre) { Event Listeners | 19 ServletRequest request = sre.getServletRequest(); //. . . } @Override public void requestInitialized(ServletRequestEvent sre) { //. . . } } The ServletRequestAttributeListener is used to listen for attribute changes in the request. There is also AsyncListener, which is used to manage async events such as completed, timed out, or an error. In addition to declaring listeners using @WebListener and web.xml, you can define them programmatically using ServletContext.addListener methods. You can do this from the ServletContainerInitializer.onStartup or ServletContextListener.con textInitialized method. The ServletContainerInitializer.onStartup method is invoked when the applica‐ tion is starting up for the given ServletContext: public class MyInitializer implements ServletContainerInitializer { public void onStartup(Set> clazz, ServletContext context) { context.addListener("org.example.MyContextListener"); } } Asynchronous Support Server resources are valuable and should be used conservatively. Consider a servlet that has to wait for a JDBC connection to be available from the pool, receiving a JMS message or reading a resource from the filesystem. Waiting for a “long-running” process to return completely blocks the thread—waiting, sitting, and doing nothing—which is not an optimal usage of your server resources. This is where the server can be asynchronously processed such that the control (or thread) is returned to the container to perform other tasks while waiting for the long-running process to complete. The request processing continues in the same thread after the response from the long-running process is re‐ turned, or may be dispatched to a new resource from within the long-running process. A typical use case for a long-running process is a chat application. The asynchronous behavior needs to be explicitly enabled on a servlet. You achieve this by adding the asyncSupported attribute on @WebServlet: @WebServlet(urlPatterns="/async", asyncSupported=true) public class MyAsyncServlet extends HttpServlet { 20 | Chapter 2: Servlets //. . . } You can also enable the asynchronous behavior by setting the element to true in web.xml or calling ServletRegistration.setAsyncSupported (true) during programmatic registration. You can then start the asynchronous processing in a separate thread using the startA sync method on the request. This method returns AsyncContext, which represents the execution context of the asynchronous request. Then you can complete the asynchro‐ nous request by calling AsyncContext.complete (explicit) or dispatching to another resource (implicit). The container completes the invocation of the asynchronous request in the latter case. Let’s say the long-running process is implemented: class MyAsyncService implements Runnable { AsyncContext ac; public MyAsyncService(AsyncContext ac) { = ac; } @Override public void run() { //. . . ac.complete(); } } This service may be invoked from the doGet method: @Override protected void doGet(HttpServletRequest request, HttpServletResponse response) { AsyncContext ac = request.startAsync(); ac.addListener(new AsyncListener() { public void onComplete(AsyncEvent event) throws IOException { //. . . } public void onTimeout(AsyncEvent event) throws IOException { //. . . } //. . . }); ScheduledThreadPoolExecutor executor = new ScheduledThreadPoolExecutor(10); executor.execute(new MyAsyncService(ac)); } Asynchronous Support | 21 In this code, the request is put into asynchronous mode. AsyncListener is registered to listen for events when the request processing is complete, has timed out, or resulted in an error. The long-running service is invoked in a separate thread and calls Async Context.complete, signalling the completion of request processing. A request may be dispatched from an asynchronous servlet to synchronous, but the other way around is illegal. The asynchronous behavior is available in the servlet filter as well. Nonblocking I/O Servlet 3.0 allowed asynchronous request processing but only permitted traditional I/O, which restricted the scalability of your applications. In a typical application, Serv letInputStream is read in a while loop: protected void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException { ServletInputStream input = request.getInputStream(); byte[] b = new byte[1024]; int len = -1; while ((len = != -1) { //. . . } } If the incoming data is blocking or streamed slower than the server can read, then the server thread is waiting for that data. The same can happen if the data is written to ServletOutputStream. This restricts the scalability of the Web Container. Nonblocking I/O allows developers to read data as it becomes available or write data when it’s possible to do so. This increases not only the scalability of the Web Container but also the number of connections that can be handled simultaneously. Nonblocking I/O only works with async request processing in Servlets, Filters, and Upgrade Processing. Servlet 3.1 achieves nonblocking I/O by introducing two new interfaces: ReadListen er and WriteListener. These listeners have callback methods that are invoked when the content is available to be read or can be written without blocking. The doGet method needs to be rewritten in this case: AsyncContext context = request.startAsync(); ServletInputStream input = request.getInputStream(); input.setReadListener(new MyReadListener(input, context)); Invoking setXXXListener methods indicates that nonblocking I/O is used instead of traditional. ReadListener has three callback methods: 22 | Chapter 2: Servlets • The onDataAvailable callback method is called whenever data can be read without blocking. • The onAllDataRead callback method is invoked whenever data for the current re‐ quest is completely read. • The onError callback is invoked if there is an error processing the request: @Override public void onDataAvailable() { try { StringBuilder sb = new StringBuilder(); int len = -1; byte b[] = new byte[1024]; while (input.isReady() && (len = != -1) { String data = new String(b, 0, len); } } catch (IOException ex) { //. . . } } @Override public void onAllDataRead() { context.complete(); } @Override public void onError(Throwable t) { t.printStackTrace(); context.complete(); } In this code, the onDataAvailable callback is invoked whenever data can be read without blocking. The ServletInputStream.isReady method is used to check if data can be read without blocking and then the data is read. context.complete is called in onAllDataRead and onError methods to signal the completion of data read. Servle tInputStream.isFinished may be used to check the status of a nonblocking I/O read. At most, one ReadListener can be registered on ServletIntputStream. WriteListener has two callback methods: • The onWritePossible callback method is called whenever data can be written without blocking. • The onError callback is invoked if there is an error processing the response. At most, one WriteListener can be registered on ServletOutputStream. ServletOut putStream.canWrite is a new method to check if data can be written without blocking. Nonblocking I/O | 23 Web Fragments A web fragment is part or all of the web.xml file included in a library or framework JAR’s META-INF directory. If this framework is bundled in the WEB-INF/lib directory, the container will pick up and configure the framework without requiring the developer to do it explicitly. It can include almost all of the elements that can be specified in web.xml. However, the top-level element must be web-fragment and the corresponding file must be called web- fragment.xml. This allows logical partitioning of the web application: MyFilter org.example.MyFilter myInitParam ... MyFilter /* The developer can specify the order in which the resources specified in web.xml and web-fragment.xml need to be loaded. The element in web.xml is used to specify the exact order in which the resources should be loaded, and the element within web-fragment.xml is used to specify relative ordering. The two orders are mutually exclusive, and absolute ordering overrides relative. The absolute ordering contains one or more elements specifying the name of the resources and the order in which they need to be loaded. Specifying allows for the other resources not named in the ordering to be loaded: MyApp MyServlet MyFilter In this code, the resources specified in web.xml are loaded first and followed by MyServ let and MyFilter. Zero or one and elements in are used to specify the resources that need to be loaded before and after the resource named in the web- fragment is loaded: 24 | Chapter 2: Servlets MyFilter MyServlet This code will require the container to load the resource MyFilter after the resource MyServlet (defined elsewhere) is loaded. If web.xml has metadata-complete set to true, then the web-fragment.xml file is not processed. The web.xml file has the highest precedence when resolving conflicts between web.xml and web-fragment.xml. If a web-fragment.xml file does not have an element and web.xml does not have an element, the resources are assumed to not have any ordering dependency. Security Servlets are typically accessed over the Internet, and thus having a security requirement is common. You can specify the servlet security model, including roles, access control, and authentication requirements, using annotations or in web.xml. @ServletSecurity is used to specify security constraints on the servlet implementation class for all methods or a specific doXXX method. The container will enforce that the corresponding doXXX messages can be invoked by users in the specified roles: @WebServlet("/account") @ServletSecurity( value=@HttpConstraint(rolesAllowed = {"R1"}), httpMethodConstraints={ @HttpMethodConstraint(value="GET", rolesAllowed="R2"), @HttpMethodConstraint(value="POST", rolesAllowed={"R3", "R4"}) } ) public class AccountServlet extends javax.servlet.http.HttpServlet { //. . . } In this code, @HttpMethodConstraint is used to specify that the doGet method can be invoked by users in the R2 role, and the doPost method can be invoked by users in the R3 and R4 roles. The @HttpConstraint specifies that all other methods can be invoked by users in the role R1. The roles are mapped to security principals or groups in the container. Security | 25 The security constraints can also be specified using the ele‐ ment in web.xml. Within it, a element is used to specify constraints on HTTP operations and web resources, is used to specify the roles permitted to access the resource, and indi‐ cates how data between the client and server should be protected by the subelement : /account/* GET manager INTEGRITY This deployment descriptor requires that only the GET method at the /account/* URL is protected. This method can only be accessed by a user in the manager role with a requirement for content integrity. All HTTP methods other than GET are unprotected. If HTTP methods are not enumerated within a security-constraint, the protections defined by the constraint apply to the complete set of HTTP (extension) methods: /account/* . . . In this code, all HTTP methods at the /account/* URL are protected. Servlet 3.1 defines uncovered HTTP protocol methods as the methods that are not listed in the and if at least one is listed in : /account/* GET . . . 26 | Chapter 2: Servlets In this code fragment, only the HTTP GET method is protected and all other HTTP protocols methods such as POST and PUT are uncovered. The element can be used to specify the list of HTTP methods not protected by the constraint: /account/* GET . . . In this code, only the HTTP GET method is not protected and all other HTTP protocol methods are protected. The element, a new element in Servlet 3.1, can be used to deny an HTTP method request for an uncovered HTTP method. The denied request is returned with a 403 (SC_FORBIDDEN) status code: /account/* GET . . . In this code, the element ensures that HTTP GET is called with the required security credentials, and all other HTTP methods are denied with a 403 status code. @RolesAllowed, @DenyAll, @PermitAll, and @TransportProtected provide an alter‐ native set of annotations to specify security roles on a particular resource or a method of the resource: @RolesAllowed("R2") protected void doGet(HttpServletRequest request, HttpServletResponse response) { //. . . } If an annotation is specified on both the class and the method level, the one specified on the method overrides the one specified on the class. Servlet 3.1 introduces two new predefined roles: Security | 27 • * maps to any defined role. • ** maps to any authenticated user independent of the role. This allows you to specify security constraints at a higher level than a particular role. At most, one of @RolesAllowed, @DenyAll, or @PermitAll may be specified on a target. The @TransportProtected annotation may occur in combination with either the @Ro lesAllowed or @PermitAll annotations. The servlets can be configured for HTTP Basic, HTTP Digest, HTTPS Client, and form- based authentication:
This code shows how form-based authentication can be achieved. The login form must contain fields for entering a username and a password. These fields must be named j_username and j_password, respectively. The action of the form is always j_securi ty_check. Servlet 3.1 requires autocomplete="off" on the password form field, further strength‐ ening the security of servlet-based forms. The HttpServletRequest also provides programmatic security with the login, log out, and authenticate methods. The login method validates the provided username and password in the password validation realm (specific to a container) configured for the ServletContext. This en‐ sures that the getUserPrincipal, getRemoteUser, and getAuthType methods return valid values. The login method can be used as a replacement for form-based login. The authenticate method uses the container login mechanism configured for the ServletContext to authenticate the user making this request. Resource Packaging You can access resources bundled in the .war file using the ServletContext.getRe source and .getResourceAsStream methods. The resource path is specified as a string with a leading “/.” This path is resolved relative to the root of the context or relative to the META-INF/resources directory of the JAR files bundled in the WEB-INF/lib directory: myApplication.war WEB-INF 28 | Chapter 2: Servlets lib library.jar library.jar has the following structure: library.jar MyClass1.class MyClass2.class stylesheets common.css images header.png footer.png Normally, if stylesheets and image directories need to be accessed in the servlet, you need to manually extract them in the root of the web application. Servlet 3.0 allows the library to package the resources in the META-INF/resources directory: library.jar MyClass1.class MyClass2.class META-INF resources stylesheets common.css images header.png footer.png In this case, the resources need not be extracted in the root of the application and can be accessed directly instead. This allows resources from third-party JARs bundled in META-INF/resources to be accessed directly instead of manually extracted. The application always looks for resources in the root before scanning through the JARs bundled in the WEB-INF/lib directory. The order in which it scans JAR files in the WEB- INF/lib directory is undefined. Error Mapping An HTTP error code or an exception thrown by a serlvet can be mapped to a resource bundled with the application to customize the appearance of content when a servlet generates an error. This allows fine-grained mapping of errors from your web applica‐ tion to custom pages. These pages are defined via : 404 /error-404.jsp Error Mapping | 29 Adding the preceding fragment to web.xml will display the /error-404.jsp page to a client attempting to access a nonexistent resource. You can easily implement this mapping for other HTTP status codes as well by adding other elements. The element is used to map an exception thrown by a servlet to a resource in the web application: org.example.MyException /error.jsp Adding the preceding fragment to web.xml will display the /error.jsp page to the client if the servlet throws the org.example.MyException exception. You can easily imple‐ ment this mapping for other exceptions as well by adding other elements. The declaration must be unique for each class name and HTTP status code. Handling Multipart Requests @MultipartConfig may be specified on a servlet, indicating that it expects a request of type multipart/form-data. The HttpServletRequest.getParts and .getPart meth‐ ods then make the various parts of the multipart request available: @WebServlet(urlPatterns = {"/FileUploadServlet"}) @MultipartConfig(location="/tmp") public class FileUploadServlet extends HttpServlet { @Override protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { for (Part part : request.getParts()) { part.write("myFile"); } } } In this code: • @MultipartConfig is specified on the class, indicating that the doPost method will receive a request of type multipart/form-data. • The location attribute is used to specify the directory location where the files are stored. • The getParts method provides a Collection of parts for this multipart request. • part.write is used to write this uploaded part to disk. 30 | Chapter 2: Servlets Servlet 3.1 adds a new method, Part.getSubmittedFileName, to get the filename speci‐ fied by the client. This servlet can be invoked from a JSP page:

In this code, the form is POSTed to FileUploadServlet with encoding multipart/form- data. Upgrade Processing Section 14.42 of HTTP 1.1 (RFC 2616) defines an upgrade mechanism that allows you to transition from HTTP 1.1 to some other, incompatible protocol. The capabilities and nature of the application-layer communication after the protocol change are entirely dependent upon the new protocol chosen. After an upgrade is negotiated between the client and the server, the subsequent requests use the newly chosen protocol for message exchanges. A typical example is how the WebSocket protocol is upgraded from HTTP, as described in the Opening Handshake section of RFC 6455. The servlet container provides an HTTP upgrade mechanism. However, the servlet container itself does not have any knowledge about the upgraded protocol. The protocol processing is encapsulated in the HttpUpgradeHandler. Data reading or writing between the servlet container and the HttpUpgradeHandler is in byte streams. The decision to upgrade is made in the Servlet.service method. Upgrading is achieved by adding a new method, HttpServletRequest.upgrade, and two new inter‐ faces, javax.servlet.http.HttpUpgradeHandler and javax.servlet.http.WebCon nection: if (request.getHeader("Upgrade").equals("echo")) { response.setStatus(HttpServletResponse.SC_SWITCHING_PROTOCOLS); response.setHeader("Connection", "Upgrade"); response.setHeader("Upgrade", "echo"); request.upgrade(MyProtocolHandler.class); System.out.println("Request upgraded to MyProtocolHandler"); } The request looks for the Upgrade header and makes a decision based upon its value. In this case, the connection is upgraded if the Upgrade header is equal to echo. The correct response status and headers are set. The upgrade method is called on HttpServ letRequest by passing an instance of HttpUpgradeHandler. Upgrade Processing | 31 After exiting the service method of the servlet, the servlet container completes the processing of all filters and marks the connection to be handled by the instance of HttpUpgradeHandler: public class MyProtocolHandler implements HttpUpgradeHandler { @Override public void init(WebConnection wc) { //. . . } @Override public void destroy() { //. . . } } This code shows an implementation of HttpUpgradeHandler. The servlet container calls the HttpUpgradeHandler’s init method, passing a WebConnection to allow the protocol handler access to the data streams. When the upgrade processing is done, HttpUpgra deHandler.destroy is invoked. The servlet filters only process the initial HTTP request and response. They are not involved in subsequent communications. 32 | Chapter 2: Servlets CHAPTER 3 JavaServer Faces JavaServer Faces (JSF) is defined as JSR 344, and the complete specification can be downloaded. JavaServer Faces is a server-side user interface (UI) framework for Java-based web ap‐ plications. JSF allows you to: • Create a web page with a set of reusable UI components following the Model-View- Controller (MVC) design pattern. • Bind components to a server-side model. This allows a two-way migration of ap‐ plication data with the UI. • Handle page navigation in response to UI events and model interactions. • Manage UI component state across server requests. • Provide a simple model for wiring client-generated events to server-side application code. • Easily build and reuse custom UI components. A JSF application consists of: • A set of web pages in which the UI components are laid out. • A set of managed beans. One set of beans binds components to a server-side model (typically CDI beans) and another set acts as controller (typically EJB or CDI beans). • An optional deployment descriptor, web.xml. • An optional configuration file, faces-config.xml. • An optional set of custom objects such as converters and listeners, created by the application developer. 33 Facelets Facelets is the view declaration language (aka view handler) for JSF. It is the replacement for JSP, which is now retained only for backward compatibility. New features introduced in version 2 of the JSF specification, such as composite components and Ajax, are only exposed to page authors using facelets. Key benefits of facelets include a powerful tem‐ plating system, reuse and ease of development, better error reporting (including line numbers), and designer-friendliness. Facelets pages are authored using XHTML 1.0 and Cascading Style Sheets (CSS). An XHTML 1.0 document is a reformulation of an HTML 4 document following the rules of XML 1.0. The pages must conform with the XHTML-1.0-Transitional DTD. You can define a simple Facelets page using XHTML: My Facelet Page Title Hello from Facelets In this code, an XML prologue is followed by a document type declaration (DTD). The root element of the page is html in the namespace An XML namespace is declared for the tag library used in the web page. Facelets HTML tags (those beginning with h:) and regular HTML tags are used to add components. Table 3-1 shows the standard set of tag libraries supported by Facelets. Table 3-1. Standard tag libraries supported by Facelets Prefix URI Examples h h:head, h:inputText f f:facet, f:actionListener c c:forEach, c:if fn fn:toUpperCase, fn:contains ui ui:component, ui:insert By convention, web pages built with XHTML have a .xhtml extension. 34 | Chapter 3: JavaServer Faces Facelets provides Expression Language (EL) integration. This allows two-way data binding between the backing beans and the UI: Hello from Facelets, my name is #{name.value}! In this code, #{name} is an EL that refers to the value field of a request-scoped CDI bean: @Named @RequestScoped public class Name { private String value; //. . . } It’s important to add @Named on a CDI bean to enable its injection in an EL. In JSF 2.2, @javax.faces.bean.ManagedBean is targeted for deprecation in a future version, so it is highly recommended that you use @Named. JSF 2.2 also introduces a new CDI scope: javax.faces.view.ViewScoped. Specifying this annotation on a bean binds it with the current view. javax.faces.bean.ViewSco ped is targeted for deprecation in a future version, so it is strongly recommended that you use the newly introduced scope. Similarly, an EJB can be injected in an EL expression: @Stateless @Named public class CustomerSessionBean { public List getCustomerNames() { //. . . } } This is a stateless session bean and has a business method that returns a list of customer names. @Named marks it for injection in an EL. It can be used in Facelets EL: #{c.value} In this code, the list of customer names returned is displayed in a table. Notice how the getCustomerNames method is available as a property in the EL. Facelets also provides compile-time EL validation. In addition, Facelets provides a powerful templating system that allows you to provide a consistent look and feel across multiple pages in a web application. A base page, called a template, is created via Facelets templating tags. This page defines a default structure for the page, including placeholders for the content that will be defined in the pages Facelets | 35 using the template. A template client page uses the template and provides actual content for the placeholders defined in the template. Table 3-2 lists some of the common tags used in the template and template client pages. Table 3-2. Common Facelets tags for a template Tag Description ui:composition Defines a page layout that optionally uses a template. If the template attribute is used, the children of this tag define the template layout. If not, it’s just a group of elements—a composition—that can be inserted anywhere. Content outside of this tag is ignored. ui:insert Used in a template page and defines the placeholder for inserting content into a template. A matching ui:define tag in the template client page replaces the content. ui:define Used in a template client page; defines content that replaces the content defined in a template with a matching ui:insert tag. ui:component Inserts a new UI component into the JSF component tree. Any component or content fragment outside this tag is ignored. ui:fragment Similar to ui:component, but does not disregard content outside this tag. ui:include Includes the document pointed to by the src attribute as part of the current Facelets page. A template page looks like:

Facelets are Cool!

Powered by GlassFish
In this code, the page defines the structure using
and CSS (not shown here). ui:insert defines the content that gets replaced by a template client page. A template client page looks like: 36 | Chapter 3: JavaServer Faces #{c.value} In this code, ui:insert with top and bottom names is not defined, so those sections are used from the template page. There is a ui:define element with a name matching the ui:insert element in the template, so the contents are replaced. Resource Handling JSF defines a standard way of handling resources, such as images, CSS, or JavaScript files. These resources are required by a component to be rendered properly. Such resources can be packaged in the /resources directory in the web application or in /META-INF/resources in the classpath. The resources may also be localized, ver‐ sioned, and collected into libraries. A resource can be referenced in EL: click here In this code, header.jpg is bundled in the standard resources directory. If a resource is bundled in a library corp (a folder at the location where resources are packaged), then you can access it using the library attribute: JavaScript may be included: In this code, myScript.js is a JavaScript resource packaged in the scripts directory in the standard resources directory. A CSS stylesheet can be included: Resource Handling | 37 The ResourceHandler API provides a programmatic way to serve these resources as well. Composite Components Using features of Facelets and resource handling, JSF defines a composite component as a component that consists of one or more JSF components defined in a Facelets markup file. This .xhtml file resides inside of a resource library. This allows you to create a reusable component from an arbitrary region of a page. The composite component is defined in the defining page and used in the using page. The defining page defines the metadata (or parameters) using and the implementation using , where cc is the prefix for the http:// namespace. Future versions of the JSF specification may relax the requirement to specify metadata, as it can be derived from the imple‐ mentation itself. You can define a composite component using JSF 1.2 as well, but it requires a much deeper understanding of the JSF life cycle and also authoring multiple files. JSF2 really simplifies the authoring of composite components using just an XHTML file. Let’s say a Facelet has the following code fragment to display a login form: This code renders a table with two rows and three columns, as shown in Figure 3-1. Figure 3-1. JSF Facelets page output in a browser 38 | Chapter 3: JavaServer Faces The first column displays a prompt for the field to be entered; the second column dis‐ plays an input text box where the data can be entered; and the third column (which is empty to begin with) is for displaying a message for the corresponding field. The first row binds the input value to the field, and the second row binds the input value to the User.password field. There is also a command button, and clicking the button invokes the register method of the UserService bean. If this login form is to be displayed in multiple pages, then instead of repeating this code everywhere, it is beneficial to convert this fragment into a composite component. This requires the code fragment to be copied to an .xhtml file, and the file itself is copied in a library in the standard resources directory. Via convention-over-configuration, the fragment is then automatically assigned a namespace and a tag name. If the fragment shown earlier is copied to login.xhtml in the resources/mycomp directory, the defining page looks like: In this code, cc:interface defines metadata that describes the characteristics of the component, such as supported attributes, facets, and attach points for event listeners. cc:implementation contains the markup substituted for the composite component. The namespace of the composite component is constructed by concatenating http:// and mycomp. The tag name is the filename without the .xhtml suffix in the using page: Composite Components | 39 Let’s say that the code fragment needs to pass different value expressions (instead of #{}) and invoke a different method (instead of #{userService.register}) when the submit button is clicked in a different using page. The defining page can then pass the values: In this code, all the parameters are explicitly specified in cc:interface for clarity. The third parameter has a targets attribute referring to ccForm:loginButton. In cc:implementation: • The h:form has an id attribute. This is required so that the button within the form can be explicitly referenced. • h:inputText is now using #{} instead of #{}. #{cc.attrs} is a default EL expression that is available for composite component authors and 40 | Chapter 3: JavaServer Faces provides access to attributes of the current composite component. In this case, #{cc.attrs} has name and password defined as attributes. • actionListener is an attach point for an event listener. It is defined as a method- signature and describes the signature of the method. • h:commandButton has an id attribute so that it can be clearly identified within the h:form. The user, password, and actionListener are then passed as required attributes in the using page: Now the using page can pass different backing beans, and different business methods can be invoked when the submit button is clicked. Overall, the composite component provides the following benefits: • Follows the Don’t Repeat Yourself (DRY) design pattern and allows you to keep code that can be repeated at multiple places in a single file. • Allows developers to author new components without any Java code or XML configuration. Request Processing Life-Cycle Phases JSF defines standard request processing life-cycle phases. Application developers don’t necessarily need to know the details of the life cycle, but it helps those who need to know information such as when validations, conversions, and events are usually handled and what they can do to change how and when they are handled. A JSF page is represented by a tree of UI components, called a view. When a client makes a request for the page, the life cycle starts. During the life cycle, the JavaServer Faces implementation must build the view while considering the state saved from a previous submission of the page. When the client submits a page, the JavaServer Faces imple‐ mentation must perform several tasks, such as validating the data input of components in the view, converting input data to types specified on the server side, and binding data to the backing beans. The JavaServer Faces implementation performs all these tasks as a series of steps in the life cycle. The different components of the application go through the following well-defined re‐ quest processing life-cycle phases: Request Processing Life-Cycle Phases | 41 Restore view Restores and creates a server-side component tree to represent the UI information from a client. If the request is made to a URL for the first time, then a new View object is created and rendered to the client. This view is also stored in the current FacesContext instance. If the view state is already found in FacesContext, then it is restored and displayed. Any custom converters, validators, renderers, if attached for the UI components, are restored in this phase. If the UI component values are directly mapped to the property defined in a managed bean, then the value for the property is restored and it is associated with the view. Most of the work is handled by the storeView method. Apply request values This phase updates the server-side components with request parameters, headers, cookies, and so on from the client. More specifically, the UIComponent.processDecodes method is called on all com‐ ponents. The outcome of this phase may either end in the process validations phase or the render response phase. If any of the conversions or the validations fail, then the current processing is terminated and the control directly goes to the render response for rendering the conversion or the validation errors to the client. Process validations This phase will process any validations and data type conversions configured for UIComponents. In this phase, the UIComponent.processValidators method is called on all com‐ ponents. If any conversion or validation error happens here, then the current pro‐ cess is terminated and the control is directed to the render response phase for re‐ porting any errors. Update model values Reaching this phase means that the request values are syntactically valid. The values from UIComponents are synchronized with the model objects, which are usually backing beans. In this phase, the UIComponent.processUpdates method is called on all components. Setting the request value to the model object may also result in events being queued and fired. Invoke application Invokes application logic and performs navigation processing. 42 | Chapter 3: JavaServer Faces All the listeners that are registered for the UIComponents are invoked. For example, all action components, like the command button or the hyperlink, have default action listeners that are invoked in this phase. Render response Renders the response back to the client application. Before rendering the response, the application stores the state of View in the cache by calling the UIViewRoot.saveState method. Ajax JSF provides native support for adding Ajax capabilities to web pages. It allows partial view processing, where only some components from the view are used for processing the response. It also enables partial page rendering, where selective components from the page, as opposed to the complete page, are rendered. There are two ways this support can be enabled: • Programmatically using JavaScript resources • Declaratively using f:ajax Programmatic Ajax integration is enabled through the resource handling mechanism. jsf.js is a predefined resource in the javax.faces library. This resource contains the JavaScript API that facilitates Ajax interaction with JSF pages. You can make it available in pages using the outputScript tag: You can also make an asynchronous request to the server: Ajax | 43 In this code: • Two input text fields accept the username and password, and the third output field displays the status (whether the user is logged in or not). • The form has prependId set to false to ensure that the id of each element is pre‐ served as mentioned in the form. Otherwise, JSF prepends the form’s id to the id of its children. • The command button has an actionListener identifying the method in the back‐ ing bean to be invoked when the button is clicked. Instead of the usual response rendering and displaying a different page, jsf.ajax.request sends an asynchro‐ nous request to the server. This request is made on the command button’s on click event. execute and render provide a space-separated identifier of the com‐ ponents. execute is the list of input components whose bean setters are invoked, and render is the list of components that needs to be rendered after the asynchro‐ nous response is received. The ability to process only part of the view (name and password elements in this case) is referred to as partial view processing. Similarly, rendering only part of the output page (the status element in this case) is referred to as partial output rendering. Table 3-3 lists the possible values of the render attribute. Table 3-3. Values for the render attribute in f:ajax Value Description @all All components on the page @none No components on the page; this is the default value @this Element that triggered the request @form All components within the enclosing form IDs Space-separated identifiers of the components EL expression EL expression that resolves to a collection of strings The execute attribute takes a similar set of values, but the default value for the execute attribute is @this. • The User bean has fields, setters/getters, and a simple business method: @Named @SessionScoped public class User implements Serializable { private String name; private String password; private String status; . . . 44 | Chapter 3: JavaServer Faces public void login(ActionEvent evt) { if (name.equals(password)) status = "Login successful"; else status = "Login failed"; } } Note the signature of the login method. It must return void and take javax. faces.event.ActionEvent as the only parameter. Declarative Ajax integration is enabled via f:ajax. This tag may be nested within a single component (enabling Ajax for a single component), or it may be “wrapped” around multiple components (enabling Ajax for many components). The preceding code can be updated to use this style of Ajax: In this code, we use f:ajax to specify the list of input elements using the execute attribute, and the output elements to be rendered using the render attribute. By default, if f:ajax is nested within a single component and no event is specified, the asynchro‐ nous request is fired based upon the default event for the parent component (the on click event in the case of a command button). A delay attribute may be specified on the f:ajax tag. This attribute takes a value in milliseconds. If multiple requests are issued before the delay time elapses, then only the most recent request is sent and all others are discarded. . . . This code fragment sets the delay to 200 milliseconds. The default value is 300 milli‐ seconds, but you could also specify the special value of none to disable this mechanism. The f:ajax tag may be wrapped around multiple components: Ajax | 45 In this code, f:ajax has a listener attribute and the corresponding Java method: public void checkFormat(AjaxBehaviorEvent evt) { //. . . } This listener method is invoked for the default event for the child elements (the value Change event for h:inputText, in this case). You can specify additional Ajax function‐ ality on the child elements using a nested f:ajax. HTTP GET JSF provides support for mapping URL parameters in HTTP GET requests to an EL. It also provides support to generate GET-friendly URLs. View parameters can be used to map URL parameters in GET requests to an EL. You can do so by adding the following fragment to a Facelets page: Accessing a web application at index.xhtml?name=jack will: • Get the request parameter by the name name. • Convert and validate if necessary. This is achieved by way of a nested f:convert er and f:validator, just like with any h:inputText, and can be done as shown: • If successful, bind it to #{}. You can postprocess the view parameters before the page is rendered using f:event: In this code, the method identified by #{user.process} can be used to perform any initialization required prior to rendering the page. 46 | Chapter 3: JavaServer Faces You can generate GET-friendly URLs using h:link and h:button. You specify the desired Facelets page instead of manually constructing the URL: This is translated to the following HTML tag: Login View parameters can be easily specified: In this code, if #{} is bound to “Jack,” then this fragment is translated to the following HTML tag: Login Similarly, h:button can be used to specify the outcome: This code will generate the following HTML tag: Server and Client Extension Points Converters, validators, and listeners are server-side attached objects that add more functionality to the components on a page. Behaviors are client-side extension points that can enhance a component’s rendered content with behavior-defined scripts. A converter converts the data entered in a component from one format to another (e.g., string to number). JSF provides several built-in converters such as f:convertNumber and f:convertDateTime. They can be applied to any editable component: Age: In this code, the text entered in the text box will be converted to an integer if possible. An error message is thrown if the text cannot be converted. A custom converter can be easily created: Server and Client Extension Points | 47 @FacesConverter("myConverter") public class MyConverter implements Converter { @Override public Object getAsObject( FacesContext context, UIComponent component, String value) { //. . . } @Override public String getAsString( FacesContext context, UIComponent component, Object value) { //. . . } } In this code, the methods getAsObject and getAsString perform object-to-string and string-to-object conversions between model data objects and a string representation of those objects that is suitable for rendering. The POJO implements the Converter in‐ terface and is also marked with @FacesConverter. This converter can then be used in a JSF page: The value attribute of @FacesConverter must match the value of the converterId attribute here. A validator is used to validate data that is received from the input components. JSF provides several built-in validators such as f:validateLength and f:validateDou bleRange. These validators can be applied to any editable component: In this code, the length of the entered text is validated to be between 1 and 10 characters. An error message is thrown if the length is outside the specified range. A custom validator can be easily created: @FacesValidator("nameValidator") public class NameValidator implements Validator { @Override public void validate( FacesContext context, UIComponent component, 48 | Chapter 3: JavaServer Faces Object value) throws ValidatorException { //. . . } } In this code, the method validate returns if the value is successfully validated. Other‐ wise, a ValidatorException is thrown. This validator can be applied to any editable component: The value attribute of @FacesValidator must match the value of the id attribute of f:validator here. JSF also provides built-in integration with constraints defined using Bean Validation. Other than placing annotation constraints on the bean, no additional work is required by the developer. Any error message because of constraint violation is automatically converted to a FacesMessage and displayed to the end user. f:validateBean may be used to specify validationGroups to indicate which validation groups should be taken into consideration when validating a particular component. This is explained in detail in Chapter 11. A listener listens for events on a component. The event can be a change of value, a click of a button, a click on a link, or something else. A listener can be a method in a managed bean or a class by itself. A ValueChangeListener can be registered on any editable component: In this code, the nameUpdated method in the User bean is called when the associated form is submitted. You can create a class-level listener by implementing the ValueChan geListener interface and specify it in the page using the f:valueChangeListener tag. Unlike converters, validators, and listeners, a behavior enhances the client-side func‐ tionality of a component by declaratively attaching scripts to it. For example, f:ajax is defined as a client-side behavior. Client-side behavior also allows you to perform client- side validation and client-side logging, show tooltips, and other similar functionality. You can define custom behaviors by extending ClientBehaviorBase and marking with @FacesBehavior. Server and Client Extension Points | 49 Validating Data In addition to using built-in and creating custom JSF validators, you can specify con‐ straints defined on a backing bean using Bean Validation. Consider a simple web application that has one page with several text fields inside of a form: Name: Age: Zip: Assume that every text field is bound to a managed bean property that has at least one Bean Validation constraint annotation attached to it: @Named @SessionScoped public class MyBean implements Serializable { @Size(min = 3, message = "At least 3 characters") private String name; @Min(18) @Max(25) private int age; @Pattern(regexp = "[0-9]{5}") private String zip; //. . . } Every h:inputText element that is backed by a UIInput component has an instance of Validator with id javax.faces.Bean attached to it. The validate method of this Validator is called for the user-specified validation constraints during the process val‐ idations phase. The javax.faces.Bean standard validator also ensures that every ConstraintViola tion that resulted in attempting to validate the model data is wrapped in a FacesMes sage and added to the FacesContext as with every other kind of validator. This message is then displayed to the user as other validator messages are handled. One or more validation groups can be associated with an input tag: Name: 50 | Chapter 3: JavaServer Faces which can also be used to create validation across multiple pages. The validation groups can also be associated with a group of input tags: In this code, the constraints are validated for the fields identified by #{} and #{person.age}. Navigation Rules JSF defines implicit and explicit navigation rules. Implicit navigation rules look for the outcome of an action (e.g., a click on a link or a button). If a Facelets page matching the action outcome is found, that page is then rendered: In this code, clicking the button will render the page login.xhtml in the same directory. You can specify explicit navigation using in faces-config.xml, and you can specify conditional navigation using : /index.xhtml success /login.xhtml #{user.isPremium} In this code, the page navigation from index.xhtml to login.xhtml only occurs if the user is a premium customer. Faces Flow JSF 2.2 introduces Faces Flow. This feature borrows core concepts from ADF Task Flows, Spring Web Flow, and Apache MyFaces CODI to provide a modular approach for defining control flow in an application and standardizes them as part of JSF 2.2. Faces Flow provides an encapsulation of related pages and corresponding backing beans as a module. This module has well-defined entry and exit points assigned by the appli‐ cation developer. Usually the objects in a faces flow are designed to allow the user to Navigation Rules | 51 accomplish a task that requires input over a number of different views. An application thus becomes a collection of flows instead of just views. Imagine a multipage shopping cart with one page for selecting the items, a second page for choosing shipping options, a third page for entering credit card details, and a fourth page for confirming the order. You can use managed beans to capture the data, session scope variables to pass information between pages, button clicks to invoke the business logic in backing EJBs, and (conditional) navigation rules to go from one page to another. There are a few issues with this approach: • This flow of sequence will typically be part of a bigger application. This application, typically with several pages, is one large flow and everything has global visibility with no logical partitioning. • The flow of pages or views cannot be encapsulated as a logical unit and thus cannot be reused—that is, incorporated into another bigger application or flow easily. • The same flow cannot be opened in multiple windows because session scoped vari‐ ables are used to pass information between pages. CDI defines @ConversationSco ped, but that is only part of the solution. • A request-based scope is for a particular request. A session-based scope is more than a request scope, but becomes invalid after the browser is closed. We require a scope of something in between that can span multiple pages per the application logic. This is what is missing. • The lowest logical granularity is a page. The only way to invoke application logic is to tie it to a UI component activated by the user in a page. Business logic cannot be invoked without any user-initiated action. Faces Flow provides a solution to these issues: • The application is broken into a series of modular flows that can call one another. • The flow of pages can be packaged as a module that can be reused within the same or an entirely different application. • Shared memory scope (for example, flow scope) enables data to be passed between views within the task flow. • A new CDI scope, @FlowScoped, can be specified on a bean. This allows automatic activation/passivation of the bean as the scope is entered/exited. • Business logic can be invoked from anywhere in the page based upon the flow definition. The flow of application is no longer restricted to flow between pages but instead is defined as flow between “nodes.” There are five different types of nodes: 52 | Chapter 3: JavaServer Faces View Any JSF page in the application. Method call Invoke application logic from the flow graph via an EL. Switch Navigation decisions in the flow graph based on Boolean EL. Flow call Call another flow with parameters and receive return values. Flow return Return to the calling flow. These nodes define the entry and exit points of a flow. The newly introduced CDI scope @FlowScoped defines the scope of a bean in the speci‐ fied flow. This enables automatic activation/passivation of the bean when the scope is entered/exited: @FlowScoped("flow1") public class MyFlow1Bean { String address; String creditCard; //. . . } In this code, the bean has two flow-scoped variables: address and creditCard. The bean is defined for the flow flow1. A new EL object for flow storage, #{flowScope}, is also introduced. This maps to facesContext.getApplication().getFlowHandler().getCurrentFlowScope(): value: In this code, the value entered in the text box is bound to #{flowScope.value}. This EL expression can be used in other pages in the flow to access the value. You can define flows declaratively using , or programmatically us‐ ing the fluent FlowBuilder API. The two mechanisms are mutually exclusive. Flows can be packaged in JAR files or in directories. JAR packaging requires flows to be explicitly declared in META-INF/faces-config.xml in the JAR file. Flow nodes are pack‐ aged in META-INF/flows/ where is a JAR directory entry whose name is identical to that of a flow id in the corresponding FlowDefinition classes. If @FlowScoped beans and a flow defined via FlowBuilder are packaged in the JAR file, they must be accompanied by META-INF/beans.xml: META-INF/faces-config.xml META-INF/flows/flow1/entry.xhtml Faces Flow | 53 META-INF/flows/flow1/next.xhtml META-INF/flows/flow1/end.xhtml META-INF/flows/flow2/start.xhtml META-INF/flows/flow2/next.xhtml META-INF/flows/flow2/end.xhtml META-INF/beans.xml org/glassfish/sample/MyFlow1Bean.class org/glassfish/sample/MyFlow2Bean.class org/glassfish/sample/MyFlow1Defintion.class org/glassfish/sample/MyFlow2Defintion.class In this JAR packaging: • There are two flows, flow1 and flow2. • META-INF/beans.xml is required to enable CDI. It may be implicitly enabled if bean-defining annotations are used in the archive. • MyFlow1Bean and MyFlow2Bean are the flow-scoped beans. These beans are used to store any flow-local data. • MyFlow1Definition defines the entry and exit points of a flow, inbound parameter name and value coming from another flow, outbound parameter name and value for another flow, and navigation to other nodes: public class MyFlow1Definition { @Produces @FlowDefinition public Flow defineFlow(@FlowBuilderParameter FlowBuilder flowBuilder) { String flowId = "flow1";"unique", flowId); flowBuilder.viewNode(flowId, "/" + flowId + "/" + flowId + ".xhtml") .markAsStartNode(); flowBuilder.returnNode("goHome"). fromOutcome("#{flow1Bean.homeValue}"); flowBuilder.inboundParameter("param1FromFlow2", "#{flowScope.param1Value}"); flowBuilder.flowCallNode("call2").flowReference("", "flow2"). outboundParameter("param1FromFlow1", "param1 flow1 value"); return flowBuilder.getFlow(); } } In this code: — Flow is defined programmatically via the CDI producer. @FlowDefinition is a class-level annotation that allows the flow to be defined via the fluent Flow Builder API. 54 | Chapter 3: JavaServer Faces — A FlowBuilder instance is injected as a parameter via the @FlowBuilderPara meter and is used to define the flow. — flow1 is defined as the flow identifier and flow1.xhtml is marked as the starting node. — The returnNode method is used to define an exit point from the flow. In this case, the flow is directed to /index for the action goHome. The node value can be specified as an EL expression as well—for example, “may be bound to a bean.” — Named inbound parameters are named parameters from another flow and are defined via the inboundParameter method. The method’s value is populated elsewhere with a corresponding outboundParameter element. The value is stor‐ ed in the flow local storage via #{flowScope}. — flowCallNode method is used to define an exit point from the flow. In this case, flow2 flow is called. A named outbound parameter and its value are set via the outboundParameter method. Similarly MyFlow2Definition class defines flow2. Flows packaged in directories use convention-over-configuration. The conventions are: • Every View Declaration Language file, defined by an .xhtml page, in that directory is a view node of that flow. • The start node of the flow is the view whose name is the same as the name of the flow. • Navigation among any of the views in the directory is considered to be within the flow. • Navigation to a view outside of that directory is considered to be an exit of the flow. • An optional -flow.xml file represents the flow definition. The rules in this file override the conventions just described: flow1/flow1.xhtml flow1/flow1a.xhtml flow1/flow1b.xhtml flow2/flow2-flow.xml flow2/flow2.xhtml flow2/flow2a.xhtml flow2/flow2b.xhtml WEB-INF/... Following the conventions just defined, in this directory: • flow1.xhtml is the starting node of flow flow1, and flow1a and flow1b are two other nodes in the same flow. Faces Flow | 55 • flow2 is the starting node of flow flow2, and flow2a and flow2b are two other nodes in the same flow. flow2/flow2-flow.xml defines declarative navigation of the flow flow2. It defines the entry and exit points of a flow, inbound parameter name and value coming from another flow, outbound parameter name and value for another flow, and navigation to other nodes: /index param1FromFlow1 #{flowScope.param1Value} flow2 param1FromFlow1 param1 flow1 value In this fragment: — defines flow for flow1, identified by the id attribute. — defines an exit point from the flow. In this case, the flow is di‐ rected to /index for the action goHome. The node value can be specified as an EL expression—for example, “may be bound to a bean.” — A named inbound parameter is defined via . Its value is populated elsewhere with a corresponding element. The value is stored in the flow local storage via #{flowScope}. — defines an exit point from the flow. In this case, flow2 flow is called. A named outbound parameter and its value are set via . 56 | Chapter 3: JavaServer Faces • The WEB-INF directory will contain other resources required by the pages, such as backing beans. Resource Library Contracts JSF 2 introduced Facelets as the default View Declaration Language. Facelets allows you to create templates using XHTML and CSS that can then be used to provide a consistent look and feel across different pages of an application. JSF 2.2 defines Resource Library Contracts, a library of templates and associated resources that can be applied to an entire application in a reusable and interchangeable manner. A configurable set of views in the application will be able to declare themselves as template-clients of any template in the resource library contract. Resource library contracts reside in the contracts directory of the web application’s root: index.xhtml new/index.xhtml contracts/blue/layout.css contracts/blue/template.xhtml contracts/blue/footer.png contracts/red contracts/red/layout.css contracts/red/template.xhtml contracts/red/logo.png WEB-INF/faces-config.xml In this code: • The application also has two pages: index.xhtml and new/index.xhtml. These are template client pages. • All contracts reside in the contracts directory of the WAR. All templates and re‐ sources for a contract are in their own directory. For example, the preceding struc‐ ture has two defined contracts, blue and red. • Each contract has a template.xhtml file, a CSS, and an image. Each template is called as a declared template. In the template, it is recommended that you refer to the stylesheets using h:outputStylesheet so that they are resolved appropriately. • The template.xhtml file has tags called as declared insertion points. • CSS, images, and other resources bundled in the directory are declared resources. • The declared template, declared insertion points, and declared resources together define the resource library contract. A template client needs to know the value of all three in order to use the contract. The client pages will use the contract by re‐ ferring to the template: Resource Library Contracts | 57 . . . • WEB-INF/faces-config.xml defines the usage of the contract: /new/* blue * red A contract is applied based upon the URL pattern invoked. Based upon the con‐ figuration specified here, the red contract will be applied to faces/index.xhtml and the blue contract will be applied to faces/new/index.xhtml. The contracts can be packaged in the META-INF/contracts entry of a JAR file. Each contract in the JAR file must have a marker file. The filename is given by the value of the symbolic constant javax.faces.application.ResourceHandler.RESOURCE_CON TRACT_XML: META-INF/contracts/blue/javax.faces.contract.xml META-INF/contracts/blue/layout.css META-INF/contracts/blue/template.xhtml META-INF/contracts/blue/footer.png META-INF/contracts/red/javax.faces.contract.xml META-INF/contracts/red/layout.css META-INF/contracts/red/template.xhtml META-INF/contracts/red/logo.png The contents of the contracts directory from our application can be packaged in the META-INF/contracts entry of a JAR file, say layout.jar. This JAR can then be packaged into WEB-INF/lib, and the declared templates can be used in the application: index.xhtml new/index.xhtml WEB-INF/lib/layout.jar You can use a new layout.jar file, providing a similar set of declared insertion points and resources (likely with a different CSS), to change the look and feel of the application. You can change the template of the page dynamically as well by enclosing the template client page ui:composition in an f:view: 58 | Chapter 3: JavaServer Faces . . . In this code: • f:view has an attribute, contracts, that binds to an EL. • The value of this EL is populated from the radio button in the form inside ui:de fine. • The radio button values match the contract names. • Clicking on the Apply command button will apply the chosen template to this page. The backing bean definition is trivial: @Named @SessionScoped public class ContractsBean implements Serializable { String contract = "red"; // getter & setter } Passthrough Attributes and HTML5-Friendly Markup HTML5 adds a series of new attributes for existing elements. These attributes include the type attribute for input elements, which supports values such as email, url, tel, number, range, and date: This code fragment allows the browser to check whether the entered text is in email format. In addition, custom data attributes, also known as data-* attributes, can be defined to store custom data private to the page or application. Every HTML element may have any number of custom data attributes specified, with any value: This code fragment introduces data-length as a custom data attribute. Passthrough Attributes and HTML5-Friendly Markup | 59 These attributes are not rendered but can be read by JavaScript. This attribute can be accessed in JavaScript as: document.getElementById("myData").dataset.length; Prior to JSF 2.2, by default, these newly introduced types and data-* attributes were not supported by the components. The set of available attributes supported by a JSF com‐ ponent is determined by the combination of the UIComponent and Renderer for that tag. In some cases, the value of the attribute is interpreted by the UIComponent or Renderer (for example, the columns attribute of h:panelGrid), and in others, the value is passed straight through to the user agent (for example, the lang attribute of h:input Text). In both cases, the UIComponent/Renderer has a prior knowledge of the set of allowable attributes. JSF 2.2 introduces passthrough attributes, which allow us to list arbitrary name/value pairs in a component that are passed straight through to the user agent without inter‐ pretation by the UIComponent or Renderer. The passthrough attributes can be specified in three different ways: • Prefixing the attribute with the shortname assigned to the jsf/passThrough XML namespace: In this code, p is the shortname for the namespace. • Nesting the tag within a component: In this code, a type attribute of value email is marked as a passthrough attribute. • Nesting the tag within a component: #{user.myAttributes} must point to a Map where the values can be either literals or a value expression. This mechanism can be applied to any JSF component and is not restricted to just HTML5 elements. Component Tags JSF 2 defines a variety of component tags. Each component is backed by a UICompo nent class. These component tags are rendered as an HTML element via the HTML RenderKit Renderer. 60 | Chapter 3: JavaServer Faces Here are sme commonly used components: h:commandButton • Usage: • HTML: h:commandLink • Usage: • HTML: myLink h:dataTable • Usage: Id #{} Name #{} Component Tags | 61 • HTML:
Id Name
1 Penny
2 Leonard
3 Sheldon
h:form • Usage: ... • HTML:
h:graphicImage • Usage: • HTML: h:inputHidden • Usage: 62 | Chapter 3: JavaServer Faces • HTML: h:inputSecret • Usage: • HTML: h:inputText • Usage: • HTML: h:inputTextArea • Usage: • HTML: h:button • Usage: Component Tags | 63 • HTML: h:link • Usage: • HTML: Next h:body • Usage: This is body • HTML: This is body h:outputFormat • Usage: • HTML: Hello Duke h:outputLabel • Usage: • HTML: h:outputLink • Usage: myOutput • HTML: myOutput h:outputText • Usage: • HTML: myOutputText h:outputScript • Usage: • HTML: The code builds an HTML form that has two textareas—one to display the chat log and the other to display the list of users currently logged in. A single text box is used for the username or the chat message. Clicking the Join button takes the user‐ name as the value, while clicking Send takes the chat message as the value. JavaScript methods, which will be explained in the next section, are invoked when these but‐ tons are clicked. The chat messages are sent and received as WebSocket payloads. There is an explicit button to disconnect the WebSocket connection. The output div is the placeholder for status messages. The WebSocket initialization occurs in the websocket.js file included at the bottom of the fragment. See Figure 16-18. Figure 16-18. Select JavaScript file type 5. Right-click “chat” in Web Pages and then select New, Web, and JavaScript File. Specify the name as “websocket” and click Finish. 6. Edit the contents of websocket.js such that it looks like: var wsUri = 'ws://' + + document.location.pathname.substr(0, document.location.pathname.indexOf("/faces")) + '/websocket'; console.log(wsUri); 294 | Chapter 16: Build an End-to-End Application var websocket = new WebSocket(wsUri); var textField = document.getElementById("textField"); var users = document.getElementById("users"); var chatlog = document.getElementById("chatlog"); var username; websocket.onopen = function(evt) { onOpen(evt); }; websocket.onmessage = function(evt) { onMessage(evt); }; websocket.onerror = function(evt) { onError(evt); }; websocket.onclose = function(evt) { onClose(evt); }; var output = document.getElementById("output"); function join() { username = textField.value; websocket.send(username + " joined"); } function send_message() { websocket.send(username + ": " + textField.value); } function onOpen() { writeToScreen("CONNECTED"); } function onClose() { writeToScreen("DISCONNECTED"); } function onMessage(evt) { writeToScreen("RECEIVED: " +; if ("joined") !== −1) { users.innerHTML +=," joined")) + "\n"; } else { chatlog.innerHTML += + "\n"; } } function onError(evt) { writeToScreen('ERROR: ' +; } function disconnect() { websocket.close(); } function writeToScreen(message) { var pre = document.createElement("p"); = "break-word"; pre.innerHTML = message; Chat Room (Java API for WebSocket) | 295 output.appendChild(pre); } You calculate the WebSocket endpoint URI by using standard JavaScript variables and appending the URI specified in the ChatServer class. You initialize the Web‐ Socket by calling new WebSocket(...). Event handlers are registered for life-cycle events via onXXX messages. The listeners registered in this script are explained in Table 16-3. Table 16-3. WebSocket event listeners Listeners Called when onOpen(evt) WebSocket connection is initiated onMessage(evt) WebSocket message is received onError(evt) Error occurs during the communication onClose(evt) WebSocket connection is terminated Any relevant data is passed along as a parameter to the function. Each method prints the status on the browser using the writeToScreen utility method. The join meth‐ od sends a message to the endpoint indicating that a particular user has joined. The endpoint then broadcasts the message to all the listening clients. The send_mes sage method appends the logged-in username and the value of the text field and broadcasts to all the clients similarly. The onMessage method updates the list of logged-in users as well. 7. Edit WEB-INF/template.xhtml and change: Item 2 to: Chat Room The outputLink tag renders an HTML anchor tag with an href attribute. ${face sContext.externalContext.requestContextPath} provides the request URI that identifies the web application context for this request. This allows the links in the left navigation bar to be fully qualified URLs. 8. Run the project by right-clicking the project and selecting Run. The browser shows localhost:8080/movieplex7, as shown in Figure 16-19. 296 | Chapter 16: Build an End-to-End Application Figure 16-19. Chat room link Click Chat Room to see the output shown in Figure 16-20. The “CONNECTED” status message is shown and indicates that a WebSocket con‐ nection with the endpoint has been established. Figure 16-20. Chat room page output Please make sure your browser supports WebSocket in order for this page to show up successfully. Chrome 14.0+, Firefox 11.0+, Safari 6.0+, and IE 10.0+ are the browsers that support WebSocket. A complete list of supported browsers is available at Open the URI localhost:8080/movieplex7 in another browser window. Enter Duke in the text box in the first browser and click Join. Notice that the user list and the status message in both the browsers gets updated. Enter Duke2 in the text box of the second browser and click Join. Once again, the user list and the status message in both the browsers is updated. Now you can type any message in either browser and click Send to send the message. Chat Room (Java API for WebSocket) | 297 The output from two different browsers after the initial greeting looks like Figure 16-21. Chrome output is shown on the top and Firefox on the bottom. Figure 16-21. Chat room output from Chrome (top) and Firefox (bottom) Chrome Developer Tools can be used to monitor WebSocket traffic. 298 | Chapter 16: Build an End-to-End Application View and Delete Movies (Java API for RESTful Web Services) PURPOSE: View and delete a movie. Several new features of JAX-RS 2 will be intro‐ duced and demonstrated in this application. This section will enable us to view all the movies, view details of a selected movie, and delete an existing movie using the JAX-RS Client API. 1. Right-click Source Packages and then select New and Java Class. Specify the class name as MovieClientBean and the package as org.glassfish.movieplex7.cli ent, and click Finish. This bean will be used to invoke the REST endpoint. 2. Add the @Named and @RequestScoped class-level annotations. This allows the class to be injected in an EL expression and also defines the bean to be automatically activated and passivated with the request. Make sure to resolve the imports by clicking the yellow lightbulb or right-clicking the editor pane and selecting Fix Imports (use the Command + Shift + I shortcut on Mac). 3. Add the following code to the class: Client client; WebTarget target; @PostConstruct public void init() { client = ClientBuilder.newClient(); target = client .target("http://localhost:8080/movieplex7/webresources/movie/"); } @PreDestroy public void destroy() { client.close(); } In this code: • ClientBuilder is used to create an instance of Client. • The Client instance is created and destroyed in the life-cycle callback methods. We set the endpoint URI on this instance by calling the target method. • We set the URI of the endpoint on the Client instance using the target method. 4. Add the following code to the class: View and Delete Movies (Java API for RESTful Web Services) | 299 public Movie[] getMovies() { return target .request() .get(Movie[].class); } Prepare a request by calling the request method. Invoke the HTTP GET method by calling the get method. The response type is specified in the last method call, so the return value is of the type Movie[]. 5. In NetBeans IDE, right-click Web Pages, select New and then Folder, specify the folder name client, and click Finish. In this folder, create movies.xhtml following the directions outlined in step 2 on page 284. 6. Replace the content within with the following code fragment: This code fragment invokes the getMovies method from MovieClientBean, iterates over the response in a for loop, and displays the name of each movie with a radio button. The selected radio button value is bound to the EL expression #{movie BackingBean.movieId}. The code also has a button with the label Details and looks for movie.xhtml in the same directory. We will create this file later. Click the yellow lightbulb in the left bar to resolve the namespace prefix-to-URI resolution. This needs to be repeated three times—for the h:, c:, and f: prefixes (see Figure 16-22). 300 | Chapter 16: Build an End-to-End Application Figure 16-22. Resolve namespace prefix/URI mapping for h:, c:, f: 7. Right-click the org.glassfish.movieplex7.client package, select New and then Java Class, specify the value as MovieBackingBean, and click Finish. Add the following field: int movieId; Add getters/setters by right-clicking on the editor pane and selecting Insert Code (use the Control + I shortcut on Mac). Select the field and click Generate. Add the @Named and @RequestScoped class-level annotations. Resolve the imports. Make sure to import javax.enterprise.context.Reques tScoped. 8. In template.xhtml, add the following code in with name="left":

Movies Running the project (Fn + F6 on Mac) and clicking Movies in the left navigation bar shows the output in Figure 16-23. All movies are displayed in a list with a radio button next to them. This output uses a REST endpoint for querying instead of a traditional EJB/JPA-backed endpoint. View and Delete Movies (Java API for RESTful Web Services) | 301 Figure 16-23. Movies page output 9. In MovieClientBean, inject MovieBackingBean to read the value of the selected movie from the page. Add the following code: @Inject MovieBackingBean bean; 10. In MovieClientBean, add the following method: public Movie getMovie() { Movie m = target .path("{movie}") .resolveTemplate("movie", bean.getMovieId()) .request() .get(Movie.class); return m; } This code reuses the Client and WebTarget instances created in @PostConstruct. It also adds a variable part to the URI of the REST endpoint, defined via {movie}, and binds it to a concrete value via the resolveTemplate method. The return type is specified as a parameter to the get method. 11. Create movie.xhtml following the directions in step 2 on page 284. Change the element such that its content looks like:

Movie Details

302 | Chapter 16: Build an End-to-End Application
Movie Id: #{}
Movie Name: #{}
Movie Actors: #{}
Click the yellow lightbulb to resolve the namespace prefix-URI mapping for h:. Display the output values by calling the getMovie method and using the id, name, and actors property values. 12. Run the project, select Movies in the left navigation bar, select a radio button next to any movie, and click on details to see the output shown in Figure 16-24. Figure 16-24. “Movie details” page output Click the Back button to select another movie. 13. Add the ability to delete a movie. In movies.xhtml, add the following code with the other commandButton: This button displays a Delete label, invokes the method deleteMovie from Movie ClientBean, and then renders movie.xhtml. View and Delete Movies (Java API for RESTful Web Services) | 303 14. Add the following code to MovieClientBean: public void deleteMovie() { target .path("{movieId}") .resolveTemplate("movieId", bean.getMovieId()) .request() .delete(); } This code again reuses the Client and WebTarget instances created in @PostCon struct. It also adds a variable part to the URI of the REST endpoint, defined via {movieId}, and binds it to a concrete value via the resolveTemplate method. The URI of the resource to be deleted is prepared and the delete method is called to delete the resource. Make sure to resolve the imports. Running the project yields the output shown in Figure 16-25. Figure 16-25. Delete button Select a movie and click the Delete button. This deletes the movie from the database and refreshes the page. Add Movie (Java API for JSON Processing) PURPOSE: Add a new movie. Several new features of the Java API for JSON Processing 1.0 will be introduced and demonstrated in this application. This section will define JAX-RS entity providers that will allow reading and writing JSON for a Movie POJO. The JAX-RS Client API will request this JSON representation. This section will enable us to add a new movie to the application. Typically, this func‐ tionality will be available after proper authentication and authorization. 1. Right-click Source Packages, select New and then Java Package, specify the value as org.glassfish.movieplex7.json, and click Finish. 304 | Chapter 16: Build an End-to-End Application 2. Right-click the newly created package, select New and then Java Class, specify the name as MovieReader, and click Finish. Add the following class-level annotations: @Provider @Consumes(MediaType.APPLICATION_JSON) @Provider allows this implementation to be discovered by the JAX-RS runtime during the provider scanning phase. @Consumes indicates that this implementation will consume a JSON representation of the resource. 3. Make the class implements MessageBodyReader. See Figure 16-26. Figure 16-26. Implement abstract methods for MessageBodyReader Click on the hint (shown as a yellow lightbulb) on the class definition and select “Implement all abstract methods.” 4. Add an implementation of the isReadable method as: @Override public boolean isReadable(Class type, Type type1, Annotation[] antns, MediaType mt) { return Movie.class.isAssignableFrom(type); } This method ascertains if the MessageBodyReader can produce an instance of a particular type. 5. Add an implementation of the readFrom method as: @Override public Movie readFrom(Class type, Type type1, Annotation[] antns, MediaType mt, MultivaluedMap mm, InputStream in) throws IOException, WebApplicationException { Movie movie = new Movie(); JsonParser parser = Json.createParser(in); while (parser.hasNext()) { switch ( { Add Movie (Java API for JSON Processing) | 305 case KEY_NAME: String key = parser.getString();; switch (key) { case "id": movie.setId(parser.getInt()); break; case "name": movie.setName(parser.getString()); break; case "actors": movie.setActors(parser.getString()); break; default: break; } break; default: break; } } return movie; } This code reads a type from the input stream in. JsonParser, a streaming parser, is created from the input stream. Key values are read from the parser and a Movie instance is populated and returned. Resolve the imports. 6. Right-click the newly created package, select New and then Java Class, specify the name as MovieWriter, and click Finish. Add the following class-level annotations: @Provider @Produces(MediaType.APPLICATION_JSON) @Provider allows this implementation to be discovered by the JAX-RS runtime during the provider-scanning phase. @Produces indicates that this implementation will produce a JSON representation of the resource. 7. Make the class implements MessageBodyWriter. See Figure 16-27. Figure 16-27. Implement abstract methods for MessageBodyWriter 306 | Chapter 16: Build an End-to-End Application Click the hint (shown as a yellow lightbulb) on the class definition and select “Im‐ plement all abstract methods.” 8. Add an implementation of the isWritable method as: public boolean isWriteable(Class type, Type type1, Annotation[] antns, MediaType mt) { return Movie.class.isAssignableFrom(type); } This method ascertains if the MessageBodyWriter supports a particular type. 9. Add an implementation of the getSize method as: public long getSize(Movie t, Class type, Type type1, Annotation[] antns, MediaType mt) { return −1; } Originally, this method was called to ascertain the length in bytes of the serialized form of t. In JAX-RS 2.0, this method is deprecated, and the value returned by the method is ignored by a JAX-RS runtime. All MessageBodyWriter implementations are advised to return −1. 10. Add an implementation of the writeTo method as: public void writeTo(Movie t, Class type, Type type1, Annotation[] antns, MediaType mt, MultivaluedMap mm, OutputStream out) throws IOException, WebApplicationException { JsonGenerator gen = Json.createGenerator(out); gen.writeStartObject() .write("id", t.getId()) .write("name", t.getName()) .write("actors", t.getActors()) .writeEnd(); gen.flush(); } This method writes a type to an HTTP message. JsonGenerator writes JSON data to an output stream in a streaming way. Overloaded write methods are used to write different data types to the stream. Resolve the imports. Add Movie (Java API for JSON Processing) | 307 11. In Web Pages, in the client folder, create addmovie.xhtml following the directions in step 2 on page 284. Change the element (the “top” and “left” ele‐ ments need to be removed) such that its content looks like:

Add a New Movie

Movie Id:
Movie Name:
Movie Actors:
This code creates a form to accept as input the movie’s id, name, and actors. These values are bound to fields in MovieBackingBean. The click of the command button invokes the addMovie method from MovieClientBean and then renders mov‐ ies.xhtml. Click the hint (shown as a yellow lightbulb) to resolve the namespace prefix/URI mapping. 12. Add movieName and actors fields to MovieBackingBean as: String movieName; String actors; Generate getters and setters. 13. Add the following code to movies.xhtml: along with rest of the s. 14. Add the following method in MovieClientBean: public void addMovie() { Movie m = new Movie(); m.setId(bean.getMovieId()); m.setName(bean.getMovieName()); m.setActors(bean.getActors()); 308 | Chapter 16: Build an End-to-End Application target .register(MovieWriter.class) .request() .post(Entity.entity(m, MediaType.APPLICATION_JSON)); } This method creates a new Movie instance, populates it with the values from the backing bean, and POSTs the bean to the REST endpoint. The register method registers a MovieWriter that enables conversion from the POJO to JSON. We specify a media type of application/json using MediaType.APPLICATION_JSON. Resolve the imports. 15. Run the project to see the updated main page as shown in Figure 16-28. Figure 16-28. “New movie button” page output You can add a new movie by clicking the New Movie button. 16. Enter the details as shown in Figure 16-29. Figure 16-29. “Add a new movie” page output Add Movie (Java API for JSON Processing) | 309 Click the Add button. The Movie Id value has to be greater than 20; otherwise, the primary key constraint will be violated. The table definition may be updated to generate the primary key based upon a sequence; however, this is not done in the application. The updated page looks like Figure 16-30. Figure 16-30. “New movie added” page output Note that the newly added movie is now displayed. Ticket Sales (Batch Applications for the Java Platform) PURPOSE: Read the total sales for each show and populate the database. Several new features of the Java API for Batch Processing 1.0 will be introduced and demonstrated in this application. This section will read the cumulative sales for each show from a CSV file and populate them in a database. 1. Right-click Source Packages, select New and then Java Package, specify the value as org.glassfish.movieplex7.batch, and click Finish. 2. Right-click the newly created package, select New and then Java Class, and specify the name as SalesReader. Change the class definition and add: extends AbstractItemReader AbstractItemReader is an abstract class that implements the ItemReader interface. The ItemReader interface defines methods that read a stream of items for chunk processing. This reader implementation returns a String item type. Add @Named as a class-level annotation; it allows the bean to be injected in Job XML. Add @Dependent as another class-level annotation to mark this bean as a bean- defining annotation so that this bean is available for injection. Resolve the imports. 310 | Chapter 16: Build an End-to-End Application 3. Add the following field: private BufferedReader reader; Override the open method to initialize the reader: public void open(Serializable checkpoint) throws Exception { reader = new BufferedReader( new InputStreamReader( Thread.currentThread() .getContextClassLoader() .getResourceAsStream("META-INF/sales.csv"))); } This method initializes a BufferedReader from META-INF/sales.csv that is bun‐ dled with the application and is shown in Figure 16-31. Figure 16-31. sales.csv The following is a sampling of the first few lines from sales.csv: 1,500.00 2,660.00 3,80.00 4,470.00 5,1100.x0 Each line has a show identifier comma-separated by the total sales for that show. Note that the last line (5th record in the sample) has an intentional typo. In addition, the 17th record has a typo. The lab will use these lines to demonstrate how to handle parsing errors. 4. Override the following method from the abstract class: Ticket Sales (Batch Applications for the Java Platform) | 311 @Override public String readItem() { String string = null; try { string = reader.readLine(); } catch (IOException ex) { ex.printStackTrace(); } return string; } The readItem method returns the next item from the stream. It returns null to indicate end of stream. Note that the end of the stream indicates the end of the chunk, so the current chunk will be committed and the step will end. Resolve the imports. 5. Right-click the org.glassfish.movieplex7.batch package, select New and then Java Class, and specify the name as SalesProcessor. Change the class definition and add: implements ItemProcessor ItemProcessor is an interface that defines a method that is used to operate on an input item and produce an output item. This processor accepts a String input item from the reader, SalesReader in our case, and returns a Sales instance to the writer (coming shortly). Sales is the prepackaged JPA entity with the application starter source code. Add @Named and @Dependent as class-level annotations to allow the bean to be in‐ jected in Job XML. Resolve the imports. 6. Add an implementation of the abstract method from the interface as: @Override public Sales processItem(Object s) { Sales sales = new Sales(); StringTokenizer tokens = new StringTokenizer((String)s, ","); sales.setId(Integer.parseInt(tokens.nextToken())); sales.setAmount(Float.parseFloat(tokens.nextToken())); return sales; } This method takes a String parameter coming from the SalesReader, parses the value, populates it in the Sales instance, and returns it. This is then aggregated with the writer. The method can return null, indicating that the item should not be aggregated. For example, the parsing errors can be handled within the method and return null if 312 | Chapter 16: Build an End-to-End Application the values are not correct. However, this method is implemented where any parsing errors are thrown as exceptions. Job XML can be instructed to skip these exceptions, and thus that particular record is skipped from aggregation as well (shown later). Resolve the imports. 7. Right-click the org.glassfish.movieplex7.batch package, select New and then Java Class, and specify the name as SalesWriter. Change the class definition and add: extends AbstractItemWriter AbstractItemWriter is an abstract class that implements the ItemWriter interface. The ItemWriter interface defines methods that write to a stream of items for chunk processing. This writer writes a list of Sales items. Add @Named and @Dependent as class-level annotations to allow the bean to be in‐ jected in Job XML. Resolve the imports. 8. Inject EntityManager as: @PersistenceContext EntityManager em; Override the following method from the abstract class: @Override @Transactional public void writeItems(List list) { for (Sales s : (List)list) { em.persist(s); } } The batch runtime aggregates the list of Sales instances returned from the Sales Processor and makes it available as a List in this method. This method iterates over the list and persists each item in the database. The method also has a @Transactional annotation that provides transactional se‐ mantics to this method. Resolve the imports. 9. Create a Job XML that defines the job, step, and chunk. In the Files tab, expand the project → src → main → resources; right-click resour‐ ces and then META-INF; select New and then Folder; specify the name as batch- jobs; and click Finish. Right-click the newly created folder, select New and then Other, select XML and then XML Document, click Next >, specify the name as eod-sales, click Next, leave the default, and click Finish. Replace the contents of the file with the following: Ticket Sales (Batch Applications for the Java Platform) | 313 id="endOfDaySales" xmlns="" version="1.0"> In this code: • job has one step of chunk type. • The , , and elements define the CDI bean name of the implementations of the ItemReader, ItemProcessor, and ItemWriter interfaces. • The item-count attribute indicates that three items are read/processed/aggre‐ gated and then given to the writer. The entire reader/processor/writer cycle is executed within a transaction. • The element specifies a set of exceptions to be skipped by chunk processing. The CSV file used for this lab has intentionally introduced a couple of typos that would generate a NumberFormatException. Specifying this element allows the ap‐ plication to skip the exception, ignore that particular element, and continue pro‐ cessing. If this element is not specified, then the batch processing will halt. The skip-limit attribute specifies the number of exceptions a step will skip. 10. Invoke the batch job. Right-click the org.glassfish.movieplex7.batch package, and select New and then Session Bean. Enter the name as SalesBean and click Finish. Add the following code to the bean: public void runJob() { try { JobOperator jo = BatchRuntime.getJobOperator(); long jobId = jo.start("eod-sales", new Properties()); System.out.println("Started job: with id: " + jobId); } catch (JobStartException ex) { ex.printStackTrace(); } } 314 | Chapter 16: Build an End-to-End Application This method uses BatchRuntime to get an instance of JobOperator, which is then used to start the job. JobOperator is the interface for operating on batch jobs. It can be used to start, stop, and restart jobs. It can additionally inspect job history, to discover what jobs are currently running and what jobs have previously run. Add @Named and @RequestScoped as a class-level annotation; it allows the bean to be injectable in an EL expression and automatically activated and passivated with the request. Resolve the imports. 11. Inject EntityManager in the class as: @PersistenceContext EntityManager em; and add the following method: public List getSalesData() { return em.createNamedQuery("Sales.findAll", Sales.class) .getResultList(); } This method uses a predefined @NamedQuery to query the database and return all rows from the table. Resolve the imports. 12. Add the following code in template.xhtml along with other s:

Sales 13. Right-click Web Pages, select New and then Folder, specify the name as batch, and click Finish. Create sales.xhtml in that folder following the directions explained in step 2 on page 284. Copy the following code inside with name="content":

Movie Sales

#{} #{s.amount} Ticket Sales (Batch Applications for the Java Platform) | 315 This code displays the show identifier and sales from that show in a table by invoking SalesBean.getSalesData(). The first command button invokes the job that pro‐ cesses the CSV file and populates the database. The second command button re‐ freshes the page. Right-click the yellow lightbulb to fix the namespace prefix/URI mapping. Repeat this process for the h: and f: prefixes. 14. Run the project to see the output shown in Figure 16-32. Figure 16-32. Sales link Notice that a new Sales entry is displayed in the left navigation bar. 15. Click Sales to see the output shown in Figure 16-33. The empty table indicates that there is no sales data in the database. 316 | Chapter 16: Build an End-to-End Application Figure 16-33. “Movie sales” page output 16. Click the Run Job button to initiate data processing of the CSV file. Wait a couple of seconds for the processing to finish and then click the Refresh button to see the updated output, as shown in Figure 16-34. Figure 16-34. “Movie sales details” page output Now the table is populated with the sales data. Ticket Sales (Batch Applications for the Java Platform) | 317 Note that record 5 is missing from the table, as this record did not have the correct numeric entries for the sales total. The Job XML for the application explicitly states to skip such errors. Movie Points (Java Message Service 2) PURPOSE: Customers accrue points for watching a movie. This section will provide a page to simulate submission of movie points accrued by a customer. These points are submitted to a JMS queue that is then read synchronously by another bean. The JMS queue can continue further processing, possibly storing messages in the database using JPA. 1. Right-click Source Packages, select New and then Java Package, specify the value as org.glassfish.movieplex7.points, and click Finish. 2. Right-click the newly created package, select New and then Java Class, and specify the name as SendPointsBean. Add the following class-level annotations: @Named @RequestScoped This marks the bean to be EL-injectable and automatically activated and passivated with the request. 3. Typically, a message to a JMS queue is sent after the customer has bought the tickets. Another bean will then retrieve this message and update the points for that cus‐ tomer. This allows the two systems, one generating the data about tickets purchased and the other about crediting the account with the points, to be completely decoupled. This lab will mimic the sending and consuming of a message via an explicit call to the bean from a JSF page. Add the following field to the class: @NotNull @Pattern(regexp = "^\\d{2},\\d{2}", message = "Message format must be 2 digits, comma, 2 digits, e.g. 12,12") private String message; 318 | Chapter 16: Build an End-to-End Application This field contains the message sent to the queue. This field’s value is bound to an inputText in a JSF page (created later). It also has a Bean Validation constraint that enables validation of data on form submit. It requires the data to consist of two digits, followed by a comma, and then two more digits. If the message does not meet the validation criteria, then the error message to be displayed is specified via a message attribute. You could think of this as conveying the customer identifier and the points accrued by that customer. Generate getter/setters for this field. Right-click in the editor pane, select Insert Code (use the Control + I shortcut on Mac), select “Getter and Setter,” select the field, and click Generate. 4. Add the following code to the class: @Inject JMSContext context; @Resource(lookup = "java:global/jms/pointsQueue") Queue pointsQueue; public void sendMessage() { System.out.println("Sending message: " + message); context.createProducer().send(pointsQueue, message); } This code uses the default factory to inject an instance of container-managed JMSContext. All messages are then sent to a Queue instance (created later) identified by the java:global/jms/pointsQueue JNDI name. The actual message is obtained from the value entered in the JSF page and bound to the message field. Resolve the imports. Make sure the Queue class is imported from javax.jms.Queue instead of the default java.util.Queue, as shown in Figure 16-35. Movie Points (Java Message Service 2) | 319 Figure 16-35. Resolve imports for Queue Click OK. 5. Right-click the org.glassfish.movieplex7.points package, select New and then Java Class, and specify the name as ReceivePointsBean. Add the following class-level annotations: @JMSDestinationDefinition(name = "java:global/jms/pointsQueue", interfaceName = "javax.jms.Queue") @Named @RequestScoped This marks the bean to be referenced from an EL expression. It also activates and passivates the bean with the session. JMSDestinationDefinition will create Queue with the JNDI name java:global/ jms/pointsQueue. 6. Add the following code to the class: @Inject JMSContext context; @Resource(lookup ="java:global/jms/pointsQueue") Queue pointsQueue; public String receiveMessage() { String message = context .createConsumer(pointsQueue) .receiveBody(String.class); System.out.println("Received message: " + message); 320 | Chapter 16: Build an End-to-End Application return message; } This code is very similar to SendPointsBean. The createConsumer method creates JMSConsumer, which is then used to synchronously receive a message. 7. Add the following method to the class: public int getQueueSize() { int count = 0; try { QueueBrowser browser = context.createBrowser(pointsQueue); Enumeration elems = browser.getEnumeration(); while (elems.hasMoreElements()) { elems.nextElement(); count++; } } catch (JMSException ex) { ex.printStackTrace(); } return count; } This code creates a QueueBrowser to look at the messages on a queue without re‐ moving them. It calculates and returns the total number of messages in the queue. Resolve the imports. 8. Right-click Web Pages, select New and then Folder, specify the name as points, and click Finish. Create points.xhtml in that folder following the directions explained in step 2 on page 284. Copy the following code inside with name="content":


Queue size:

Click the yellow lightbulb to resolve namespace prefix/URI mapping for the h: prefix. Movie Points (Java Message Service 2) | 321 This page displays the number of messages in the current queue. It provides a text box for entering the message that can be sent to the queue. The first command button invokes the sendMessage method from SendPointsBean and refreshes the page. An updated queue count, incremented by 1 in this case, is displayed. The second command button invokes the receiveMessage method from Receive PointsBean and refreshes the page. The queue count is updated again, decremented by 1 in this case. If the message does not meet the validation criteria, then the error message is dis‐ played on the screen. 9. Add the following code in template.xhtml along with other s:

Points 10. Run the project. The update page looks like Figure 16-36. Figure 16-36. Points link Click Points to see the output in Figure 16-37. 322 | Chapter 16: Build an End-to-End Application Figure 16-37. Points page default output The output shows that the queue has 0 messages. Enter the message 1212 in the text box and click Send Message to see the output shown in Figure 16-38. Figure 16-38. Bean Validation error message This message does not meet the validation criteria, so the error message is displayed. Enter the message 12,12 in the text box and click the Send Message button to see the output in Figure 16-39. Movie Points (Java Message Service 2) | 323 Figure 16-39. Points page output: one message in queue The updated count now shows that there is one message in the queue. Click the Receive Message button to see the output in Figure 16-40. Figure 16-40. Points page output: zero messages in queue The updated count now shows that the message has been consumed and the queue has zero messages. Click Send Message four times to see the output in Figure 16-41. 324 | Chapter 16: Build an End-to-End Application Figure 16-41. Points page output: four messages in queue The updated count now shows that the queue has four messages. Click Receive Message twice to see the output in Figure 16-42. Figure 16-42. Points page output: two messages in queue The count is once again updated to reflect the two consumed and two remaining messages in the queue. Movie Points (Java Message Service 2) | 325 Conclusion This hands-on lab built a trivial three-tier web application using Java EE 7 and demon‐ strated the following features of the platform: • Java EE 7 Platform — Maven coordinates — Default DataSource — Default JMSConnectionFactory • Java Persistence API 2.1 — Schema generation properties • Java API for RESTful Web Services 2.0 — Client API — Custom entity providers • Java Message Service 2.0 — Default JMS ConnectionFactory — Injecting JMSContext — Synchronous message send and receive • JavaServer Faces 2.2 — Faces Flow • Contexts and Dependency Injection 1.1 — Automatic discovery of beans — Injection of beans • Bean Validation 1.1 — Integration with JavaServer Faces • Batch Applications for the Java Platform 1.0 — Chunk-style processing — Exception handling • Java API for JSON Processing 1.0 — Streaming API for generating JSON — Streaming API for consuming JSON • Java API for WebSocket 1.0 — Annotated server endpoint 326 | Chapter 16: Build an End-to-End Application — JavaScript client • Java Transaction API 1.2 — @Transactional Hopefully, this has piqued your interest in trying out Java EE 7 applications using GlassFish 4. Send us feedback at Troubleshooting 1. How can I start/stop/restart GlassFish from within the IDE? In the Services tab, right-click GlassFish Server 4. All the commands to start, stop, and restart are available from the pop-up menu. View the server log by clicking View Server Log, and view the web-based administration console by clicking View Admin Console. 2. I accidentally closed the GlassFish output log window. How do I bring it back? In the Services tab of NetBeans, expand Servers, choose the GlassFish node, and select View Domain Server Log. Completed Solution The completed solution can be downloaded as a zip. Troubleshooting | 327 APPENDIX A Further Reading This appendix provides a reference to the specifications for different technologies in‐ cluded in the Java EE 7 platform. Web Technology Specifications • JSR 45: Debugging Support for Other Languages 1.0 • JSR 52: Standard Tag Library for JavaServer Pages (JSTL)1.2 • JSR 245: JavaServer Pages (JSP) 2.3 • JSR 340: Java Servlet 3.1 • JSR 341: Expression Language 3.1 • JSR 344: JavaServer Faces (JSF) 2.2 • JSR 353: Java API for JSON Processing (JSON-P) 1.0 • JSR 356: Java API for WebSocket 1.0 Enterprise Technology Specifications • JSR 236: Concurrency Utilities for Java EE 1.0 • JSR 250: Common Annotations for the Java Platform 1.2 • JSR 318: Interceptors 1.2 • JSR 322: Java EE Connector Architecture 1.7 • JSR 330: Dependency Injection for Java 1.0 • JSR 338: Java Persistence API (JPA) 2.1 • JSR 343: Java Message Service (JMS) 2.0 329 • JSR 345: Enterprise JavaBeans (EJB) 3.2 • JSR 346: Contexts and Dependency Injection (CDI) for the Java EE Platform 1.1 • JSR 349: Bean Validation 1.1 • JSR 352: Batch Applications for Java Platform 1.0 • JSR 907: Java Transaction API (JTA) 1.2 • JSR 919: JavaMail 1.5 Web Service Technologies • JSR 93: Java API for XML Registries (JAXR) 1.0 • JSR 101: Java API for XML-based RPC (JAX-RPC) 1.1 • JSR 109: Implementing Enterprise Web Services 1.4 • JSR 181: Web Services Metadata for the Java Platform 2.1 • JSR 222: Java Architecture for XML Binding (JAXB) 2.2 • JSR 224: Java API for XML Web Services (JAX-WS) 2.2 • JSR 339: Java API for RESTful Web Services (JAX-RS) 2.0 Management and Security Technologies • JSR 77: J2EE Management API 1.1 • JSR 88: Java Platform EE Application Deployment API 1.2 • JSR 115: Java Authorization Contract and Containers (JACC) 1.5 • JSR 196: Java Authentication Service Provider Interface for Containers (JASPIC) 1.0 330 | Appendix A: Further Reading We’d like to hear your suggestions for improving our indexes. Send email to Index A absolute-ordering element, 24 AbstractBatchlet class, 265 AbstractCheckpointAlgorithm class, 264 AbstractChunkListener class, 266 AbstractItemProcessListener class, 266 AbstractItemReader class, 258, 260, 261 AbstractItemReadListener class, 266 AbstractItemWriter class, 258, 260, 262 AbstractJobListener class, 266 AbstractStepListener class, 266 AbstractWriteListener class, 266 ActionEvent class, 45 @AdministeredObjectDefinition annotation, 10 AfterBeanDiscovery event, 184 AfterDeploymentValidation event, 184 Ajax, JSF support for, 43–46, 72 @Alternative annotation, 172–173, 182 alternative beans, CDI, 172–173, 182 annotated client endpoints, WebSocket, 132– 135 annotated server endpoints, WebSocket, 122– 127 annotations, 5 (see also specific annotations) @Any annotation, 172 Application class, 74, 82 application-managed entity manager, 222 @ApplicationPath annotation, 74 @ApplicationScoped annotation, 180 apply request values phase, JSF, 42 @AroundConstruct annotation, 9, 151 @AroundInvoke annotation, 175 @AssertFalse annotation, 204 @AssertTrue annotation, 204 async-supported element, 21 AsyncContext class, 21 asynchronous processing client invocations with JAX-RS, 86, 87 dispatch-based dynamic client, 106 JMS messages, 249, 253–254 message-driven beans, 154 programmatic client endpoints, 135 programmatic server endpoints, 129 server requests with Ajax, 43 server responses with JAX-RS, 76 servlets, 20–22 session bean methods, 159–160 tasks, 189–194 AsyncListener interface, 20, 22 attached objects, server-side, 47–49 @AttributeOverrides annotation, 220 auth-constraint element, 26 authentication, WebSocket endpoints, 142–143 B Batch Applications, 3, 7, 257–258 batchlets, 258, 265–266 331 chunk-oriented processing for, 258–265 checkpoints in, 263 exception handling in, 264 interfaces and classes for, 258 item processor, 261 item reader, 260 item writer, 262 starting and stopping jobs, 262 steps in, 259 jobs, 257 decisions in, 269–271 flows in, 268 partitioning, 271–274 sequence of, specifying, 267–271 splits in, 269 listeners for, 266–267 movie application using, 277, 310–318, 326 steps, 258, 267 batchlet element, 265 Batchlet interface, 265 bean archives, 167 Bean Validation, 2, 6, 10, 203 built-in constraints, 203–206 custom constraints, 207–210 JPA entities, 237–239 JSF using, 49, 50–51 method and constructor constraints, 212– 214 movie application using, 326 for resources, 94–96 validation groups, 210–212 bean-defining annotation, 168 bean-managed transactions (see BMT) beans, 167–170 (see also EJB) alternative, 172–173, 182 built-in beans, 185–186 contexts of, 179, 180 decorators for, 178–179 disposer methods for, 174 events with, 182–183 injection points for, 35, 170–171 interceptors for, 5, 9, 174–178 observer beans, 182 portable extensions with, 183 producer beans, 182 producer methods for, 173–174 qualifiers for, 171–172 scope of, 179–180 stereotypes for, 181–182 submitting as tasks, 191 beans element, 168 beans.xml file, 168 enabling decorators in, 179 enabling interceptors in, 177 BeforeBeanDiscovery event, 184 BeforeShutdown event, 184 behaviors, JSF, 49 BindingProvider interface, 105 BMT (bean-managed transactions), 157–159, 215 built-in beans, 185–186 ByteMessage type, 247 C c: prefix, 34 Cache interface, 242 CacheRetrieveMode enumeration, 242 CacheStoreMode eumeration, 242 caching entities, 241–243 Callable interface, 190, 195 Cascading Style Sheets (CSS), facelets using, 34 cc: prefix, 38–41 cc:implementation element, 38, 40 cc:interface element, 38–40 CDI (Contexts and Dependency Injection), 2, 5, 9, 167 alternative beans, 172–173, 182 bean discovery, 167–170 bean qualifiers, 171–172 built-in beans, 185–186 container life-cycle events, 184 contexts, 179, 180 decorators, 178–179 disposer methods for beans, 174 events, 182–183 injection points, 35, 170–171 interceptors, 5, 9, 174–178 life-cycle callback methods, 186 movie application using, 326 portable extensions, 183–185 producer methods for beans, 173–174 scopes, 179–180 @ApplicationScoped, 180 @ConversationScoped, 180 @Dependent, 180 @FlowScoped, 53 @RequestScoped, 180 332 | Index @SessionScoped, 180 @TransactionScoped, 10, 218 @ViewScoped, 35 stereotypes, 181–182 submitting beans as tasks, 191 checkpoint-algorithm element, 263 checkpoints, Batch Applications, 263 chunk element, 259, 263 chunk-oriented processing, 258–265 checkpoints in, 263 exception handling in, 264 interfaces and classes for, 258 item processor, 261 item reader, 260 item writer, 262 starting and stopping jobs, 262 steps in, 259 ChunkListener interface, 266 class element, 177, 179 client API, JAX-RS, 84–87 Client class, 85 client proxy object, 180 client, JMS, 245 client-side extension points, 47–49 ClientBehaviorBase class, 49 ClientBuilder class, 85 @ClientEndpoint annotation, 132–135, 141 ClientEndpointConfig.Configurator class, 136 ClientRequestContext interface, 89 ClientRequestFilter interface, 88, 92 ClientResponseContext interface, 89 ClientResponseFilter interface, 88, 92 code examples (see example movie application) @CollectionTable annotation, 220 Common Annotations, 5 component specifications, 3–5 component tags, JSF, 60–72 composite components, 38–41 Concurrency Utilities, 3, 5, 7, 189 asynchronous tasks, 189–194 dynamic contextual objects, 198–201 managed threads, 197–198 scheduled tasks, 194–197 Connection interface, 250, 253, 255 ConnectionFactory interface, 2, 250, 253 @ConnectorFactoryDefinitions annotation, 10 @ConnectorFactoryDefinition annotation, 10 @Constraint annotation, 207 constraints built-in, 203–206 custom, 207–210 method and constructor, 212–214 security constraints, 25–28, 142 validation groups for, 210–212 ConstraintViolationException class, 237 constructors, constraints for, 212–214 @Consumes annotation, 79 contact information for this book, xv container life-cycle events, CDI, 184 container-managed entity manager, 222 container-managed transactions, 157–159, 216– 218 ContainerProvider class, 134 ContainerRequestFilter interface, 88, 90, 92 ContainerResponseFilter interface, 88, 92 @Context annotation, 81 Contexts and Dependency Injection (see CDI) contexts, CDI, 179, 180 ContextService interface, 198–201 conventions used in this book, xiii @ConversationScoped annotation, 180 Converter interface, 48 converters, JSF, 47 @CookieParam annotation, 81 cookies (see HTTP cookies) Criteria API, 229–232 CRUD operations on entities, 229–232 CSS (Cascading Style Sheets), facelets using, 34 D data validation (see Bean Validation; con‐ straints; validators, JSF) data-* attributes, input element, 59 DataSource class, 2 Decider interface, 270 @DecimalMax annotation, 204 @DecimalMin annotation, 204 decision element, 269–271 Decoder interface, 138–141 @Decorator annotation, 178 decorators, 178–179 decorators element, 179 @Default annotation, 172 Default validation group, 210 defining page, 38 delegate injection point, decorators, 178 @DELETE annotation, 77, 78 Index | 333 deny-uncovered-http-methods element, 27 @DenyAll annotation, 27 @Dependent annotation, 180 @DependsOn annotation, 150 Destination interface, 250–253, 255 @Digits annotation, 205 @Discriminator annotation, 221 Dispatch-based dynamic client, JAX-WS, 105– 107 disposer methods, 174 @Disposes annotation, 174 Don’t Repeat Yourself design pattern, 41 durable publisher/producer, 254 dynamic contextual objects, 198–201 DynamicFeature interface, 91 E .ear file extension, 156 EJB (Enterprise JavaBeans), 5, 8, 145 asynchronous invocation of methods, 159– 160 Embeddable API for, 164–165 injecting in EL expressions, 35 life-cycle callback methods, 151–154, 186 message-driven beans (MDB), 154–156, 253 movie application using, 277 no-interface view of, 146, 149 passivation of, 148 portable global JNDI name for, 156–157 remote access of, 146, 149 session beans singleton, 150–151 stateful, 145–148 stateless, 148–150 Timer Service, 160–164 transactions with, 157–159 @EJB annotation, 149 EJB Lite, 165–166 ejb-jar.xml file, 156 EL (Expression Language), 8 facelets using, 35 referencing resources, 37 @ElementCollection annotation, 220, 222 @Embeddable annotation, 220 embeddable classes, 220 Embeddable EJB API, 164–165 @Embedded annotation, 220 Encoder interface, 138–141 end element, 270 Endpoint class, 102, 128–132, 135–137 onClose method, 130 onError method, 130 Endpoint-based endpoints, JAX-WS, 102–103 Enterprise Technologies, 4 entities, 219–222 caching, 241–243 CRUD operations on, 229–232 entity manager, 222–226 inheriting from superclasses, 221 locking for, 239–241 persistence context, 222–226 persistence unit, 222–226 transactions for, 239–241 validating, 237–239 @Entity annotation, 219 entity interceptors, JAX-RS, 88, 92–94 entity listeners, 232–235 entity manager, 222–226 entity providers, JAX-RS, 82–84, 86 entity-listeners element, 234 entity-mappings element, 234 @EntityListeners annotation, 233 EntityManager interface createNamedXXX methods, 229 createNativeXXX methods, 229 merge method, 231 remove method, 232 EntityManagerFactory interface, 226, 242 EntityTransaction interface, 239 merge method, 239 persist method, 239 refresh method, 239 remove method, 239 rollback method, 240 error mapping, 29 error-page element, 29 event listeners, 17–20, 22, 41, 44, 46, 49 events, CDI, 182–183 example movie application Add Movie component, 304–310 Chat Room component, 292–298 Movie Points component, 318–325 problem statement for, 276–278 sample application for, 278–282 Show Booking component, 283–292 software requirements for, 275 Ticket Sales component, 310–318 334 | Index View and Delete Movies component, 299– 304 exception handling chunk-oriented batch processing, 264 mapping exceptions, 29, 87–88 exception-type element, 30 exclude element, 168, 264 explicit bean archive, 168 Expression Language (see EL) extended persistence context, 225 extension points, client-side, 47–49 F f: prefix, 34 f:ajax element, 43–46, 49, 72 f:convertDateTime element, 47 f:converter element, 46 f:convertNumber element, 47 f:event element, 46 f:passThroughAttribute element, 60 f:passThroughAttributes element, 60 f:validateBean element, 49, 211 f:validateDoubleRange element, 48 f:validateLength element, 48 f:validator element, 46, 49 f:valueChangeListener element, 49 f:view element, 58 facelets, 34–37 tag libraries for, 34 template client pages for, 36–37 templates for, 35–37, 57 Faces Flow, 51–57 defining flows, 53 nodes in, 52 packaging flows, 53–57 scope of beans in a flow, 53 faces-config.xml file, 51 @FacesBehavior annotation, 49 @FacesConverter annotation, 48 FacesMessage class, 49 @FacesValidator annotation, 49 fail element, 270 FetchType enumeration, 221 filter chains, JAX-RS, 92 filter element, 16 filter-mapping element, 16 filters JAX-RS, 88–92 servlet, 16–17 flow element, 268 flow-call element, 56 flow-definition element, 53, 56 flow-return element, 56 FlowBuilder class, 53 flows, JSF (see Faces Flow) @FlowScoped annotation, 53 fn: prefix, 34 @ForeignKey annotation, 228 @FormParam annotation, 77, 81 @Future annotation, 206 G @GET annotation, 74, 77 GlassFish server, 6, 327 @GroupSequence annotation, 211 H h: prefix, 34, 40 h:body element, 64 h:button element, 47, 63 h:commandButton element, 41, 44, 61, 72 h:commandLink element, 61 h:dataTable element, 61 h:form element, 62, 71 h:graphicImage element, 62 h:inputFile element, 71 h:inputHidden element, 62 h:inputSecret element, 63 h:inputText element, 40, 44, 63 h:inputTextArea element, 63 h:link element, 47, 64 h:outputFormat element, 64 h:outputLabel element, 64 h:outputLink element, 65 h:outputScript element, 43, 65 h:outputStylesheet element, 66 h:outputText element, 65 h:panelGrid element, 66 h:selectBooleanCheckbox element, 67 h:selectManyCheckbox element, 69 h:selectManyListbox element, 70 h:selectManyMenu element, 71 h:selectOneListbox element, 68 h:selectOneMenu element, 68 h:selectOneRadio element, 67 handlers, JAX-WS, 107–109 @HEAD annotation, 77, 78 Index | 335 @HeaderParam annotation, 7, 81 HTML5, 2 HTTP cookies, sending and receiving, 12, 14 HTTP headers, filters for, 88 HTTP messages, entity interceptors for, 88 HTTP methods, binding with JAX-RS, 77–79 HTTP requests binding resources to, 81–82 JAX-RS client API handling, 84–87 JSF support for, 46–47 servlets handling, 12–13 HTTP upgrade processing, 31–32 http-method-omission element, 27 @HttpConstraint annotation, 25 HttpHeaders interface, 82 HttpMethod class, 79 @HttpMethodConstraint annotation, 25 HttpServlet class, 11 (see also servlets) HttpServletRequest bean type, 186 HttpServletRequest class, 12 authenticate method, 28 getPart method, 30 getParts method, 30 getRequestDispatcher method, 15 login method, 28 logout method, 28 upgrade method, 31 HttpServletResponse class, 12 HttpServletResponse.sendRedirect method, 15 HttpSession bean type, 186 HttpSession interface, 14 HttpSessionActivationListener interface, 18 HttpSessionAttributeListener interface, 19 HttpSessionBindingListener interface, 19 HttpSessionListener interface, 18 HttpUpgradeHandler interface, 31 I I/O, nonblocking, 22–23 @Id annotation, 220, 228 IETF RFC 6455 Protocol, 121 if element, 51 implicit bean archive, 168 inbound-parameter element, 56 include element, 264 @Index annotation, 228 @Inheritance annotation, 221 inheritance from superclasses, 221 @Inject annotation, 170–171, 248 injection points, 35, 170–171 input element, 59 @Interceptor annotation, 175 interceptor chains, JAX-RS, 93 @InterceptorBinding annotation, 175 interceptors, 5, 9, 174–178 interceptors element, 177 InvocationCallback interface, 86 invoke application phase, JSF, 42 ItemProcessListener interface, 266 ItemProcessor interface, 258, 261 ItemReader interface, 258, 260 ItemReadListener interface, 266 ItemWriteListener interface, 266 ItemWriter interface, 258, 260 J Java API for XML Binding (see JAXB) Java API for XML Web Services (see JAX-WS) Java Community Process (see JCP) Java EE 6 Pocket Guide (O’Reilly), xiii Java EE 7, 1–3 architecture, 5–6 component specifications, 3–5 deliverables, 3 new features, 6 specifications, list of, 329–330 tutorial for, 277 Java EE Connector Architecture (see JCA) Java Message Service (see JMS) Java Persistence API (see JPA) Java Persistence Query Language (see JPQL) Java Specification Request (see JSR) Java Transaction API (see JTA) JavaMail, 10 JavaScript Object Notation (see JSON) JavaServer Faces (see JSF) javax.ejb package, 164 javax.faces library, 43 javax.persistence.criteria package, 229 javax.persistence.metamodel package, 229 JAX-RS (Java API for RESTful Web Services), 7, 73 Bean Validation with, 94–96 binding HTTP methods, 77–79 client API, 84–87 entity interceptors, 88, 92–94 entity providers, 82–84, 86 336 | Index exceptions, mapping, 87–88 filters, 88–92 movie application using, 277, 299–304, 326 resources accessing, 73–77 binding requests to, 81–82 restricting media types of, 79–80 JAX-WS (Java API for XML Web Services), 97– 98 Dispatch-based dynamic client, 105–107 Endpoint-based endpoints, 102–103 handlers, 107–109 Provider-based dynamic endpoints, 101–102 web service client, 103–105 web service endpoints, 98–101 WSDL mapping, 98 JAXB (Java API for XML Binding), 97, 100, 106 JCA (Java EE Connector Architecture), 10 JCP (Java Community Process), 3 JMS (Java Message Service), 2, 5, 7, 245 administered objects, 245 classic API for, 247 client, 245 message-driven beans for, 154 messages, 245 acknowledgment mode, 251 body component, 247 header component, 246 property component, 246 receiving asynchronously, 249, 253–254 receiving synchronously, 251–253 sending, 247–251 types of, 247 movie application using, 277, 318–325 Point-to-Point messaging model, 245 providers, 245 Publish-Subscribe messaging model, 246 quality of service, 246, 254 simplified API for, 247 temporary destinations, 255 JMSConnectionFactory class, 248 JMSConsumer interface, 252 JMSContext interface, 2, 248, 252, 255 @JMSDestinationDefinition annotation, 248 @JSMDestinationDefinitions annotation, 248 @JMSPasswordCredential annotation, 249 JMSProducer interface, 2, 255 JNDI name, for EJB, 156–157 job element, 259, 265, 267 JobListener interface, 266 JobOperator interface, 258, 262 JobRepository interface, 258 jobs, batch, 257 decisions in, 269–271 flows in, 268 partitioning, 271–274 sequence of, specifying, 267–271 splits in, 269 JPA (Java Persistence API), 5, 219 Bean Validation with, 237–239 caching entities, 241–243 CRUD operations on entities, 229–232 entities, 219–222 entity listeners, 232–235 locking, 239–241 movie application using, 326 persistence context, 222–226 persistence unit, 222–226 schema generation, 226–229 stored procedures, 235–236 transactions, 239–241 JPQL (Java Persistence Query Language), 229– 232 JSESSIONID cookie, 14 JSF (JavaServer Faces), 2, 9, 33 Ajax supported by, 43–46, 72 Bean Validation with, 49, 50–51 client-side extension points, 47–49 component tags, 60–72 composite components, 38–41 facelets, 34–37 Faces Flow, 51–57 HTTP GET requests with, 46–47 movie application using, 277, 283–292, 326 navigation rules, 51 passthrough attributes with, 59 request processing life-cycle phases, 41–43 resource handling, 37 resource library contracts, 57 server-side attached objects, 47–49 UI component tree for, 41 jsf.js file, 43 JSON (JavaScript Object Notation), 111–112 consuming, 112–113, 116 generating, 114–115, 117–119 movie application using, 304–310, 326 JSON Processing, 2, 6, 7, 83, 111–112 Object Model API, 116–119 Index | 337 streaming API, 112–115 JsonArray interface, 117 JsonArrayBuilder interface, 117 JsonBuilderFactory class, 118 JsonGenerator class, 114 JsonObject class, 117 JsonObjectBuilder class, 117 JsonParser class, 112 JsonParserFactory class, 112 JsonReader class, 116 JsonReaderFactory class, 116 JsonWriter class, 118 JSR (Java Specification Request), 329–330 JSR 101, 4, 6, 330 JSR 109, 4, 330 JSR 115, 4, 330 JSR 153, 6 JSR 181, 4, 330 JSR 196, 5, 330 JSR 222, 4, 330 JSR 224, 4, 97, 330 JSR 236, 4, 189, 329 JSR 245, 3, 329 JSR 250, 4, 329 JSR 316, 4 JSR 318, 4, 329 JSR 322, 4, 329 JSR 330, 4, 329 JSR 338, 4, 219, 329 JSR 339, 4, 73, 330 JSR 340, 3, 11, 329 JSR 341, 3, 329 JSR 342, 3 JSR 343, 4, 245, 329 JSR 344, 3, 33, 329 JSR 345, 4, 145, 330 JSR 346, 4, 167, 330 JSR 349, 4, 203, 330 JSR 352, 4, 257, 330 JSR 353, 4, 111, 329 JSR 356, 4, 121, 329 JSR 45, 3, 329 JSR 52, 3, 329 JSR 77, 4, 330 JSR 88, 4, 6, 330 JSR 907, 4, 215, 330 JSR 919, 4, 330 JSR 93, 4, 6, 330 JTA (Java Transaction API), 215 container-managed transactions, 216–218 entities, 239 movie application using, 327 @TransactionScoped annotation, 218 user-managed transactions, 215–216 jta-data-source element, 224 L life-cycle contexts, 167 life-cycle events CDI container, 184 entity listeners for, 232–235 entity validation for, 238 interceptors for, 151–154, 177 resource initialization or cleanup, 186 listener element, 267 listeners, 17 (see also event listeners) for batch execution, 266–267 entity listeners, 232–235 listeners element, 267 @Local annotation, 147 @Lock annotation, 151 locking entities, 239–241 @Logging annotation, 175 logical handlers, JAX-WS, 107 LogicalHandler interface, 107 M @MailSessionDefinition annotation, 10 @MailSessionDefinitions annotation, 10 ManageableThread interface, 198 managed beans, 5 managed threads, 197–198 ManagedExecutorService interface, 2, 189–194 execute method, 191 invokeAll method, 191 invokeAny method, 192 submit method, 191 ManagedScheduledExecutorService interface, 194–197 schedule method, 195 scheduleAtFixedRate method, 196 scheduleWithFixedDelay method, 197 ManagedTask interface, 192 ManagedTaskListener interface, 193 taskAborted method, 193 338 | Index taskDone method, 193 taskStarting method, 193 taskSubmitted method, 193 ManagedThreadFactor interface, 197–198 Management and Security Technologies, 4 @ManyToMany annotation, 221 @ManyToOne annotation, 221, 228 @MapKey annotation, 222 @MapKeyClass annotation, 222 @MapKeyColumn annotation, 222 MapMessage type, 247 @MappedSuperclass annotation, 221 mapper element, 272 @MatrixParam annotation, 81 @Max annotation, 204 MDB (message-driven beans), 154–156, 253 message payload (see entity providers) message-driven beans (see MDB) message-oriented middleware (see MOM) Message.setJMSExpiration method, 255 MessageBodyReader interface, 80, 83 MessageBodyWriter interface, 80, 83 MessageConsumer interface, 253 @MessageDriven annotation, 154, 254 MessageDrivenContext class, 156 MessageHandler class, 128, 135 MessageListener interface, 155 MessageListener.onMessage method, 254 MessageProducer interface, 251, 253 messages, JMS (see JMS: messages) metadata-complete element, 14, 25 methods, constraints for, 212–214 @Min annotation, 204 Model-View-Controller (see MVC) MOM (message-oriented middleware), 245 movie application example (see example movie application) @MultipartConfig annotation, 30 MVC (Model-View-Controller), 33 N @NameBinding annotation, 91 @Named annotation, 35, 172, 261 @NamedQueries annotation, 230 @NamedQuery annotation, 230, 231, 241 @NamedStoredProcedureQuery annotation, 235–236 namespaces for composite components, 39 for facelets tag libraries, 34 navigation rules, JSF, 51 navigation-rule element, 51 NetBeans, 275 @New annotation, 172 next element, 270 nonblocking I/O, 22–23 @NotNull annotation, 204, 207, 237 @Null annotation, 204 O Object Model API, JSON Processing, 116–119 ObjectMessage type, 247 observer beans, 182 @OnClose annotation, 126, 132 @OnError annotation, 126, 132 @OneToMany annotation, 221 @OneToOne annotation, 221 @Oneway annotation, 100 @OnMessage annotation, 123, 133 @OnOpen annotation, 126, 132 optimistic concurrency control, 240 @OPTIONS annotation, 77, 79 Oracle GlassFish Server, 6 ordering element, 24 orm.xml file, 234 P Part.getSubmittedFileName method, 31 partial page rendering, 43 partial view processing, 43 partition element, 272 PartitionMapper interface, 273 @Past annotation, 205 @Path annotation, 73, 74 @PathParam annotation, 74, 124 @Pattern annotation, 206, 207 payload (see entity providers) PbC (Programming by Contract), 212 @PermitAll annotation, 27 @PerPersist annotation, 232 persistence, 9 (see JPA) persistence context, 222–226 persistence element, 224 persistence unit, 222–226 persistence-unit element, 224 persistence-unit-metadata element, 234 persistence.xml file, 223, 226, 238, 241 Index | 339 @PersistenceContext annotation, 222 @PersistenceUnit annotation, 223 Point-to-Point messaging model, 245 portable extensions, CDI, 183–185 @POST annotation, 77 @PostActivate annotation, 154 @PostConstruct annotation, 150, 152, 186 @PostLoad annotation, 232 @PostPersist annotation, 232 @PostRemove annotation, 233 @PostUpdate annotation, 232 pre-persist life-cycle callback method, 238 pre-remove life-cycle callback method, 238 pre-update life-cycle callback method, 238 @PreDestroy annotation, 153, 186 @PreMatching annotation, 90 @PrePassivate annotation, 148, 153 @PreRemove annotation, 232 @PreUpdate annotation, 232 Principal bean type, 185 Priorities class, 93 @Priority annotation, 9, 93, 176, 178 process validations phase, JSF, 42 ProcessAnnotatedType event, 184 ProcessInjectionTarget event, 184 ProcessProducer event, 184 producer beans, 182 producer methods, 173–174 @Produces annotation, 79, 173–174 programmatic client endpoints, WebSocket, 135–137 programmatic server endpoints, WebSocket, 128–132 Programming by Contract (see PbC) properties element, 224 protocol handlers, JAX-WS, 107, 108 @Provider annotation, 80, 90 Provider-based dynamic endpoints, JAX-WS, 101–102 Providers interface, 82 providers, JMS, 245 Publish-Subscribe messaging model, 246 @PUT annotation, 77, 78 Q @Qualifier annotation, 171–172 quality of service, JMS, 246, 254 @QueryParam annotation, 7, 75 Queue interface, 251 QueueBrowser interface, 253 QueueConnectionFactory interface, 250 queues, JMS, 245 R Reader-Processor-Writer pattern, 258 ReaderInterceptor interface, 92 ReadListener interface, 22 Reference Implementation (see RI) @Remote annotation, 146, 147, 149, 156 render response phase, JSF, 43 Request interface, 82 request processing lifecycle phases, 41–43 RequestDispatcher class, 15 @RequestScoped annotation, 180 @Resource annotation, 190, 194, 197, 199, 253 resource library contracts, JSF, 57 resource packaging, 28–29 resource-env-ref element, 190 resource-env-ref-name element, 195, 198, 199 resource-env-ref-type element, 190, 195, 198, 199 resources files, referencing, 37 RESTful Web Services accessing, 73–77 binding requests to, 81–82 restricting media types of, 79–80 validation of, 94–96 server, conserving, 20–22 Response class, 87 RESTful Web Services, 7, 73 (see also JAX-RS) restore view phase, JSF, 42 retryable-exception-classes element, 264 RetryProcessListener interface, 265, 266 RetryReadListener interface, 265, 266 RetryWriteListener interface, 265, 266 RI (Reference Implementation), 3, 6 @RolesAllowed annotation, 27 Runnable interface, 190, 195 S scan element, 168 @Schedule annotation, 160 scheduled tasks, 194–197 schema generation, 226–229 340 | Index scopes, CDI, 179–180 @ApplicationScoped, 180 @ConversationScoped, 180 @DependentScoped, 180 @FlowScoped, 53 @RequestScoped, 180 @SessionScoped, 180 @TransactionScoped, 10, 218 @ViewScoped, 35 security authentication for WebSocket endpoints, 142–143 security principal name, checking, 185 servlets, 25–28 security-constraint element, 26 SecurityContext interface, 82 SEI (Service Endpoint Interface)-based end‐ point, 99 Serializable interface, 220 server-side attached objects, 47–49 ServerApplicationConfig interface, 130 @ServerEndpoint annotation, 122–127, 140 ServerEndpointConfig.Configurator class, 131 Service Endpoint Interface-based endpoint (see SEI-based endpoint) Service Provider Interface (see SPI) @ServiceMode annotation, 102 servlet element, 13 servlet-mapping element, 13 Servlet.service method, 31 ServletContainerInitializer.onStartup method, 15, 17, 20 ServletContext bean type, 186 ServletContext class, 14 addFilter method, 17 addListener method, 17, 20 addServlet method, 15 getContext method, 15 getRequestDispatcher method, 15 getResource method, 28 getResourceAsStream method, 28 getSessionCookieConfig method, 14 ServletContextAttributeListener interface, 18 ServletContextListener interface, 17 ServletContextListener.contextInitialized meth‐ od, 15, 17, 20 ServletInputStream class, 22 ServletOutputStream class, 22 ServletRegistration.setAsyncSupported method, 21 ServletRequestAttributeListener interface, 20 ServletRequestListener interface, 19 servlets, 8, 11 asynchronous processing of, 20–22 context for, 14 defining, 11, 13, 15 error mapping for, 29 event listeners for, 17–20 filters for, 16–17 HTTP cookies sent and received by, 12, 14 HTTP requests forwarded by, 15 HTTP requests handled by, 12–13 HTTP responses redirected by, 15 HTTP upgrade processing for, 31–32 initialization parameters for, 11, 13 lifecycle call methods, overriding, 13 multipart requests handled by, 30 nonblocking I/O for, 22–23 packaging, 14 resource packaging for, 28–29 security for, 25–28 URLs deployed at, 11 @ServletSecurity annotation, 25 session beans asynchronous processing of, 159–160 portable global JNDI name for, 156–157 singleton, 150–151 stateful, 145–148 stateless, 35, 148–150 Session interface, 253 commit method, 250 createXXXMessage methods, 251 getAsyncRemote method, 129, 135 getBasicRemote method, 129, 135 rollback method, 250 session tracking, 14 @SessionScoped annotation, 180 @Singleton annotation, 150 singleton session beans, 150–151 @Size annotation, 205, 207, 237 skippable-exception-classes element, 264 SkipProcessListener interface, 265, 266 SkipReadListener interface, 265, 266 SkipWriteListener interface, 265, 266 SOAP-Based Web Services, 97–98 (see also JAX-WS) @SOAPBinding annotation, 100 Index | 341 SOAPHandler interface, 108 specifications, 3–5, 329–330 (see also component specifications; JSR) SPI (Service Provider Interface), 183–185 split element, 269 SQL queries, 229–232 @SQLResultSetMapping annotation, 229 @Startup annotation, 150 @Stateful annotation, 146 stateful session beans, 145–148 @Stateless annotation, 35, 148 stateless session beans, 35, 148–150 step element, 259, 265, 267 StepListener interface, 266 @Stereotype annotation, 181 stereotypes, CDI, 181–182 stop element, 270 stored procedures, 235–236 streaming API, JSON Processing, 112–115 StreamMessage type, 247 superclasses, entities inheriting from, 221 synchronous communication, JMS messages, 251–253 T tag libraries, for facelets, 34 @Target annotation, 175, 207 tasks CDI beans as, 191 scheduling, 194–197 submitting asynchronously, 189–194 TCK (Technology Compliance Kit), 3, 6 template client pages, for facelets, 36–37 templates, for facelets, 35–37, 57 templating system, 34 @Temporal annotation, 221 TemporaryQueue.delete method, 256 TemporaryTopic.delete method, 256 TextMessage type, 247 threads, managed (see managed threads) @Timeout annotation, 162 Timer Service, EJB, 160–164 TimerService class, 161 Topic interface, 251, 253 TopicConnection interface, 253 TopicConnectionFactory interface, 250, 253 topics, JMS, 246 TopicSession.createDurableSubscriber method, 253 @Transactional annotation, 2, 10, 177, 216–218 transactional observers, 183 @Transactional.TxType annotation, 217 @TransactionAttribute annotation, 158 @TransactionManagement annotation, 157 TransactionManager.getStatus method, 218 transactions, 10 for asynchronous tasks, 192 committing, 250 container-managed, 157–159, 216–218 bean-managed, 157–159 entity, 239–241 rolling back, 250 user-managed, 215–216 @TransactionScoped annotation, 10, 218 @TransportProtected annotation, 27 type attribute, input element, 59 U ui: prefix, 34 ui:component element, 36 ui:composition element, 36 ui:define element, 36, 37 ui:fragment element, 36 ui:include element, 36 ui:insert element, 36, 57 UIComponent class, 60 update model values phase, JSF, 42 UriInfo interface, 82 user-data-constraint element, 26 user-managed transactions, 215–216 User.nameUpdated method, 49 UserTransaction bean type, 185 UserTransaction interface, 157, 192, 215–216 UserTransaction.getStatus method, 218 using page, 38 V @Valid annotation, 96, 209, 237 @ValidateExecutable annotation, 213 validation (see Bean Validation; constraints; val‐ idators, JSF) Validator.validate method, 239 ValidatorException class, 49 validators, JSF, 48 ValueChangeListener interface, 49 @Version annotation, 240 @Vetoed annotation, 9, 169 342 | Index view declaration language, 34 (see also facelets) @ViewScoped annotation, 35 W W3C JavaScript API, 121, 137–138 .war file extension, 28 RESTful resources in, 74 servlets packaged in, 14 session beans in, 156 web fragments, 6, 24–25 web service endpoints, JAX-WS, 98–101 Web Service Technologies, 4 Web Services Description Language (see WSDL) Web Technologies, 3 web-fragment element, 24 web-fragment.xml file, 24 web-resource-collection element, 26 web.xml file asynchronous tasks in, 190 context services in, 199 defining servlet filters in, 16 defining servlets in, 13 enabling asynchronous behavior in, 21 error mapping in, 30 managed threads in, 197 scheduled tasks in, 195 security constraints in, 26, 142 WebConnection interface, 31 @WebFault annotation, 100 @WebFilter annotation, 16 @WebInitParam annotation, 11, 13, 16 @WebListener annotation, 17 @WebMethod annotation, 99 @WebParam annotation, 99 @WebService annotation, 98, 103 @WebServiceProvider annotation, 101 @WebServlet annotation, 11 (see also servlets) WebSocket constructor, 137 WebSocket protocol, 2, 6, 121–122 annotated client endpoints, 132–135 annotated server endpoints, 122–127 authentication for, 142–143 encoders and decoders, 138–141 JavaScript API for, 137–138 movie application using, 277, 292–298, 326 programmatic client endpoints, 135–137 programmatic server endpoints, 128–132 WriteListener interface, 22, 23 WriterInterceptor interface, 92 WSDL (Web Services Description Language), 97, 98, 103–105 X XHTML 1.0, facelets using, 34 .xhtml file extension, 34, 38 XML, mapping to and from Java, 83, 97, 100, 106 @XmlRootElement annotation, 74, 75, 100 Index | 343 About the Author Arun Gupta is a Java Evangelist working at Oracle. As a founding member of the Java EE team, he works to create and foster the community around Java EE, GlassFish, and WebLogic. He led a cross-functional team to drive the global launch of the Java EE 7 platform through strategy, planning, and execution of content, marketing campaigns, and programs. He is extremely passionate about developers and loves to engage with partners, customers, Java user groups, Java champions, and others around the world to spread the goodness of Java. Arun has extensive speaking experience in more than 30 countries on myriad topics. An author, a prolific blogger at‐ ta, an avid runner, and a globe trotter, Arun is easily accessible at @arungupta. Colophon The animals on the cover of Java EE 7 Essentials are Asiatic glassfish (members of the family Ambassidae). Found only in the waters of Asia and Oceania, the fish in this family are divided into eight genera that include around 40 species. In addition to the Asiatic glassfish, the family also includes the Striped Glass Catfish, the Borneo Glass Catfish, the Duskyfin glassfish, and the Three-Striped African Glass Catfish. Most members of this family are quite small, but the larger species can grow to a maximum of 10 inches. The most popular member of Ambassidae among aquarium hobbyists is the Indian glassfish, due to its distinctive transparent body. In many species of glassfish, the internal organs and skeleton are visible through the skin. Unfortunately, this remarkable trait has led to the practice of injecting dye directly into fish to produce neon stripes or spots. This process is incredibly harmful to the fish, and most die during the procedure. Any that live are sold as “painted” or “disco” fish, but they are very susceptible to infection and disease and usually die within weeks or months. In 1997, the UK publication Prac‐ tical Fishkeeping started a largely successful campaign to stop merchants from stocking fish that have been dyed. While the movement was able to halt the sale of these fish in almost half the stores in the UK, the problem still persists in global markets. Despite a reputation of being difficult to keep, glassfish actually make excellent aquar‐ ium additions if given the right environment. Their natural habitats range from fresh to salt water depending on the species, but most prefer standing freshwater as opposed to brackish salt water. It is better to keep a school instead of an individual or a pair, as a group of these fish will act much more energetically and boldly than would one or two alone. The cover image is from a loose plate, origin unknown. The cover font is Adobe ITC Garamond. The text font is Adobe Minion Pro; the heading font is Adobe Myriad Con‐ densed; and the code font is Dalton Maag’s Ubuntu Mono.





需要 8 金币 [ 分享pdf获得金币 ] 0 人已下载





下载需要 8 金币 [金币充值 ]
亲,您也可以通过 分享原创pdf 来获得金币奖励!