Geeky Thing of the Day (Not Remotely Fascinating)

Click now for JiffNotes

WARNING: The Geek Content of this post has been rated DANGER, DANGER WILL ROBINSON...YOU MUST KNOW XML AND JAXB to continue! If these terms mean nothing to you (especially JAXB), BAIL NOW!

Your last chance to bail.

And this is why you always create a separate JAXB bindings file for your schema....

I'm all about keeping things together. Hibernate: XML file versus annotations? DUH, annotations, because then the class files are self-documenting! Inner class that's only used by its parent versus separate class? DUH, inner class, because then it's all in one place. So when I learned how to do custom bindings for JAXB, OF COURSE I put them right smack dab in the middle of the schema (XSD), because whytheheck would you have yet another file in your schema (we already have one for complex types, one for attribute groups, etc., etc.). That's just one more "piece" to get lost.

However.

Today I learned why you create a separate binding file. So here is your Cautionary Tale in Case You Are Considering Smashing Bindings into Your Schema As I Foolishly Did.

Wayyyyyy back at the end of January, we placed the finishing touches on a new web service, and it went into testing. We had a nice document that described all the elements in the XSD, what they were, whether they were required or optional, etc. However, we continually told the technical people, "When the test server goes live, you should use the XSD from the WSDL to code to, because that's what we're coding to."

They did not pay attention. And to make things worse, the pretty document (sent off accompanied by our XSD) did not get updated after the beginning of January (unbeknownst to us).

So THIS release, for some reason, they decided to actually pull down the latest XSD from the WSDL. I think you can see where this is going. Every tiny field that went from "required" to "optional" created a static wave of MAJOR FREAK-OUT from their project manager. Nevermind that: Who cares if you're sending it and we're not looking for it...there is no problem there...WHY USE LOGIC TO DETERMINE IF THERE IS A PROBLEM when you can just use DIFF!!

Most everything was explained away...except for a little issue of binding. Somehow, even though I set up "type_OurResponseToYou" to bind to OurResponse.class IN NOVEMBER, they pulled an XSD that was generating OurResponseToYou.class through JAXB.

Omigosh, recoding! RECODING!!! DING DING DING EVERYBODY PANIC!!!

Dudes. Not only did we tell you to use the XSD from test (which has ALWAYS, since the BEGINNING OF TIME, i.e., BEGINNING OF TEST, bound to OurResponse.class), we had no idea you were going to go and run our stuff through JAXB on your end! This was not a fixed interface!!

So. It turns out that we build using Ant, and you can specify an external binding file on the xjc task. You don't have to refer to it in your schema, you don't have to refer to it in the WSDL, you can keep it secret, keep it safe.

The moral of this story is, share your XSD, but keep your binding file close to the vest. Let them define their own. That way, if your IT organization implements a new naming standard, or you get a name conflict you can't resolve with packages (really?), or you JUST DECIDE ON A WHIM TO MAKE MORE WORK FOR YOURSELF BY RENAMING EVERYTHING, you can do it without freaking out your client.

JiffNotes
Pictures of pretty yarn soon! =)