Wednesday, November 26, 2014

Cannot Uninstall JavaFX SceneBuilder 1.0 with JDK 8

I was recently removing some of the software development applications, tools, and files I had used from an old Vista-based laptop because the people who are primarily using that laptop now have no interest in software development. As part of that effort, I tried to remove JavaFX Scene Builder 1.0, which I had installed a couple of years ago on that laptop. I hadn't used it recently (JavaFX Scene Builder 2.0 is available) but I had not removed the version from the laptop when I stopped using that old version.

My first attempt to remove JavaFX Scene Builder 1.0 was via the Windows Vista menu option Control Panel | Programs | Uninstall a program. The next screen snapshot shows this version of JavaFX Scene Builder 1.0 that I wanted to install along with the version of Java installed on that machine (JDK 8 and Java 8 JRE). No versions of Java (JDK or JRE) before Java 8 were on this machine.

The next screen snapshot demonstrates the normal requested confirmation of the removal of JavaFX Scene Builder 1.0.

Clicking the "Yes" button on the confirmation dialog just shown led to the removal process beginning.

Unfortunately, the removal of JavaFX Scene Builder 1.0 aborted and showed the error message: "No suitable 32-bit Java Runtime Environment (JRE) has been found. You should install Java 6 Update 29 (32-bit) or above OR Java 7 Update 2 (32-bit) or above."

I was a bit surprised that JavaFX Scene Builder could not be uninstalled with a Java 8 JRE installed on the machine. I tried to uninstall it more than once to make sure, but it was resistant to removal with only JRE 8 installed. I ended up simply removing the JavaFX Scene Builder 1.0 directory with Windows Explorer as shown in the next screen snapshot.

Because I could not use the uninstaller to remove JavaFX Scene Builder 1.0, I also needed to manually remove the shortcut as shown in the next screen snapshot.

It was not a big deal to remove the directory and shortcut when the installer was unable to remove JavaFX Scene Builder 1.0 from this machine. It also would not have been too difficult to download and install a Java SE 7 JRE to use in uninstalling JavaFX Scene Builder. However, I was a bit surprised that it was written so that an appropriate version of JRE 6 or JRE 7 was required. It explicitly prevents JRE 8 or any future JRE from being used to uninstall it.

I saw this same type of situation recently with a different tool in a different environment. In that case, the version of SQLDeveloper being used would only work with a certain specified range of updates for Java SE 6 and not for any Java SE 6 updates outside of that range and not for any versions of JDK 7 or JDK 8.

Conclusion

There is a software development reminder (or lesson to be learned) from this. It is easy as humans to think only about the current timeframe and about the past, but we as software developers should put some thought into what the future holds. The prevailing version of software is not always going to be the prevailing version and when our software's documentation or the software itself advertises supporting certain versions "and above" or "and later," then we should probably not put an explicit check in our code that forces the software to have the one of the expected major revisions or that caps the supported versions.

Monday, November 24, 2014

Book Review: RESTful Java Patterns and Best Practices

Bhakti Mehta's RESTful Java Patterns and Best Practices was recently published by Packt Publishing. Consisting of six chapters and an appendix spanning approximately 125 substantive pages, its subtitle is, "Learn best practices to efficiently build scalable, reliable, and maintainable high performance RESTful services."

Preface

The Preface of RESTful Java Patterns and Best Practices begins with a description of why REST is important today. It includes several short summaries of each of the book's chapters. The Preface explains that Maven 3 and GlassFish 4 are required to build and run the book's examples and states that the book is designed as "a perfect reading source for application developers to get familiar with REST."

Chapter 1: REST – Where It Begins

RESTful Java Patterns and Best Practices's initial chapter provides a single paragraph on SOAP/WSDL-based web services before turning attention to REST-based web services. The basic characteristics of and increased "-ilities" provided by REST are described. The Richardson Maturity Model is also examined in some detail. I'm not sure that the Richardson Maturity Model clears things up or muddies them by encouraging interchangeable use of the terms HTTP and REST.

The first chapter includes brief descriptions of the characteristics of safe methods and of idempotent methods and describes which HTTP methods fit each category. The chapter then lists several "design principles for building RESTful services" before describing each in greater detail. This is section provides a brief and highly readable introduction to the basics of REST.

Chapter 1's introduction of the Java API for RESTful Web Services (JAX-RS) includes simple examples of turning POJOs into REST resources using JAX-RS annotations such as @GET, @POST, @Path, @Produces, @Consumes, and @ValidateOnExecution.

Chapter 1 provides a nice introduction to the Client API that is new to JAX-RS 2.0. It also briefly discusses some other approaches one can use to communicate and work with REST-based services: curl, Postman on Chrome, Advanced REST Client for Google Chrome, and JSONLint. Both curl and Postman get extra attention including a color screen snapshot of Postman in the electronic edition I reviewed.

The first chapter concludes with a bullet-format list of "best practices when designing resources," a list of related online resources, and a Summary. Overall, this first chapter is a nice high-level introduction to REST and to Java's approach to REST via JAX-RS. The code examples are simple and short and easy to understand. Just enough detail is provided to get a feel for REST and JAX-RS.

Chapter 2: Resource Design

Chapter 2 of RESTful Java Patterns and Best Practices delves more deeply into HTTP and REST concepts such as content negotiation (including contrasting use of HTTP headers versus URL patterns), alternative resource representation (MessageBodyReader and MessageBodyWriter, StreamingOutput, and ChunkedOutput), Jersey's JSON support (ObjectMapper, @XMLRootElement, JsonArray, and JsonObject), API versioning (comparing URI, request query parameter, and Accept header approaches), HTTP response codes, and the JAX-RS classes Response and ResponseBuilder.

The second chapter provides greater details regarding application of JAX-RS to REST-based application implementation. The examples are relatively short and clear and illustrate well the points being made.

Chapter 3: Security and Traceability

The third chapter opens up with two paragraphs explaining why security and traceability are important in today's REST-based applications. The specific security and traceability topics discussed in this chapter are logging in REST-based applications, exception handling in REST-based applications, validation patterns, and federated identity.

The section on logging from a REST-based application demonstrates writing of a servlet filter (annotated with @WebFilter and implementing Filter) that can log certain metadata about each request as each request occurs. This section also outlines some logging best practices that I'd say are general logging best practices rather than REST-specific logging best practices.

Chapter 3's section on validating services states, "JAX-RS supports the Bean Validation to verify JAX-RS resource classes." The text and accompanying code samples demonstrate use of bean validation with standard annotations such as @ValidateOnExecution, @Valid, and @NotNull and a custom annotation @VerifyValue. This section also demonstrates with code and explanation how to create a custom exception mapper (implementation of ExceptionMapper that "catch[es] thrown application exceptions and write[s] specific HTTP responses.").

Part of Chapter 3 focuses on authentication and authorization. This section introduces Security Assertion Markup Language (SAML) and SAML Web Browser Profile for authentication and OAuth (open authorization) for authorization. This section has some nice graphics (with a bit of color in the PDF version) depicting how authentication with SAML and authorization with OAuth work at a high level.

Chapter 3's coverage or authorization includes more details on characteristics of OAuth 2.0. Access and refresh tokens are covered as is the level of support for OAuth 2.0 provided by Jersey (the Jersey implementation supports client side only and Authorization Code Grant Flow).

The third chapter includes a section titled "Best practices for OAuth [2.0] in the REST API." Although these seem to be generally applicable to use of OAuth whether REST is involved or not, I liked the table presenting different situations and when SAML or OAuth is preferable. There is a very brief section in Chapter 3 that introduces OpenID Connect, which the author describes as "a simple REST- and JSON-based interoperable protocol built on top of OAuth 2.0."

Before concluding with the summary and recommended reading sections typical of chapters in RESTful Java Patterns and Best Practices, the third chapter briefly outlines "REST architectural components" to be covered in more detail later. One "recommended reading" that I found particularly interesting is OAuth 2.0 and the Road to Hell.

Chapter 4: Designing for Performance

RESTful Java Patterns and Best Practices's fourth chapter advertises itself as covering "advanced design principles related to performance that every developer must know when building RESTful services." Discussion of strong and weak HTTP caching headers is preceded by an overview of general caching principles. A code listing and accompanying explanation demonstrate how to specify HTTP caching headers in JAX-RS responses. Similarly, this section also looks at the ETag response-header field and how to apply it to a JAX-RS response. The section of Chapter 4 on caching concludes with a brief description of RESTEasy's extension to JAX-RS caching.

"Asynchronous and long-running jobs in REST" is the second major topic of Chapter 4. This section uses code listings, textual explanations, and sequence diagrams to demonstrate use of JAX-RS 2.0 support for asynchronous processing with constructs such as AsyncResponse, @Suspended, CompletionCallback, ConnectionCallback, InvocationCallback, and Java SE Future interface.

The "Asynchronous resources best practices" section of Chapter 4 briefly describes "best practices when working with asynchronous RESTful resources." These tend to be best practices for working with HTTP asynchronously whether in REST or not.

There is a section in Chapter 4 that discusses dealing with partial updates in a REST application using PATCH, PUT, or POST. This section demonstrates creation of an annotation called @PATCH to annotate JAX-RS methods to be used for patch functionality.

The final section of Chapter 4 of RESTful Java Patterns and Best Practices before its summary and recommended reading section is on JSON Patch. This section provides a brief overview of JSON Patch and provides code listing and explanations of how to use JSON Patch.

Chapter 5: Advanced Design Principles

The promise of RESTful Java Patterns and Best Practices's fifth chapter is to cover "advanced design principles that every developer must know when designing RESTful services." The covered topics are rate-limiting patterns, response pagination, internationalization and localization, REST pluggability and extensibility, and some miscellaneous topics. The section on rate-limiting pagination is relatively lengthy and includes code snippets and discussion as well as an outline of some best practices for reducing and avoiding rate-limiting pagination.

"Response pagination" is covered in the fifth chapter, which looks at three types of response pagination: Offset-based pagination, Time-based pagination, and Cursor-based pagination. The chapter then provides an example of implementing offset-based pagination with JAX-RS.

Chapter 5's section on internationalization and localization describes the setting of localization parameters on HTTP headers, on query parameters, and as part of REST responses. Discussion in this section on runtime content negotiation covers HTTP headers Accept-Language and Content-Language and application of the JAX-RS Variant class.

The "Miscellaneous topics" section of Chapter 5 discusses Hypermedia as the Engine of Application State (HATEOAS), which I believe is one of the most commonly misunderstood and under-appreciated features of REST for those new to REST. This chapter's introduction, which includes examples, is a relatively straightforward and concise introduction to the topic. After introducing HATEOAS, the chapter uses an example of PayPal's REST API support for HATEOAS to illustrate real-world application of HATEOAS.

Another Chapter 5 "Miscellaneous Topic" addresses REST extensibility. This is only covered very briefly (single paragraph) and makes assertions about REST being more maintainable and readable (presumably than SOAP-based web services) with lightly offered justification for these claims. Given how little concrete evidence (and no practical examples) is provided, this section is not very compelling.

Chapter 5 concludes with a brief discussions of topics related to documenting and testing REST-based applications. The most appealing part of this coverage for me was the reference to tools that can be used for testing and documenting REST-based applications. This section introduces REST Assured, which it describes as "the Java DSL for easy testing of RESTful services," and provides a simple illustrative example of this in action. The coverage of Swagger does not illustrate its use, but does describe it as "a language-agnostic framework implementation for describing, producing, consuming, and visualizing RESTful web services."

Chapter 6: Emerging Standards and the Future of REST

Although the Fielding dissertation that codified the REST concept was published in 2000, it continuing rising popularity has meant new developments in understanding and applying of the REST architectural style and in the available related tooling. This chapter begins by describing real-time APIs and describing polling and the disadvantages of polling.

Chapter 6 provides brief explanations of how PubSubHubbub and streaming can each be used to address the limitations of polling. Both of these approaches are explained with text and simple graphics. The section on streaming discusses server-sent events (SSE) and their nonstandard support in Jersey.

RESTful Java Patterns and Best Practices's final chapter also introduces WebHooks, which it defines as "a form of user-defined custom HTTP callbacks." This section uses text description, simple graphics, and coverage of implementing case studies to explain this topic. The WebSockets protocol is also covered in the sixth chapter and is described as "a protocol that provides full-duplex communication channels over a single TCP connection." WebSockets is explained with text descriptions, simple graphics, a table, and a code listing. A couple paragraphs each are also dedicated to introducing (at a conceptual level) XMPP and BOSH over XMPP.

Chapter 6 includes a section with text and a table that compares and constrasts WebHooks, WebSockets, and Server-Sent Events. Chapter 6's section "REST and Micro Services" briefly describes "different advantages of Micro Services as compared to monolithic services."

As is the case with the previous five chapters, Chapter 6 ends with a "Recommended Reading" section and a "Summary." The "Summary" is mostly a summary of the chapter rather than the book, though there is a reference to another book co-authored by this book's author: Developing RESTful Services with JAX-RS 2.0, WebSockets, and JSON. The summary for the overall book is left to the Appendix, which is really just another chapter and which I review later in this post.

The sixth and final chapter of RESTful Java Patterns and Best Practices is a high-level overview of trending considerations for REST-based applications. This chapter has very little Java-specific (or JAX-RS-specific) content.

Appendix

Although RESTful Java Patterns and Best Practices's table of contents lists six chapters and an appendix, the Appendix feels just like the six chapters. It not only has "Recommended Reading" and "Summary" sections like its preceding chapters, but it even includes text that refers to "this chapter." The chapter/appendix introduces three REST APIs: REST API from GitHub, Open Graph API from Facebook, and REST API from Twitter. For me, the most interesting aspect of these introductions was how the author illustrated some of the patterns covered previously in the book from each covered API's perspective. This provides reinforcement with concrete APIs of some of the previously discussed concepts and patterns.

The Appendix's "Summary" summarizes the appendix and the entire book.

General Observations

  • The code listings in RESTful Java Patterns and Best Practices are black text on white background with no color syntax (even in the PDF version) and no line numbers. Most of the code listings are short enough that color syntax and line numbers are not as important as they otherwise might be.
  • I liked the approach taken in RESTful Java Patterns and Best Practices of presenting small snippets of code to illustrate points being made and referencing the code available for download for additional and context code.
  • There are several illustrative graphics in RESTful Java Patterns and Best Practices, a few of of them with multiple colors in the PDF edition and some of them in grayscale, and many of them black font on white background, even in the PDF edition.
  • There are some typos in RESTful Java Patterns and Best Practices. They're generally minor and I provide some examples here to demonstrate their nature:
    • One sentence states, "JAX-RS 2.0 had newer Client APIs for accessing RESTful resources."
    • The section introducing JAX-RS annotations discusses @PATH when it really should be @Path.
    • The section on JSON and Jersey references JSONArray and JSONObject when JsonArray and JsonObject are intended.
    • The acronym PPI when spelled out only has an opening parenthesis and not a closing parenthesis.
  • I liked how each chapter included a "Recommended Reading" section with several freely available online resources, most of which had been referenced earlier in the chapter.
  • I liked the Appendix's use of three popular REST APIs to illustrate some of the concepts and patterns introduced in the book's six chapters.
  • In some cases, I would have liked to see more Java/JAX-RS implementation details for certain patterns, especially in the sixth chapter.
  • Other reviews of RESTful Java Patterns and Best Practices are available and worth checking out for a more complete overall picture of the book based upon multiple perspectives:

Conclusion

RESTful Java Patterns and Best Practices introduces basic REST concepts, patterns, and practices and how to apply many of those patterns and concepts with JAX-RS. This book is probably best suited for those looking for introductory information on a broad set of considerations pertinent to REST applications and implementing those considerations with Java and JAX-RS. For those seeking more detailed coverage of REST principles and JAX-RS application of those principles, RESTful Java with JAX-RS 2.0 might be more appropriate.

Saturday, November 15, 2014

Book Review: JavaScript Promises Essentials

Because JavaScript Promises are a trendy web development topic that I know very little about, I accepted Packt Publishing's offer to review the electronic (PDF) edition of Rami Sarieddine's JavaScript Promises Essentials. Sarieddine provides introduces this book on his blog post JavaScript Promises Essentials. The subtitle of the book is, "Build fully functional web applications using promises, the new standard in JavaScript." JavaScript Promises Essentials is a short book with six chapters and a preface covering approximately 70 pages of substantive content.

Preface

The "Preface" of JavaScript Promises Essentials states that the book is "a practical guide to the new concept of promises" that "presents a single resource replacing all the scattered information out there about the topic" (I added the links). The Preface introduces the concept of promises and why they are useful.

JavaScript Promises Essentials's Preface provides very brief summaries of each of its chapters before covering what readers of the book need when reading it. The author states that readers "just need an HTML and JavaScript editor" and recommends three candidates: Microsoft Visual Studio Express 2013 for Web, Microsoft's WebMatrix, or jsFiddle. The Preface also suggests that JavaScript Promises Essentials is designed for "all developers who are involved in JavaScript programming" with special appeal for those "interested in learning about asynchronous programming in JavaScript and the new standard that will make that experience much better."

Chapter 1: JavaScript Promises – Why Should I Care?

The initial chapter of JavaScript Promises Essentials provides a brief summary of JavaScript and how it became a popular programming language, especially in web browsers. The chapter talks about how web development and user experience has progressed. The chapter provides a basic overview and examples of applying JavaScript event handlers and callback functions.

Chapter 1 also includes a section "Why should I care about promises?" that starts with a definition of promise quoted from the Promises/A+ web page: "A promise represents the eventual result of an asynchronous operation." After presenting this simple introductory definition, the chapter then moves onto further elaboration on the nature of promises (incuding having state and being immutable). This section provides a nice overview of what JavaScript promises are and the syntax for them.

Part of Chapter 1 demonstrates how complicated chained callbacks can become and how much easier they are to read when presented as promises instead. The chapter concludes with an interesting summary: "Promises are a pattern that allows for a standardized approach in asynchronous programming" and enables "developers to write asynchronous code that is more readable and maintainable."

Chapter 2: The Promise API and Its Compatibility

JavaScript Promises Essentials's second chapter covers "current browser support for the promises standard" and "JavaScript libraries out there that implement promises and promise-like features." Coverage of the Promises API begins by contrasting the Promises/A+ specification with the Promises/A specification and focusing on additions, removals ("omissions"), and clarifications. This discussion gets fairly deep into the descriptions of the rules to be supported by Promises/A+ implementations.

The second chapter's discussion rises back to a higher level of discussion on "browser support and compatibility" for promises. This includes a reproduction (in color in electronic edition) of the Promises portion of the "ECMAScript 6 compatibility table" provided by kangax. The author introduces Remy Sharp's concept of a polyfill ("piece of code (or plugin) that provides the technology that you, the developer, expect the browser to provide natively") and then references a particular polyfill for web browsers that don't support promises natively.

Chapter 2 moves onto coverage of "libraries with promise-like features" and provides descriptions of libraries that implement "the promises concept" (though not necessarily ECMAScript 6 or Promises/A+ compliant). The briefly described libraries are kriskowal/q, tildeio/rsvp.js, cujojs/when.js, the then collection, and jQuery.Deferred().

Chapter 3: Chaining of Promises

The third chapter of JavaScript Promises Essentials revisits the discussion from the first chapter about the disadvantages of using chained callbacks in JavaScript and how promises address those callbacks. The author states that promises provide a "straightforward, standard mechanism to chain asynchronous operations." This short chapter provides fairly detailed introductory examples of chaining promises.

Chapter 4: Error Handling

The fourth chapter of JavaScript Promises Essentials begins with a brief explanation of the challenges of dealing with asynchronous error handling in JavaScript before looking at how promises address these challenges. Discussion and examples illustrate use of then, catch, onFulfilled, and onRejected.

Chapter 5: Promises in WinJS

The focus of Chapter 5 of JavaScript Promises Essentials is on WinJS, an implementation of Promises. The chapter briefly introduces WinJS and advantages of using WinJS. This discussion includes mention of the increasing number of environments supporting WinJS and the open sourcing of WinJS. The WinJS namespace is introduced with an introduction to its basic features including xhr and Promise.

Unsurprisingly, the fifth chapter emphasizes the WinJS.Promise object. The three main components of a WinJS.Promise object (Constructors, single Event, and Methods) are discussed. The discussion on WinJS.Promise's methods contrasts the then and done methods. This section also explains that WinJS is compliant with Promises/A, but not tested for compliance with Promises/A+ and explains practical ramifications of this.

JavaScript Promises Essentials's fifth chapter includes an example (including color screen snapshot) of using Visual Studio to apply a WinJS promise. The example includes use of WinJS.Utilities.ready and WinJS.xhr. I like that the author recommends http://try.buildwinjs.com/ for those interested in trying out WinJS. For those who are not using WinJS, this chapter could probably be skipped, though there are some general ideas of promises that come out in the chapter even as it discusses WinJS specifically.

Chapter 6: Putting It All Together – Promises in Action

Chapter 6 of JavaScript Promises Essentials begins by explaining and demonstrating creation of "a minimal JavaScript library that implements promises." I found this final chapter of JavaScript Promises Essentials to be one of the more interesting as the explanations of building a promise implementation in JavaScript definitely provided concreteness that helped solidify my understand of JavaScript promises.

Once the simple promises implementation is built, the chapter moves onto using that implementation in examples. The chapter's summary also serves as a summary of the entire book.

General Observations

  • JavaScript Promises Essentials provides a general overview of JavaScript promises fit for general development. However, it is is particularly relevant for Windows developers with a chapter focused on a Windows-specific implementation of Promises.
  • Some of the text in the book is a bit choppy and some of it I'm not even sure conveys what was originally intended. Here is an example: "Callbacks are lightweight since we need to add extra libraries."
  • There are a few illustrations in JavaScript Promises Essentials. Some of them are in color and some are in grayscale even in the PDF. In one case, a flow chart in chapter 4, the text references green and red colors but the illustration is grayscale.
  • The code listings are black font on white background with proper indenting but without line numbers or color syntax highlighting.
  • Because book reviews are opinionated by nature, it can be useful to read several different reviews for different opinions. Other reviews can be found (or likely soon will be found) at the following sources:

Conclusion

JavaScript Promises Essentials covers one of the trendiest concepts (promises) in one of today's most popular languages (JavaScript). The book is no longer than it needs to be and provides a nice overview of implementing and using promises in JavaScript. It is especially well suited for Windows developers with one of its six chapters entirely focused on WinJS, but the other five chapters are of benefit to anyone who wants to know more about applying promises in JavaScript.

The information in JavaScript Promises Essentials is generally conveyed well, though there are some awkward (and sometimes too lengthy) sentences. Some of the book's strengths include coverage of the Promises/A and Promises/A+ standards, coverage of the current state of promises in JavaScript, and description of current JavaScript Promises implementations and libraries.

Thursday, October 30, 2014

Book Review: Play Framework Essentials

This post is a review of Julien Richard-Foy's recently published Play Framework Essentials (Packt Publishing). Play Framework Essentials consists of seven chapters and approximately 180 pages of substantive content. The book's subtitle is, "An intuitive guide to creating easy-to-build scalable web applications using the Play framework."

Preface

The Preface of most Packt Publishing books is a great place to start when trying to decide whether to read a Packt Publishing book. This is because the Packt Publishing Prefaces, including the Preface of Play Framework Essentials, frequently summarize each of the chapters of the book (one to three sentences per chapter in this case), describe what is needed for using the book's examples (Play 2.3.x, JDK 6 or newer, and a web browser in this case), and who the target audience is ("Java or Scala developers who already have some knowledge of web development" in this case).

Chapter 1: Building a Web Service

With a title that include the word "essentials", one might expect the book to be light of "fluffy" text and this is the case with Play Framework Essentials. The initial chapter of Play Framework Essentials starts off fast with a very brief description of what the Play Framework is before diving immediately into the first example that shows the Scala and Java versions of the service layer. The chapter then explains how to bootstrap a Play Framework application with Typesafe Activator.

The remainder of the chapter demonstrates building a simple application with the Play Framework. Along the way, the chapter introduces sbt (described as "a build tool for Scala projects"), Human-Optimized Config Object Notation (HOCON) for configuration, URL routing in Play, curl (for testing connectivity to session via HTTP), building HTTP responses with HTTP status codes, serializing data in JSON (includes mention of significant differences between implementing in Java or Scala), reading JSON data, validating JSON data.

Chapter 2: Persisting Data and Testing

Chapter 2 of Play Framework Essentials begins with a coverage of Play's support for integrated testing with specs2 (Scala) and JUnit (Java). There is a section that describes Play's use of Scala's reverse routing. The test-focused portion of the second chapter ends with discussion regarding effective writing of HTTP tests and "running a fake Play application."

The second half of Play Framework Essentials's second chapter is focused on database persistence with specific focus on use of Play's JDBC plugin and JPA plugin. After looking at use of JDBC-based persistence, the chapter moves to coverage of using Slick (Scala) and JPA (Java).

Part of Chapter 2's coverage of database persistence with Play discusses use of GlobalSettings to use startup of a Play application to enable database fixtures. Play's database evolutions support is also covered. Chapter 2 concludes with a section on using H2 as an in-memory database for testing code related to relational databases.

Chapter 3: Turning a Web Service into a Web Application

The third chapter of Play Framework Essentials is about building a web application with user interface from a web service. The chapter introduces the template engine Twirl and provides several examples of syntax and constructs used with the template.

The middle portion of Chapter 3 deals with HTML forms. In particular, it covers generation of forms and reading and validating form data. Discussion touches on Play's HTML helpers and how these can be customized. The chapter's section on form validation specifically covers both the Java validation API and the Scala validation API. The chapter introduces Scala-based content negotiation and provides examples of how to write "some helper functions similar to the Scala content negotiation API" for Java.

Play Framework Essentials's third chapter concludes with an introduction of Selenium as an approach to "programmatically drive a web browser" and an introduction of FluentLenium as "a library that provides a fluent interface for the [Selenium] WebDriver." This section of the chapter demonstrates their use with Java and Scala to test the web interface.

Chapter 4: Integrating with Client-side Technologies

Chapter 4 of Play Framework Essentials continues from where Chapter 3 left off. While Chapter 3 discussed converting web services into web applications, Chapter 4 covers integrating traditional web client-side technologies with the applications built on top of the Play framework. The author points out an interesting observation regarding Play and these client-side technologies: "The Play framework essentially focuses on the server-side part of your application and gives you freedom on which client-side technology to use." Chapter 4 focuses on the features that Play does provide to assist with the development of the client.

The first client-side-supporting feature of Play discussed in Chapter 4 is serving of static (or public) assets. JavaScript reverse routing is another Play feature covered in this chapter.

The fourth chapter introduces sbt-web as "an sbt plugin family" that "can manage ... processing steps" such as generating JavaScript from higher-level languages (sbt-coffeescript and sbt-less) and concatenating (sbt-rjs), minifying (sbt-uglify), and compressing (sbt-gzip) code. It demonstrates examples of each of these functions implemented using an sbt plugin. The chapter also discusses using sbt-web plugin's support of WebJars as "a repository of client-side artifacts" and using the sbt-mocha plugin to "run Mocha tests from the sbt test runner."

Play Framework Essentials's fourth chapter ends with a more substantial "Summary" section than one typically sees in books. In fact, it includes a useful graphical representation of how the plugins covered in the chapter fit together is the "assets processing pipeline."

Chapter 5: Reactively Handling Long-running Requests

Chapter 5 of Play Framework Essentials "presents the challenges of stream processing and the way the Play framework solves them." The chapter begins by referencing Benjamin Erb's diploma thesis Concurrent Programming for Scalable Web Architectures and introducing Play's "evented execution model." The author explains how the Scala model can be better, but warns that caution needs to be used to explicitly ensure that threads are not blocked. He introduces Play's support for Scala's Future API to allow for asynchronous blocks. The author also describes the need to use a distinct execution context to handle blocking functionality such as JDBC interaction with a relational database. This section is also useful because it introduces and briefly explains Akka.

Another significant section of Chapter 5 introduces Iteratee, which the author describes as "an incremental computation" and which he warns should be used only with Scala (not with Java). Enumerators are introduced by comparing them to iteratees: "Streaming results using enumerators Iteratees make it possible to consume streams of data in a non-blocking way. Conversely, enumerators produce data streams in a non-blocking way."

The Summary of Chapter 5 states, "This chapter detailed a lot of things on the internals of the framework." That might be an understatement. There is a lot of detailed description of the internal workings of the Play Framework in this chapter. I felt like this chapter really points out some of the distinguishing features of Play.

Chapter 6: Leveraging the Play Stack – Security, Internationalization, Cache, and the HTTP Client

Play Framework Essentials's sixth chapter begins by articulating the topics covered in the chapter: security (authentication, cross-site scripting, cross-site request forgery, HTTPS), cache, internationalization, and HTTP client. The section of authentication explains and illustrates using Java and Scala examples how Play supports session scope/cookies in conjunction with authentication. The sections on cross-site scripting (XSS) and cross-site request forgery (CSRF) explain tactics that can be used to avoid those vulnerabilities.

The portion of Chapter 6 covering CSRF delves into Play's support for HTTP request filters. It uses this introduction to Play filters to look at Play's CSRF Filter, which is described as a filter that "automatically checks that the CSRF token of a form submission corresponds to the one in the client's session."

Chapter 6's section on HTTPS states that Play's default is to "use only HTTP." This section then demonstrates configuring HTTPS via system property specification.

Chapter 6 describes Play's cache support (which is built upon Ehcache): "Play provides a minimal cache library and some controller level caching features that can help you leverage both client-side and server-side caches." The coverage of Play's cache support includes Java and Scala examples and talks about client-side and server-side caching. The chapter's discussion of Play Framework's internationalization support also covers both Scala and Java examples.

The sixth chapter concludes with sections on calling remote web services and begins with an introduction of OAuth 2.0. The chapter then proceeds to discuss how to connect to the reader's "preferred social network" using an OAuth client to call the HTTP API of the preferred social network.

Chapter 7: Scaling Your Codebase and Deploying Your Application

The final chapter of Play Framework Essentials "presents common code patterns you want to use in order to keep a productive code base." The chapter begins by discussion how to apply Play's action builders to make an "action's logic reusable and composable." The chapter then goes on to discuss use of dependency injection to achieve greater modularity. An example using Guice is presented as part of this discussion on dependency injection. The section of Chapter 7 on mocking applies Mockito.

Chapter 7 also looks at separating application code into separate independent artifacts with specific focus on splitting the controller into multiple artifacts. Th chapter then moves onto deployment with brief sections on deploying to traditional infrastructure and deploying to the cloud. There is also a section on distinguishing between development and production modes using different configuration files or system properties.

General Observations
  • Play Framework Essentials provides examples in both Scala and Java. There are a couple of advantages of this. The first is that it allows developers to use the language they are more comfortable with or are allowed or expected to use when using Play. The second advantage is that it allows Java developers to learn more about Scala by comparing Scala examples to Java examples. The only downside is that explanations take longer when both languages are used, but I consider the value of examples in both languages greater than the cost. It is fairly easy to skip over the examples written in the language that is not of interest. I also like that the author mentions when certain features are only available in Scala or in Java.
  • The code listings in Play Framework Essentials tend to be well-formatted. The biggest downside of these code listings is their lack on line numbers and the black text on white background (no color syntax highlighting).
  • Play Framework Essentials includes several graphics depicting architecture and other high-level concepts. Although these generally serve their purpose of illustrating what is being described, it would have been nice to have some color in more of these in the electronic version rather than the grayscale presentation of several of them. However, these grayscale images are sharp enough that I suspect they present well in printed copies.
  • Although Play Framework Essentials has under 200 pages and largely focuses on "essentials" of the Play Framework, I still felt like there was a lot of detail in this book. The book contains low-level and high-level details, but spends (or wastes, depending on your perspective) little time on introductory and historical details. All chapters are relatively technically detailed, but Chapters 5 through 7 are particularly detailed.
Conclusion

Play Framework Essentials does as its title suggests and introduces essential aspects of the Play Framework.

Friday, October 24, 2014

Book Review: Learning AngularJS for .NET Developers

The subtitle of Alex Pop's Learning AngularJS for .NET Developers (Packt Publishing) is "Build single-page web applications using frameworks that help you work efficiently and deliver great results." Learning AngularJS for .NET Developers consists of approximately 175 substantive pages divided into 6 chapters. This blog post is my review of Learning AngularJS for .NET Developers.

Preface

The "Preface" of Learning AngularJS for .NET Developers describes how web development has changed with focus on single-page applications behaving more like desktop applications and using approaches such as responsive web design and progressive enhancement.

The Preface also describes the objective of the Learning AngularJS for .NET Developers and the experience readers of the book should have before reading it:

The main focus of this book is on how to rapidly prototype and build modern web applications with AngularJS in the context of .NET development tools and frameworks. The book assumes the reader has already built websites, web applications, or web services using Microsoft technologies such as ASP.NET, ASP.NET MVC, Silverlight, or WCF and knows the fundamentals of HTML5, CSS3, JavaScript, jQuery, and ASP.NET MVC.

The "Who this book is for" section of the Preface reaffirms its intended audience: "The book is targeted at .NET developers who have already built web applications or web services and have a fundamental knowledge of HTML, JavaScript, and CSS. As is the case with other Packt Publishing books I have reviewed, the Preface of Learning AngularJS for .NET Developers provides short descriptions of each of the book's six chapters.

The final significant observation from Learning AngularJS for .NET Developers's Preface that is important to highlight here comes from its "What you need for this book" section. That section states that Visual Studio 2013 Professional is recommended, but that Visual Studio 2013 Express for Web is sufficient. Node.js, Node.js Tools for Visual Studio, and JDK 7 are recommended for testing. Later in the book, the author also recommends use of Google Chrome web browser with the AngularJS Batarang extension.

Chapter 1: Introducing AngularJS

The initial chapter of Learning AngularJS for .NET Developers is dedicated to AngularJS. The chapter includes a reference to the AngularJS 1.2.15 Documentation and to the AngularJS 1.2.15 API Documentation because a single chapter cannot cover all the details of AngularJS. The chapter then uses examples to introduce AngularJS concepts.

The first examples of Chapter 1 demonstrate fundamental characteristics of an AngularJS application by comparing a single example written in AngularJS to the same example implemented with jQuery and JavaScript. This comparison and the accompanying text are a nice method for introducing AngularJS, how it is different, and highlighting some of its advantages. The text description associated with the first comparison-oriented example introduces significant AngularJS concepts such as directives, expressions, and scopes.

Learning AngularJS for .NET Developers's first chapter includes sections on AngularJS architecture and the structure of an AngularJS application. The latter part includes discussion of AngularJS modules. The section on "JavaScript patterns and practices used in AngularJS applications" includes some nice explanations of JavaScript scope and hoisting issues and how these are often dealt with in AngularJS applications using JavaScript patterns such as Immediately-Invoked Function Expressions (IIFE) and revealing module pattern, using JavaScript strict mode, and using explicit dependency injection.

The lengthy first chapter (almost one-fourth of the entire book) of Learning AngularJS for .NET Developers moves onto an introduction of controllers and services in AngularJS and then moves onto more detailed description of directives that were introduced by example earlier in the chapter. In particular, this section covers specific built-in AngularJS directives ngRepeat and ngInclude before looking at creation of custom AngularJS directives. The chapter concludes with a discussion of AngularJS filters.

Chapter 2: Creating an AngularJS Client-side Application in Visual Studio

The initial chapter of Learning AngularJS for .NET Developers is completely focused on AngularJS and is useful to anyone using AngularJS regardless of whether they are using .NET or not. Chapter 2 is the first chapter of Learning AngularJS for .NET Developers that includes .NET-specific details. The author states that this chapter "assumes that you already know the fundamentals of .NET web development using Visual Studio."

The second chapter of Learning AngularJS for .NET Developers introduces using VisualStudio with an empty web project that doesn't require specification of any particular web framework. The chapter then explains and demonstrates use of NuGet to download packages. Several NuGet commands run in VisualStudio are demonstrated and a quick reference is made to the NuGet command line tool. The chapter briefly discusses Visual Studio extensions in general before specifically focusing on the Web Essentials 2013 and SideWafflet extensions which the author maintains turn Visual Studio into "a powerful AngularJS IDE."

Chapter 2 builds a client-side example based on AngularJS and Bootstrap. This example explanation begins by discussing "the organization of AngularJS code" as exemplified in the AngularJS starter project angular-seed. It provides a brief overview of other approaches for organizing an AngularJS application.

Learning AngularJS for .NET Developers's second chapter looks at integrating AngularJS with JavaScript with a section on integration with native JavaScript and a section on integration with third-party JavaScript frameworks. The section of Chapter 2 on routing describes how AngularJS supports two types of routing to allow a single page application to appear to update "seamlessly" in the web browser even for different URLs. The chapter concludes with a demonstration of building a client-side application with a bicycle rental management example.

Chapter 3: Creating .NET Web Services for AngularJS

Chapter 3 of Learning AngularJS for .NET Developers begins with a brief introduction to .NET's historical support for SOAP-based web services with ASP.NET Web Services and Windows Communication Foundation (WCF). Discussion then moves into a brief overview of REST and support for REST in AngularJS. This part of the chapter introduces Hypermedia as the Engine of Application State (HATEOAS), but then states that HATEOAS will not be used in the book's examples.

A section in Chapter 3 looks at different .NET-oriented RESTful web services frameworks that can be used with AngularJS (including ASP.NET Web API) before focusing on ServiceStack. The chapter lists advantages of ServiceStack, provides a brief overview of ServiceStack, and presents a small ServiceStack example application that demonstrates several key features of ServiceStack.

After introducing the use of ServiceStack to implement web services, the third chapter of Learning AngularJS for .NET Developers looks at invoking RESTful web services from AngularJS using the ngResource module. This section includes coverage of AngularJS's Promise API.

Chapter 4: Creating an AngularJS, ASP.NET MVC, ServiceStack Application

Chapter 4 of Learning AngularJS for .NET Developers begins with discussion of advantages of ASP.NET MVC and some primary features provided by ASP.NET MVC. The chapter demonstrates how to integrate ASP.NET MVC into the "Rent that Bike!" sample application started earlier in the book and with ServiceStack. The chapter also discusses the additional complexity associated with "changing an AngularJS application to use the HTML5 History API instead of hashbang URLs."

The fourth chapter of Learning AngularJS for .NET Developers examines "ASP.NET bundling bundling and minification features for AngularJS files." The chapter also briefly describes multiple approaches for securing AngularJS applications. ServiceStack.Mvc is introduced as a means for "deeper integration" of ServiceStack and ASP.NET MVC.

The focus of Chapter 4 switches from security to approaches to "ensure that AngularJS works well with the backend." Specific approaches include alerting users to existence of long-running operations and handling exceptions with $http interceptor and the $q promise.

There is a section in Chapter 4 on database persistence. The author mentions several .NET-oriented ORM and micro-ORM frameworks, but focuses on ServiceStack.OrmLite and introduces ServiceStack.OrmLite.Sqlite32 for use with SQLLite. I also liked the author's referencing of Firefox add-on SQLite Manager.

Chapter 5: Testing and Debugging AngularJS Applications

The fifth chapter of Learning AngularJS for .NET Developers reintroduces Node.js and also mentions Node.js Tools for Visual Studio as foundational for testing AngularJS applications. The chapter demonstrates coverage of installing Node.js, installing and configuring Karma, an overview of using Jasmine and injecting mocking with $httpBackend service.

Chapter 5 introduces Protractor, which it describes as "an AngularJS-friendly wrapper around the Selenium WebDriver browser automation framework." There is a section that discusses how to install Protractor, including installing the JDK for Selenium to use. The next section describes configuration of Protractor before discussing writing Protractor tests.

Learning AngularJS for .NET Developers's fifth chapter covers several more testing-related subjects. These include testing web service endpoints, using xBehave.net for behavior-driven development (BDD) tests, xUnit.net, the moq4 framework, debugging AngularJS applications with AngularJS Batarang, and using JavaScript frameworks to deal with HTML5 validation and older web browsers.

Chapter 6: Advanced AngularJS Topics

The final chapter of Learning AngularJS for .NET Developers covers four "advanced AngularJS topics": internationalization and localization (ngLocale and angular-dynamic-locale), AngularJS animations (ngAnimate), remote web services (JSON with padding [JSONP] and Cross-origin Resource Sharing [CORS]), and template caching ($templateCache).

General Observations
  • Learning AngularJS for .NET Developers includes several code listings. These are black font on white background (no color syntax) without line numbers. However, the code can also be viewed in Visual Studio or even via Plunker (which provides color coded syntax and line numbers) using URLs provided in the book's text. The book's code listings include bold highlighting of portions of the code that are the specific focus of the associated text.
  • Learning AngularJS for .NET Developers includes useful diagrams that help to understand AngularJS's architecture and lifecycle. A couple of these are black-only on white background even in the electronic (PDF) version I reviewed. Some descriptions differentiate portions of the graphic by referring to "darker" but this can be difficult to distinguish.
  • The PDF version of Learning AngularJS for .NET Developers includes color screen snapshots (such as of using Visual Studio); I assume this is true for other electronic formats.
  • The title of Learning AngularJS for .NET Developers advertises this as a book about using AngularJS with .NET. The author frequently mentions in the book that it is assumed that the reader knows certain background technologies and concepts when reading that chapter. Even though the title and the author's many statements make this very clear, I cannot overemphasize this point: Learning AngularJS for .NET Developers is best suited for .NET developers with basic web skills who want to learn and apply AngularJS. Developers wanting to learn to use AngularHS with Java EE or some other back-end technology should look elsewhere. That stated, the single chapter that focuses exclusively on AngularJS is a nice introduction to and high-level coverage of AngularJS.
  • By assuming readers' .NET experience, Learning AngularJS for .NET Developers is able to focus primarily on AngularJS and developing applications with AngularJS and integrating AngularJS with .NET.
  • Learning AngularJS for .NET Developers is generally well-written and the text is fairly easy to follow and understand.
  • As one would expect from a book on using AngularJS with .NET, Learning AngularJS for .NET Developers provides significant coverage of applying Visual Studio and integrating AngularJS with .NET. However, it also contains quite a bit of coverage on open source and third-party products that are commonly used in applications built with AngularJS and .NET.
Conclusion

Learning AngularJS for .NET Developers delivers on what its title advertises. Readers of Learning AngularJS for .NET Developers should expect to learn the basics of AngularJS and how to apply AngularJS to front-ends for their .NET applications. The book does assume some .NET knowledge and experience and does devote considerable attention to using .NET frameworks and Visual Studio. I also like that the book mentions several open source projects and demonstrates integrating those with the applications built with AngularJS and .NET.

Wednesday, October 22, 2014

Java Extension Mechanism Loads All JARs

The Java Extension Mechanism is described in the Java Tutorial as a "standard, scalable way to make custom APIs available to all applications running on the Java platform." As described in Understanding Extension Class Loading, "the extension framework makes use of the class-loading delegation mechanism" with extension classes loaded after the bootstrap classes in rt.jar (and related JARs) but before the classes loaded from the typical classpath.

The extension directory works a bit like the classpath in that its part of the class loading mechanism and classes available within JARs in the extension directory are made available to Java applications. There are some key, differences, however, and some of these are highlighted next.

Characteristic Classpath Extension Mechanism (Optional Packages)
Scope Typically Application-Specific
Potentially All JREs on Host
All JVMs Running in Specific JRE All Host's JREs
  • Solaris: /usr/jdk/packages/lib/ext
  • Linux: /usr/java/packages/lib/ext
  • Windows: %SystemRoot%\Sun\Java\lib\ext
How Specified .jar Files
  • Explicitly specified by name (including .jar)
  • Wildcard (*) matching all all JAR files with .jar extensions
.class Files
  • Directory containing .class files specified
All JAR files (even if extension other than .jar or no extension at all) in designated directories are loaded.
Class Loading Order After bootstrap and extensions loading. After bootstrap but before classpath.

One of the most significant observations worth some more emphasis is that the extension mechanism will pick up all JAR format files in the extension directory even if the file does not have a .jar extension. The implication of this is that while one can change the name of a JAR located in a classpath directory to have an extension other than .jar so that the wildcard does not pick it up, this technique will not work with the extension directory.

I'm going to use some simple examples in this post to demonstrate some of these differences. The next two code listings are for a very simple HelloWorld class and a main application class called Main that uses the HelloWorld class.

HelloWorld.java
public class HelloWorld
{
   @Override
   public String toString()
   {
      return "Hello, World!";
   }
}
Main.java
import static java.lang.System.out;

public class Main
{
   public static void main(final String[] arguments)
   {
      out.println(new HelloWorld());
   }
}

To demonstrate a primary difference between classpath and the extension mechanism (optional packages), I will archive the compiled HelloWorld.class file into a JAR called HelloWorld.jar and place it in a different directory than the compiled Main.class file.

To demonstrate the use of the traditional classpath, I place the HelloWorld.jar file in a directory called C:\hello and will access that JAR via wildcard (*) for Main to use. This is demonstrated in the next two screen snapshots.

The two previous images demonstrate that the Java Main application can still load the HelloWorld.class file even though I had deleted it from the current directory because the Java launcher was explicitly told (via the -classpath option) to look for it in C:\hello. Using the extensions mechanism (optional packages), it is possible to have the class loaded without it being in the same directory and without explicit classpath specification. This is shown in the next screen snapshot.

The previous screen snapshot demonstrates that the Java launcher doesn't even need the HelloWorld.class in the same directory or specified on its classpath when that class is inside a JAR that is in the extensions (optional packages) directory. This is often cited as a benefit of using the extensions mechanism because all applications using that JRE (or potentially all applications on the host) can see the same classes without need to explicitly specify them on the classpath.

With the traditional classpath approach of instructing an application to load classes from JARs, the JAR file containing the .class file needs to end with the .jar extension. The next screen snapshot demonstrates what happens when the HelloWorld.jar is renamed HelloWorld.backup in the same classpath-referenced directory.

The last image demonstrates that a NoClassDefFoundError is encountered when the JAR file in the classpath-referenced directory does not have a .jar extension. Perhaps a bit surprisingly, the extensions (optional packages) mechanism does not work the same way. Instead, all JAR files in the extensions specified directory are loaded regardless of their extension and regardless of even if they have a file extension. This is demonstrated in the next screen image.

The previous image demonstrates that renaming the JAR file that resides within the extensions directory to not have any file extension whatsoever does not prevent the classloader from loading the classes of that JAR. In other words, the classloading mechanism loads all JAR files in the specified extensions directory based on file type rather than on file name or extension. As the Optional Packages Overview summarizes, "There is nothing special about any particular JAR file itself or the classes it contains that makes it an installed optional package. It is an installed optional package by virtue of its location in jre/lib/ext."

There are some risks and downsides associated with placing too many class definitions in JARs inside the extensions directory. It can be maddening to wonder why NoSuchMethodErrors, for example, are occurring when one can see that a class specified explicitly on the classpath has the method in question. I have previously written about one of the many potential causes of NoSuchMethodError, but forgotten outdated and obsolete class definitions residing inside of JAR files in the extensions directory are another potential cause. This is demonstrated next.

The next two code listings show revised versions of Main.java and HelloWorld.java. In particular, HelloWorld has an all-new method that the new version of Main invokes. In this case, I'm going to leave the newly compiled HelloWorld.class file in the same directory when I run the Main to demonstrate that the old, busted version of HelloWorld.class in the JAR in the extensions directory takes precedence over the new hotness HelloWorld.class in the current directory.

Revised Hello World.java (New Method)
public class HelloWorld
{
   @Override
   public String toString()
   {
      return "Hello, World!";
   }

   public String directedHello(final String name)
   {
      return "Hello, " + name;
   }
}
Revised Main.java
import static java.lang.System.out;

public class Main
{
   public static void main(final String[] arguments)
   {
      final HelloWorld helloWorld = new HelloWorld();
      out.println(helloWorld);
      out.println(helloWorld.directedHello("Dustin"));
   }
}

The last image demonstrates that the now obsolete class definition of HelloWorld in the extensions directory takes precedence over the new class definition of HelloWorld in the same directory. Even when I specify the current directory on the classpath, the old version in the extensions directory takes precedence. This is shown in the next screen snapshot, which also shows that the JAR in the extensions directory that is "hiding" the newer JAR and its class's newer method is still not even named with a .jar extension.

The example just demonstrated is not even the most difficult situation a forgotten JAR in the specified extensions directory (or directories) can cause. In that example, at least I had a NoSuchMethodError to alert me to a problem. A potentially even more difficult situation to debug can exist when the old class definition has the same method signature but has an outdated method implementation. In such cases, there may be no error, exception, or throwable of any kind, but the application logic will simply not work correctly or as expected. The old functionality could exist in the code base for some time before it's even recognized as an issue, especially if unit tests and other testing is lacking.

Use of the extensions directory can make things easier on developers because classes in JAR files residing in the extensions directory (or directories) are available to all applications in the JRE associated with the extensions directory (or with all JREs on the host if the operating system-based host-wide extensions directory is used). However, there are definite risks associated with too liberal use of the directory. It can be easy to forget that outdated class definitions residing in JARs in that directory are preventing classloaders from loading the newer and seemingly obvious versions of the class definitions. When this happens, the very extensions (optional packages) mechanism that made developers' lives easier now make it more difficult.

Elliotte Rusty Harold provides a warning about use of the extensions (optional packages) mechanism, "While this seems convenient, it is also a long-term mistake... Sooner or later (probably sooner), you'll load the wrong version of a class from a place you aren't even thinking about and waste hours debugging." The Java Tutorial also recommends caution (I added the emphasis), "Since this mechanism extends the platform's core API, its use should be judiciously applied. Most commonly it is used for well standardized interfaces such as those defined by the Java Community Process, although it may also be appropriate for site wide interfaces."

Although the extensions (optional packages) mechanism is similar to the classpath mechanism and both are used as part of class loading, the differences between the two are important to note. In particular, it is important to remember that all JAR files (even if they don't have .jar file extensions) that reside in the directory referenced as an extension directory will be loaded. Renaming these JARs and even changing their file extension will not be sufficient to have the classloading ignore them. With classpath, on the other hand, renaming the JAR is sufficient to prevent loading when the classpath specifies individual JAR files explicitly and changing the file extension is typically sufficient to prevent loading even when the classpath uses the wildcard (*) to specify all JARs in a directory.

There are situations when the extensions (optional packages) mechanism is the appropriate choice, but these seem fairly rare. It is also important to keep in mind the extensions (optional packages) mechanism in mind when dealing with unexplained NoSuchMethodErrors so that one can check it out to see if the offender lives in that directory or directories.