Apress, Java, a Bunch of New Books and What's to Come

by Jessica Sant

Return to Top

An Interview with Jacquie Barker, author of Beginning Java Objects

by Jessica Sant

Return to Top

Touring the Commons - part 2

by Jason Menard (jason@javaranch.com)

This is the second in a three part series discussing elements of the Jakarta Commons project. The first part discussed the Commons BeanUtils package, the second part discusses the Commons Digester package, and the final part will demonstrate using these packages together to build a framework for dynamically generating data transfer objects.

Introduction

Last month we took a look at using the Jakarta Commons BeanUtils package to dynamically create and manipulate JavaBeans. This month we take a look at another very useful component of the Commons project - Digester. Digester is a component that facilitates the easy mapping of XML documents to Java objects.

The reasons why you might want to map an XML document to a set of Java objects are nearly limitless. A primary reason you might do this is to extract configuration information stored in an XML file to use in your own classes. Maybe you need this capability simply because "that's where the data is". XML is a popular format for storing a large variety of information, and having the ability to easily map this data to your own set of application specific objects is nothing to sneeze at. Regardless what your motivation is, it's very likely that Digester is just what you've been looking for.

The Problem: A Collection of Book Reviews

We have an XML file containing the book reviews here at JavaRanch, along with information about the books being reviewed. We want to write a Swing application to add new reviews and edit existing reviews. It is obvious to us that we need a way to import the XML data and have it mapped to a set of Java classes which we will use within our application. We decide to use Digester to handle the object mapping for us.

First, let's take a look at a snippet of our XML. See reviews.xml for the entire file.

<books>
  <book>
    <title>Design Patterns</title>
    <category>Design Patterns, UML, and Refactoring</category>
    <edition number="1">
      <author>
        <lastName>Gamma</lastName>
        <firstName>Erich</firstName>
      </author>
      <author>
        <lastName>Helm</lastName>
        <firstName>Richard</firstName>
      </author>
      <author>
        <lastName>Johnson</lastName>
        <firstName>Ralph</firstName>
      </author>
      <author>
        <lastName>Vlissides</lastName>
        <firstName>John</firstName>
      </author>
      <isbn>0201633612</isbn>
      <review>
        <rating>8</rating>
        <content>The most popular computer science book of all time...</content>
        <reviewer>Paul Wheaton</reviewer>
	<ranchCategory>trailboss</ranchCategory>
        <reviewDate>
          <month>1</month>
          <year>2000</year>
        </reviewDate>
      </review>
    </edition>
  </book>
</books>

This looks straightforward enough. We have a collection of books, each of which has a title, a category for the type of book it is, and one or more editions. We see that each edition has one or more authors (each having first and last names), an ISBN number, and one or more reviews. Taking a look at the reviews, we can see that each review is given a rating, has the month and year the review was done, the text of the review, and the name and JavaRanch category of the person who did the review. Based on this information we come up with Books.java, Book.java, Edition.java, Author.java, and Review.java. Since the review month and review year are one-to-one mappings with Review, we made them properties of Review since there was no need for a separate class just to store those two pieces of information.

Let's take a look at our Book class.

public class Book {
    private String title;
    private ArrayList editions = new ArrayList();

    public Book() {
    }

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }

    public List getEditions() {
        return editions;
    }

    public void addEdition(Edition edition) {
        editions.add(edition);
    }
}

The only thing to really note here is that there is an addEdition() method for adding an Edition object to an instance of Book. This is done throughout the classes we wrote where a class is maintaining a collection of objects, just like Book has a collection of Editions. We will need to have methods like this when we start working with Digester.

Now that we have some XML and some classes to map the XML to, let's take a look at using Digester.

Inside Digester

Digester uses three main concepts that must be understood in order to effectively make use of it: the object stack, element matching patterns, and processing rules.

The Object Stack

The Digester class maintains an internal stack of objects. Typically objects are pushed onto the stack or popped off of the stack according to processing rules. The Digester class contains the typical operations for manipulating the stack: clear(), peek(), push(), and pop().

• clear() - removes all objects from the stack
• peek() - gets a reference to the top object on the stack, but doesn't remove it
• push() - places an object on top of the stack
• pop() - removes the top object from the stack

Just to make sure we are all clear on how a stack works, let's walk through a quick example. I have a stack 'S' which is currently empty. I will represent it like so:

===
 S

Next let's push an Object 'A' onto the stack using the push() method. Our stack now looks like the following:

 A
===
 S

After pushing two more objects on the stack, 'B' and 'C' in that order, the stack is in the following state:

 C
 B
 A
===
 S

A call to peek() would return a reference to 'C', but the stack would remain in its current state. If we were to now pop() the stack, we would get a reference to 'C' and our stack would be left in the following state:

 B
 A
===
 S

Calling clear() would naturally remove all objects from the stack:

===
 S

Element Matching Patterns

Digester uses element matching patterns to describe the location of elements of your XML document relative to each other. You can think of it as similar to a directory hierarchy. Looking back at our XML document we can see that the first element in the document is the <books> element. The element matching pattern for the <books> element is simply:

books

Getting back to the analogy of our XML document as a directory tree, if we can imagine our XML document as being the "directory" that we are currently in, then referencing the <books> element with the element matching pattern that is simply "books" seems to make sense.

Well how about the <book> element? Our XML document lays it out like this:

<books>
  <book>

books/book

Once again, if we could imagine our XML document as a directory tree structure, this makes perfect sense. Let's try one more. What would the element matching pattern be for the author's last name? If you said...

books/book/edition/author/lastName

...then you are absolutely correct. Nothing too fancy here. It's a fairly straightforward concept.

Processing Rules

Processing rules are used by Digester to determine what actions need to be taken when the parser encounters a given element matching pattern. Processing rules typically are used to manipulate the stack (for example, popping an object off of the stack), create objects, and manipulate objects on the stack. Digester's processing rules are classes that implement the Rule interface.

Processing rules are fired when the parser matches the rule's element matching pattern. In other words, when the parser encounters the specified element in the XML document, the rule is triggered. Just like an XML element has a beginning tag, body content, and a closing tag, a Rule has a begin() method, a body() method, and an end() method. The begin() method of the Rule is called when the beginning of the XML element is encountered, the body() method is called when the body of the XML element is encountered, and the end() method is called when the end of the XML element is encountered. When parsing is complete, the finish() method of the rule is called, in order to take care of any resources which might need to be cleaned up.

While you may write your own rules, and in fact may often need to do so, the Digester package comes with several common Rule implementations. The Digester class has methods to register these processing rules. We'll take a look at a few of the more common processing rules and the Digester methods which register them.

ObjectCreateRule - This rule is used to create an instance of an object. The object is created by callings its no-argument constructor and pushed onto the stack when the begin() method is called. When the end() method is called, the object is popped off of the stack. To register an ObjectCreateRule that creates a new Book object whenever the <book> element is encountered, we make a call to Digester's addObjectCreate() method:

Digester digester = new Digester();
digester.addObjectCreate("books/book", Book.class);

We can see that addObjectCreate() take an element matching pattern and the class of the Java object to be created. In fact, every Digester method we'll look at that creates a Rule will take an element matching pattern as its first parameter.

BeanPropertySetRule - Sets a property of the bean that is the top object in the stack. By default, the property of the bean set is the same as the name of the current XML element being examined. The value set is the body content of the XML element.

digester.addBeanPropertySetter("books/book/title");

In the above example, setTitle() will be called on the bean on top of the object stack, setting that property with the body content of the <title> tag.

SetPropertiesRule - Sets a property of the bean that is the top object in the stack to the value of an XML attribute.

digester.addSetProperties("books/book/edition", "number", "number");

This example registers a SetPropertiesRule that calls the method setNumber()(the third argument of addSetProperties()) of the object on top of the stack, setting the value to the number attribute (the second argument of addSetProperties()) of the <edition> element.

SetPropertyRule - Sets a property of the bean on top of the stack to a value of an XML attribute. The property of the bean to be set is specified by another XML attribute.

For example, given the XML element <set-property property="name" value="jason"/>...

digester.addSetProperty("some/pattern/set-property", "property", "value");

...would call the setName() method of the object on top of the stack, passing the value "jason" as the argument.

CallMethodRule and CallParamRule - These two rules used in conjunction with each other allow the execution of arbitrary methods of the top bean on the stack. A CallMethodRule specifies the name of the method to call, the number of arguments that the method expects, and of course when it should be called as indicated by the element matching pattern. The method is called when the CallMethodRule's end() method executes. A CallParamRule indicates the values to be passed to method specified by the CallMethodRule. Values for the CallParamRule may be taken from either the character data of an XML element, or from an attribute of an XML element.

digester.addCallMethod("books/book/edition/isbn", "setIsbn", 1);
digester.addCallParam("books/book/edition/isbn", 0);

The first line in the above code specifies that the setIsbn() method should be called on the object on top of the stack, and that it takes one argument. The second line states that the character data of the <isbn> element should be passed as the first parameter (parameters are indexed zero-relative, so the first parameter has an index of 0) to the setIsbn() method. If we wanted to pass a parameter value from an XML element's attribute instead of its character data, our addCallParam() method might look something like this:

digester.addCallParam("books/book/edition", 0, "number");

In this case, the value passed will be taken from the number attribute of the <edition> element.

Looking back at the addCallMethod() method of Digester, one might think that to call a method that takes no attributes then we would use "0" as the value of the method's third argument. This is not the case however.

digester.addCallMethod("books/book/edition/isbn", "setIsbn", 0);

This example is a shorthand for the previous example where we used both addCallMethod() and addCallParam(). What this says is that we will call setIsbn() and pass the character data of the <isbn> element as the value of the argument to the method.

If these examples look like they accomplish essentially the same thing as a similar call to addBeanPropertySetter(), that is absolutely correct! The combination of addCallMethod() and addCallParam()do give us the flexibility to invoke arbitrary method calls however, which addBeanPropertySetter() does not provide for.

But what if we want to invoke a method that takes no arguments? In that case we can use the signature of addCallMethod() which takes only two methods - the element matching pattern and the name of the method, as in the following example:

digester.addCallMethod("some/pattern", "someMethod");

SetNextRule - This rule sets a property of the object that is next from the top of the stack, passing the object that is at the top of the stack as the value of the property being set. When the end() method is called, the object on top of the stack is popped and set to a property of the newly exposed top object. Typically a SetNextRule will be used to add one or more child objects to a parent object.

digester.addSetNext("books/book/edition/review", "addReview");

The example code shown here will call the addReview() method of the object that is next from the top of the stack, passing the object that is at the top of the stack as an argument. It is important to keep in mind that the stack is popped by this rule.

Using Digester

Once you understand the concepts outlined in the preceding sections, actually using Digester is really rather easy. All we need to do is follow a few simple steps and we are on our way.

The first thing we must do is create a new instance of Digester.

Digester digester = new Digester();

Now that we have our instance of Digester, we need to set any configuration properties that we might need. Configuration operations include whether or not the XML document should be validated against a DTD, the class loader to use for loading objects created by an ObjectCreateRule, and whether or not namespace aware parsing is enabled. There are a host of other configuration options, and I would urge you to read the API documents for further information.

digester.setValidating(false);

Next we must register our processing rules.

digester.addObjectCreate("books", Books.class);
digester.addObjectCreate("books/book", Book.class);
digester.addBeanPropertySetter("books/book/title");
digester.addObjectCreate("books/book/edition", Edition.class);
digester.addSetProperties("books/book/edition", "number", "number");
digester.addBeanPropertySetter("books/book/edition/isbn");
digester.addObjectCreate("books/book/edition/author", Author.class);
digester.addBeanPropertySetter("books/book/edition/author/lastName");
digester.addBeanPropertySetter("books/book/edition/author/firstName");
digester.addSetNext("books/book/edition/author", "addAuthor");
digester.addObjectCreate("books/book/edition/review", Review.class);
digester.addBeanPropertySetter("books/book/edition/review/rating");
digester.addBeanPropertySetter("books/book/edition/review/content");
digester.addBeanPropertySetter("books/book/edition/review/reviewer");
digester.addBeanPropertySetter("books/book/edition/review/reviewDate/month");
digester.addBeanPropertySetter("books/book/edition/review/reviewDate/year");
digester.addSetNext("books/book/edition/review", "addReview");
digester.addSetNext("books/book/edition", "addEdition");
digester.addSetNext("books/book", "addBook");

Once we register our processing rules we are almost home. In order to proceed we must identify our input XML document. In this example we are specifying a File, but the API specifies several other suitable input sources.

File input = new File(REVIEWS_XML);

If necessary, push any objects onto the stack that we need to. Finally all we need to do is call parse(), which returns the root object of the stack.

Books books = (Books)digester.parse(input);

That's all there is to it!. See ReviewDigester.java for the complete source code.

Conclusion

In this article we've seen just how easy it can be to create a mapping between an XML document and a hierarchy of Java objects. We focused on using the Rule implementations that Digester provides for us. Next month we will learn how to write our own Rule implementations, as well as what to do when you want to create an object using a constructor that takes arguments.

Digester has a few other tricks up its sleeve that we won't have time to look at. These include specifying our processing rules in XML and pluggable rules processing, among others. Take a look at the API documentation for more information.

Resources

• Jakarta Commons Digester

Please feel free to email me with any questions or comments concerning this article.

Return to Top

The Coffee House

by Solveig Haugland

This Month's Story: How to Convince Yourself or Your Grumpy Sysadmin to Adopt OpenOffice.org

"I'm a little afeared myself," admitted Brenda. "Guess this is one of them things they make movies about, ordinary people facing extraordinary challenges and courage and all that stuff."

Just then, like it happens in the movies, the swinging doors of the coffee house flung open and a tall, dark, handsome, and very very tired cowboy walked on into the coffee house and kinda slumped over the bar.

"Espresso...triple shot...please..." he gasped.

"Brenda, get this man a shot, pronto!" The women swung into action and before you could say JavaBeans, they had him perked up and feelin' good on espresso, with a cafe au lait chaser.

"Thank you, ladies! I can't say as I've ever had a finer Egyptian roast, 'cept maybe in Kansas City a few years ago in the height of the coffee boom."

Brenda blushed and could hardly respond, since she was the one who roasted the beans herself.

"And you know, I thought I overheard you gals talkin' about making the big courageous switch to OpenOffice.org. Did I hear right?"

Brenda and Lacey nodded. "You know somethin' about it, mister?"

"Call me Sam. Why yes I do, ladies. I ride my horse Ned throughout the West, stoppin' wherever people need a helpin' hand to make the switch from Microsoft Office to OpenOffice.org. I show folks how to do it smart, and that it ain't as hard as the Microsoft Folks make out."

"That would be just dandy, mister! I mean Sam." And before they could say 'Richard Stallman', the stranger had a couple of laptops set up with a projector, and had a clipboard out on his knee.

"All righty. Now there's usually about five things folks are afeared of when they want to switch from Microsoft Office to OpenOffice.org. Here's one of'em."

1. General fear of the unknown, fear of going to something that?s open source and potentially flaky or unsupported.

"Now I don't know about you ladies, but I ain't exactly had a fabulous time with the support you gotta pay for. You gals  need to go on the users@openoffice.org list (just look on the www.openoffice.org site) and talk to other folks who?ve switched. You mighta heard of Cassens Transport in Illinois, Ernie Ball Guit-tar in Washington, and Jefferson County government in Golden, Colorado, just down west apiece. Once you've talked to other folks who've done it, succeeded, and liked it, there'll be less general fear of the unknown."

"That's mighty true," Brenda admitted. "I sure would like to talk to other folks; that'd make me feel better for sure."

Sam nodded. "The folks on the users@openoffice.org list, by the way, are not only a font of information but they are as prompt and courteous as a lady could want."

"So let's take another look at something else y'all will have to do."

2. Converting existing documents.

"This can be a big ol' job, but it might be not so bad. All depends on what's in your documents. You could probably get some folks who come in here regular to help convert a few test documents to just see what all happens when you switch over. You got some guys who just sit here at the bar all day long who would help you switch over your spreadsheets and invoices and stuff to OpenOffice.org to see what would happen?"

"We sure do! Lefty and Sid, and Zeke too I think, have been itching to take their ranches Open Source. They'd sure help us out, that's a great idea."

"Dandy, that's dandy," replied Sam. "All righty. Here's the third thing."

3. Training

"This isn?t trivial-like," Sam began, "but it?s certainly manageable. If you take a look at the programs, you'll see they look a heck of a lot alike. You drive on into Dodge for a couple days, get yourself a couple days of training, get a couple books to take back, and you'll be surprised how much you can do. . Do the training early and often and in manageable chunks, Oh, and OpenOffice.org is just a bit weird with some things, you'll take a long time trying to find out how to do them. so make sure you get them books. I use them myself, this Norwegian feller is the one who wrote my "OpenOffice.org Resource Kit" and I like it real fine. Big index. Oh, and the whole OpenOffice.org CD is tucked real neat in the back, so you don't gotta download it. That's kinda nice."

"Well, OK," said Lacey, "that sounds like it could work. It doesn't sound like it would be all that expensive to head into Dodge. And I shore think it would be tax deductible."

4. Ya gotta commit.

"Here's the thing. If you gals keep Microsoft Office on your computers, you ain't never going to learn OpenOffice.org proper. You gotta take off the Awfice after a month or two and just use OpenOffice.org. Just like when you go to France for a trip -- you ain't never learnin' no French if you hang out with your American buddies."

5. It's just too much work, ain't it?

"It's finally just the effort of doing it. It seems intimidating, but think about it. Think about when you've done some test documents, and you've got some learnin' under your belt, and you've talked to other folks. It'll seem real easy at that point, once you've got your mental obstacles overcome- like."

"And I just wanna mention a couple dandy things. OpenOffice.org file sizes are tiny. If you're concerned about disk space that files take up on servers or going through email, OpenOffice.org will be a dandy change. And if you ladies have a lot of licenses for Canvas, Illustrator, or Visio, you might be able to get rid of those too and just use OpenOffice.org Draw. It's got them connector lines from Visio, the object and text manipulation things you can do in Illustrator, and the general types of things you can do in Canvas. Plus it's the easiest thing to use in the whole  OpenOffice.org program, I think."

Brenda and Lacey sighed happily and looked at each other. Brenda exclaimed "Dang, I can hardly wait to put that OpenOffice.org program on our computer! We can sure save a lot of money, not sendin' in to Uncle Bill for the upgrades and support and stuff. And I kinda like the idea of a nice drawing program tucked into it too. I could sure do a lot with that Draw thing."

"We should ask Sam if he could show us a couple things before he leaves. Sam--?? What in tarnation? He was here a second ago!"

But the swinging doors of the coffee house told the story clearly -- Sam had cleared out. Onto another town, to free people from their fears and from Uncle Bill.

Riding, always riding, into the west. Every day, one mile closer to Redmond.

Solveig Haugland is an independent writer and trainer based in Colorado. You can contact her through her myriad Web sites, www.getopenoffice.org, www.datingdesignpatterns.com, www.cafepress.com/datingpatterns, and www.cafepress.com/techspeak.

If you or your organization are leaning toward learning OpenOffice.org, Solveig can provide you with training, learning materials, and consulting. Contact her through solveig@getopenoffice.org.

Return to Top

Programming Diversions Puzzle

by Jason Menard

Binary Reflected Gray Code

Background

A Gray code is an ordered set of binary numbers such that only one bit changes from one element to the next. Any n-bit Gray code will have 2ⁿ elements. {000, 001, 011, 010, 110, 111, 101, 100} and {000, 010, 011, 001, 101, 100, 110, 111} are both examples of 3-bit Gray codes. Note that only one bit changes between each element and each set has 8 (2³) elements.

A binary reflected Gray code (BRGC) is a particular encoding for non-negative integers. To find a BRGC of n bits, take the BRGC of ( n - 1 ) bits, writing it forward and then backward. Prefix the first half of the binary numbers with 0, and prefix the second half of the binary numbers with 1. The binary reflected Gray code of 1 bit (integer values 0 and 1) is:

Integer   BRGC
=======   ====
      0      0
      1      1

To find the BRCG up through 2-bit integers (0, 1, 2, 3), write the BRCG of 1 bit going forward (0, 1), then backwards (1, 0), to get (0, 1, 1, 0). Prefix the first half of those numbers with 0 and the second half with 1, giving us:

Integer   BRGC
=======   ====
      0     00
      1     01
      2     11
      3     10

Looking at the above chart we came up with, we can see that the BRCG encoding for the integer 2 is 11.

Let's try it one more time, finding the BRCG for integers up to 3-bits (0, 1, 2, 3, 4, 5, 6, 7). First we write the 2 bit BRGC forward then backwards (00, 01, 11, 10, 10, 11, 01, 00). Finally we prefix the first half of those numbers with 0, and the second half with 1:

Integer   BRGC
=======   ====
      0    000
      1    001
      2    011
      3    010
      4    110
      5    111
      6    101
      7    100

Looking that the chart above tells us that the BRGC encoding for the integer 7 is 100.

The Challenge

Write a class BRGC containing three static methods. The first method displays a table of long integers and their BRGC encoded values up to n-bits. It should have the following signature:

public static void displayBRCG(long n)

Calling the method...

BRGC.displayBRGC(3);

...should produce something similar to the following output:

Integer   BRGC
=======   ====
      0    000
      1    001
      2    011
      3    010
      4    110
      5    111
      6    101
      7    100

The second method returns the BRGC encoded representation of an input non-negative long integer. It should have the following signature:

public static String encode(long n)

Calling the method...

System.out.println(BRGC.encode(5));

...should display 111 on the console.

The third method returns the long integer representation of an input BRGC encoding. It should have the following signature...

public static long decode(String brgc)

Calling the method...

System.out.println(BRGC.decode("111"));

...should display 5 on the console.

See the thread August Newsletter Puzzle in the Programming Diversions forum to post your answer and discuss this problem.

Return to Top

Mosey on in and pull up a stool. The JavaRanch Big Moose Saloon is the place to get your Java questions answered. Our bartenders keep the peace, and folks are pretty friendly anyways, so don't be shy!

Over in The Java In General (Beginner) Forum, JavaRanch's founder, Kathy Sierra, did a heck of a job tellin' folks about that dot in the whole CLASSPATH thing. Following is an excerpt from the original forum thread.

Question: Why do we define . in the Java classpath environment setting?

Answer: Both the compiler and the JVM need to find any of the classes that you're using in your code. If those classes are from the standard edition API, then no problem -- both java and javac know where *those* are. But they don't know about your *own* classes... the ones you're writing.

So... if you have a class that you just wrote, in a directory "foo", and the class is NOT in a package, then you cd to directory "foo" and then compile from that directory. That's the simplest way, to start out with. Including the dot "." in your classpath is the way you tell they system to "when you're looking for classes, be sure to look in the current directory (i.e. the one you cd to)."

Where to put that "."? You can add it permanently to your classpath as an environment variable in DOS (via autoexec.bat, if you're still on Windows 98!), or a property in Windows NT (I think -- can't remember it's been so long since I've seen NT). Or if you're on some flavor of Unix (including Mac OSX), you can put it in one of several places, including your .cshrc file (or whatever your initialization file is for your particular shell).

That's my preferred way... I never have to think about the current directory that way. (And you can still override that if you do NOT want the current directory to be included, which is sometimes necessary with RMI, but that's another story...)

Or, you can make sure that you have the "." by using the -classpath flag with java and javac:

java -classpath . MyClass

Or, you can do it just for your current terminal session, by using whatever it is you have to do for your particular shell. Something like:

%SET CLASSPATH = ${CLASSPATH}:.

(this says, "Take the current classpath, and add the current directory (.) to it, and then make that the new classpath setting for as long as this terminal is active.")

%java MyClass

(this is not necessarily *real* syntax)

If you use packages, it gets a little more complicated, although you'll still need the "." on the classpath.

What has troubled some programmers is that they are using an IDE which makes all kinds of settings for the classpath, and which may NOT include the current directory. That's when it's probably easiest to just use the -classpath flag:

javac -classpath . MyClass.java

There is of course more to the story than this, but if you're just starting out, this should work fine.

Return to Top