Here are a small bit of feedback on the javadoc in a few files. I
figure it might make sense to pipeline this if that's okay with you.
-- Bruce
On 2/8/07, Miguel Méndez <mme...@google.com> wrote:
> A user/src/com/google/gwt/user/server/rpc/RPC.java
Javadoc...
The class itself:
- Would be nice if there was a code example at the top of how to use
the RPC utility methods in a canonical way.
In decodeRequest(String):
- Does it really need to specify that it calls
decodeRequest(String,Class) as part of its implementation?
In decodeRequest(String, Class):
- Typo in decodeRequest(String, Class). Search for "the this method".
- It isn't really clear what "service" is from reading the doc. Must
it be a class? Can it be an interface? It isn't clear that the phrase
"the requested interface and method" is talking about the payload
contents...it sounds like it could be talking about the 'service'
param itself.
In invoke():
- The doc doesn't make it clear why the result is a String rather than
an object. The API looked orthogonal until I saw that. Wouldn't you:
1) call invoke()
2) receive the result object
3) call encodeSuccess on the object from #2
?
There's probably a good reason, but the javdoc doesn't make it clear.
In encodeSuccess() and encodeFailure():
- Why do you have to pass the Method in? It isn't clear from the Javadoc.
> M user/src/com/google/gwt/user/server/rpc/package.html
- "see and override" sounds a little funny
- The RemoteServiceServlet.processCall reference should be a hyperlink
(@link works from inside package.html)
- "or by code invoked by overrides of the processCall method" is hard
to parse; rephrase?
- The RemoteServiceServlet.handleFailure reference should be a hyperlink
Miguel,
Here are a small bit of feedback on the javadoc in a few files. I
figure it might make sense to pipeline this if that's okay with you.
-- Bruce
On 2/8/07, Miguel Méndez <mme...@google.com> wrote:
> A user/src/com/google/gwt/user/server/rpc/RPC.java
Javadoc...
The class itself:
- Would be nice if there was a code example at the top of how to use
the RPC utility methods in a canonical way.
In decodeRequest(String):
- Does it really need to specify that it calls
decodeRequest(String,Class) as part of its implementation?
In decodeRequest(String, Class):
- Typo in decodeRequest(String, Class). Search for "the this method".
- It isn't really clear what "service" is from reading the doc. Must
it be a class? Can it be an interface? It isn't clear that the phrase
"the requested interface and method" is talking about the payload
contents...it sounds like it could be talking about the 'service'
param itself.
In invoke():
- The doc doesn't make it clear why the result is a String rather than
an object. The API looked orthogonal until I saw that. Wouldn't you:
1) call invoke()
2) receive the result object
3) call encodeSuccess on the object from #2
?
There's probably a good reason, but the javdoc doesn't make it clear.
In encodeSuccess() and encodeFailure():
- Why do you have to pass the Method in? It isn't clear from the Javadoc.
> M user/src/com/google/gwt/user/server/rpc/package.html
- "see and override" sounds a little funny
- The RemoteServiceServlet.processCall reference should be a hyperlink
(@link works from inside package.html)
- "or by code invoked by overrides of the processCall method" is hard
to parse; rephrase?
- The RemoteServiceServlet.handleFailure reference should be a hyperlink
Hi Bruce,
In encodeSuccess() and encodeFailure():
- Why do you have to pass the Method in? It isn't clear from the Javadoc.
The Method parameter is used to perform additional checks. In encodeSuccess we make sure that the return value is compatible with the Method's declared return type. In encodeFailure, we check that the Throwable is compatible with the Method's list of checked exceptions.
Overall
- Copyright headers on anything you touch need to be updated to 2007 (and not 2006-2007). Emily can probably help if the checkstyle rules need tweaking.
We definitely need to tweak our checkstyle settings to allow either 2006 or 2007 (mutually exclusive), but we I don't think we have to gate that on doing a sweep.On 2/23/07, Scott Blum < sco...@google.com> wrote:On 2/23/07, Bruce Johnson <br...@google.com> wrote:Overall
- Copyright headers on anything you touch need to be updated to 2007 (and not 2006-2007). Emily can probably help if the checkstyle rules need tweaking.
Not to derail the thread, but this is an issue we need to address on a much larger scale, and programmatically. Files using the 2007 header will still break the build; we need to fix this and then do a programmatic sweep of the whole source tree to bump the versions on either a) everything or b) everything that's changed since 1/1/07.
Scott
"Worth the wait" would be my description of this thread :-)
Also, thanks very much Miguel for effectively owning these changes to
the patch. If you would like me to help with fielding Bruce's
comments, please let me know; otherwise my assumption is that you're
OK with continuing to bring this in to a final landing.
Some specific peanut-gallery replies to Bruce's questions:
>- FFTI: is Class.forName() fast? could we speed things up by caching
>String=>Type mappings in an instance HashMap?
I would want to profile the overall subsystem with a few different
stress cases before adding more optimization like that. I'm sure a
map would be faster than just Class.forName, but I'm not sure it's
enough of a hotspot to matter.
>- The check "RemoteService.class.isAssignableFrom(serviceIntf)" requires the
>target to implement RemoteService; I'm just checking that this is an okay
>requirement for the use cases we care about (TMIF welcome)
The service interface has to implement RemoteService in order for GWT
to compile the client-side service class. So enforcing that
requirement on the server seems congruent with that. A deeper
question might be, why have the RemoteService marker interface at all,
on either client side OR server side? But if you have it on one,
seems good to verify it on the other.
(What does TMIF mean? Too Much InFormation? Google is remarkably
unhelpful on this!)
>Code for encodeSuccess
> - the error message relies on Class.getName() generating a user-readable
>type name...might not look right for all types (e.g. arrays of primitives)?
Good point, albeit moderately cumbersome to fix.
> - the error message relies on serviceMethod.toString() generating a
>user-readable method declaration...does it? (TMIF welcome)
Yes, in my experience it does.
Best regards,
Rob
(What does TMIF mean? Too Much InFormation? Google is remarkably
unhelpful on this!)
>- FFTI: is Class.forName() fast? could we speed things up by caching
>String=>Type mappings in an instance HashMap?
I would want to profile the overall subsystem with a few different
stress cases before adding more optimization like that. I'm sure a
map would be faster than just Class.forName, but I'm not sure it's
enough of a hotspot to matter.
(What does TMIF mean? Too Much InFormation? Google is remarkably
unhelpful on this!)
AFAICT the code is essentially isomorphic to the 1.3.3 code -- it's
basically the same code, just rearranged. I'm not at all opposed to
profiling in order to verify that, but on inspection, at least,
there's nothing very different happening. (Amazing how refactoring
can enhance extensibility without altering function...)
I would say TMIF, but it seems presumptuous somehow :-)
Thanks for the TMIF clues.
Cheers,
Rob
AFAICT the code is essentially isomorphic to the 1.3.3 code
I would say TMIF, but it seems presumptuous somehow :-)
Overall
- I couldn't build this from the command line due to doc build problems.
- Copyright headers on anything you touch need to be updated to 2007 (and not 2006-2007). Emily can probably help if the checkstyle rules need tweaking.
RemoteServiceServlet.java
Javadoc for the class
- Funky grammar with the "Or, " paragraphs.
Javadoc for onUnexpectedFailure
- looks funky; maybe overly aggressive doc autoformatting?
Code for doPost
- catch(Throwable e): We need more of an explanation of the possible control flow here. It isn't clear whether or not onUnexpectedFailure() can/should throw an exception or not. The semantics a little confusing themselves, but at least onUnexpectedFailure() is well documented. It's just that here at the call site, you don't really know what to expect.
RPC.java
Javadoc for the class
- Bad corss reference to CanonicalExample#doPost() -- should it be processCall?
- Unneeded comma after Spring
More descriptive methods names would be nice:
- encodeFailure => encodeResponseForFailure
- encodeSuccess => encodeResponseForSuccess
- invoke => invokeAndEncodeResponse
- Yes, these names are longer but I had to reference the Javadoc to understand the semantics, and the longer name reduces the need to look up doc
Javadoc for decodeRequest(String)
(see comments for the other overload, most apply)
Javadoc for decodeRequest(String, Class)
- It still isn't totally clear from the description exactly when I'd want to supply a constraint type or not. Does doing so make my code somehow safer? If I don't supply one and the type gets loaded, does it enforce any checks at all? Maybe an example would help.
- "implements the" might be clearer as "is assignable to the" (requires a tweak to the grammar later in the sentence regarding "method")
- @param payload: rephrase? the payload actually includes more than "the request parameters"
- @param classOrInterface: could rename to "type" to get the same effect; also, would be clearer to change "implements the" to "is assignable to the"
- @throws NullPointerException: nice to add <code> brackets around null [you can ctrl+space immediately after typing null to get doc completion to do that]
- @throws SerializationException: grammar issue
- @throws SecurityException: stale reference to the old param name "constraintClass"
- look for other places you could change "null" to "<code>null</code>"
- look for other places with inline code you could add <code> tags around (e.g. "RPC.getClass().getClassLoader)")
Code for decodeRequest(String, Class)
- The check "RemoteService.class.isAssignableFrom(serviceIntf)" requires the target to implement RemoteService; I'm just checking that this is an okay requirement for the use cases we care about (TMIF welcome)
- Error message typo; search for "RemoteService; ;"
Code for getClassFromSerializedName
- FFTI: is Class.forName() fast? could we speed things up by caching String=>Type mappings in an instance HashMap?
Javadoc for encodeSuccess
- @return: reword? strictly speaking, the string encodes the object passed in -- it really doesn't literally "encode the result of calling a service method" per se (although, yes, that's how it would be used in practice)
Code for encodeSuccess
- throw new IllegalArgumentException
- the error message relies on Class.getName() generating a user-readable type name...might not look right for all types (e.g. arrays of primitives)?
- the error message relies on serviceMethod.toString() generating a user-readable method declaration...does it? (TMIF welcome)
Javadoc for invoke
- @param serviceMethod: grammar? spurious period
- @param parameters: the name "args" would be more correct
- @return: grammar
- @throws SecurityException
- needs to be updated if you rename "parameters"
- the tense seems different in the two clauses
- "type-valid" isn't a well known phrase, maybe rephrase to clarity?
Code for invoke
- Tone down both error messages for "Security vioation" to match the tone in decodeRequest(); it isn't necessarily a "real" security violation; it's a blocked attempt to do something incorrect that could be caused by a variety of reasons (e.g. client/server mismatch). Matching the phrasing in decodeRequest() would enhance consistency and is less likely to induce unjustified paranoia.
AdvancedExample.java
Sample code in doPost()
- FFTI (feel free to ignore): the names "returnSuccess", "returnFailure", and "returnGenericFailure" imply we're returning from the function. How about "sendResponseForSuccess", etc? (Or some variation of a name that doesn't mix the "return" keyword idea with the idea of writing a response the socket.
On 2/22/07, Miguel Méndez <mme...@google.com > wrote:Hi Bruce,In encodeSuccess() and encodeFailure():
- Why do you have to pass the Method in? It isn't clear from the Javadoc.
The Method parameter is used to perform additional checks. In encodeSuccess we make sure that the return value is compatible with the Method's declared return type. In encodeFailure, we check that the Throwable is compatible with the Method's list of checked exceptions.
It makes sense. I thought maybe there would be a more elegant way to do this while reducing possible error modes, but I don't really think there is.
On 2/22/07, Miguel M�ndez <mme...@google.com > wrote:Hi Bruce,In encodeSuccess() and encodeFailure():
- Why do you have to pass the Method in? It isn't clear from the Javadoc.
The Method parameter is used to perform additional checks. In encodeSuccess we make sure that the return value is compatible with the Method's declared return type. In encodeFailure, we check that the Throwable is compatible with the Method's list of checked exceptions.
It makes sense. I thought maybe there would be a more elegant way to do this while reducing possible error modes, but I don't really think there is.
--
Miguel
I'm actively working on integrating GWT with Seam, based on my g4jsf
patch, which is ready to land as soon as... well, as soon as THIS
patch lands. Now that Exadel is effectively part of JBoss, the whole
Seam -> ajax4jsf -> GWT connection is just that much more interesting
to JBoss, so it's getting some attention from over there. I'll
definitely keep this group posted on developments.
:-)
Cheers!
Rob
=== RemoteServiceServlet.java
- The hyperlink in processCall() to invokeAndEncodeResponse() comes out broken when we build GWT doc; it looks good in the standard javadoc; would you mind entering a bug against our doc tool?
=== RPC.java
- The first sample looks messed up in the GWT generated doc; it looks good in the standard javadoc; would you enter a bug against doctool for this also, please?
- The advanced example has some weird and apparently-unnecessary concatenations of consecutive string literals in messages (see the catch blocks).
- The first sentence in the javadoc for invokeAndEncodeResponse() needs a comma before the phrase beginning with "which could be"; this isn't a nitpick: without the comma it seems like the phrase is referring to the service method that gets called rather than the result that the invocation produces.
Now... dare I ask whether it's time to have a CONTRIBUTORS file, with
me in it? (and all of you, I presume, also?)
See this thread: http://groups.google.com/group/Google-Web-Toolkit-Contributors/browse_thread/thread/d288a5a6a3c5eb1a
My reading of it is that you guys did plan to have one, once you had
outside contributors. Well, now you do ;-)
(Sandymac should be able to resubmit his compiler patch too, now that
Scott did the necessary cleanup... correct?)
Cheers!!!!!
Rob
On Mar 21, 10:35 am, "Bruce Johnson" <b...@google.com> wrote:
> Rob, Miguel, you guys rock.
>
> On 3/21/07, Miguel Méndez <mmen...@google.com> wrote:
> > W00T!!!!