[jsr366-experts] Re: updated requirements

From: Jason Greene <jason.greene_at_redhat.com>
Date: Tue, 24 Mar 2015 12:21:21 -0500

> On Mar 23, 2015, at 5:17 PM, Bill Shannon <bill.shannon_at_oracle.com> wrote:
> Jason Greene wrote on 03/23/15 14:38:
>> While the other discussion is ongoing I thought I would address this one,
>> even though it was written before my other replies:
>>> On Mar 19, 2015, at 8:21 PM, Bill Shannon <bill.shannon_at_oracle.com> wrote:
>>> I've tried to coalesce our recent discussion into an updated set of
>>> requirements. If we can come to agreement on these requirements, we'll
>>> update the spec accordingly. I've written these in the style of RFC 2119,
>>> although they'll need to be rewritten to better fit into the current style
>>> of the spec, and will need to be added to the appropriate places in the
>>> spec. Right now I'm just trying again to make sure we agree on what the
>>> requirements *are*. And again, none of these are intended to be new
>>> requirements, they're intended to be clarifications of the existing
>>> requirements. If we decided we want to strengthen any of these
>>> requirements, we would do that for Java EE 8.
>>> If you disagree with any of these, let me know what you think they *should*
>>> say.
>>> If anything is missing based on our recent discussion, please suggest
>>> additions.
>>> Thanks
>>> -----
>>> If annotations are being processed (as required by table EE.10-1, Servlet
>>> table 8-1, and EJB tables 16 and 17), *at least* all of the classes
>>> specified in table EE-5.1 MUST be scanned for annotations that specify
>>> deployment information. As specified in section EE.8.5.2, all classes that
>>> can be used by the application MAY be scanned for these annotations.
>>> (These are the annotations that specify information equivalent to what can
>>> be specified in a deployment descriptor. This requirement says nothing
>>> about the processing of annotations that were defined for other purposes.)
>>> These annotations MAY appear on classes, methods, and fields.
>> The approach of explicitly allowing B and C for EE7 is reasonable, since it
>> preserves compatibility for existing implementations.
>>> All resources specified by resource definition annotations MUST be created.
>>> All resource reference annotations MUST result in JNDI entries in the
>>> corresponding namespace.
>> This seems to contradict the weaker SHOULD language in the paragraph on
>> defaults below?
> I guess the question is, if you use java:comp where it's not valid, and
> you *don't* fail deployment in that case, what's allowed to happen?
> Ignoring the annotation would be fine, and probably the second best choice.
> Creating the annotation in some product-specific java:comp namespace
> associated with some product-defined "component" would also be fine.

I agree both of those should be fine.

> If I rewrite the above sentence to this does that solve it?
> All valid resource reference annotations MUST result in JNDI entries in the
> corresponding namespace.
> Do I need to fully define what's "valid”?

Perhaps it should be followed with: “If the namespace is not available to the class declaring or inheriting the reference, the resulting behavior is undefined. Future versions of this specification may alter this behavior."
>>> The metadata-complete attribute in the standard deployment descriptors
>>> effects *only* the scanning of annotations that specify deployment
>>> information, including web services deployment information. It has no
>>> impact on the scanning of other annotations.
>> That’s fine.
>>> The default JNDI namespace for resource reference and definition
>>> annotations MUST *always* be "java:comp/env". Note that this applies to
>>> both the case where no name has been supplied so the rules for choosing a
>>> default name are used, and the case where a name has been supplied
>>> explicitly but the name does not specify a java: namespace. Since the
>>> java:comp namespace is not available in some contexts, use of that
>>> namespace in such a context SHOULD result in a deployment error. Likewise,
>>> the java:module namespace is not valid in some contexts; use of that
>>> namespace in such contexts SHOULD result in a deployment error.
>> I really think we should figure out the EE8 strategy for what we are going to
>> do before deciding on this, but I do prefer this over a compatibility
>> breaking MUST. If we do go with the SHOULD language, I think we need to
>> update the CDI spec and examples to use fully qualified namespaces.
> For EE 8 we can get away with taking an error case that's supposed to result
> in a deployment failure and defining some useful semantics for it. I'm
> more concerned if products start interpreting it as a valid case it will
> constrain what we can do for EE 8. Currently it's something that apps are
> not supposed to do. The flexibility we're allowing is whether you detect
> that error at deployment or whether some undefined behavior happens at
> runtime. The intent is not to allow you to define it as a valid case
> for EE 7.

Ok, I think that works.

>>> All resource references SHOULD be mapped to resources defined in the target
>>> operational environment. By default, if a resource reference is not
>>> mapped, deployment MUST fail. A product MAY provide a deployment option
>>> that allows deployment to succeed in this case.
>> Thats fine.
>>> Deployment SHOULD fail if the lookup attribute in a resource annotation, or
>>> the lookup-name element in a deployment descriptor entry, does not specify
>>> a name with an explicit java: namespace.
>> Also fine.
> I'd *really* like to say MUST here. After all, the reason we have lookup
> in addition to mappedName is because mappedName was non-portable. Allowing
> non-portable behavior for lookup is a mistake. I'm just afraid it's a
> mistake we can no longer correct, even though that was clearly our original
> intent.

I agree that it likely can’t be changed. However, the SHOULD is strong enough to call out the portability problem.

>>> Deployment MAY provide an option that controls whether or not an
>>> application is attempted to be started during deployment. If no such
>>> option is provided, and deployment is successful, the application MUST be
>>> started. If the application is attempted to be started during deployment,
>>> CDI MUST be initialized during deployment. [XXX - need reference to exactly
>>> what constitutes CDI initialization]. If CDI initialization fails,
>>> deployment MUST fail. CDI MUST ONLY be initialized if the application is
>>> attempted to be started. [XXX - need to determine whether any other
>>> initialization is required]
>> Would this “start” state be step 3 of E 2.11.4?
> Yes.

Ok. So I think the reference you want is 12.2:

" If the application is attempted to be started during deployment, the startup initialization procedure defined by the relevant Java EE component specifications must be executed during deployment. Notably, CDI MUST be initialized during deployment, in accordance with "12.2 Application initialization lifecycle" of the CDI specification. Failure of application startup during deployment MUST also abort the deployment. If the application is not started during deployment, then the startup initialization procedure defined by relevant Java EE component specifications MUST not be executed.”

If desired we could include a non-normative:

 “Since startup initialization is deferred, errors during that occur during this process are also deferred. Therefore, the deployment process may succeed in spite of such errors."

Jason T. Greene
WildFly Lead / JBoss EAP Platform Architect
JBoss, a division of Red Hat