This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com < Day Day Up > Jakarta Commons Cookbook By Timothy M O'Brien of • Table Contents • Index • Reviews • Reader Reviews • Errata • Academic Publisher: O'Reilly Pub Date: November 2004 ISBN: 0-596-00706-X Pages: 400 This collection provides expert tips for using the utilities of the Java-based Jakarta Commons open source project You don't have to be an expert, the book's solution-based format contains code examples for a wide variety of web, XML, network, testing, and application projects If you want to learn how to use Jakarta Commons utilities to create powerful Java applications and tools, the Jakarta Commons Cookbook is for you < Day Day Up > This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com < Day Day Up > Jakarta Commons Cookbook By Timothy M O'Brien of • Table Contents • Index • Reviews • Reader Reviews • Errata • Academic Publisher: O'Reilly Pub Date: November 2004 ISBN: 0-596-00706-X Pages: 400 Copyright Preface What's Inside Conventions Used in This Book What You'll Need The Jakarta Commons Community The Apache Software License Using Code Examples We'd Like to Hear from You Acknowledgments Chapter Supplements to the Java Platform Introduction Recipe 1.1 Obtaining Commons Lang Recipe 1.2 Joining the Commons-User Mailing List Recipe 1.3 Getting the Commons Lang Source Code Recipe 1.4 Automating the Generation of toString( ) Content Recipe 1.5 Customizing Generated toString( ) Content Recipe 1.6 Automating hashCode( ) and equals( ) Recipe 1.7 Automating compareTo( ) Recipe 1.8 Printing an Array Recipe 1.9 Cloning and Reversing Arrays Recipe 1.10 Transforming Between Object Arraysand Primitive Arrays Recipe 1.11 Finding Items in an Array Recipe 1.12 Creating a Map from a Multidimensional Array Recipe 1.13 Formatting Dates Recipe 1.14 Rounding Date Objects Recipe 1.15 Truncating Date Objects Recipe 1.16 Creating an Enum Recipe 1.17 Generating Unique Numeric Identifiers Recipe 1.18 Validation of Method Parameters Recipe 1.19 Measuring Time Chapter Manipulating Text Introduction This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com Recipe 2.1 Setting Up StringUtils and WordUtils Recipe 2.2 Checking for an Empty String Recipe 2.3 Abbreviating Strings Recipe 2.4 Splitting a String Recipe 2.5 Finding Nested Strings Recipe 2.6 Stripping and Trimming a String Recipe 2.7 Chomping a String Recipe 2.8 Creating an Emphasized Header Recipe 2.9 Reversing a String Recipe 2.10 Wrapping Words Recipe 2.11 Testing the Contents of a String Recipe 2.12 Measuring the Frequency of a String Recipe 2.13 Parsing Formatted Strings Recipe 2.14 Calculating String Difference Recipe 2.15 Using Commons Codec Recipe 2.16 Getting the Commons Codec Source Code Recipe 2.17 Calculating Soundex Chapter JavaBeans Introduction Recipe 3.1 Representing Beans Graphically Recipe 3.2 Obtaining Commons BeanUtils Recipe 3.3 Getting the Commons BeanUtils Source Code Recipe 3.4 Accessing Simple Bean Properties Recipe 3.5 Accessing Nested Bean Properties Recipe 3.6 Accessing Indexed Bean Properties Recipe 3.7 Accessing Mapped Bean Properties Recipe 3.8 Accessing a Simple, Nested, Indexed, and Mapped Bean Property Recipe 3.9 Determining the Type of a Bean Property Recipe 3.10 Comparing Beans Recipe 3.11 Copying Bean Properties Recipe 3.12 Cloning a Bean Recipe 3.13 Setting a Bean Property Recipe 3.14 Testing Property Access Recipe 3.15 Validating Beans with Predicates Recipe 3.16 Creating a Map of Bean Properties Recipe 3.17 Wrapping a Bean with a Map Recipe 3.18 Creating a Dynamic Bean Recipe 3.19 Getting and Setting Properties as Strings Chapter Functors Introduction Recipe 4.1 Obtaining Commons Collections Recipe 4.2 Getting the Commons Collections Source Code Recipe 4.3 Reversing a Comparator Recipe 4.4 Chaining Comparators Recipe 4.5 Comparing Nulls Recipe 4.6 Fixed-Order Comparison Recipe 4.7 Using Simple Predicates Recipe 4.8 Writing a Custom Predicate Recipe 4.9 Creating Composite Predicates Recipe 4.10 Transforming Objects Recipe 4.11 Creating a Chain of Transformations Recipe 4.12 Applying Conditional Transformations Recipe 4.13 Writing a Closure This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com Recipe 4.13 Writing a Closure Recipe 4.14 Chaining Closures Recipe 4.15 Modeling Conditional Statements with Closures Recipe 4.16 Modeling Loops with Closures Chapter Collections Introduction Recipe 5.1 Obtaining Commons Collections Recipe 5.2 Using a Looping Iterator Recipe 5.3 Iterating Over an ArrayList Recipe 5.4 Filtering a Collection with a Predicate Recipe 5.5 Iterating Through Distinct Elements Recipe 5.6 Using a Bag Recipe 5.7 Using a Buffer Recipe 5.8 Creating a Priority Queue Recipe 5.9 Using a Blocking Buffer Recipe 5.10 Storing Multiple Values in a Map Recipe 5.11 Retrieving a Key by a Value Recipe 5.12 Using a Case-Insensitive Map Recipe 5.13 Creating Typed Collections and Maps Recipe 5.14 Constraining Map Values Recipe 5.15 Constraining List Contents Recipe 5.16 Transforming Collections Recipe 5.17 Creating a Least Recently Used Cache Recipe 5.18 Using a Lazy Map Recipe 5.19 Counting Objects in a Collection Recipe 5.20 Performing Set Operations Recipe 5.21 Retrieving Map Values Without Casting Chapter XML Introduction Recipe 6.1 Obtaining Jakarta Commons Digester Recipe 6.2 Turning XML Documents into Objects Recipe 6.3 Namespace-Aware Parsing Recipe 6.4 Creating a Simple XML Command Language Recipe 6.5 Variable Substitution and XML Parsing Recipe 6.6 Obtaining Jakarta Commons Betwixt Recipe 6.7 Turning Beans into XML Documents Recipe 6.8 Customizing XML Generated from an Object Recipe 6.9 Turning XML Documents into Beans Chapter Application Infrastructure Introduction Recipe 7.1 Obtaining Commons CLI Recipe 7.2 Parsing a Simple Command Line Recipe 7.3 Parsing a Complex Command Line Recipe 7.4 Printing Usage Information Recipe 7.5 Obtaining Commons Configuration Recipe 7.6 Configuring Applications with Properties Files Recipe 7.7 Configuring Applications with XML Recipe 7.8 Using Composite Configuration Recipe 7.9 Obtaining Commons Logging Recipe 7.10 Using an Abstract Logging Interface Recipe 7.11 Specifying a Logging Implementation Recipe 7.12 Obtaining Apache Log4J Recipe 7.13 Configuring Log4J with a Properties File This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com Recipe 7.14 Configuring Log4J with XML Chapter Math Introduction Recipe 8.1 Using Fractions Recipe 8.2 Finding the Maximum and Minimum in an Array Recipe 8.3 Using Number Ranges Recipe 8.4 Generating Random Variables Recipe 8.5 Obtaining Commons Math Recipe 8.6 Calculating Simple Univariate Statistics Recipe 8.7 Solving a System of Linear Equations Recipe 8.8 Arithmetic with Complex Numbers Recipe 8.9 Establishing Relationships Between Variables Recipe 8.10 Estimating the Amount of Time Left in a Process Chapter Templating Introduction Recipe 9.1 Obtaining Commons JEXL Recipe 9.2 Using an Expression Language Recipe 9.3 Invoking Methods in an Expression Recipe 9.4 Externalizing Logic with an Expression Language Recipe 9.5 Obtaining Jakarta Velocity Recipe 9.6 Using a Simple Templating Language Recipe 9.7 Writing Templates with Conditionals and Loops Recipe 9.8 Using Macros in a Templating Engine Recipe 9.9 Invoking Methods in a Template Recipe 9.10 Obtaining FreeMarker Recipe 9.11 Using a Complex Scripting Engine Recipe 9.12 Accessing XML Documents from a Templating Engine Recipe 9.13 Using Velocity in a Web Application Recipe 9.14 Using FreeMarker in a Web Application Recipe 9.15 Writing Templates in Eclipse Chapter 10 I/O and Networking Introduction Recipe 10.1 Obtaining Commons IO Recipe 10.2 Copying Streams, byte[ ], Readers, and Writers Recipe 10.3 Closing Streams, Readers, and Writers Recipe 10.4 Printing a Human-Readable File Size Recipe 10.5 Copying Files, Strings, and URLs Recipe 10.6 Deleting Directories Recursively Recipe 10.7 Obtaining the Size of a Directory Recipe 10.8 Touching a File Recipe 10.9 Filtering Files Recipe 10.10 Measuring Stream Traffic Recipe 10.11 Splitting an OutputStream Recipe 10.12 Obtaining Jakarta ORO Recipe 10.13 Using Globs and Perl5 Regular Expressions to List Files Recipe 10.14 Obtaining Commons Net Recipe 10.15 Writing an FTP Client Recipe 10.16 Sending Mail with SMTP Recipe 10.17 Checking a POP3 Mailbox Chapter 11 HTTP and WebDAV Introduction Recipe 11.1 Obtaining Jakarta HttpClient Recipe 11.2 Getting Jakarta HttpClient Source Code This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com Recipe 11.2 Getting Jakarta HttpClient Source Code Recipe 11.3 Performing an HTTP GET Recipe 11.4 Sending Parameters in a Query String Recipe 11.5 Retrieving Content with a Conditional GET Recipe 11.6 Debugging HTTP Communications Recipe 11.7 Making an HTTP POST Request Recipe 11.8 Sending POST Data from a File Recipe 11.9 Uploading Files with a Multipart POST Recipe 11.10 Basic Authentication Recipe 11.11 NTLM Authentication Recipe 11.12 Working with Cookies Recipe 11.13 Handling Redirects Recipe 11.14 SSL Recipe 11.15 Accepting a Self-Signed Certificate Recipe 11.16 Obtaining Jakarta Slide Recipe 11.17 Connecting to WebDAV Resources Recipe 11.18 Modifying a WebDAV Resource Chapter 12 Searching and Filtering Introduction Recipe 12.1 Obtaining Commons JXPath Recipe 12.2 Querying an Object Graph with XPath Recipe 12.3 Search a Collection of Simple Objects Recipe 12.4 Applying XPath Queries to Complex Object Graphs Recipe 12.5 Obtaining Jakarta Lucene Recipe 12.6 Creating an Index of XML Documents Recipe 12.7 Searching for a Specific Term in a Document Index Recipe 12.8 Finding the Frequency of Terms in an Index Colophon Index < Day Day Up > This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com < Day Day Up > Copyright © 2005 O'Reilly Media, Inc 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 (http://safari.oreilly.com) For more information, contact our corporate/institutional sales department: (800) 998-9938 or corporate@oreilly.com Nutshell Handbook, the Nutshell Handbook logo, and the O'Reilly logo are registered trademarks of O'Reilly Media, Inc The Cookbook series designations, Jakarta Commons Cookbook, the image of an aardvark, and related trade dress are trademarks of O'Reilly Media, Inc Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States and other countries O'Reilly Media, Inc is independent of Sun Microsystems, 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 trademark 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 authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein < Day Day Up > This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com < Day Day Up > Preface In this book, you'll find information about a set of libraries developed within the Jakarta Commons (also referred to as "Commons") Commons (http://jakarta.apache.org/commons) is a set of small, popular components from the Apache Software Foundation's Jakarta project Ranging from the elementary to the complex, many would consider some of these libraries indispensable to any Java© project These components are so widespread, they may already be on your classpath If you develop an application using Jakarta Struts, Apache Tomcat, or Hibernate, you have Commons BeanUtils and Commons Logging in your classpath If you just installed Red Hat Enterprise Linux with the default configuration, you've got Commons libraries somewhere in /usr If you downloaded Sun's J2EE 1.4 SDK, you will have also downloaded Commons Logging and Commons Launcher While Jakarta Commons may be everywhere, many are still unaware of the capabilities these components provide This book uses Jakarta Commons to focus on tactical implementation details, answering such questions as: How we parse XML? How we serialize beans? Is there an easier way to work with Collections? How we work with HTTP and keep track of cookies? The tactical is often sacrificed for the strategic Consider a complex J2EE system with a solid, well-conceived architecture The strategic (or high-level) design appears reasonable from 40,000 feet, but as soon as you drill into the details, you notice that every Servlet or JSP contains pages upon pages of unmaintainable and unnecessary code because the developers were not aware of some valuable time-saver like BeanUtils, Collections, or the Digester Or, worse, the developer may have spent a week reimplementing most of the capabilities of Commons BeanUtils even though BeanUtils was already in the classpath Knowing what Jakarta Commons has to offer often helps to inform decisions made at the lowest level Few application developers would consider writing a custom XML parser, but developers will frequently write custom components that duplicate freely available libraries Take, as an example, a set of static utility methods that seems to pop up in almost every complex project A common process such as reading a file to a String may be refactored into a CommonFileUtils class, or turning a DOM Document into a set of beans may be accomplished with a set of classes in some custom code Jakarta Commons provides solutions to both of these problems and many more, and reading this book may help you to avoid unnecessary wheel reinvention Many people know of these components in a general sense, but few have the months or weeks necessary to sit down and read the relevant tutorials, FAQs, blogs, and archived mailing lists associated with each component The amount of work involved in keeping up-to-date with an array of open source communities is not trivial This is why I've tried to compact much of this information into easily accessible recipes These recipes were written to provide the information you need to start using Commons in a few minutes, but the Discussion and See Also sections give you an opportunity to dig deeper into the motivation behind each Commons component if you need more information The tools introduced herein save you serious time and provide you with a set of alternatives you may not currently be aware of I wish I had read a book like this five years ago; it would have accelerated my learning and helped me to avoid some costly design decisions Use this text as you will; if you are only interested in Commons Collections, you should be able to quickly familiarize yourself with Collections by browsing Chapter On the other hand, if you are looking for a survey of some of the major projects in Jakarta Commons, read this book from start to finish Part structured reference, part prose, the cookbook format lets you customize your reading experience, and I hope this book is as interesting to read as it was to write < Day Day Up > This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com < Day Day Up > What's Inside This book covers components from Jakarta Commons, a few projects from Jakarta, and one project outside of the Apache Software Foundation This book covers the following components: Jakarta Commons BeanUtils Jakarta Commons Betwixt Jakarta Commons CLI Jakarta Commons Codec Jakarta Commons Collections Jakarta Commons Configuration Jakarta Commons Digester Jakarta Commons HttpClient Jakarta Commons ID Jakarta Commons IO Jakarta Commons JEXL Jakarta Commons JXPath Jakarta Commons Lang Jakarta Commons Logging Jakarta Commons Math Jakarta Commons Net Apache Log4J Jakarta Velocity FreeMarker Jakarta Lucene Jakarta Slide All of these projects are covered in detail in the following chapters Here's what's in each chapter: Chapter 1, Supplements to the Java Platform This chapter introduces Commons Lang Automation of toString( ), working with arrays, formatting and rounding dates, working with enumerations, generating identifiers, and measuring time are some of the topics discussed in this chapter This chapter also covers the generation of unique identifiers with Commons ID Chapter 2, Manipulating Text While Java does not have the extensive text manipulation capabilities of a scripting language like Perl, Commons Lang's StringUtils has a number of utility methods that can be used to manipulate text This chapter deals with StringUtils, WordUtils, and Commons Codec This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com deals with StringUtils, WordUtils, and Commons Codec Chapter 3, JavaBeans Beans appear throughout Java; from Jakarta Struts to Hibernate, beans are a unit of information in an object model This chapter introduces Commons BeanUtils, one of the most widely used components from Jakarta Commons Chapter 4, Functors Functors are a fundamental way of thinking about programming as a set of functional objects Commons Collections introduced predicates, transformers, and closures, and functors, which can be used to model control structures and loops This chapter demonstrates how one would apply functors to any program Chapter 5, Collections Iterators, filtering with predicates, buffers, queues, bidirectional maps, type-safe collections, constraining collections, lazy maps, and set operations are a few of the topics introduced in this chapter This chapter deals with Commons Collections, new collection types introduced, and the application of functors to various collections Chapter 6, XML If you are constantly parsing or creating XML documents, this chapter introduces some alternatives to the standard parser APIs (SAX, DOM, and JDOM) This chapter introduces Commons Digester, Commons Betwixt, and Commons JXPath Chapter 7, Application Infrastructure Commons Configuration is introduced as a way to parse properties files and XML configuration files Other recipes in this chapter show how Commons CLI can be used to parse a complex set of required and optional command-line options This chapter also details the configuration and use of Commons Logging and Apache Log4J Chapter 8, Math This chapter focuses on simple mathematical capabilities in both Commons Lang and Commons Math This chapter introduces classes to work with fractions, complex numbers, matrices, and simple univariate statistics Chapter 9, Templating This chapter deals with simple expression languages such as Commons JEXL to more complex templating engines such as Jakarta Velocity and FreeMarker This chapter also demonstrates the integration of both Velocity and FreeMarker with a J2EE servlet container such as Jakarta Tomcat Chapter 10, I/O and Networking This chapter introduces Commons IO, which contains a number of utilities for working with streams and files, and Commons Net, which contains simple clients for the FTP, POP, and SMTP protocols Chapter 11, HTTP and WebDAV If you need to communicate with anything over HTTP, read this chapter, which deals with Jakarta HttpClient and the WebDAV client library from Jakarta Slide Chapter 12, Searching and Filtering Commons JXPath can be used to apply XPath expressions to collections and object graphs Jakarta Lucene is a fully functional search engine that can index any structured document This chapter demonstrates the use of Lucene with Commons Digester Limited time and resources forced me to make some decisions about which projects to include in this text Projects like Velocity, FreeMarker, and Log4J, while not Commons components, were included because they fit the mold of a small, easily reusable component Other Commons components were not included in this book because they were still being This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com easily reusable component Other Commons components were not included in this book because they were still being developed at the time of writing, or because a short recipe would have been impossible without a detailed 30-page introduction Commons DbUtils, DBCP, Discovery, Jelly, Launcher, Modeler, Pool, Primitives, Chain, and promising sandbox components could fill another entire volume Some projects, such as Jakarta HiveMind, started as components in the Commons Sandbox only to be promoted directly to subproject status of the Jakarta project Classification of projects and components in Jakarta can also be somewhat arbitrary; Jakarta ORO and Jakarta RegExp would both seem to be prime candidates for the Jakarta Commons, but they are both subprojects of Jakarta Other projects, such as Jakarta Commons HttpClient, have recently been promoted to be subprojects of Jakarta, leaving the Commons entirely Think of this book as focusing on Jakarta Commons with some other projects thrown in to liven up the discussion I apologize in advance if I left your favorite project out Writing a book about a series of frequently released components is reminiscent of a game called whack-a-mole Just when you finish updating a chapter for a new release, another component has a release On average, one commons component is released every one or two weeks; therefore, a few of the versions in this book may be obsolete as soon as this book hits the shelves In general, Jakarta Commons makes a concerted effort to preserve backward compatibility and keep a stable public interface Lessons learned on Commons BeanUtils 1.6 should remain applicable to Commons BeanUtils 1.7 If you find that a more recent version of a component has been released, you should download that more recent version and check the O'Reilly site for updates related to this book < Day Day Up > This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com < Day Day Up > Conventions Used in This Book I'll use a number of conventions you should know about in this book For example, menu items are separated with an like this: File New Project To make them stand out, new lines of code will be displayed highlighted when they're added Example code is often presented out of context; instead of developing an entire class, only the relevant block of code is presented Most examples will include the necessary import statements for Commons-relevant classes, and other import statements will be implied When code is omitted or implied, it will be represented by ellipses: import org.apache.commons.digester.Digester; Digester digester = new Digester( ); digester.doSomething( ); In addition, the following typographical conventions are also used in this book: Italic Indicates new terms, URLs, email addresses, filenames, file extensions, pathnames, directories, and Unix utilities Constant width Indicates commands, options, switches, variables, types, classes, namespaces, methods, modules, properties, parameters, values, objects, events, event handlers, and XML tags Constant width italic Shows text that should be replaced with user-supplied values Constant width bold Highlights important text within code examples This icon signifies a tip, suggestion, or general note This icon indicates a warning or caution < Day Day Up > This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com < Day Day Up > What You'll Need To experiment with the various libraries introduced in this book, you will need the J2SE 1.4 SDK, which can be obtained from http://www.javasoft.com The examples in this book were developed in an IDE named Eclipse, which can be downloaded from the Eclipse project site at http://www.eclipse.org Each chapter contains instructions for downloading the various Jakarta Commons components; to download any component from Jakarta Commons, go to the Jakarta Commons page at http://jakarta.apache.org/commons and click on "Binaries" under "Download" in the left menu < Day Day Up > This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com < Day Day Up > The Jakarta Commons Community The Jakarta community and the larger community of the Apache Software Foundation is committed to developing open source software The Apache Software Foundation is a nonprofit corporation registered in Delaware that supports ongoing collaborative software development according to a set of simple ideals: transparency, meritocracy, consensus, and mutual respect To learn more about the foundation, start at the Frequently Asked Questions page on www.apache.org (http://www.apache.org/foundation/faq.html) Jakarta is a project under the Apache Software Foundation, and it is managed by what is known as a Project Management Committee (PMC) This committee manages a number of Jakarta subprojects including the Jakarta Commons The Jakarta community and Apache XML community both had tremendous growth spurts from 1999 to 2003, with both projects becoming dominant forces in open source Java Tomcat, Struts, Xerces, Xalan, Ant, Cocoon, and other projects were embraced by the larger community and Java developed a very strong association with open source because of the influence of Jakarta Toward the end of this growth spurt, the corporate structure of Apache required a certain level of oversight and accountability, which could not be achieved in an umbrella project like Jakarta with hundreds of committers A decision was made to encourage Jakarta subprojects to move toward smaller, more focused PMCs One of the first projects to leave Jakarta was Apache Ant, and other projects such as Maven, Struts, and Log4j followed suit This new, more nimble approach to the structure of collaborative software development avoids the creation of a management layer between project participants and the PMC Apache is making way for a new generation of projects that will set the standard for open source Java, including Geronimo, Pluto, Directory, Derby, and Axion Be aware that the structure of projects and subprojects in Jakarta is somewhat fluid at the moment, and, as the situation evolves, certain components could be split off into separate Apache projects If you find the components in this book helpful, I encourage you to take some time to observe the commons-dev developer mailing list The ASF is (mostly) transparent, and this means that the general public has a window into the collaborative development process that is used to create a large body of great software I would encourage any developer to take an interest in a piece of software and watch the development process Follow the decisions, releases, arguments, flame-wars, and evolution of something like Jakarta Commons and you can see for yourself what works and what doesn't work This is also a great way to keep yourself informed of the changes and direction of certain projects I don't intend to speak for this community, and, honestly, no one can speak for a group as diverse as the one that has formed around Jakarta Commons I wanted to write this book to help attract more people to the concept of Jakarta Commons and to take some time to encourage people to think about how they could contribute to that effort If there are more people paying attention to the software, Commons components will have higher quality, more bug reports will be filed, and more people might take some time to submit documentation patches If you find Jakarta Commons (or any other Apache software) useful, you should consider taking a little bit of time to help a fellow user on the user mailing list or submit documentation patches If you find a typo or a bug, file a report on Apache's Bugzilla installation (http://issues.apache.org/bugzilla) or Jira installation (http://issues.apache.org/jira) There is always a need for greater unit test coverage, and any time you find an inconsistency in code you should file a bug Contributions can come in many forms — answering user questions, writing documentation, writing unit tests, submitting patches, or providing feedback All of these contributions help sustain a living community If you find yourself unable to participate in the community, you can make a small (possibly tax-deductible) donation to the Apache Software Foundation to help offset the cost of infrastructure and bandwidth (http://www.apache.org/foundation/contributing.html) < Day Day Up > This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com < Day Day Up > The Apache Software License Everything in this book is covered by the Apache Software License 2.0 (except FreeMarker, which is covered by a similar BSD-style license) All developers who touch open source should be familiar with the various licenses and come to their own conclusions; most importantly, you should become familiar with the Apache license (and other BSD-style licenses) and how it differs from the GNU General Public License (GPL) and GNU Lesser General Public License (LGPL) Read the Apache Software License 2.0 at http://www.apache.org/licenses/ I am not a lawyer (IANAL), but I would urge you to learn as much as you can about these licenses before you start to use them For more information about open source, and for a comprehensive list of licenses, see the Open Source Initiative (OSI) at http://www.opensource.org The Apache license does not place restrictions on people or organizations that wish to redistribute the software it covers, and, in general, the Apache license creates fewer licensing headaches for individuals and organizations that want to incorporate open source software into a commercial product < Day Day Up > This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com < Day Day Up > Using Code Examples This book is here to help you get your job done In general, you may use the code in this book in your programs and documentation You 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 example code from this book into your product's documentation does require permission We appreciate, but not require, attribution An attribution usually includes the title, author, publisher, and ISBN For example: "Jakarta Commons Cookbook, by Timothy M O'Brien Copyright 2005 O'Reilly Media, Inc., 0-596-00706-X." If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at permissions@oreilly.com < Day Day Up > This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com < Day Day Up > We'd Like to Hear from You 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) O'Reilly maintains a web page for this book, where errata, examples, and any additional information are listed You can access this page at: http://www.oreilly.com/catalog/jakartackbk To comment or ask technical questions about this book, send email to: bookquestions@oreilly.com For more information about O'Reilly books, conferences, Resource Centers, and the O'Reilly Network, see the web site: http://www.oreilly.com < Day Day Up > This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com < Day Day Up > Acknowledgments This book would have been impossible to write were it not for the support and inspiration of a number of colleagues, friends, and family Thanks to Brett McLaughlin, my editor, who had a huge impact on the quality, structure, and content of the book His feedback and advice over the course of the past year has been immeasurably valuable Thanks also to Karen Tegtmeyer for reviewing this book Primary credit should first go to the Jakarta community and the various individuals who give hours upon hours of time to cut releases and maintain infrastructure In the face of constant challenge, Jakarta has remained a well spring of innovation Thanks to Michael Podrazik, Stefan Winz, Bob Hartlaub, Gautam Guliani, Jarret Rackoff, Robert Sorkin, and Federico Hatoum, and Grassroots Technologies in New York, NY Stefan originally introduced me to the Commons in the form of the Digester Thanks to various colleagues: Tim Beynart, Mike Smith, Felix Sheng, Julian Bleecker, Jim Buswell, Peter Costa, Rich Angeletti, David Winterfeldt, Ray Krueger, Chris Bobbitt, Tom Bergerson, Alex Wolfe, David Navin, Mark Snell, Bill Martens, Sultan Meghji, Daniel Summers, Greg Sandell, Dan Waite, and Benjamin Burton Mad props to Dave and Nicola, Rock, Patrick, Kat and Jay, Mike, Kelcey, John, Heather, Nick, Jessica, Marc, Krys, Joan, Jim, Zach, Sarah, and Mickey Much respect to John Bicknell, Karen Brunssen, Kit Bridges and the Trinity Episcopal Church Choir Endless thanks to Andrea and Klaus Thanks to my family, Chris, Kriste, Charlotte, Lily, Sean, Amy, Lucy, Kathy, Toby, Julie, Taylor, the Gilmores, Janey, all the O'Briens, and my parents Margaret and Michael Thanks to the Paynes: Becky, James, Heather, Chris, Jeannette, Matt, Susette and Tom, Grandma Barbee and James Sr Most of all, I would like to thank my wife, Susan O'Brien, for being perfect Happy Halloween < Day Day Up > This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com < Day Day Up > Preface In this book, you'll find information about a set of libraries developed within the Jakarta Commons (also referred to as "Commons") Commons (http://jakarta.apache.org/commons) is a set of small, popular components from the Apache Software Foundation's Jakarta project Ranging from the elementary to the complex, many would consider some of these libraries indispensable to any Java© project These components are so widespread, they may already be on your classpath If you develop an application using Jakarta Struts, Apache Tomcat, or Hibernate, you have Commons BeanUtils and Commons Logging in your classpath If you just installed Red Hat Enterprise Linux with the default configuration, you've got Commons libraries somewhere in /usr If you downloaded Sun's J2EE 1.4 SDK, you will have also downloaded Commons Logging and Commons Launcher While Jakarta Commons may be everywhere, many are still unaware of the capabilities these components provide This book uses Jakarta Commons to focus on tactical implementation details, answering such questions as: How we parse XML? How we serialize beans? Is there an easier way to work with Collections? How we work with HTTP and keep track of cookies? The tactical is often sacrificed for the strategic Consider a complex J2EE system with a solid, well-conceived architecture The strategic (or high-level) design appears reasonable from 40,000 feet, but as soon as you drill into the details, you notice that every Servlet or JSP contains pages upon pages of unmaintainable and unnecessary code because the developers were not aware of some valuable time-saver like BeanUtils, Collections, or the Digester Or, worse, the developer may have spent a week reimplementing most of the capabilities of Commons BeanUtils even though BeanUtils was already in the classpath Knowing what Jakarta Commons has to offer often helps to inform decisions made at the lowest level Few application developers would consider writing a custom XML parser, but developers will frequently write custom components that duplicate freely available libraries Take, as an example, a set of static utility methods that seems to pop up in almost every complex project A common process such as reading a file to a String may be refactored into a CommonFileUtils class, or turning a DOM Document into a set of beans may be accomplished with a set of classes in some custom code Jakarta Commons provides solutions to both of these problems and many more, and reading this book may help you to avoid unnecessary wheel reinvention Many people know of these components in a general sense, but few have the months or weeks necessary to sit down and read the relevant tutorials, FAQs, blogs, and archived mailing lists associated with each component The amount of work involved in keeping up-to-date with an array of open source communities is not trivial This is why I've tried to compact much of this information into easily accessible recipes These recipes were written to provide the information you need to start using Commons in a few minutes, but the Discussion and See Also sections give you an opportunity to dig deeper into the motivation behind each Commons component if you need more information The tools introduced herein save you serious time and provide you with a set of alternatives you may not currently be aware of I wish I had read a book like this five years ago; it would have accelerated my learning and helped me to avoid some costly design decisions Use this text as you will; if you are only interested in Commons Collections, you should be able to quickly familiarize yourself with Collections by browsing Chapter On the other hand, if you are looking for a survey of some of the major projects in Jakarta Commons, read this book from start to finish Part structured reference, part prose, the cookbook format lets you customize your reading experience, and I hope this book is as interesting to read as it was to write < Day Day Up > This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com < Day Day Up > Jakarta Commons Cookbook By Timothy M O'Brien of • Table Contents • Index • Reviews • Reader Reviews • Errata • Academic Publisher: O'Reilly Pub Date: November 2004 ISBN: 0-596-00706-X Pages: 400 This collection provides expert tips for using the utilities of the Java-based Jakarta Commons open source project You don't have to be an expert, the book's solution-based format contains code examples for a wide variety of web, XML, network, testing, and application projects If you want to learn how to use Jakarta Commons utilities to create powerful Java applications and tools, the Jakarta Commons Cookbook is for you < Day Day Up > This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com < Day Day Up > Jakarta Commons Cookbook By Timothy M O'Brien of • Table Contents • Index • Reviews • Reader Reviews • Errata • Academic Publisher: O'Reilly Pub Date: November 2004 ISBN: 0-596-00706-X Pages: 400 Copyright Preface What's Inside Conventions Used in This Book What You'll Need The Jakarta Commons Community The Apache Software License Using Code Examples We'd Like to Hear from You Acknowledgments Chapter Supplements to the Java Platform Introduction Recipe 1.1 Obtaining Commons Lang Recipe 1.2 Joining the Commons-User Mailing List Recipe 1.3 Getting the Commons Lang Source Code Recipe 1.4 Automating the Generation of toString( ) Content Recipe 1.5 Customizing Generated toString( ) Content Recipe 1.6 Automating hashCode( ) and equals( ) Recipe 1.7 Automating compareTo( ) Recipe 1.8 Printing an Array Recipe 1.9 Cloning and Reversing Arrays Recipe 1.10 Transforming Between Object Arraysand Primitive Arrays Recipe 1.11 Finding Items in an Array Recipe 1.12 Creating a Map from a Multidimensional Array Recipe 1.13 Formatting Dates Recipe 1.14 Rounding Date Objects Recipe 1.15 Truncating Date Objects Recipe 1.16 Creating an Enum Recipe 1.17 Generating Unique Numeric Identifiers Recipe 1.18 Validation of Method Parameters Recipe 1.19 Measuring Time Chapter Manipulating Text Introduction This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com Recipe 2.1 Setting Up StringUtils and WordUtils Recipe 2.2 Checking for an Empty String Recipe 2.3 Abbreviating Strings Recipe 2.4 Splitting a String Recipe 2.5 Finding Nested Strings Recipe 2.6 Stripping and Trimming a String Recipe 2.7 Chomping a String Recipe 2.8 Creating an Emphasized Header Recipe 2.9 Reversing a String Recipe 2.10 Wrapping Words Recipe 2.11 Testing the Contents of a String Recipe 2.12 Measuring the Frequency of a String Recipe 2.13 Parsing Formatted Strings Recipe 2.14 Calculating String Difference Recipe 2.15 Using Commons Codec Recipe 2.16 Getting the Commons Codec Source Code Recipe 2.17 Calculating Soundex Chapter JavaBeans Introduction Recipe 3.1 Representing Beans Graphically Recipe 3.2 Obtaining Commons BeanUtils Recipe 3.3 Getting the Commons BeanUtils Source Code Recipe 3.4 Accessing Simple Bean Properties Recipe 3.5 Accessing Nested Bean Properties Recipe 3.6 Accessing Indexed Bean Properties Recipe 3.7 Accessing Mapped Bean Properties Recipe 3.8 Accessing a Simple, Nested, Indexed, and Mapped Bean Property Recipe 3.9 Determining the Type of a Bean Property Recipe 3.10 Comparing Beans Recipe 3.11 Copying Bean Properties Recipe 3.12 Cloning a Bean Recipe 3.13 Setting a Bean Property Recipe 3.14 Testing Property Access Recipe 3.15 Validating Beans with Predicates Recipe 3.16 Creating a Map of Bean Properties Recipe 3.17 Wrapping a Bean with a Map Recipe 3.18 Creating a Dynamic Bean Recipe 3.19 Getting and Setting Properties as Strings Chapter Functors Introduction Recipe 4.1 Obtaining Commons Collections Recipe 4.2 Getting the Commons Collections Source Code Recipe 4.3 Reversing a Comparator Recipe 4.4 Chaining Comparators Recipe 4.5 Comparing Nulls Recipe 4.6 Fixed-Order Comparison Recipe 4.7 Using Simple Predicates Recipe 4.8 Writing a Custom Predicate Recipe 4.9 Creating Composite Predicates Recipe 4.10 Transforming Objects Recipe 4.11 Creating a Chain of Transformations Recipe 4.12 Applying Conditional Transformations Recipe 4.13 Writing a Closure This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com Recipe 4.13 Writing a Closure Recipe 4.14 Chaining Closures Recipe 4.15 Modeling Conditional Statements with Closures Recipe 4.16 Modeling Loops with Closures Chapter Collections Introduction Recipe 5.1 Obtaining Commons Collections Recipe 5.2 Using a Looping Iterator Recipe 5.3 Iterating Over an ArrayList Recipe 5.4 Filtering a Collection with a Predicate Recipe 5.5 Iterating Through Distinct Elements Recipe 5.6 Using a Bag Recipe 5.7 Using a Buffer Recipe 5.8 Creating a Priority Queue Recipe 5.9 Using a Blocking Buffer Recipe 5.10 Storing Multiple Values in a Map Recipe 5.11 Retrieving a Key by a Value Recipe 5.12 Using a Case-Insensitive Map Recipe 5.13 Creating Typed Collections and Maps Recipe 5.14 Constraining Map Values Recipe 5.15 Constraining List Contents Recipe 5.16 Transforming Collections Recipe 5.17 Creating a Least Recently Used Cache Recipe 5.18 Using a Lazy Map Recipe 5.19 Counting Objects in a Collection Recipe 5.20 Performing Set Operations Recipe 5.21 Retrieving Map Values Without Casting Chapter XML Introduction Recipe 6.1 Obtaining Jakarta Commons Digester Recipe 6.2 Turning XML Documents into Objects Recipe 6.3 Namespace-Aware Parsing Recipe 6.4 Creating a Simple XML Command Language Recipe 6.5 Variable Substitution and XML Parsing Recipe 6.6 Obtaining Jakarta Commons Betwixt Recipe 6.7 Turning Beans into XML Documents Recipe 6.8 Customizing XML Generated from an Object Recipe 6.9 Turning XML Documents into Beans Chapter Application Infrastructure Introduction Recipe 7.1 Obtaining Commons CLI Recipe 7.2 Parsing a Simple Command Line Recipe 7.3 Parsing a Complex Command Line Recipe 7.4 Printing Usage Information Recipe 7.5 Obtaining Commons Configuration Recipe 7.6 Configuring Applications with Properties Files Recipe 7.7 Configuring Applications with XML Recipe 7.8 Using Composite Configuration Recipe 7.9 Obtaining Commons Logging Recipe 7.10 Using an Abstract Logging Interface Recipe 7.11 Specifying a Logging Implementation Recipe 7.12 Obtaining Apache Log4J Recipe 7.13 Configuring Log4J with a Properties File This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com Recipe 7.14 Configuring Log4J with XML Chapter Math Introduction Recipe 8.1 Using Fractions Recipe 8.2 Finding the Maximum and Minimum in an Array Recipe 8.3 Using Number Ranges Recipe 8.4 Generating Random Variables Recipe 8.5 Obtaining Commons Math Recipe 8.6 Calculating Simple Univariate Statistics Recipe 8.7 Solving a System of Linear Equations Recipe 8.8 Arithmetic with Complex Numbers Recipe 8.9 Establishing Relationships Between Variables Recipe 8.10 Estimating the Amount of Time Left in a Process Chapter Templating Introduction Recipe 9.1 Obtaining Commons JEXL Recipe 9.2 Using an Expression Language Recipe 9.3 Invoking Methods in an Expression Recipe 9.4 Externalizing Logic with an Expression Language Recipe 9.5 Obtaining Jakarta Velocity Recipe 9.6 Using a Simple Templating Language Recipe 9.7 Writing Templates with Conditionals and Loops Recipe 9.8 Using Macros in a Templating Engine Recipe 9.9 Invoking Methods in a Template Recipe 9.10 Obtaining FreeMarker Recipe 9.11 Using a Complex Scripting Engine Recipe 9.12 Accessing XML Documents from a Templating Engine Recipe 9.13 Using Velocity in a Web Application Recipe 9.14 Using FreeMarker in a Web Application Recipe 9.15 Writing Templates in Eclipse Chapter 10 I/O and Networking Introduction Recipe 10.1 Obtaining Commons IO Recipe 10.2 Copying Streams, byte[ ], Readers, and Writers Recipe 10.3 Closing Streams, Readers, and Writers Recipe 10.4 Printing a Human-Readable File Size Recipe 10.5 Copying Files, Strings, and URLs Recipe 10.6 Deleting Directories Recursively Recipe 10.7 Obtaining the Size of a Directory Recipe 10.8 Touching a File Recipe 10.9 Filtering Files Recipe 10.10 Measuring Stream Traffic Recipe 10.11 Splitting an OutputStream Recipe 10.12 Obtaining Jakarta ORO Recipe 10.13 Using Globs and Perl5 Regular Expressions to List Files Recipe 10.14 Obtaining Commons Net Recipe 10.15 Writing an FTP Client Recipe 10.16 Sending Mail with SMTP Recipe 10.17 Checking a POP3 Mailbox Chapter 11 HTTP and WebDAV Introduction Recipe 11.1 Obtaining Jakarta HttpClient Recipe 11.2 Getting Jakarta HttpClient Source Code This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com Recipe 11.2 Getting Jakarta HttpClient Source Code Recipe 11.3 Performing an HTTP GET Recipe 11.4 Sending Parameters in a Query String Recipe 11.5 Retrieving Content with a Conditional GET Recipe 11.6 Debugging HTTP Communications Recipe 11.7 Making an HTTP POST Request Recipe 11.8 Sending POST Data from a File Recipe 11.9 Uploading Files with a Multipart POST Recipe 11.10 Basic Authentication Recipe 11.11 NTLM Authentication Recipe 11.12 Working with Cookies Recipe 11.13 Handling Redirects Recipe 11.14 SSL Recipe 11.15 Accepting a Self-Signed Certificate Recipe 11.16 Obtaining Jakarta Slide Recipe 11.17 Connecting to WebDAV Resources Recipe 11.18 Modifying a WebDAV Resource Chapter 12 Searching and Filtering Introduction Recipe 12.1 Obtaining Commons JXPath Recipe 12.2 Querying an Object Graph with XPath Recipe 12.3 Search a Collection of Simple Objects Recipe 12.4 Applying XPath Queries to Complex Object Graphs Recipe 12.5 Obtaining Jakarta Lucene Recipe 12.6 Creating an Index of XML Documents Recipe 12.7 Searching for a Specific Term in a Document Index Recipe 12.8 Finding the Frequency of Terms in an Index Colophon Index < Day Day Up > ... Jakarta Commons CLI Jakarta Commons Codec Jakarta Commons Collections Jakarta Commons Configuration Jakarta Commons Digester Jakarta Commons HttpClient Jakarta Commons ID Jakarta Commons IO Jakarta. .. Jakarta Commons JEXL Jakarta Commons JXPath Jakarta Commons Lang Jakarta Commons Logging Jakarta Commons Math Jakarta Commons Net Apache Log4J Jakarta Velocity FreeMarker Jakarta Lucene Jakarta. .. for downloading the various Jakarta Commons components; to download any component from Jakarta Commons, go to the Jakarta Commons page at http:/ /jakarta. apache.org/commons and click on "Binaries"