Wednesday, December 17, 2008

Managing contexts in CXF JAXRS

In JAXRS, a number of classes representing various features of a given request exist, as opposed to a composite WebServiceContext in JAXWS which lets get to individual contexts and message properties.

Imagine this JAXRS resource class which needs to know where the request came from, how secure it is, what the structure of the request URI is, what servlet context parameters corresponding to a given request are, what HTTP headers are involved and if certain request preconditions are met. And if you're writing a composite message body provider then, in addition to the above requirements, you also want to query other available providers as well as to check if a certain context resolver is available.

How unreatistic these requirements are ? It's likely they won't arise in many cases at the same time but likewise it's likely they'll will have to be met in some cases.

So here's a portable JAXRS code showing how you can get an access to all the contexts :


public class CompositeMessageReader
implements MessageBodyReader<Composite> {

@Context UriInfo u;
@Context SecurityContext sc;
@Context HttpHeaders h;
@Context Request r;
@Context ServletContext sc;
@Context HttpServletRequest httpR;
@Context ContextResolver contextR;

// use the injected contexts

}



And here's a CXF JAXRS specific code on how you can get an access to all the contexts plus the properties of the underlying message.


public class CompositeMessageReader
implements MessageBodyReader<Composite> {

@Context org.apache.cxf.jaxrs.ext.MessageContext mc;
// use the injected contexts
mc.getSecurityContext();
mc.getHttpHeaders();
mc.getUriInfo();
mc.getContextResolver(JAXBContext.class)
mc.getRequest();
mc.getServletContext();
mc.getServletConfig();
mc.getHttpServletRequest();
mc.getHttpServletResponse();

FutureJAXRSContext newContext =
mc.getContext(FutureJAXRSContext.class);

mc.get(PROPERTY_KEY);

}

I'm contradicting here to my previous post where I'm whining :-) about the JAXRS portability.
But you know how long would it take you to get back to a portable JAXRS code.

JAXRS Wish List

I think I won't say anything new by repeating that a JAXRS specification has been a success.

It brings so many new annotations into a Java code but the main goal behind it, at least as far I see was to popularize the REST paradigm among java developers and surely, the goal has been achieved.

Marc Hadley, Paul Sandoz and indeed all the experts who contributed to the JAXRS specification have done a fantastic job. And no doubts more is to come from newer versions of JAXRS.

So here's my wish list. It's not a long one. May be it's a bit early given that JAXRS 1.0 was only released last September but here it goes :

Please focus on the Portability.
There's no uniform way to express that a given service class is a singleton. There's no portable client api - why is that ? In JAXWS one can do a portable code which creates and consumes services. There's no uniform way to query for a document describing a service.

That's it really - not a long list indeed :-)

Tuesday, December 9, 2008

CXF JAXRS Keeps Getting Better

I could not resist it, even though I'm not a Christina Aguilera's fan :-)

CXF JAXRS is catching up. Jersey is an extremely strong player, and I have little doubt about the top quality of other JAXRS implementations - but their CXF competitor has something to say on its own - right now.

CXF is there to offer a number of approaches toward building serious web services. The fusion of JAXWS and JAXRS is likely to appeal to many developers and this is just one of the areas where CXF JAXRS can play its part.

Stay tuned.

Monday, December 1, 2008

Continuations in CXF

It's a classic problem really, how a service can help a client to submit a request and obtain a response asynchronously. A number of approaches exist :

* Client does an invocation on a web service and provides an address to reply to - this requires a client to have a web service of its own for the callback to eventually arrive while on the server side, for the (HTTP) transport thread be released, a typical HTTP 201 may be sent back as an initial acknowledgement, depending on if it's a typical two-way or so-called one way operation.

* Service responds with a resource address a client needs to poll for the results be eventually obtained which requires a client to structure the code accordingly.

There's another approach emerging - using suspended invocations or continuations. Actually, it's not a new approach but with Jetty supporting and Servlet 3 embracing them the suspended invocations are bound to enter the mainstream.

Please read a Jetty Continuations page on when using continuations can make sense.

Without further ado, here's a sample code fragment showing how one can do continuations in CXF in a transport neutral way. CXF Continuations API is currently supported for SOAP-HTTP services based on Jetty 6 and SOAP-JMS services. CXF JAXRS runtime supports them too :



import org.apache.cxf.jaxrs.ext.MessageContext;

@Path("/")
public class WebResource {

private @Context MessageContext context;
private Executor executor = ...;

@GET @PATH("/quote/{id}")
public Quote getQuote(@PathParam("id") String policyId) {

String key =
"org.apache.cxf.continuations.ContinuationProvider";
ContinuationProvider provider = context.get(key);

Continuation c = provider.getContinuation();
synchronized (c) {
if (c.isNew()) {
FutureTask f = new FutureTask(
new CallablePolicyHandler(policyId, c));
c.setUserObject(f);
executor.execute(f);
c.suspend(timeout);
} else {
FutureTask f = (FutureTask)c.getUserObject();
if (f.done()) {
return f.get();
}
c.suspend(decreaseTimeout());
}
}
}
}


What happens is that when continuation.suspend(timeout) is called, the current transport thread gets immediately released and a pending request is put back in the requests queue. Once an asynchronous activity gets completed, it will call continuation.resume() - in this example it's done somewhere inside a CallablePolicyHandler, which results in a suspended request be returned to this method. The code now checks if the FutureTask is done and if not then it means an initial timeout was not enough for the asynchronous activity to complete - in this specific case we decide to suspend a request yet again but with a smaller timeout.

Note that in case of JAXWS the code will be absolutely identical for this specific sample, except that a ContinuationProvider instance will have to be obtained from a JAXWS WebServiceContext.getMessageContext().

Both CXF JAXRS MessageContext and JAXWS MessageContext will have to be used when combining JAXWS and JAXRS. I think we may need to come up with a common MessageContext interface for such cases.

Finally, this CXF Continuations API won't change when Jetty 7 (and indeed Tomcat) implementing Servlet 3 specification will ship.

For another example see this CXF-based demo in a Jetty 7 trunk. It shows the use of JAXWS asynchronous handlers among other things. Note in this demo a new ServletRequest.suspend() call is used as opposed to ContinuationsSupport.getContinuation() and Continuation.suspend() pair of calls in Jetty 6. Nothing to worry about though if you're a CXF Continuations API user - it all will be handled internally without you noticing it.

Thursday, November 6, 2008

Portugal

Here are some photos from our trip to Portugal, it was a great trip.

Tuesday, November 4, 2008

Pragmatic message about REST

Sam Ruby says in his Progressive Disclosure post :

"Without intending to take anything away from Roy’s (valid) criticism on labeling, REST isn’t an all or nothing proposition. One can get significant value from partial adoption."

IMHO this message is much stronger and much more likely to be heard in the SOAP quarters than the "drop WS, adopt REST" message. For the latter message to (ever) get mostly if not fully materialized, the former needs to be heard well.

+1.

Indeed, Apache CXF preaches this message too with its best-of-breed JAX-WS support and its fledgling but being constantly improved JAX-RS support, now supporting 1.0 API with just few exceptions.

On How to Get a Cup of Coffee

InfoQ has recently published a How To Get a Cup of Coffee article about RESTful services.

I did like reading the article : it talks about workflows, shows with the help of state diagrams how clients actually drive and execute applications and overall it entertains the reader so I'd like to join those who welcomed this article. It was the only technical article I read last week, on vacation, and I was nearly killed when I was spotted reading it :-)

What surprised me a bit though is what the authors say about clients discovering which method, say PUT which may be invoked on a given resource service. For example :

"to find out if we can change the order, we ask the resource what operations it's prepared to process using the HTTP OPTIONS verb, as shown on the wire in Figure 6." - please refer to the original article to see Figure 6.

Next :

"From Figure 6 we see that the resource is readable (it supports GET) and it's updatable (it supports PUT)."

I think this use of OPTIONS is of no practical use at all. I agree it does show what OPTIONS can be used for but I find it difficult to imagine a compiled client code checking how a given resource can be updated, especially given what is said next in the article :

"Although partial updates are the subject of deep philosophical debates within the REST community, we take a pragmatic approach" and (authors) decide to use PUT to do a partial update. Big +1 on the pragmatic approach by the way.

In meantime Mark Nottingham provides some insightful comments but again this comment on the use of PUT for partial updates catches my attention :

"This is a flagrant abuse of the semantics of PUT; if you want to combine a representation with the existing state of the resource, use POST or the emerging PATCH. "

To me it all means only one thing : the RESTful HTTP-aware compiled client code is as tightly coupled to a given resource with a generic HTTP interface as the client code generated from either WSDL or WADL is. One service will use PUT, the other one will do POST and the 3rd one will use PATCH - but the knowledge of the verb to be used when doing a given type of update is embedded in the client application code - unless it's a totally generic client application, say a browser handling HTML forms.

Here's one more excerpt from the article.

"Consumers typically agree the semantics of representations and transitions with a service during design and development. But there's no guarantee that as service evolves, it won't confront the client with state representations and transitions the client had never anticipated but knows how to process – that's the nature of the loosely coupled Web. Reaching agreement on resource formats and representations under these circumstances is, however, outside the scope of this article."

I'm curious what can be said about reaching agreements under these circumstances ? I'm seeing the client codes being recompiled in these cases if the newly introduced data or semantically important links are to be noticed.

Friday, October 17, 2008

Football : Belarus vs England

Belarus played versus England on Wednesday 15th of October and lost 1 : 3. Even though I was disappointed they did not manage to draw or even win, I was still encouraged by quite positive reviews of the way Belarus played.

They managed to get level after losing 0:1 and who knows what could have happened if Rooney hadn't rediscovered his lethal attacking skills by the time this campaign started.

I was on a plane when the match was on, but I have it recorded. The only thing which concerns me a bit is that my (soon to be) 6 year-old son Alex is getting crazy about football at the moment and he's so excited about watching Rooney playing. I'm concerned that if I show him this match he'll start supporting England even when they play Belarus :-) May be I should wait and see if Belarus manages to shock England in the away game :-)

Slightly orthogonal note : BATE, a football club from Borisov, a small town near Minsk, is playing in the Champions League this season. In fact, it's the first ever club from Belarus which managed to achieve it. And they play Real Madrid (0:2 - in their 1st meeting in Madrid), Juventus (2:2 in Minsk) and Zenit St Petersburg (1:1 - away). Well done - great effort and it brings that much needed experience and indeed finances into the Belarussian football.

Tuesday, September 2, 2008

Fixing capitalism with the open source

I never thought I'd write about capitalism on this blog :-)

So I was flying to Minsk the other day and I was about to enjoy my holidays at home. While my fellow passengers were reading the home newspapers, I was reading an article by Bill Gates "How to fix capitalism" published by "Time". I knew I was looking a bit pretentious :-) at a time, but it was an interesting read. I picked up my copy of Time in the Dublin airport for the only reason - Bill Gates was looking at me from the front page. Actually, the article is called differently online, not sure why, possibly because 'fixing' sounds a bit strong to some hard-core capitalists :-).

That article is a brief and concise guide on how businesses can help those in great need and still make money out of it. For someone like myself knowing not much about how the business is really made it was quite an inspiring read - I was flying high - literally :-) at that moment of time and I was imagining myself doing some strategic business decisions which would make the world a better place.

Like the way the open source movement is affecting the way the business is made in the software industry, it's likely what Bill Gates wrote about will affect the way the business is made in general, sooner or later. Customers will prefer to buy from producers who are known to be associated with good causes.

The open source business model is primarily based on the promise that once the ubiquity is reached there will always be customers which would prefer to buy a certified version of the open-source product, that is, pay for the top-class support.

The open source, by definition, is free and it's being doing well in making capitalism more creative by lowering the cost of entry for those who need to write functioning applications fast. Not everyone who is using the open source software is in great need but those who really are can certainly avail of the freely available software.

And it's likely that customers will eventually reward vendors who're investing in the open source - simply because the open-source vendors will be seen as the ones who are associated with the good cause.

Friday, July 25, 2008

Rest and Soap united in CXF

Please ignore the fact that Rest and Soap are presented as two alternatives - even though it's not very accurate this just helps me to make a shorter title for this blog entry.

I was quite interested in a 'Restifying' SOAP-based services idea awhile back, especially after a Web Method Feature was introduced. I'm not sure anyone relies on it today, when writing practical SOAP-based web services - I just don't know.

The arrival of JAX-RS introduces some new interesting possibilities in this area - from the perspective of the server-side application development at least.

Consider the ever popular Bank-Account scenario which uses a Factory pattern.
Here's a typical JAX-WS class :

@WebService
public class BankService {

public javax.xml.ws.wsaddressing.W3CEndpointReference createAccount(AccountInfo ai) {
// code omitted for brevity
}
}

This class will return EPRs, one per every new Account created.

Now consider the same class slightly updated :

@WebService(wsdlLocation="bank.wsdl")
@Path("/bank")
public class BankService {

@POST
public javax.xml.ws.wsaddressing.W3CEndpointReference createAccount(AccountInfo ai) {
// code omitted for brevity
}
}

It is the same class with JAX-WS and JAX-RS annotations mixed in.

In case of SOAP, POST createAccount requests will be targeted to, say, http://localhost:8080/bankservice endpoint address, while in the other case POST requests will be targeted to http://localhost:8080/bank address.

The only missing bit is a JAX-RS MessageBodyWriter which can handle the handling of W3CEndpointReferences :

public class W3c
MessageBodyWriter {

public void writeTo(W3CEndpointReference epr, ..., MutivaluedMap<String, Object> headers, OutputStream os) {
// just update the headers, do not write into the stream
headers.putSingle("Location", getEprAddress(epr));
}

}

Now, the problem is that status code needs to be set to 201 in this case and it's not possible to set a custom http status code in JAX-RS MessageBodyWriters. Enter CXF JAX-RS filters. They will be invoked before the headers and status code is set on a CXF private Message class :

public class EprResponseHandler implements ResponseHandler {
public Response handleResponse(Message m,
OperationResourceInfo invokedOperation,
Response response) {
Object entity = response.getEntity();
if (entity != null
&& W3CEndpointReference.class.isAssignableFrom(entity)) {
return Response.created(getEndpointAddress(entity)).build();
} else {
return null;
}
}
}

Note, the need for a custom MessageBodyWriter goes away now.

Finally, one needs to configure both JAX-WS and JAX-RS endpoints using Spring for ex, and you're done.

A couple of additional notes. There's really no need to go for all this trouble of creating custom filters unless you'd like to preserve the same interface you've already used before starting to play with JAX-RS - this may not be that far-fetched a requirement at all. And sorry for writing a lame and incomplete code - hopefully it still makes sense :-)

Finally, note how very similar the programming model on the server can be, when using both JAX-WS and JAX-RS. Big Web Services are often compared to Corba for a number of reasons, one of them the use of EPRs - this is definitely a red-herring. It's the non-support for GET and fine-grained interfaces which put the sides apart.

A RESTful Core for Web-like Application Flexibility

I spotted a RESTful Core for Web-like Application Flexibility article on the ServerSide.

Please read it.

I was musing a bit about the universal web programming in a couple of previous posts, using an "if REST approach is considered so appealing to the web application developers then why don't we just have the generic interfaces even in the local JVM" kind of argument, without any practical suggestions.

Looks like some clever people are after it - and my take on it is that it's just a matter of time before we'll see a new programming language, say, W#, pronounced as 'Web Sharp'. It will come out from Microsoft or Sun or IBM or Google or indeed from 1060 Research labs. I don't see how this would be W# language ever replace Java , but I have little doubt it will be unveiled eventually.

The authors do not propose to replace, say, a java.util.List interface with a more generic version such that a client code is never even compiled against a fine-grained interface. Given that what they write is considered 'extreme' by some of the readers of their article, deprecating the whole notion of the interface is not a starter even in the nearest longer future :-) What the authors propose seems like an interesting and promising idea, of some moderate 'extreme' :-).

Interesting stuff.

Tuesday, July 15, 2008

Is it all about agreement ?

I remember reading one of the Mark Little's posts (sorry can't find the link) where he was saying that, yes, it was possible to write transactions in REST, in fact he'd even had some practical experience in that area before.
Yes, while I don't have such experience I know now how I can do it now with REST.

Then Mark said that a number of partners had managed to demonstrate the interoperability of one of WS-* Transaction specification as part of some of the interoperability events.

This makes me wonder : is it what actually defines Web Services ? Not only the actual technology per se but the fact that multiple businesses can do the same technology and successfully interoperate ?

Will it ever happen with RESTful services ? Will it be possible for multiple companies to interoperate with more sophisticated things involved such as transactions, for ex, something which is possible to do with WS-BusinessActivity which does not really lock all involved ?

Or is it something which will not be ever needed in practice ? Local transactions, different business alliance-specific standards is all what will be needed to either just do transactions or achieve the interoperability in say the transactions area ?

About the 10 year plan

Through Stefan Titkov I came across this comment by Benjamin Carlyle. Benjamin says :

"Perhaps the clearest contrast is between REST and a strongly-typed O-O language. In nice, crinkly java I get a compile error whenever two components disagree on the definition of an interface. The client tries to call method foo. There is no method foo. Bail. In this setting it makes sense to leverage the strongly-typed nature of the language to make sure you don't release junk. You define interfaces in a detailed and domain-specific way that is checked to yield a consistent releasable whole."

I briefly touched on it before but given that an interface with more than 4 methods is deemed unsuitable on the Web (for all the reasons associated by REST advocates with this approach) why does it seem so natural and acceptable to do OO finer interfaces in a single JVM ? Will it be the ultimate WEB experience everywhere if there were only generic methods everywhere, on the WEN and in virtual machines ? The only difference would be that when programming remote services clients would need to be able to catch up remote exceptions and handle them as needed ?

This is probably a lot of nonsense. But I hope it captures what seems like one the main reasons behind a 'split' between RESTful and WebServices communities : for some it's natural to program in terms of generic interfaces, some will eventually accept it, for others it's simply a non-starter and more specific interfaces are on the map - with the proper data extensibility policy they can fare pretty well too.

Benjamin then says :

"
In REST, I want the client or the server I deployed literally 10 years ago to work with whatever I am putting out today. I also want whatever I'm putting out today to work with every bit of code written since that time, and every bit of code that will be written in the next 10 years. "

I think I've read on one of the
Benjamin's blogs that in 10 years time it will be all about REST. I have to admit that prediction may be much closer to the reality as people are getting behind REST more and more.

The one quoted above is basically unrealistic IMHO. With one exception only. If you're a client doing GET. I've always believed that GET is one of the main driving force behind the Web (plus links to URIs which can be GETed). Doing POSTs, PUTs, etc, in 10 years time ? I doubt - but I'm happy to be eventually proven wrong.

CXF and JAX-RS

I've had a chance to get involved recently in a JAX-RS project in Apache CXF. This project is far from being complete yet but that's another story... I have to admit I've had a very positive experience while working on it.

CXF JAX-RS has entered the game quite late, with the leading implementations like Jersey, and very likely equally strong RestEasy and Restlets JAX-RS being there for a while already. Thanks to the work of my former colleague Jervis Liu, the feedback from the CXF users and the tremendous feedback from JAX-RS experts and the very open process behind the way JAX-RS and Jersey RI team operates has helped CXF JAX-RS to catch up a little bit with 0.8 api mostly supported now.

One can wonder what is next for CXF JAX-RS ? I hope that with the help of the large CXF community, its JAX-RS implementation will eventually become as solid as its top-notch (CXF) JAX-WS 'counterpart'. Will it be able to compete with the likes of Jersey, with it's client api gem (which will hopefully get standardized one day :-) ) ? It's hard to tell - not in the nearest future for sure.

Still I reckon CXF JAX-RS will eventually find its niche. While CXF JAX-RS users can certainly write RESTful service only with no JAX-WS (SOAP) involved, possibly its best 'argument' is that it sits on top of and is closely integrated with the same runtime which hosts quite possibly the best JAX-WS implementation out there. CXF users will be able to write the services combining JAX-WS and JAX-RS technologies, with one or more closely related Java classes involved, some will experiment and decide to move to JAX-RS altogether, some will use the combination of two technologies and some might get back to JAX-WS, you never know :-)

Generally, I'm somewhat pessimistic about Java code relying on various annotations which is what JAX-RS is all about. Having said that I have to admit that JAX-RS is much more involved in that it's not only about the annotations. Possibly the main achievement of JAX-RS authors is that JAX-RS 'breaks' the barrier for Java users at large and let them experiment with RESTful services while still being in the comfort of the their JAVA code. It's a great effort by those behind the specification and the RI.

Futile arguments about REST and Web Services

It's ongoing. It's not going to stop until the battle is over and Web Services inventors acknowledge their defeat and apologize to the WEB community at large for the damage they've done to the Web.

Many REST practitioners have stopped their campaigns a long time ago and moved on to implement the real specifications and applications - there's no point in trying to argue all the time. Atom and AtomPub, Microsoft Astoria and Google GData, Atom-based repositories and JAX-RS - a number of successful examples is growing. They speak and convince better than bitter arguments.

Likewise, many Web Services practitioners have just moved on with their work. There's no point to keep arguing non-stop.

Where camp do I belong to ? As it happens I didn't have a need to work practically with real Web Services for the most part of the last 2 years or so. Is it a strong enough reason for me to believe that Web Services have no real and practical use now that I know I can do an awful lot and more with plain REST ? I don't think so, not yet.

For the REST advocates who can't stop arguing : relax, REST is getting the momentum it deserves and sooner or later many developers will come to it - if it proves an ultimately better technology then it's just a matter of time. Just give people some time.

For the Web Service advocates who can't stop arguing : relax, Web Services have proved they can work - they can be overused like any other technology but they can deliver. And learn REST with open eyes and see what it can bring to you - don't ignore it.

What happened to Web3S ?

Web3S is somewhat 'close' to me given that I dedicated my very first technical post in this blog to that technology :-)
I remember seeing an announcement, then I remember seeing a lot of very critical remarks, then there were some Web3S vs AtomPub discussions, then some silence followed, and then it was all over for Web3S.

I can still link to it - perhaps this link is alive because there could be some customers out there depending on it. Either way, there could a lot of reasons why Microsoft chose to go with AtomPub.

The momentum behind Atom/AtomPub is second to none and it has some attractive features which appeal to different categories of developers.

Still, there's something positive I'd like to say about Web3s - despite its somewhat complicated namespace schemes and some other drawbacks which may've been attributed to it, Web3S XML instances reminded me, well, plain and simple XML.

The role of big Web Services ?

Dare Obasanjo posts an interesting analysis of what looks like a controversial new offering from Google, the Protocol Buffers. Personally I always try to see different sides of a given technology even though I may not like it. I like reading reviews which offer the same kind of perspective and this post certainly fits the bill, not that I'm planning to use Protocol Buffers any soon, but anyway...

I'm curious though, what would Dare have to say about the role of big Web Services given that he's explained when it might make sense to use Protocol Buffers ?

Coldplay : Viva La Vida

I reckon I should create another category for off-topic posts, will do it if I find myself blogging about not web-servicy things a lot...

The latest Coldplay album seems to be their best so far. My criteria is simple : if this music can inspire me while I'm driving to work, possibly stuck in a traffic :-) then by definition it's a very good music - and thus Coldplay join Muse and Killers as one my favorite bands...

While the Killers' text "Higher and higher we're gonna take it, down to the wire we're gonna make it" is probably my favorite piece of 'applicable to the software business' kind of text, Coldplay's "If I'm losing it does not mean I'm lost" is also not too bad and is quite applicable.

Thursday, June 26, 2008

Euro 2008 : Russia vs Spain

As you know, every fairytale comes to an end one day. For those cheering Russia this is what happened tonight.

The Russian team, thanks to its players and their Dutch master, has shown some truly brilliant football against Sweden and Holland. They really played well in those games. But one has to accept that they've been comprehensively beaten by even more brilliant Spanish team. I think they just shocked the Russians with their absolutely top display today, it was a soccer fan's joy to see them playing like that. Spain look like the true Euro 2008 champions.

The good news for Russian fans is that their team, being the youngest in the competition , showed some real quality and talent. They have a good chance to qualify and impress in South Africa.


Who knows, may be I'll be lucky to see Belarus playing in the major tournament one day too.

Wednesday, January 16, 2008

Overloaded GET

GET has always suffered most with respect to being overloaded.

With SOAP, people 'GET' something over POST. But SOAP is not the only 'culprit' in overloading HTTP verbs and GET (or POST, whichever way you look at it) in particularly.

While people use GET to perform actions with side-effects, that is something which is not very interesting as there are often some obvious solutions available like using POST instead.

More interesting is how to GET the metadata for a given resource.
Dave Orchard writes in one of his latest posts :

One interesting aspect of the document is that it specifies how a web site can authorize other web sites to do non-GET operations such as PUT or DELETE. The client makes an authorization request by creating an HTTP GET with the http header Method-Check. The server then responds with an HTTP Response containing Access-Control HTTP Headers or even an XML document with Processing Instructions.
Now the part that I found very interesting is that it seems that the client's authorization request isn't really for the resource identified by the URI, because the goal is to actually get the authorization information. Thus, an HTTP GET has been over-ridden to be a GET of metadata about a resource. Also interestingly, if the URI for some reason doesn't know about the Method-Check header, then it will return the "wrong" representation, that is the actual representation. There is no way of requiring that the server knows about the Method-Check request.


Here's another example from a Waddling in Jersey post :

GET /resources/form/colours
Accept: application/vnd.sun.wadl+xml

returns a piece of metadata describing how to access this "/resources/form/colours" resource but not the actual state of this resource like {red, blue}.

I was explained recently how Rails approaches problems like this one.
The Rails way is to do

GET /resources/form/colours.wadl

or to get the access control data :

GET /resources/form/colours.acl

This approach is probably the least ambiguous but some care needs to be taken here to avoid clashes with actual custom resources, etc.

When HTTP headers are used to 'overload' GETs as in examples above, one issue, as noted by David, is that if a given resource does not recognize a header then a 'wrong' representation is returned. Using 'MustUnderstand' SOAP feature is indeed can be of interest in cases when a service node needs to either recognize a header or fail.