Dan Jemiolo:
What kind of client generation are you looking for?
~shiver~
I suppose I must not have gotten around to telling Dan my horror
stories of using WSDL in the early, early days of
Jazz.
The low point was when it once took me two working days to get
the code working again, after we made some slight changes to the WSDL.
Of course, we were doing some evil, evil things, like parsing Java
code with a JDT jar in an ant task, and replacing generated code
from the WSDL generation process. But still, code generation of
this ilk leaves a bad taste in my mouth.
Also see
Dare's issues with bananas.
The best code generation is no code generation.
And that's what we changed in Jazz. Because we already had complete control over the
data typing story
(EMF),
we had no problem generating the XML and JSON we wanted, completely dynamically, by reflecting over the data
used in our services. But we had to do something about the service methods themselves.
So we rolled our own client and server side stack for this.
We kept the notion of defining the operations in a web service in a Java interface,
because this makes a lot of sense to do in Java. We can reflect over it to look at the
methods and signatures. On the server, you can write a class to implement the interface,
and that's your service implementation. The low-level server interface (ie, Servlet for Java)
can figure out what service to invoke, and then call the service implementation reflectively.
And on the client, you can use
Proxy
and friends to build an object which implements the interface by making the HTTP request
on your behalf.
(Quick aside to note that Jazz services are largely RPC styled, though there
are some that are more RESTy flavored - stay tuned; they've caught the REST bug.
I think the 'client library' or invocation style is largely independent of the
architectural style, so I think everything I'm saying here completely holds for
REST as well as RPC, and everything in between.)
By having the client and server work completely reflectively, all we had to do was
make sure the data classes and service interfaces were the same (or at least compatible)
between the client and server. Understand, "all we had to do" can be a problem; but
at least we didn't have the generated code to deal with as well, nor did we have a
separate build step for it that can be an agility killer.
It goes without saying that you can get by with a lot less configuration
in such a situation. Reflection over Configuration. Don't Repeat Yourself.
Looking back on this, I think this was a great trade-off in the time expended
to build the stacks. For instance, we were able to tweak the system in various
ways that would have been impossible to do with a code-gen built system. I
suspect this is going to be the case for any medium- to large-scaled system
built using a number of services. You can either lock yourself into a
system under which you have very limited control, and spend your time
working around it and fighting it, or you can write code customized to your
needs and spend time tweaking as you need.
Let's get back to your original question, but tweak it a bit:
What should we do to make it easier for people to build clients?
- Provide machine-readable descriptions of the service interfaces. These
machine-readable descriptions can be used to generate human-readable descriptions.
For instance, instead of generating an HTML table for your Gregorio tables,
how about generating JSON? Then you can generate an HTML file that uses some
JavaScript to format the result in an HTML table. Perhaps you can use it,
once you've built a little client invocation stack, to build some dynamic
callable objects which serve as proxies to the server (if you're lucky enough
to be working in a dynamic language).
- Provide machine-readable descriptions of the data flowing over the wire.
Not just the HTTP content, but query string parameters where appropriate.
If you can reflect on your service interfaces and data dynamically in the server,
then you can generate all this meta-data reflectively as well.
Or if you really do want to do some code gen, and your client is able to load
directly runnable code from your server *cough* JavaScript *cough* then it's easy
to imagine that you could code-gen a client library dynamically on the server
as well. I suspect that's actually overkill though.
