On Nov 1, 2007, at 5:45 AM, Michael McMahon wrote:
I wonder if you have an opinion on the points/questions raised below?
I'd like to get agreement on the general shape of the API before
anyone goes off and reworks the existing proposal.
Some comments interspersed below.
Michael McMahon wrote:
I agree with most of the suggestions below. The main things
we want are:
1) alignment, ie. the JSR311 class extends the java.net class
although I would imagine that if JSR311 is finalised before jdk7
then it will not initially extend it. So, it should at least be
aligned
sufficiently so that it could extend the java.net class in the
future
I agree with the goal but we'd rather not be tied to jdk7. The
current plan is to make the API available separately for jdk5 or
later. Would we be able to bundle any jdk7 superclass to achieve that ?
2) then we combine the building capabilities of UriBuilder
(probably use that name also)
with the retrieval/query manipulation capabilities of
UrlEncodedQueryString.
I think the method names from UrlEncodedQueryString will have
to change though
eg addParameter() would need to be addQueryParameter() etc.
The builder is strictly that, a builder, so I'm not sure if it makes
sense to add read capabilities to it. Would it make sense to add the
read capabilities of UrlEncodedQueryString directly to URI ?
Some questions.
1) I'm not familiar with the notion of "matrix" parameters.
Google seems to
only reveal one old w3c article about them. Are they more
widely used than this?
If the concept is more specific to JSR311, then I think I'd
prefer to leave them
out of the java.net. class
Matrix parameters aren't specific to JSR311, I believe that a number
of Web APIs make use of them but I don't have an example at hand.
2) Initially I was sceptical about URI templates, and I do think
that the
general class probably doesn't need any of the methods related to
reflection/annotation processing (of URI templates), but it does
look like a useful feature
and it's worth considering supporting the build() capability
which replaces
{} templates with specific instance values from the Map passed in.
The risk of course is that the specification for URI templates
could change
before it is standardised by the IETF.
That is a definite risk. Currently we are discussing more complex
notations for representing things like default values, prefixes,
suffixes etc. The simple {param_name} syntax is likely to survive
though so its possible we could implement that initially and add full
support in a subsequent release.
Regards,
Marc.
Marc Hadley wrote:
On Oct 12, 2007, at 6:31 PM, Richard Kennard wrote:
> [UriBuilder has] 4 methods associated with accessing URI
templates of a class or method, but it is simple to generalize
by removing such methods
This seems a good starting point. If I may propose a logical
progression:
1. We split JSR311's UriBuilder into a JSR311-specific version
and a generalized java.net version
2. We add further generalized methods into the java.net version
to cover the other URI segments (scheme, host, port, authority,
user-info)
The JSR 311 UriBuilder has methods for scheme, host, port and
userInfo. We did have authority too but removed it since its a
composite of some of the others.
3. We would now have a class that looks not unlike what I was
proposing last year. The java.net team's objection to this class
(which I agree is valid) was that some methods (queryParam,
matrixParam) are not strictly part of the RFC 2396 URI spec. So
we may split it again, into a 'strict URI' part and a 'www-form-
urlencoded query string' part (which I think is essentially what
queryParam and matrixParam are implying)
4. We agree that parsing and retrieving is also a useful feature
and include that (the class can still be called 'builder' -
StringBuilder has methods for retrieving, for example)
I think how we do the split in 3) is the most important
decision. The java.net team and I tried two ways - a generalized
superclass and a specialized subclass, and a standalone class -
and preferred the latter, hence where we are with
UrlEncodedQueryString today.
What do you think?
I think it would make sense for the JSR 311 class to extend a
generalized java.net class since we'd want to add support for URI
templates. That support is pervasive so its not just a case of
adding new methods, we'd want to override existing ones to allow
URI templates to be used within their values.
Regards,
Marc.
---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.
