Jakarta Commons Cookbook By Timothy M O'Brien Publisher : O'Reilly Pub Date : November 2004 ISBN : 0-596-00706-X Table of • Pages : 400 Contents • Index • Reviews Reader • Reviews • Errata • Academic 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 Jakarta Commons Cookbook Table of • Contents • Index • Reviews Reader • Reviews • Errata • Academic By Timothy M O'Brien 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 Apache Software License We'd Like to Hear from You The Jakarta Commons Community Using Code Examples Acknowledgments Chapter 1 Supplements to the Java 2 Platform Introduction Recipe 1.1 Obtaining Commons Lang Recipe 1.2 Joining the Commons-User Mailing List Recipe 1.4 Automating the Generation of toString( ) Content Recipe 1.6 Automating hashCode( ) and equals( ) Recipe 1.3 Getting the Commons Lang Source Code Recipe 1.5 Customizing Generated toString( ) Content Recipe 1.7 Automating compareTo( ) Recipe 1.8 Printing an Array Recipe 1.10 Transforming Between Object Arraysand Primitive Arrays Recipe 1.12 Creating a Map from a Multidimensional Array Recipe 1.14 Rounding Date Objects Recipe 1.16 Creating an Enum Recipe 1.18 Validation of Method Parameters Recipe 1.9 Cloning and Reversing Arrays Recipe 1.11 Finding Items in an Array Recipe 1.13 Formatting Dates Recipe 1.15 Truncating Date Objects Recipe 1.17 Generating Unique Numeric Identifiers Recipe 1.19 Measuring Time Chapter 2 Manipulating Text Introduction Recipe 2.1 Setting Up StringUtils and WordUtils Recipe 2.2 Checking for an Empty String Recipe 2.4 Splitting a String Recipe 2.6 Stripping and Trimming a String Recipe 2.8 Creating an Emphasized Header Recipe 2.10 Wrapping Words Recipe 2.12 Measuring the Frequency of a String Recipe 2.14 Calculating String Difference Recipe 2.16 Getting the Commons Codec Source Code Recipe 2.3 Abbreviating Strings Recipe 2.5 Finding Nested Strings Recipe 2.7 Chomping a String Recipe 2.9 Reversing a String Recipe 2.11 Testing the Contents of a String Recipe 2.13 Parsing Formatted Strings Recipe 2.15 Using Commons Codec Recipe 2.17 Calculating Soundex Chapter 3 JavaBeans Introduction Recipe 3.1 Representing Beans Graphically Recipe 3.2 Obtaining Commons BeanUtils Recipe 3.4 Accessing Simple Bean Properties Recipe 3.3 Getting the Commons BeanUtils Source Code Recipe 3.5 Accessing Nested Bean Properties Recipe 3.6 Accessing Indexed Bean Properties Recipe 3.7 Accessing Mapped Bean Properties Recipe 3.9 Determining the Type of a Bean Property Recipe 3.11 Copying Bean Properties Recipe 3.13 Setting a Bean Property Recipe 3.15 Validating Beans with Predicates Recipe 3.17 Wrapping a Bean with a Map Recipe 3.8 Accessing a Simple, Nested, Indexed, and Mapped Bean Property Recipe 3.10 Comparing Beans Recipe 3.12 Cloning a Bean Recipe 3.14 Testing Property Access Recipe 3.16 Creating a Map of Bean Properties Recipe 3.18 Creating a Dynamic Bean Recipe 3.19 Getting and Setting Properties as Strings Chapter 4 Functors Introduction Recipe 4.1 Obtaining Commons Collections Recipe 4.3 Reversing a Comparator Recipe 4.5 Comparing Nulls Recipe 4.7 Using Simple Predicates Recipe 4.9 Creating Composite Predicates Recipe 4.11 Creating a Chain of Transformations Recipe 4.13 Writing a Closure Recipe 4.15 Modeling Conditional Statements with Closures Recipe 4.2 Getting the Commons Collections Source Code Recipe 4.4 Chaining Comparators Recipe 4.6 Fixed-Order Comparison Recipe 4.8 Writing a Custom Predicate Recipe 4.10 Transforming Objects Recipe 4.12 Applying Conditional Transformations Recipe 4.14 Chaining Closures Recipe 4.16 Modeling Loops with Closures Chapter 5 Collections Introduction Recipe 5.1 Obtaining Commons Collections Recipe 5.2 Using a Looping Iterator Recipe 5.4 Filtering a Collection with a Predicate Recipe 5.3 Iterating Over an ArrayList Recipe 5.5 Iterating Through Distinct Elements Recipe 5.6 Using a Bag Recipe 5.7 Using a Buffer Recipe 5.9 Using a Blocking Buffer Recipe 5.11 Retrieving a Key by a Value Recipe 5.13 Creating Typed Collections and Maps Recipe 5.15 Constraining List Contents Recipe 5.17 Creating a Least Recently Used Cache Recipe 5.19 Counting Objects in a Collection Recipe 5.8 Creating a Priority Queue Recipe 5.10 Storing Multiple Values in a Map Recipe 5.12 Using a Case-Insensitive Map Recipe 5.14 Constraining Map Values Recipe 5.16 Transforming Collections Recipe 5.18 Using a Lazy Map Recipe 5.20 Performing Set Operations Recipe 5.21 Retrieving Map Values Without Casting Chapter 6 XML Introduction Recipe 6.1 Obtaining Jakarta Commons Digester Recipe 6.3 Namespace-Aware Parsing Recipe 6.5 Variable Substitution and XML Parsing Recipe 6.7 Turning Beans into XML Documents Recipe 6.2 Turning XML Documents into Objects Recipe 6.4 Creating a Simple XML Command Language Recipe 6.6 Obtaining Jakarta Commons Betwixt Recipe 6.8 Customizing XML Generated from an Object Recipe 6.9 Turning XML Documents into Beans Chapter 7 Application Infrastructure Introduction Recipe 7.1 Obtaining Commons CLI Recipe 7.3 Parsing a Complex Command Line Recipe 7.5 Obtaining Commons Configuration Recipe 7.7 Configuring Applications with XML Recipe 7.9 Obtaining Commons Logging Recipe 7.2 Parsing a Simple Command Line Recipe 7.4 Printing Usage Information Recipe 7.6 Configuring Applications with Properties Files Recipe 7.8 Using Composite Configuration 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 Recipe 7.14 Configuring Log4J with XML Chapter 8 Math Introduction Recipe 8.1 Using Fractions Recipe 8.3 Using Number Ranges Recipe 8.5 Obtaining Commons Math Recipe 8.7 Solving a System of Linear Equations Recipe 8.9 Establishing Relationships Between Variables Recipe 8.2 Finding the Maximum and Minimum in an Array Recipe 8.4 Generating Random Variables Recipe 8.6 Calculating Simple Univariate Statistics Recipe 8.8 Arithmetic with Complex Numbers Recipe 8.10 Estimating the Amount of Time Left in a Process Chapter 9 Templating Introduction Recipe 9.1 Obtaining Commons JEXL Recipe 9.2 Using an Expression Language Recipe 9.4 Externalizing Logic with an Expression Language Recipe 9.6 Using a Simple Templating Language Recipe 9.8 Using Macros in a Templating Engine Recipe 9.10 Obtaining FreeMarker Recipe 9.12 Accessing XML Documents from a Templating Engine Recipe 9.14 Using FreeMarker in a Web Application Recipe 9.3 Invoking Methods in an Expression Recipe 9.5 Obtaining Jakarta Velocity Recipe 9.7 Writing Templates with Conditionals and Loops Recipe 9.9 Invoking Methods in a Template Recipe 9.11 Using a Complex Scripting Engine Recipe 9.13 Using Velocity 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.4 Printing a Human-Readable File Size Recipe 10.3 Closing Streams, Readers, and Writers Recipe 10.5 Copying Files, Strings, and URLs Recipe 10.6 Deleting Directories Recursively Recipe 10.8 Touching a File Recipe 10.10 Measuring Stream Traffic Recipe 10.12 Obtaining Jakarta ORO Recipe 10.14 Obtaining Commons Net Recipe 10.16 Sending Mail with SMTP Recipe 10.7 Obtaining the Size of a Directory Recipe 10.9 Filtering Files Recipe 10.11 Splitting an OutputStream Recipe 10.13 Using Globs and Perl5 Regular Expressions to List Files Recipe 10.15 Writing an FTP Client 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 Recipe 11.4 Sending Parameters in a Query String Recipe 11.6 Debugging HTTP Communications Recipe 11.8 Sending POST Data from a File Recipe 11.10 Basic Authentication Recipe 11.12 Working with Cookies Recipe 11.14 SSL Recipe 11.16 Obtaining Jakarta Slide Recipe 11.3 Performing an HTTP GET Recipe 11.5 Retrieving Content with a Conditional GET Recipe 11.7 Making an HTTP POST Request Recipe 11.9 Uploading Files with a Multipart POST Recipe 11.11 NTLM Authentication Recipe 11.13 Handling Redirects Recipe 11.15 Accepting a Self-Signed Certificate 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.3 Search a Collection of Simple Objects Recipe 12.2 Querying an Object Graph with XPath 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 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 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 do we parse XML? How do we serialize beans? Is there an easier way to work with Collections? How do 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, wellconceived 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 timesaver 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 modifying response codes, redirects retrieveFile( ) method retrieveMessage( ) method retrieving content (conditional GET method) ReverseComparator reversing arrays Comparators strings RFC 2109 RMI (remote method invocation) rounding dates rules, XML RuleSetBase [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] SAX parsers scripts HTTP POST requests redirect.cgi searching [See also Jakarta Lucene] arrays Jakarta ORO downloading listing files objects strings seconds, rounding seconds, truncating Secure Sockets Layer [See SSL] self-signed certificates sending email HTTP POST request files parameters query parameters redirects servers authentication cookies FTP HTTP, debugging POP3 SMTP servlets, HTTP POST requests set operations set( ) method setCookiePolicy( ) method setCredentials( ) method setFollowRedirects( ) method setParameter( ) method setRequestBody( ) method setRequestContentLength( ) method setting bean properties Simple Mail Transfer Protocol [See SMTP] Simple Object Access Protocol [See SOAP] SimpleBean SimpleDateFormat class SimpleRegression 2nd sizing directories print files Slide [See Jakarta Slide] SmartDraw SMTP (Simple Mail Transfer Protocol) SMTPReply.isPositiveCompletion( ) method SOAP (Simple Object Access Protocol) solve( ) method sorting bean properties Comparators Soundex source code Commons BeanUtils Commons Codec Commons Collections Commons Lang Jakarta HttpClient Soundex specific searches, Jakarta Lucene split( ) method splitting OutputStreamsCommons IO strings src/java subdirectory src/test subdirectory SSL (Secure Sockets Layer) SSLProtocolSocketFactory StandardAnalyzer start( ) method StatUtil object StatUtils StockQuoteTransformer StopWatch StopWatch.getTime( ) method StopWatch.unsplit( ) method storage, expressions streams closing copying tracking stringAlphanumericIdentifierFactory( ) method strings abbreviating beans properties built via reflection chomping closing comparing copying 2nd countryCode empty, testing measuring frequency parsing reversing searching splitting stripping testing trimming StringUtils class configuration text abbreviating strings chomping strings comparing strings measuring string frequency parsing strings printing headers reversing strings searching nested strings splitting strings stripping strings testing empty strings testing strings trimming strings StringUtils.abbreviate( ) method StringUtils.center( ) method StringUtils.chomp( ) method StringUtils.countMatches( ) method StringUtils.difference( ) method StringUtils.indexOfDifference( ) method StringUtils.isBlank( ) method StringUtils.join( ) method StringUtils.repeat( ) method StringUtils.reverse( ) method StringUtils.split( ) method StringUtils.trim( ) method stripping strings Struts JSP tag libraries styles subdirectories [See also directories] cleaning src/java src/test substring( ) method substringBetween( ) method subtract( ) method SuffixFileFilter instances SwitchTransformer syntax [See also code] Jakarta Velocity System.currentTimeMillis( ) method [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] tags app tag library email entity JSTL printStuff TeeOutputStream Telnet template.process( ) method templating Eclipse expression languages FreeMaker, downloading 2nd Jakarta Velocity, downloading macros Web applications term frequency, Jakarta Lucene TermEnum object testing arrays bean properties connections empty strings parameters strings text StringUtils class abbreviating strings chomping strings comparing strings measuring string frequency parsing strings printing headers reversing strings searching nested strings splitting strings stripping strings testing empty strings testing strings trimming strings WordUtils class wrapping Text( ) method TFTP (Trivial File Transfer Protocol) Tiger time, measuring timestamps Commons IO updating toMap( ) method tools Eclipse randomUtils StatUtils UML editors VelocityTools toString( ) methods automation customization ToStringBuilder class 2nd 3rd ToStringStyle class customization tracking cookies traffic Commons IO tracking trailing newlines, deleting transform( ) method transformation beans collections objects chaining conditional translation, arrays trimming strings trimToNull( ) method Trivial File Transfer Protocol [See TFTP] troubleshooting mailing lists truncating dates typed collections TypedCollection.decorate( ) method types of bean properties [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] UML (Unified Modeling Language) diagrams editors UnboundedFifoBuffer Unified Modeling Language [See UML] uniform resource locators [See URLs] unions, collections unique alphanumeric identifiers unique numeric identifiers UniqueFilterIterator univariate statistic calculations Universal Unique Identifier [See UUID] unlockMethod( ) method updating timestamps uploading files URLs (uniform resource locators) copying Jakarta HttpClient SSL user.properties UsernamePasswordCredentials object utilities Eclipse RandomUtils StatUtils VelocityTools UUID (Universal Unique Identifier) [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] validation bean properties parameters predicates ValuedEnum, extending values Boolean case-insensitive maps casting key by value retrieval map constraints multiple value storage populating UUID variables Boolean expression language inventoryBag random substitution (XML) VariableSubstitutor Velocity [See Jakarta Velocity] Velocity.init( ) method VelocityContext 2nd VelocityEngine 2nd VelocityStruts VelocityTools viewing source code Virtual Machine Identifier [See VMID] VMID (Virtual Machine Identifier) [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] Web applications, templating WebDav connections Jakarta Slide, downloading modifying whitespace stripping trimming words [See also text] Soundex wrapping WordUtils class configuration text, wrapping World Wide Web (WWW) wrapping bean properties words write methods writers closing copying WWW-Authenticate header [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] Xalan XML (Extensible Markup Language) beans 2nd Commons Betwixt Commons Configuration Commons Digester, downloading documents commands converting to objects namespace-aware parsing Jakarta Lucene Log4J object customization parsing rules XML Path Language [See XPath] XPath (XML Path Language) 2nd [See also Commons JXPath] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] years, rounding ... 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 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... 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"