SOAP Web Services chapter added to MEAP

I just added a new chapter discussing Groovy and SOAP-based web services to the Manning Early Access Program (MEAP) version of Making Java Groovy. I prepared a decent introduction for the MEAP subscribers, which I thought I would share here:

“Though they’ve fallen out of favor recently, SOAP-based web services provide a perfect opportunity for Java/Groovy integration. The technology is mature, with known use cases and a tool set that has been added to Java’s standard edition. In this chapter, I go over the basics of web services with a focus on the wsimport and wsgen tools that are built into JDK 1.6.

Using Groovy to build a client-side web service application is almost trivial. The wsimport tool generates Java stubs, which Groovy can instantiate and use like any other Java class. I illustrate a case where a publicly-available web service returns XML, rather than objects, which is much easier to process with Groovy than with Java.

To create a web service, I find it much easier to use Groovy if the service implementation bean supports a service endpoint interface, even though that is not strictly required by the specification. The standard interface/implementation split makes mixing Java and Groovy wherever desired quite easy, however. There is a slight complication when dealing with domain classes, but as long as they are annotated to prefer field access rather than properties, everything works just fine.

In general, with SOAP-based web services no XML is exposed on either the client side or the server side. The exception is when using handlers to pre- or post-process the messages. As usual, using Groovy for XML processing is much easier than Java. My proposed solution is to use a Java class to implement the appropriate Handler interface, but to delegate to a Groovy class for the actual XML processing and manipulation.

Finally, I present Gradle tasks to perform the wsimport and wsgen tasks, based on the corresponding Ant tasks.

Though much of the industry is switching from SOAP to REST, SOAP-based web services are going to be a fact of life at many companies for the foreseeable future. This chapter shows how you can use Groovy to make developing them and working with them easier.

Note that this is listed as Chapter 7 in the outline. The code examples do use some technologies covered in the intervening chapters (Spock tests, Gradle builds, and so on), but you don’t need the details to be able to read this chapter.”

These days whenever I discuss web services, I feel obligated to show the Gartner Hype Cycle. In case you haven’t seen it, here’s an image from Wikipedia:

The Gartner Hype Cycle, from Wikipedia

I like the model, though I always suspect that the actual data Gartner periodically adds to the figure is pure hand waving speculation. In my experience, right now REST is rapidly approaching that Peak of Inflated Expectations. I know several people who have been successful with it, but the tools and APIs are still quite immature. I’m working on my REST chapter in Making Java Groovy at the moment, and while I can get everything to work, it’s taking more effort than I expected. Don’t get me wrong — I see the value in REST, but right now getting it to work with Java is a lot more effort than using SOAP, believe it or not.

(Obligatory moderately humorous anecdote: back when I was working at a training company about six or seven years ago, we were partners with the company that produced Crystal Reports for business intelligence reporting. They were eventually bought by a company called Business Objects (who in turn was bought by SAP, but that’s a different story). Anyway, Business Objects preferred the abbreviation BOBJ over that of B.O., for obvious reasons. Of course, we used to joke about teaching a BO class followed by a SOAP class….)

The attitude toward REST may be an overreaction, but that’s nothing compared to the loathing for SOAP-based web services you find in much of the community these days. You would think that SOAP would be safely on the Plateau of Productivity by now, but if you go to any conferences (or talk to any REST advocates) the contempt you see for SOAP is such that it must be deep in the Trough of Disillusionment.

I don’t necessarily agree, but fortunately I don’t have to resolve that argument. As I see it, one of the major tasks Java developers face these days is working with SOAP-based web services, probably as part of a (potentially misguided, but what can you do?) Service Oriented Architecture, and those services aren’t going away any time soon. Those same developers are also going to be working with REST, if not already then soon, and are starting to get used to terms like safe, idempotent, and HATEOAS.

My task is to show Java developers how Groovy can help in both situations. Chapter 7 discusses JAX-WS (the SOAP tool set for Java) and how it works with Groovy. Chapter 8 talks about REST and JAX-RS, with the same goal in mind. Hopefully I’ll be able to provide enough information that you’ll be able to make up your own mind as to whether Groovy is helpful in either case.

—-

On an unrelated note, next weekend (3/5 and 3/6) I’ll be at the No Fluff Just Stuff event in Minneapolis. I’m giving three presentations: one on improving your Java with Groovy, one on testing with Spock, and one on using Gradle for builds. Oh, and leave it to the Gradle people to announce another milestone release four days before I’m supposed to give a presentation on it. 🙂 Sigh. That’s life in the Groovy ecosystem for you. In any case, I’m really looking forward to the event. If you plan to attend, please drop by and say hi, even if you’re just on your way to go see Neal Ford, Tim Berglund, the inimitable Dave Klein, or any of the other great speakers at the conference. I might even have a discount code to give out…

Testing Groovy Scripts

I often start Groovy development with scripts rather than classes. Scripts are quick and easy, both to write and to run, and the feeling of having only a few lines of code makes me more willing to experiment. Most of my scripts eventually turn into classes, but once in a while, either for convenience or as demos, they stay the way they are.

This happens a lot while I’m working on my book*. I often generate little scripts that illustrate one point or another, and most of them aren’t worth converting into classes.

(*What book is that, you say? Why, Making Java Groovy, which shows you how to add Groovy to Java to make your development tasks easier. It’s available now from the Manning Early Access Program at http://manning.com/kousen)

While I’m not sure I practice true Test Driven Development (TDD), I know I practice GDD. That’s Guilt Driven Development, which means if I write anything significant that isn’t tested I feel guilty about it, so I then write the tests. In this post I’ll show how I now write tests for my Groovy scripts.

Before I do so, however, I should acknowledge the assistance of the indefatigable Hamlet D’Arcy on the Groovy Users email list. He blogged about a similar issue back in 2006 (!). Of course, he was dealing with straight Java back then and trying to manage standard error.

There are two features I need to use:

  • The groovy.lang.GroovyShell and groovy.lang.Binding classes, and
  • Overriding System.out to capture printed output

I use a GroovyShell to execute the scripts, and a Binding to manage input and output variables, if any. To handle printed output, I redirect standard output to a ByteArrayOutputStream and then check the results.

To illustrate, here are three extremely powerful scripts. The first is the classic “Hello, World!” script in Groovy. I stored it in a file called hello_world.groovy.

println 'Hello, World!'

Second, here is a script that contains an assert in it, in a file I called script_with_assert.groovy.

def ok = true
assert ok

I used a local variable, called ok, in that script, mostly to contrast it with a binding variable. Speaking of which, here’s my super duper script that has a binding variable in it, stored in a file called script_with_variable.groovy.

package mjg.scripts
ok

Recall from the fantastic book Groovy in Action* (even after all these years and language changes, I still find valuable information in there) that if a variable in a script is not declared, then it can be set and retrieved via an instance of groovy.lang.Binding.

 

(*Yeah, I linked to the second edition, even though I’m still using the first edition on a regular basis. That’s still my all-time favorite technical book, so I don’t mind recommending the new version.)

With all that in mind, here’s my JUnit 4 test, written in Groovy for convenience.

package mjg.scripts

import static org.junit.Assert.*

import org.junit.After;
import org.junit.Before;
import org.junit.Test;

class ScriptTests {
    GroovyShell shell
    Binding binding
    PrintStream orig
    ByteArrayOutputStream out

    @Before
    void setUp() {
        orig = System.out
        out = new ByteArrayOutputStream()
        System.setOut(new PrintStream(out))
        binding = new Binding()
        shell = new GroovyShell(binding)
    }

    @After
    void tearDown() {
        System.setOut(orig)
    }

    @Test
    void testScriptWithAssert() {
        shell.evaluate(new File("src/mjg/scripts/script_with_assert.groovy"))
    }

    @Test
    void testScriptWithTrueVariable() {
        binding.ok = true
        shell.evaluate(new File("src/mjg/scripts/script_with_variable.groovy"))
        assertTrue shell.ok
    }

    @Test
    void testScriptWithFalseVariable() {
        binding.ok = false
        shell.evaluate(new File("src/mjg/scripts/script_with_variable.groovy"))
        assertFalse shell.ok
    }

    @Test
    void testHelloWorld() {
        shell.evaluate(new File("src/mjg/scripts/hello_world.groovy"))
        assertEquals "Hello, World!", out.toString().trim()
    }

}

Actually, all my scripts (and the test class) are in a package called mjg.scripts, where mjg stands for Making Java Groovy, of course.

 

I made the GroovyShell and the Binding instances attributes so I could reuse them. It turns out that by keeping a reference to the Binding, I can still set and get variables using it even though I’ve already instantiated by Groovy shell around it. That’s helpful.

In the set up method (annotated with @Before), I save the current output stream into an attribute so I can restore it later in the tear down method (annotated with @After). That’s not really necessary here, but it seems like a good practice in general.

I’m using a ByteArrayOutputStream to hold the printed data in memory. The System.setOut method requires a PrintStream as an argument, so I wrapped the byte stream inside one.

The first test, testScriptWithAssert, finds the proper file and executes it. That script has the line assert ok in it, after setting the local variable ok to true. If I go into the script and change ok to false, the test fails. This tells me two things:

  1. If my scripts are full of assert statements, I can run them as part of a normal build and failures will be reported in the usual way.
  2. If an assert fails, there isn’t much I can do to prepare for it in my tests. I can’t, for example, wrap the call inside an assertFalse call. The failure happens before I get back, for one thing.

I basically have to hope that any assert statements in my scripts always succeed, or my tests will fail. Arguably that’s what I want anyway.

The next two tests, testScriptWithTrueVariable and testScriptWithFalseVariable, set the ok variable from the binding, then run the script. The script in question just returns the variable. I check the binding variable at the end of each script, just to prove that I was able to set it properly with the binding.

Finally, I test the “Hello, World!” script. By redirecting standard out to the byte stream, I’m able to capture the print output in a variable. I then invoke the toString method to get the value in the buffer. The trim call is added to handle any whitespace associated with carriage returns, line feeds, etc.

In his blog post, Hamlet used an encoding as the argument to his toString call, claiming that otherwise the output would be different on different platforms. I decided to let Groovy worry about that, so hopefully I won’t get burned by it later.

That’s all there is to it. Now, whenever I add Groovy scripts to a chapter of my book, I make sure to add a test class to check them as well. So far that seems to be working just fine.

Any comments, especially about errors or omissions, are of course welcome. For those who have already purchased the book, (1) you totally rock, and (2) a new chapter will be added to the MEAP early next week, on using Groovy with SOAP-based web services. I’ll blog about that when the new chapter appears.

Note: the source code for this project, including a Gradle build file, is located in my TestingGroovyScripts repository at GitHub.

Groovy Groundhogs (again)

Last year on Groundhog Day I posted a short Groovy script about the consequences of the groundhog seeing his shadow. I wasn’t going to do it again, but then I thought about the movie and realized I had to.

Here’s the script, which I’ll explain afterwards.

println 'Groundhog sees shadow --> 6 more weeks of Winter'
def c = Calendar.instance
c.set 2011, Calendar.FEBRUARY, 2
def groundHogDay = c.time
c.set 2011, Calendar.MARCH, 20
def firstDayOfSpring = c.time
def days = firstDayOfSpring - groundHogDay
assert days == (firstDayOfSpring..groundHogDay).size() - 1
println """
There are ${(int)(days/7)} weeks and ${days % 7} days between GroundHog Day 
and the first day of Spring (March 21), so Spring 
comes early if the groundhog sees his shadow.
"""

Date and time manipulation in Java has always been ugly and awkward. Groovy doesn’t really fix that, but at least it requires fewer lines of code. By accessing the instance property on java.util.Calendar, I wind up invoking the getInstance() factory method. Calendar has a set method that takes three arguments: the year, the month, and the day. Here I left out the optional parentheses, and made sure to use the month constants because the integer values have an off-by-one problem (January = 0, etc).

Just to remind you you’re dealing with a dumb API, the way to extract a Date from a Calendar is to call getTime, so I accessed the time property to do that.

So basically I generated a java.util.Date for Groundhog Day, and a java.util.Date for the vernal equinox for this year (i.e., the first day of Spring). All that was essentially just Java. Then comes the cool part. Groovy adds a minus method to Date, so I can subtract dates and get the number of days in between. I did that, and verified the calculation by also using the dates in a range and asking its size() method and again correcting for any off-by-one errors.

(Bad joke warning: Java arrays have a length attribute, Strings have a length() method, collections have a size() method, NodeLists have a getLength() method, and so on. In Groovy, you just use size() everywhere and it works. In other words, in Groovy, size matters.

Sorry about that. Now back to your blog post, already in progress.)

The bottom line is that in 2011, there are six weeks and four days between Groundhog Day and the first day of Spring. Therefore, if Punxutawney Phil were to see his shadow, we would then expect six more weeks of winter. That’s a good thing — Spring will be four days early.

It’s a silly demo to be sure, but it’s easy enough to do in Groovy.

Two points are worth noting. First, Phil didn’t see his shadow this year (an unusual occurrence), so we are supposed to have an early Spring. Good. Second, according to the Wikipedia page on Groundhog Day, before the Gregorian calendar messed it up the equinox fell on March 16, which is exactly six weeks after February 2.

To go off on a tangent, did you know that the switch from Julian to Gregorian calendars actually impacted U.S. history? That seems unlikely, given that Pope Gregory signed the relevant decree in 1582, long before the Europeans started settling here in big numbers. However, Pope Gregory was a contemporary of Henry VIII, who engineered the separation of the Church of England, so Britain wasn’t going to do anything just because the Pope said so. Britain (and therefore the British Empire) didn’t formally adopt the Gregorian calendar until 1752. As a result, the American colonies dropped 11 days from September of that year.

In a book I read about calendaring (a fascinating subject, by the way) about 20 years ago (sigh), I seem to remember the author making a big deal out of how 11 days were removed from February and that George Washington lost a birthday that year. Five minutes of research on the web showed me that the lost days were in September. And they say the Internet hasn’t made life better…

Incidentally, Groundhog Day is one of the few movies actually available in the Netflix instant queue (which has almost nothing else that I search for, unfortunately), so I could actually watch it again tonight assuming the web access in my hotel room in Austin, TX could handle it. I’ve seen it so many times, though, that maybe I’ll actually work on my book rather than doing so.

What book, you say? Why, Making Java Groovy, available now through the Manning Early Access Program, which will contain the above example, among others. 🙂

%d bloggers like this: