From richard at kennardconsulting.com Wed Aug 1 12:10:06 2007 From: richard at kennardconsulting.com (Richard Kennard) Date: Thu, 02 Aug 2007 05:10:06 +1000 Subject: Updated URLEncodedQueryString In-Reply-To: <469DDB04.5010401@kennardconsulting.com> References: <469B5F42.1080100@sun.com> <469B805C.3050703@sun.com> <469B9E88.50704@sun.com> <469DDB04.5010401@kennardconsulting.com> Message-ID: <46B0DA8E.2010106@kennardconsulting.com> Michael, I have further updated URLEncodedQueryString to incorporate everybody's JavaDoc feedback: https://jdk-collaboration.dev.java.net/servlets/ProjectForumMessageView?messageID=20908&forumID=1463 Hoped to hear from you soon, Richard. From Christopher.Hegarty at Sun.COM Thu Aug 2 02:55:19 2007 From: Christopher.Hegarty at Sun.COM (Christopher Hegarty - Sun Microsystems Ireland) Date: Thu, 02 Aug 2007 10:55:19 +0100 Subject: Updated URLEncodedQueryString In-Reply-To: <46B0DA8E.2010106@kennardconsulting.com> References: <469B5F42.1080100@sun.com> <469B805C.3050703@sun.com> <469B9E88.50704@sun.com> <469DDB04.5010401@kennardconsulting.com> <46B0DA8E.2010106@kennardconsulting.com> Message-ID: <46B1AA07.8000208@sun.com> Some initial (picky) comments: 1) "Thread Safety Instances of UrlEncodedQueryString are not not synchronized." Typo: "not not". I would expand this a little. Maybe taking wording similar to java.util.HashMap: "Note that this implementation is not synchronized. If multiple threads access a query string concurrently, and at least one of the threads modifies the query string, it must be synchronized externally. This is typically accomplished by synchronizing on some object that naturally encapsulates the query string." 2) Consistency when documenting to how separators are handled. parse(java.net.URI uri) "...When parsing, all separators from the Separators enum are recognised." I would change this as follows: "...When parsing, all Separators are recognised." 3) getParameterValues "Returns an array of String objects containing all of the values the named parameter has, or null if the parameter does not exist. If the parameter has a single value, the array has a length of 1." Should read: "Returns a List of String objects containing all of the values the named parameter has, or..." How about returning an empty list if the parameter does not exist? Similar to getParameterNames, "an empty Iterator if there are no parameters" Also, typo in @returns "an List of String objects..." -> "a List of String objects..." -Chris. Richard Kennard wrote: > Michael, > > I have further updated URLEncodedQueryString to incorporate everybody's > JavaDoc feedback: > > > https://jdk-collaboration.dev.java.net/servlets/ProjectForumMessageView?messageID=20908&forumID=1463 > > > Hoped to hear from you soon, > > Richard. > > > From richard at kennardconsulting.com Thu Aug 2 15:34:38 2007 From: richard at kennardconsulting.com (Richard Kennard) Date: Fri, 03 Aug 2007 08:34:38 +1000 Subject: Updated URLEncodedQueryString In-Reply-To: <46B1AA07.8000208@sun.com> References: <469B5F42.1080100@sun.com> <469B805C.3050703@sun.com> <469B9E88.50704@sun.com> <469DDB04.5010401@kennardconsulting.com> <46B0DA8E.2010106@kennardconsulting.com> <46B1AA07.8000208@sun.com> Message-ID: <46B25BFE.6000302@kennardconsulting.com> Chris, Thanks for your feedback. And actually, picky is good! I much prefer picky feedback to no feedback at all. I have updated the JavaDoc with your suggestions: https://jdk-collaboration.dev.java.net/servlets/ProjectForumMessageView?messageID=20922&forumID=1463 However, on the question of... > How about [getParameterValues] returning an empty list if the parameter does not exist? ...I guess this comes down to whose behaviour it makes more sense to model. Do we model the behaviour of getParameterNames, as you suggest, and return an empty List, or do we model the behaviour of getParameterValue (it's non-plural version) and return null if the parameter does not exist? I've leaned towards the latter, but I am open to reasons to lean toward the former. Regards, Richard. Christopher Hegarty - Sun Microsystems Ireland wrote: > Some initial (picky) comments: > > 1) "Thread Safety > Instances of UrlEncodedQueryString are not not synchronized." > > Typo: "not not". > > I would expand this a little. Maybe taking wording similar to > java.util.HashMap: > > "Note that this implementation is not synchronized. If multiple > threads access a query string concurrently, and at least one of the > threads modifies the query string, it must be synchronized > externally. This is typically accomplished by synchronizing on some > object that naturally encapsulates the query string." > > 2) Consistency when documenting to how separators are handled. > > parse(java.net.URI uri) > "...When parsing, all separators from the Separators enum are > recognised." > > I would change this as follows: > "...When parsing, all Separators are recognised." > > 3) getParameterValues > > "Returns an array of String objects containing all of the values > the named parameter has, or null if the parameter does not exist. > > If the parameter has a single value, the array has a length of 1." > > Should read: > "Returns a List of String objects containing all of the values > the named parameter has, or..." > > How about returning an empty list if the parameter does not exist? > Similar to getParameterNames, "an empty Iterator if there are no > parameters" > > Also, typo in @returns > "an List of String objects..." -> "a List of String objects..." > > -Chris. > > Richard Kennard wrote: > >> Michael, >> >> I have further updated URLEncodedQueryString to incorporate >> everybody's JavaDoc feedback: >> >> >> https://jdk-collaboration.dev.java.net/servlets/ProjectForumMessageView?messageID=20908&forumID=1463 >> >> >> Hoped to hear from you soon, >> >> Richard. >> >> >> > > From Michael.McMahon at Sun.COM Fri Aug 3 01:22:10 2007 From: Michael.McMahon at Sun.COM (Michael McMahon) Date: Fri, 03 Aug 2007 09:22:10 +0100 Subject: Updated URLEncodedQueryString In-Reply-To: <46B25BFE.6000302@kennardconsulting.com> References: <469B5F42.1080100@sun.com> <469B805C.3050703@sun.com> <469B9E88.50704@sun.com> <469DDB04.5010401@kennardconsulting.com> <46B0DA8E.2010106@kennardconsulting.com> <46B1AA07.8000208@sun.com> <46B25BFE.6000302@kennardconsulting.com> Message-ID: <46B2E5B2.7060601@sun.com> Richard Kennard wrote: > Chris, > > Thanks for your feedback. And actually, picky is good! I much prefer > picky feedback to no feedback at all. > > I have updated the JavaDoc with your suggestions: > > > https://jdk-collaboration.dev.java.net/servlets/ProjectForumMessageView?messageID=20922&forumID=1463 > > > However, on the question of... > > > How about [getParameterValues] returning an empty list if the > parameter does not exist? > > ...I guess this comes down to whose behaviour it makes more sense to > model. Do we model the behaviour of getParameterNames, as you suggest, > and return an empty List, or do we model the behaviour of > getParameterValue (it's non-plural version) and return null if the > parameter does not exist? > > I've leaned towards the latter, but I am open to reasons to lean > toward the former. > I agree with Chris. It is generally thought to be better practice to return empty collection objects rather than null. It means that calling code often does not need special handling for this case. We should finalize the spec soon. I will submit it to the CCC on Tuesday next week, unless there are any further issues raised before then. Monday is a holiday here. Thanks Michael From Michael.McMahon at Sun.COM Fri Aug 24 10:17:49 2007 From: Michael.McMahon at Sun.COM (Michael McMahon) Date: Fri, 24 Aug 2007 18:17:49 +0100 Subject: CCC request for 6306820 Message-ID: <46CF12BD.30800@sun.com> The CCC request for this feature was finalised on 13 August. We've had one comment back so far relating to the sample code in the docs. It seems the samples still refer to the old constructors rather than the factory creation methods. I've updated the docs to fix this. - Michael.