Specifications blues...

I am responsible for our WSRP implementation and it's been challenging at times. The basics of the specification is easy enough but, as usual, the devil is in the details.

Take for example what I'm currently working on: support for file uploading (i.e. forms that use the multipart/form-data enctype). The specification is far from clear on how it's supposed to be handled. On one side, you have form parameters, which are the parsed parameters in a form (with a application/x-www-form-urlencoded MIME type). On the other side, you have upload contexts which are, according to the specification: an optional field where mime types not parsed into formParameters are placed for transfer to the Producer. How's that for not explicit?

Then you take a look at the UploadContext type and you see that there are two required fields, mimeType and uploadData. mimeType is the MIME type of what is in the uploadData. Alright, clear enough, but what is supposed to go in uploadData? Well, according to the spec: a binary data blob that is being uploaded!

There are so many ways you could write code that conforms to this rather vague specification that it's not even funny: do you put the whole form data as a binary blob (similarly to what is done in the portlet specification) or do you use one UploadContext per file being uploaded? Do you include any of the form metadata in the blob? Far from clear!

The approach that I first took was to split each file into its own UploadContext, including only the file data in the uploadData field. However, by doing that, I quickly realized that some of the form metadata is lost in the process: when the producer receives the interaction parameters, there is no way to know which uploadData was associated with which form field. So I was stumped for a while. Julien pointed me to a message on the WSRP mailing list archive, showing that I wasn't the only one confused with the issue (note, by the way, that the thread didn't resolve the issue): the optional field mimeAttributes, which, according to the specification, are MIME attributes that are not represented elsewhere could potentially offer a solution. How helpful! What are those MIME attributes is not clear, though, according to the message, they might be used to contain the needed metadata. How exactly is still a mystery! Note also that none of this in actually mentioned in the specification.

More googling resulted in finding a post on MSDN where I found this gem:

The specification for uploading binary data for WSRP is a bit unclear. The technique that has been adopted by most vendors is to pass the MIME contents, derived directly from a browser post operation, into the uploadData byte array with the MIME type defined as multipart/form-data. The MIME contents include all the attributes and form data, in addition to the binary data.

At this point, I'm wondering how I am supposed to figure this out when I work mostly off of the specification. Why isn't this clearly explained in it?

If that was the only ambiguous/unclear part of the specification, it wouldn't be too much of a problem. However, there are many such instances where there is a lot of room for interpretation. It wouldn't be as bad if there was a decent TCK but this is not the case: WSRPtk is pretty much dead, almost impossible to work with and doesn't have good coverage. Sometimes working with the specification it feels like the big boys did their thing, discussed issues and no traces (or close to none) were left of it and the actual specification was written as an afterthought, just the bare minimum to work with (which is feasible only if you interpret the things the way they are supposed to).

And people wonder why standards are not more widely adopted or supposedly compatible implementation turn out not so compatible after all... <sigh>