Core JavaServer Faces, 2nd Edition

Core JavaServer™ Faces, Second Edition by David Geary, Cay Horstmann Publisher: Prentice Hall Pub Date: May 08, 2007 Print ISBN-10: 0-13-173886-0 Print ISBN-13: 978-0-13-173886-7 Pages: 752 Overview JavaServer Faces (JSF) is quickly emerging as the leading solution for rapid user interface development in Java-based server-side applications. Now, Core JavaServer™ Faces—the #1 guide to JSF—has been thoroughly updated in this second edition, covering the latest feature enhancements, the powerful Ajax development techniques, and open source innovations that make JSF even more valuable. Authors David Geary and Cay Horstmann delve into all facets of JSF 1.2 development, offering systematic best practices for building robust applications, minimizing handcoding, and maximizing productivity. Drawing on unsurpassed insider knowledge of the Java platform, they present solutions, hints, tips, and "how-tos" for writing superior JSF 1.2 production code, even if you're new to JSF, JavaServer Pages™, or servlets. The second edition's extensive new coverage includes: JSF 1.2's improved alignment with the broader Java EE 5 platform; enhancements to the JSF APIs; controlling Web flow with Shale; and using Facelets to replace JSP with XHTML markup. The authors also introduce Ajax development with JSF—from real-time validation and Direct Web Remoting to wrapping Ajax in JSF components and using the popular Ajax4jsf framework. This book will help you Automate low-level details and eliminate unnecessary complexity in server-side development Discover JSF best practices, ranging from effective UI design and style sheets to internationalization Use JSF with Tiles to build consistent, reusable user interfaces Leverage external services such as databases, LDAP directories, authentication/authorization, and Web services Use JBoss Seam to greatly simplify development of database-backed applications Implement custom components, converters, and validators Master the JSF 1.2 tag libararies, and extend JSF with additional tag libraries by: ita

Searching Strings for Specific Endings/Beginnings

Searching Strings for Specific Endings/Beginnings if f.endswith('.py'): print "Python file: " + f elif f.endswith('.txt'): print "Text file: " + f The endswith(suffix, [, start, [,end]]) and startswith(prefix, [, start, [,end]]) methods provide a simple and safe way to determine whether a string begins or ends with a specific prefix or suffix, respectively. The first argument is a string used to compare to the prefix or suffix of the string. The endswith and startswith methods are dynamic enough for you to limit the search to within a specific range of the string using the start and/or end arguments. Note The endswith and startswith methods are extremely useful when parsing file lists for extensions or filenames. import os for f in os.listdir('C:\\txtfiles'): if f.endswith('.py'): print "Python file: " + f elif f.endswith('.txt'): print "Text file: " + f end_str.py Python file: comp_str.py Python file: end_str.py Python file: eval_str.py Python file: join_str.py Text file: output.txt Python file: replace_str.py Python file: search_str.py Python file: split_str.py Python file: trim_str.py Python file: unicode_str.py Python file: var_str.py Output from end_str.py code

Chapter 1 - Introduction to Software Patterns Patterns in Java, Volume 1: A Catalog of Reusable Design Patterns Illustrated with UML, Second Edition by Mark Grand John Wiley & Sons � 2002

Chapter 1: Introduction to Software Patterns

Overview

Software patterns are reusable solutions to recurring problems that we encounter during software development. Because this book is all about software patterns, they are simply referred to as patterns throughout.

What makes a bright, experienced programmer much more productive than a bright, but inexperienced programmer? Experience. Experience gives programmers a wealth of wisdom. As programmers gain experience, they recognize the similarity of new problems to those they have solved in the past. With even more experience, they recognize that solutions to similar problems follow recurring patterns. With knowledge of these patterns, experienced programmers can recognize a problem to which specific patterns apply and immediately determine the solution without having to stop to analyze the problem first.

When a programmer discovers a pattern, it’s just an insight. In most cases, to go from an unverbalized insight to a well-thought-out idea that the programmer can clearly articulate is surprisingly difficult. It’s also an extremely valuable step. When we understand a pattern well enough to put it into words, we are able to intelligently combine it with other patterns. More important, once put into words, a pattern can be used in discussions among programmers who know the pattern. Such discussions allow programmers to more effectively collaborate and combine their wisdom. They can also help avoid the situation in which programmers argue over different solutions to a problem but find that they were actually thinking of the same solution, only expressing it in different ways.

Putting a pattern into words has an additional benefit for less experienced programmers who have not yet discovered the pattern. Once a pattern has been put into words, more experienced programmers can teach it to programmers who aren’t familiar with the pattern.

The intended value of this book is that it provide experienced programmers with a common vocabulary to discuss patterns. It should also allow programmers who have not yet discovered a pattern to learn about the pattern.

Although this book includes a substantial breadth of patterns, you may discover additional patterns yourself. Some patterns that you discover may be highly specialized and of interest only to a small number of people. Other patterns may be of broad interest and worthy of inclusion in a future volume of this book. If you wish to communicate such a pattern to this book’s author, you may send an email to mgrand@mindspring.com.

The patterns cataloged in this book convey constructive ways for organizing parts of the software development cycle. There are, however, nonconstructive patterns that can recur in programs. These are called AntiPatterns because they can cancel out the benefits of patterns. This book does not attempt to catalog AntiPatterns, for the subject is well covered in other books.

Patterns and AntiPatterns are similar but fundamentally different. The point of a pattern is to recognize when you have the opportunity to apply a good solution to a problem. The point of an AntiPattern is to recognize the nature of a bad situation and suggest solutions.

Section 11.3. BusyBox Operation

11.3. BusyBox Operation When you build BusyBox, you end up with a binary called, you guessed it, busybox. BusyBox can be invoked from the binary name itself, but it is more usually launched via a symlink. When BusyBox is invoked without command line parameters, it produces a list of the functions that were enabled via the configuration. Listing 11-3 shows such an output (it has been formatted slightly to fit the page width). Listing 11-3. BusyBox Usage root@coyote # ./busybox BusyBox v1.01 (2005.12.03-18:00+0000) multi-call binary Usage: busybox [function] [arguments]... or: [function] [arguments]... BusyBox is a multi-call binary that combines many common Unix utilities into a single executable. Most people will create a link to busybox for each function they wish to use and BusyBox will act like whatever it was invoked as! Currently defined functions: [, ash, basename, bunzip2, busybox, bzcat, cat, chgrp, chmod, chown, chroot, chvt, clear, cmp, cp, cut, date, dd, deallocvt, df, dirname, dmesg, du, echo, egrep, env, expr, false, fgrep, find, free, grep, gunzip, gzip, halt, head, hexdump, hostname, id, ifconfig, init, install, kill, killall, klogd, linuxrc, ln, logger, ls, mkdir, mknod, mktemp, more, mount, mv, openvt, pidof, ping, pivot_root, poweroff, ps, pwd, readlink, reboot, reset, rm, rmdir, route, sed, sh, sleep, sort, strings, swapoff, swapon, sync, syslogd, tail, tar, tee, test, time, touch, tr, true, tty, umount, uname, uniq, unzip, uptime, usleep, vi, wc, wget, which, whoami, xargs, yes, zcat From Listing 11-3, you can see the list of functions that are enabled in this BusyBox build. They are listed in alphabetical order from ash (a shell optimized for small memory footprint) to zcat, a utility used to decompress the contents of a compressed file. This is the default set of utilities enabled in this particular BusyBox snapshot. To invoke a particular function, execute busybox with one of the defined functions passed on the command line. Thus, to display a listing of files in the current directory, execute this command: [root@coyote]# ./busybox ls Another important message from the BusyBox usage message in Listing 11-3 is the short description of the program. It describes BusyBox as a multicall binary, combining many common utilities into a single executable. This is the purpose of the symlinks mentioned earlier. BusyBox was intended to be invoked by a symlink named for the function it will perform. This removes the burden of having to type a two-word command to invoke a given function, and it presents the user with a set of familiar commands for the similarly named utilities. Listings 11-4 and 11-5 should make this clear. Listing 11-4. BusyBox Symlink StructureTop Level [root@coyote]$ ls -l / total 12 drwxrwxr-x 2 root root 4096 Dec 3 13:38 bin lrwxrwxrwx 1 root root 11 Dec 3 13:38 linuxrc -> bin/busybox drwxrwxr-x 2 root root 4096 Dec 3 13:38 sbin drwxrwxr-x 4 root root 4096 Dec 3 13:38 usr Listing 11-4 shows the target directory structure as built by the BusyBox package via the make install command. The executable busybox file is found in the /bin directory, and symlinks have been populated throughout the rest of the structure pointing back to /bin/busybox. Listing 11-5 expands on the directory structure of Listing 11-4. Listing 11-5. BusyBox Symlink StructureTree Detail [root@coyote]$ tree . |-- bin | |-- ash -> busybox | |-- busybox | |-- cat -> busybox | |-- cp -> busybox | |-- ... | '-- zcat -> busybox |-- linuxrc -> bin/busybox |-- sbin | |-- halt -> ../bin/busybox | |-- ifconfig -> ../bin/busybox | |-- init -> ../bin/busybox | |-- klogd -> ../bin/busybox | |-- ... | '-- syslogd -> ../bin/busybox '-- usr |-- bin | |-- [ -> ../../bin/busybox | |-- basename -> ../../bin/busybox |-- ... | |-- xargs -> ../../bin/busybox | '-- yes -> ../../bin/busybox '-- sbin '-- chroot -> ../../bin/busybox The output of Listing 11-5 has been significantly truncated for readability and to avoid a three-page listing. Each line containing an ellipsis (...) indicates that this listing has been pruned to show only the first few and last few entries of that given directory. In actuality, more than 100 symlinks can be populated in these directories, depending on what functionality you have enabled using the BusyBox configuration utility. Notice the busybox executable itself, the second entry from the /bin directory. Also in the /bin directory are symlinks pointing back to busybox for ash, cat, cp... all the way to zcat. Again, the entries between cp and zcat have been omitted from this listing for readability. With this symlink structure, the user simply enters the actual name of the utility to invoke its functionality. For example, to configure a network interface using the busybox ifconfig utility, the user might enter a command similar to this: $ ifconfig eth1 192.168.1.14 This would invoke the busybox executable through the ifconfig symlink. BusyBox examines how it was calledthat is, it reads argv[0] to determine what functionality is executed. 11.3.1. BusyBox Init Notice the symlink in Listing 11-5 called init. In Chapter 6 "System Initialization," you learned about the init program and its role in system initialization. Recall that the kernel attempts to execute a program called /sbin/init as the last step in kernel initialization. There is no reason why BusyBox can't emulate the init functionality, and that's exactly how the system illustrated by Listing 11-5 is configured. BusyBox handles the init functionality. BusyBox handles system initialization differently from standard System V init. A Linux system using the System V (SysV) initialization as described in Chapter 6 requires an inittab file accessible in the /etc directory. BusyBox also reads an inittab file, but the syntax of the inittab file is different. In general, you should not need to use an inittab if you are using BusyBox. I agree with the BusyBox man page: If you need run levels, use System V initialization.[2] [2] We covered the details of System V initialization in Chapter 6. Let's see what this looks like on an embedded system. We have created a small root file system based on BusyBox. We configured BusyBox for static linking, eliminating the need for any shared libraries. Listing 11-6 contains a tree listing of this root file system. We built this small file system using the steps outlined in Chapter 9, "File Systems," Section 9.10, "Building a Simple File System." We do not detail the procedure again here. The files in our simple file system are those shown in Listing 11-6. Listing 11-6. Minimal BusyBox Root File System $ tree . |-- bin | |-- busybox | |-- cat -> busybox | |-- dmesg -> busybox | |-- echo -> busybox | |-- hostname -> busybox | |-- ls -> busybox | |-- ps -> busybox | |-- pwd -> busybox | '-- sh -> busybox |-- dev | '-- console |-- etc '-- proc 4 directories, 10 files This BusyBox-based root file system occupies little more than the size needed for busybox itself. In this configuration, using static linking and supporting nearly 100 utilities, the BusyBox executable came in at less than 1MB: # ls -l /bin/busybox -rwxr-xr-x 1 root root 824724 Dec 3 2005 /bin/busybox Now let's see how this system behaves. Listing 11-7 captures the console output on power-up on this BusyBox-based embedded system. Listing 11-7. BusyBox Default Startup ... Looking up port of RPC 100003/2 on 192.168.1.9 Looking up port of RPC 100005/1 on 192.168.1.9 VFS: Mounted root (nfs filesystem). Freeing init memory: 96K Bummer, could not run '/etc/init.d/rcS': No such file or directory Please press Enter to activate this console. BusyBox v1.01 (2005.12.03-19:09+0000) Built-in shell (ash) Enter 'help' for a list of built-in commands. -sh: can't access tty; job control turned off / # The example of Listing 11-7 was run on an embedded board configured for NFS root mount. We export a directory on our workstation that contains the simple file system image detailed in Listing 11-6. As oneof the final steps in the boot process, the Linux kernel on our target board mounts a root file system via NFS. When the kernel attempts to execute /sbin/init, it fails because there is no /sbin/init on our file system. However, as we have seen, the kernel also attempts to execute /bin/sh. In our BusyBox-configured target, this succeeds, and busybox is launched via the symlink /bin/sh on our root file system. The first thing BusyBox displays is the complaint that it can't find /etc/init.d/rcS. This is the default initialization script that BusyBox searches for. Instead of using inittab, this is the preferred method to initialize an embedded system based on BusyBox. When it has completed initialization, BusyBox displays a prompt asking the user to press Enter to activate a console. When it detects the Enter key, it executes an ash shell session waiting for user input. The final message about job control is a result of the fact that we are creating the system console on a serial terminal. The Linux kernel contains code to disable job control if it detects the console on a serial terminal. This example produced a working system, with nearly 100 Linux utilities available, including core utilities, file utilities, network support, and a reasonably capable shell. You can see that this simple package provides a powerful platform upon which to build your own system applications. Of course, it should be noted that without any support for libc and other system libraries, you would face a formidable task implementing your applications. You would have to provide support for all the usual system calls and other library functions that a typical C program relies on. Alternatively, you could statically link your applications against the libraries it depends on, but if you have more than a couple applications using this method, your applications will likely exceed the combined size of linking dynamically and having the shared libraries on your target. 11.3.2. Example rcS Initialization Script Before BusyBox spawns an interactive shell, it tries to execute commands from a script called /etc/init.d/rcS, as shown in Listing 11-7. It is here where your applications come to life in a BusyBox system. A simple rcS initialization script is provided in Listing 11-8. Listing 11-8. Simple rcS BusyBox Startup Script #!/bin/sh echo "Mounting proc" mount -t proc /proc /proc echo "Starting system loggers" syslogd klogd echo "Configuring loopback interface" ifconfig lo 127.0.0.1 echo "Starting inetd" xinetd # start a shell busybox sh This simple script is mostly self-explanatory. First, it is important to mount the /proc file system on its reserved mount point, /proc. This is because many utilities get their information from the /proc file system. This is explained more fully in Chapter 9. Next we launch the system loggers as early as possible, to capture any startup problems. Following the system log daemons, we configure the local loopback interface for the system. Again, a number of traditional Linux facilities assume that a loopback interface is present, and if your system has support for sockets configured, you should enable this pseudo interface. The last thing we do before starting a shell is launch the Internet superserver xinetd. This program sits in the background listening for network requests on any configured network interfaces. For example, to initiate a telnet session to the board, xinetd intercepts the request for telnet connection and spawns a telnet server to handle the session. Instead of starting a shell, your own applications can be launched from this rcS initialization script. Listing 11-8 is a simple example of a Telnet-enabled target board running basic services such as system and kernel loggers. 11.3.3. BusyBox Target Installation The discussion of BusyBox installation can proceed only when you understand the use and purpose of symlinks. The BusyBox makefile contains a target called install. Executing make install creates a directory structure containing the busybox executable and a symlink tree. This environment needs to be migrated to your target embedded system's root directory, complete with the symlink tree. The symlink tree eliminates the need to type busybox command for each command. Instead, to see a listing of files in a given directory, the user need only type ls. The symlink executes busybox as described previously and invokes the ls functionality. Review Listing 11-4 and Listing 11-5 to see the symlink tree. Note that the BusyBox build system creates links only for the functionality that you have enabled via the configuration utility. The easiest way to populate your root file system with the necessary symlink farm is to let the BusyBox build system do it for you. Simply mount your root file system on your development workstation and pass a PREFIX to the BusyBox makefile. Listing 11-9 shows the procedure. Listing 11-9. Installing BusyBox on Root File System $ mount -o loop bbrootfs.ext2 /mnt/remote $ make PREFIX=/mnt/remote install /bin/sh applets/install.sh /mnt/remote /mnt/remote/bin/ash -> busybox /mnt/remote/bin/cat -> busybox /mnt/remote/bin/chgrp -> busybox /mnt/remote/bin/chmod -> busybox /mnt/remote/bin/chown -> busybox ... /mnt/remote/usr/bin/xargs -> ../../bin/busybox /mnt/remote/usr/bin/yes -> ../../bin/busybox /mnt/remote/usr/sbin/chroot -> ../../bin/busybox -------------------------------------------------- You will probably need to make your busybox binary setuid root to ensure all configured applets will work properly. -------------------------------------------------- $ chmod +s /mnt/remote/bin/busybox $ ls -l /mnt/remote/bin/busybox -rwsr-sr-x 1 root root 863188 Dec 4 15:54 /mnt/remote/bin/busybox First we mount the root file system binary image on our desired mount pointin this case, /mnt/remote, a favorite of mine. Then we invoke the BusyBox make install command, passing it a PREFIX specifying where we want the symlink tree and busybox executable file to be placed. As you can see from the listing, the makefile invokes a script called applets/install.sh to do the bulk of the work. The script walks through a file containing all the enabled BusyBox applets and creates a symlink for each one on the path we have specified using the PREFIX. The script is very chatty; it outputs a line for each symlink created. For brevity, only the first few and last few symlink announcements are displayed. The ellipsis in the listing represents those we have eliminated. The message about setuid is also displayed by the install script, to remind you that it might be necessary to make your busybox executable setuid root. This is to allow BusyBox functions that require root access to function properly even when invoked by a nonroot user. This is not strictly necessary, especially in an embedded Linux environment, where it is common to have only a root account on a system. If this is necessary for your installation, the required command (chmod +s) is shown in Listing 11-9. The result of this installation step is that the busybox binary and symlink tree are installed on our target root file system. The end result looks very similar to Listing 11-4. It is useful to note that BusyBox also has an option to enable creation of this symlink tree on the target system at runtime. This option is enabled in the BusyBox configuration and is invoked at runtime by executing busybox with the -install option. You must have the /proc file system mounted on your target system for this support to work. 11.3.4. BusyBox Commands In a recent BusyBox snapshot, 197 commands (also called applets) were documented in the man page. There is sufficient support for reasonably complex shell scripts, including support for Bash shell scripting. BusyBox has support for awk and sed, frequently found in Bash scripts. BusyBox supports network utilities such as ping, ifconfig, TRaceroute, and netstat. Some commands are specifically included for scripting support, including true, false, and yes. Spend a few moments perusing Appendix C, "BusyBox Commands," where you can find a summary of each BusyBox command. After you have done so, you will have a better appreciation for the capabilities of BusyBox and how it might be applicable to your own embedded Linux project. As mentioned at the beginning of this chapter, many of the BusyBox commands contain a limited subset of features and options compared to their full-featured counterparts. In general, you can get help on any given BusyBox command at runtime by invoking the command with the --help option. This produces a usage message with a brief description of each supported command option. The BusyBox gzip applet is a useful example of a BusyBox command that has support for a limited set of options. Listing 11-10 displays the output from gzip-help on a BusyBox target. Listing 11-10. BusyBox gzip Applet Usage / # gzip --help BusyBox v1.01 (2005.12.01-21:11+0000) multi-call binary Usage: gzip [OPTION]... [FILE]... Compress FILE(s) with maximum compression. When FILE is '-' or unspecified, reads standard input. Implies -c. Options: -c Write output to standard output instead of FILE.gz -d Decompress -f Force write when destination is a terminal The BusyBox version of gzip supports just three command line options. Its full-featured counterpart contains support for more than 15 different command line options. For example, the full-featured gzip utility supports a --list option that produces compression statistics for each file on the command line. No such support exists for BusyBox gzip. This is usually not a significant limitation for embedded systems. We present this information so you can make an informed choice when deciding on BusyBox. When the full capabilities of a utility are needed, the solution is simple: Delete support for that particular utility in the BusyBox configuration and add the standard Linux utility to your target system.

Part 1: Hibernate in a Hurry

Our first goal is to get up to speed with Hibernate as quickly as
possible. Most of the chapters in this part are updated versions of
content from Hibernate: A Developer's Notebook
(O'Reilly), reflecting the major changes that came about with Hibernate 3.
The sample code now works with the latest versions of the tools we rely on
to provide an easy yet realistic environment for working with Hibernate.
There is also a new chapter covering the ability to use Java 5
annotations, rather than XML mapping files, to
configure Hibernate mappings.

NOTE

Of course, with any printed book about active open source
projects, things will get out of date quickly! See Appendix E for the
specific versions we discuss, and for ideas on how to cope with
changes.

Getting started and following along with the examples is even easier
in this new version of the book because we've adopted Maven to help
download many of the tools and libraries. As we hope you will see, there's
no excuse to avoid diving in and trying this stuff yourself!

Once you're comfortable with the fundamentals of Hibernate, Part 2 will demonstrate
how to tie Hibernate into some other environments to make each more
powerful than they are on their own.

All right, time to dive in….

Chapter 1. Installation and Setup

It continues to amaze me how many great, free, open source Java™ tools
are out there. When I needed a lightweight object/relational mapping service
for a JSP e-commerce project at the turn of the
millennium, I had to build my own. It evolved over the years, developed some
cool and unique features, and we've used it in a wide variety of different
contexts. But, once I discovered Hibernate, we used that for new development
instead of my own familiar system (toward which I'll cheerfully admit bias).
That should tell you how compelling it is!

If you're looking at this book, you're likely interested in a powerful
and convenient way to bridge the worlds of Java objects and relational
databases. Hibernate fills that role very nicely, without being so
complicated that learning it becomes a daunting challenge in itself. To
demonstrate that, this chapter guides you to the point where you can play
with Hibernate and see for yourself why it's so exciting.

Later chapters will look at using Hibernate as part of more complex
environments such as Spring and Stripes, as well as using it with other
databases. The goal of this first chapter is to show you how easy it is to
put together a basic, self-contained environment in which you can explore
Hibernate and do real things with it.

1.1. Getting an Ant Distribution

Although it might be surprising, the first few things you need
to get Hibernate running have nothing to do with Hibernate
itself. First, you must set up an environment in which the remaining
examples work. This will have the pleasant side effect of building a solid
foundation for any actual project you might be undertaking.

If you're not already using Ant to manage the building, testing,
running, and packaging of your Java projects, now is the time to start.
The examples in this book are Ant-driven, so you'll need a working Ant
installation to run them and experiment with variations on your own
system, which is the best way to learn.

First of all, get an Ant binary and install it.

1.1.1. Why do I care?

The examples use Apache Ant for several reasons. It's convenient
and powerful; it's one of the standard build tools for Java-based
development; it's free; and it's cross-platform. If you use Ant, the
examples will work equally well anywhere there's a Java environment,
which means readers of this book won't be frustrated or annoyed.
Fortunately, it also means we can do many more cool things with less
effort—especially since several Hibernate tools have explicit Ant
support, which I'll show you how to leverage. (I should note that these
days more complex Java projects often use Maven, which adds many other
project management capabilities. Since I had to pick one, in the spirit
of keeping things simple and true to what I find useful, I went with Ant
for these examples.)

If you are currently using Maven as a build tool, you will notice that we are using Maven's Ant Tasks to
manage dependencies from our Ant builds. Although Maven is gaining
momentum, Ant continues to be the most widely used build tool in Java
development. Every chapter's example code folder also has a Maven
pom.xml file and can be compiled
with Maven. In many cases, the Maven build file provides the same
functionality as the Ant build.xml
file by using the Maven Hibernate3 plug-in. In Chapter 12 you will find some
guidance for building and deploying Hibernate applications using
full-blown Maven, but the majority of the examples in this book focus on
Ant as a build tool, using the Maven Ant Tasks to relieve the tedium of
finding and downloading the various libraries we need, and the libraries
on which they, in turn, rely.

To take advantage of all these capabilities, you need to have Ant
installed and working on your system.

NOTE

I used to wonder why people bothered with Ant when they could
use Make. Now that I've seen how well Ant manages Java builds, I feel
lost without it.

1.1.2. How do I do that?

You can download a binary release of Ant from http://ant.apache.org/bindownload.cgi. Scroll down to
find the current release of Ant, and download the archive in a format
that's convenient for you to work with. Pick an appropriate place for it
to live, and expand the archive there. The directory into which you've
expanded the archive is referred to as ANT_HOME.
Let's say you've expanded the archive into the directory /usr/local/apache-ant-1.7.0; you may want to
create a symbolic link to make it easier to work with and to avoid the
need to change any environment configuration when you upgrade to a newer
version:

/usr/local % ln -s apache-ant-1.7.0 ant

Once Ant is situated, you need to do a couple of things to make it
work correctly. You need to add its bin directory in the distribution (in this
example, /usr/local/ant/bin) to
your command path. You also need to set the environment variable
ANT_HOME to the top-level directory you installed (in
this example, /usr/local/ant).
Details about how to perform these steps under different operating
systems can be found in the Ant manual (http://ant.apache.org/manual/) if you need
them.

Section 6.2. Defining a Persistent Enumerated Type

6.2. Defining a Persistent Enumerated Type

An enumerated type is a common and
useful programming abstraction allowing a value to be selected
from a fixed set of named choices. These were originally well represented
in Pascal, but C took such a minimal approach (essentially just letting
you assign symbolic names to interchangeable integer values) that early
Java releases reserved C's enum keyword but
declined to implement it. A better, object-oriented approach known as the
"typesafe enum pattern" evolved and was popularized in Joshua Bloch's
Effective Java. This approach required a fair
amount of boilerplate coding, but it lets you do all kinds of interesting
and powerful things. One of the many delightful innovations in the Java 5
specification was the ability to resuscitate the enum keyword as an easy way to get the power of
typesafe enumerations without all the tedious boilerplate coding, and it
provides other nifty benefits.

NOTE

C-style numeric "enumerations" still appear too often in Java.
Older parts of the Sun API contain many of
them.

Regardless of how you implement an enumerated type, you're sometimes
going to want to be able to persist such values to a database. And even
though there is now a standard way to do it in Java, Hibernate doesn't
offer any built-in support. So let's see how to implement a
UserType that can persist an enum for us.

Let's suppose we want to be able to specify whether our tracks came
from cassette tapes, vinyl, VHS tapes,
CDs, a broadcast, an Internet download site, or a
digital audio stream. (We could go really nuts and distinguish between
Internet streams and satellite radio services like Sirius or
XM, or radio versus television broadcast, but this is
plenty to demonstrate the important ideas.)

Without any consideration of persistence, our typesafe enumeration
class might look something like Example 6-1. (The JavaDoc has been compressed to take
less printed space, but the downloadable version is formatted
normally.)

Example 6-1. SourceMedia.java, our initial typesafe enumeration

Code View: package com.oreilly.hh; /** * This is a typesafe enumeration that identifies the media on which an * item in our music database was obtained. */ public enum SourceMedia { /** Music obtained from magnetic cassette tape. */ CASSETTE("Audio Cassette Tape"), /** Music obtained from a vinyl record. */ VINYL("Vinyl Record"), /** Music obtained from VHS tapes. */ VHS("VHS Videocassette tape"), /** Music obtained from a broadcast. */ BROADCAST("Analog Broadcast"), /** Music obtained from a digital compact disc. */ CD("Compact Disc"), /** Music obtained as an Internet download. */ DOWNLOAD("Internet Download"), /** Music obtained from a digital audio stream. */ STREAM("Digital Audio Stream"); /** * Stores the human-readable description of this instance, by which it is * identified in the user interface. */ private final String description; /** * Enum constructors are always private since they can only be accessed * through the enumeration mechanism. * * @param description human readable description of the source for the * audio, by which it is presented in the user interface. */ private SourceMedia(String description) { this.description = description; } /** * Return the description associated with this enumeration instance. * * @return the human-readable description by which this value is * identified in the user interface. **/ public String getDescription() { return description; } }

Of course, the beauty of working with Hibernate is that we don't
need to change our normal Java classes to add support for persistence.
Even though we've not thought about persistence in designing this enum, we will be able to use it as-is. Now that
we no longer have to consider using the deprecated PersistentEnum interface, defining a
persistent enumerated type is no different than defining any other
enumerated type.

NOTE

The PersistentEnum interface did require
you to change your enumerations for persistence. That was probably an
even bigger reason why it was deprecated than the fact that it did not
mesh well with the Effective Java persistent
enumeration pattern or the Java 5 enum
keyword.

So how do we teach Hibernate to persist values of our
enumeration?

Chapter 13. Databases and Persistence

Chapter 13. Databases and Persistence We all want to leave behind something that will outlast us, and Ruby processes are no exception. Every program you write leaves some record of its activity, even if it's just data written to standard output. Most larger programs take this one step further: they store data from one run in a structured file, so that on another run they can pick up where they left off. There are a number of ways to persist data, from simple to insanely complex. Simple persistence mechanisms like YAML let you write Ruby data structures to disk and load them back later. This is great for simple programs that don't handle much data. Your program can store its entire state in a disk file, and load the file on its next invocation to pick up where it left off. If you never keep more data than can fit into memory, the simplest way to make it permanent is to store it with YAML, Marshal, or Madeleine, and reload it later (see Recipes 13.1, 13.2, and 13.3). Madeleine also lets you revisit the prior states of your data. If your dataset won't fit in memory, you need a database: a way of storing data on disk (usually in an indexed binary format) and retrieving parts of it quickly. The Berkeley database is the simplest database we cover: it operates like a hash, albeit a hash potentially much bigger than any you could keep in memory (Recipe 13.6). But when most people think of a "database" they think of a relational database: MySQL, Postgres, Oracle, SQLite, or the like. A persistence mechanism stores data as Ruby data structures, and a Berkeley DB stores data as a hash of strings. But relational databases store data in the form of structured records with typed fields. Because the tables of a relational database can have a complex structure and contain gigabytes of data, their contents are not accessed like normal Ruby data structures. Instead they're queried with SQL, a special programming language based on relational algebra. Most of the development time that goes into Ruby database libraries is spent trying to hide this fact. Several libraries hide the details of communication between a Ruby program and a SQL database; the balance of this chapter is devoted to showing how to use them. Every relational database exposes a C API, and Ruby bindings to each API are available. We show you how to use the two most popular open source databases: MySQL (Recipe 13.9) and Postgres (Recipe 13.10).[1] But every database has different bindings, and speaks a slightly different variant of SQL. Fortunately, there are other libraries that hide these differences behind a layer of abstraction. Once you install the bindings, you can install abstraction layers atop them and rely on the abstraction layer to keep track of the differences between databases. [1] SQLite deserves an honorable mention because, unlike other relational databases, it doesn't require a server to run. The client code can directly query the database file. This makes things a lot easier to set up. Note that SQLite has two incompatible file formats (version 2 and version 3), and a gem exists for each version. You probably want the sqlite3-ruby gem. Ruby's simplest database abstraction library is DBI (it's modeled after Perl's DBI module). It does nothing more than provide a uniform interface to the different database bindings. You still have to write all the SQL yourself (and if you're serious about database neutrality, you must use the lowest common denominator of SQL), but you only have to learn a single binding API. The more popular database abstraction libraries are ActiveRecord (the library of choice for Rails applications) and Og. Not only do these libraries hide the differences between databases, they hide most of the actual SQL. The database tables are represented as Ruby classes, the rows in the database tables as instances of those classes. You can find, create, and modify database rows by manipulating normal-looking Ruby objects. Neither Og nor ActiveRecord can do everything that raw SQL can, so you may also need to use DBI or one of the database-specific bindings. One standard argument for database abstraction layers is that they make it easy to switch an application's underlying database without having to rewrite all the code. They certainly do make this easier, but it almost never happens.[2] The real advantage is that with abstraction layers, you don't have to learn all the different database bindings. Even if you never change databases for any given project, throughout your career you'll find yourself using different databases on different projects. Learning how to use a database abstraction layer can save you from having to learn multiple database-specific bindings. [2] What does happen is that you may write a product designed to work with whatever database the user has installed. You can't always require that your users run a specific database. Whether you use ActiveRecord, Og, DBI, or database-specific bindings, you'll need an actual database for your code to connect to. The recipes in this chapter assume you've got a database called cookbook and that you connect to it with the username "cookbook_user" and the password "password". Here's how to set up cookbook as a MySQL database: $ mysql -u root Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 6 to server version: 4.0.24_Debian-10-log Type 'help;' or '\h' for help. Type '\c' to clear the buffer. mysql> create database cookbook; Query OK, 1 row affected (0.00 sec) mysql> grant all privileges on cookbook.* to 'cookbook_user'@'localhost' identified by 'password'; Query OK, 0 rows affected (0.00 sec) Here's how to set cookbook up as a Postgres database (you'll probably need to run these commands as the postgres user): $ createuser Enter name of user to add: cookbook_user Enter password for new user: password Enter it again: password Shall the new user be allowed to create databases? (y/n) y Shall the new user be allowed to create more new users? (y/n) n CREATE USER $ createdb cookbook CREATE DATABASE To avoid showing you the database connection code in every single recipe, we've factored it out into a library. If you want to run the code in this chapter's recipes, you should put the following code in a file called cookbook_dbconnect.rb. Keep it in the directory where you keep the recipe code, or somewhere in your library include path, so that require 'cookbook_dbconnect' will work. This file defines database connection functions for DBI, ActiveRecord, and Og: # cookbook_dbconnect.rb require 'rubygems' require 'dbi' require 'active_record' require 'og' The with_db method gets a database connection through DBI and runs a code block in the context of that connection: def with_db DBI.connect("dbi:Mysql:cookbook:localhost", "cookbook_user", "password") do |c| yield c end end The activerecord_connect method only needs to be called once at the beginning of a program: after that, ActiveRecord will acquire database connections as needed. def activerecord_connect ActiveRecord::Base.establish_connection(:adapter => "mysql", :host => "localhost", :username => "cookbook_user", :password => "password", :database => "cookbook") end For your reference, this table presents the ActiveRecord adapter names for various kinds of databases. Table 13-1. Database Adapter name MySQL mysql PostgreSQL postgresql Oracle oci Microsoft SQL Server sqlserver SQLite 2 sqlite SQLite 3 sqlite3 DB2 db2 The og_connect also needs to be called only once. One caveat: you must call it after you've defined the classes for your Og data model. def og_connect Og.setup( { :destroy => false, :store => :mysql, :user => "cookbook_user", :password => "password", :name => "cookbook" } ) end This version of cookbook_dbconnect assumes you're running against a MySQL database. For a different database, you just need to change the database name so that DBI, ActiveRecord, and Og know which adapter they should use. Here are some resources for more information about databases in Ruby: http://ruby-dbi.rubyforge.org/ http://www.rubyonrails.org/show/ActiveRecord http://www.rubygarden.com/index.cgi/Libraries/og_tutorial.rdoc