Re: JSR311: Aggregation(?) of "Targets for @*Param, @DefaultValue, @Encoded"

From: Marc Hadley <Marc.Hadley_at_Sun.COM>
Date: Thu, 20 Mar 2008 13:59:40 -0700

On Mar 20, 2008, at 1:19 PM, Stephan Koops wrote:
> aggregation of discussion for root resource classes
> if I collect the disussion points of the last days, I think we can
> aggregate this to the following points realting to @*Param:
> Allow @*Param on parameters, fields and setters (setters are not
> required to be thread save)
> singelton lifecycle runtime environments must reject root
> resource classes (rrcs) with annotated fields or setters. (Other
> possibilities with Numbers and CharSequences are to complicated)
> This is close to (iv) of the proposals of Marc.
> Paul, Marc, is this right? Did I forget something important?
Not exactly my suggestion. I don't think an implementation should be
required to police use of @*Param annotations on fields+methods of
resource classes with lifecycles other than per-request. If an
implementation defers object creation to an IoC framework it may not
know the lifecycle so it can't be expected to enforce it. I suggest we
warn developers about the consequences (i.e. it will probably break),
offer an alternative (use resource method params) and then caveat

> BTW: What about other instance fields? They may cause trouble in
> singelton lifecycle rrcs -> reject rrcs with any instance field?
> But there are questions for
> non-root resource classes:
> While thinking about (if all agree with the point above):
> Non-root resource classes have app developer managed lifecycles (see
> spec). For them I propose (not discussed):
> If the lifecycle is per-request (or the app developer otherwise
> ensures that only one thread uses it the same time, e.g. pooling):
> the app developer can use @*Param on parameters, fields and setters.
> If the lifecycle is singelton: the app developer must only use
> them on method parameters.
> It is the responsibility of the app developer to use them right
> here. It is good to put a related warning in the javadoc of all
> @*Param, and also in the spec.
An implementation doesn't inject on non-root resource classes, see
section 5.2 "Injection Scope". One thing we could do here if this is
desirable is to allow a sub-resource locator to return a Class rather
than an instance, the runtime would then instantiate an instance and
inject that.

> Independent of the results for @*Param, there is the same question for
> @Context
> Must instances be thread save or not? Neither the specification nor
> the javadoc defines anything.
> In rrcs it depends exactly on the used lifecycle: if singelton,
> than @Context annotated fields must be thread save, if not, than not.
> non-root resource classes may be singeltons or not, independent
> of the lifecycle of the rrcs (app developer responsibility, see above)
> Here a definition is needed, if a non-root resource classses can
> estimate a thread save implementation of UriBuilder, SecurityContext
> and so on. BTW: This must kept in mind also for @Resource of JSR-250
> (and perhaps others).
> A possibility is to not require thread safety; singelton non-root
> resource classes must not use them on fields and setters (the same
> as for @*Param for singelton non-root resource classes, see above);
> the app developer has the responsibility to ensure, that he use it
> correct. This is consistent to the proposal above.
For @Context the injected instance should be a thread-local proxy. I
thought I had included this in the spec but apparently not - sorry
about that.


Marc Hadley <marc.hadley at>
CTO Office, Sun Microsystems.