Hello experts,
Since I have not heard any objection to these clarifications, I plan to
update the spec tomorrow COB with these changes.
Shing Wai Chan
On 7/31/12 4:37 PM, Shing Wai Chan wrote:
> After discussing in jira, http://java.net/jira/browse/SERVLET_SPEC-36 ,
> we found several other places with similar issue.
> The following is the list of proposed changes:
>
> Section 8.2.4 of Servlet 3.0,
> Original:
> In addition to the ServletContainerInitializer we also have an
> annotation - HandlesTypes. The annotation will be applied on the
> implementation of ServletContainerInitializer to express interest in
> classes that are either annotated with the classes specified in the
> value or if a class extends / implements one of those classes anywhere
> in the classes super types.
>
> New:
> In addition to the ServletContainerInitializer we also have an
> annotation - HandlesTypes. The annotation will be applied on the
> implementation of ServletContainerInitializer**to express interest in
> classes that are either annotated with the classes specified in the
> value or if a class extends / implements one of those classes anywhere
> in the classes super types. *The @HandlesTypes annotation is applied
> irrespective of the setting of metadata-complete.*
>
>
> Section 1.6.2
> Original:
> However in servlet 3.0 metadata-complete affects scanning of all
> annotations and web- fragments at deployment time. The version of the
> descriptor MUST not affect which annotations you scan for in a web
> application. An implementation of a particular version of the
> specification MUST scan for all annotations supported in that
> configuration, unless metadata-complete is specified.
>
> New:
> However in servlet 3.0 metadata-complete affects scanning of all
> annotations *that specify deployment information* and web- fragments
> at deployment time. The version of the descriptor MUST not affect
> which annotations you scan for in a web application. An implementation
> of a particular version of the specification MUST scan for all
> annotations supported in that configuration, unless metadata-complete
> is specified.
>
>
> Section 8.1
> Original:
> If "metadata-complete" is set to "true", the deployment tool MUST
> ignore any servlet annotations present in the class files of the
> application and web fragments. If the metadata-complete attribute is
> not specified or is set to "false", the deployment tool must examine
> the class files of the application for annotations, and scan for web
> fragments.
>
> New:
> If "metadata-complete" is set to "true", the deployment tool MUST
> ignore any servlet annotations *that specify deployment information*
> present in the class files of the application and web fragments. If
> the metadata-complete attribute is not specified or is set to "false",
> the deployment tool must examine the class files of the application
> for annotations, and scan for web fragments.
>
> Section 8.2.1
> Original:
> As before, if the metadata-complete element is set to true in the
> web.xml descriptor, annotations in the class files and web-fragments
> bundled in jars will not be processed. It implies that all the
> metadata for the application is specified via the web.xml descriptor.
>
> New:
> As before, if the metadata-complete element is set to true in the
> web.xml descriptor, annotations *that specify deployment information
> present* in the class files and web-fragments bundled in jars will not
> be processed. It implies that all the metadata for the application is
> specified via the web.xml descriptor.
>
>
> Section 8.2.2.1.d
> Original:
> Excluded jars are not scanned for classes to be handled by any
> ServletContainerInitializer.
>
> New:
> *Irrespective of the setting of metadata-complete, jars excluded by an
> <absolute-ordering> element* are not scanned for classes to be handled
> by any ServletContainerInitializer.
>
>
> Shing Wai Chan
>
>
> On 7/31/12 7:34 AM, Mark Thomas wrote:
>> On 31/07/2012 08:20, Rémy Maucherat wrote:
>>> On 07/31/2012 12:57 AM, Mark Thomas wrote:
>>>> On 30/07/2012 23:49, Shing Wai Chan wrote:
>>>>> On 7/30/12 3:41 PM, Mark Thomas wrote:
>>>>>> On 30/07/2012 23:21, Shing Wai Chan wrote:
>>>>>>> I am looking at issuehttp://java.net/jira/browse/SERVLET_SPEC-36
>>>>>>> ("Clarify relationship of metadata-complete and
>>>>>>> ServletContainerInitializers")
>>>>>>>
>>>>>>> The metadata-complete=true means the completeness of data specified in
>>>>>>> deployment descriptor.
>>>>>>> But it does not mean the annotation will be ignored in the given
>>>>>>> application.
>>>>>>> For instance, CDI annotations will still be scanned and processed.
>>>>>>>
>>>>>>> The ServletContainerInitializer is a service provider specified in
>>>>>>> META-INF/services, not by annotation. In a
>>>>>>> ServletContainerInitializer,
>>>>>>> there may be a @HandlesTypes, which does not have corresponding
>>>>>>> metadata
>>>>>>> in deployment descriptor. Since a ServletContainerInitializer and
>>>>>>> @HandlesTypes work together, it should be interpreted whenever a
>>>>>>> ServletContainerInitializer is loaded.
>>>>>>>
>>>>>>> In section 8.2.4 of Servlet 3.0,
>>>>>>> "In addition to the ServletContainerInitializer we also have an
>>>>>>> annotation - HandlesTypes. The annotation will be applied on the
>>>>>>> implementation of ServletContainerInitializer to express interest in
>>>>>>> classes that are either annotated with the classes specified in the
>>>>>>> value or if a class extends / implements one of those classes anywhere
>>>>>>> in the classes super types."
>>>>>>>
>>>>>>> I propose the following clarification in wording:
>>>>>>> "In addition to the ServletContainerInitializer we also have an
>>>>>>> annotation - HandlesTypes. The annotation will be applied on the
>>>>>>> implementation of ServletContainerInitializer*, independent of
>>>>>>> metadata-complete,* to express interest in classes that are either
>>>>>>> annotated with the classes specified in the value or if a class
>>>>>>> extends
>>>>>>> / implements one of those classes anywhere in the classes super
>>>>>>> types."
>>>>>>>
>>>>>>> Shing Wai Chan
>>>>>> What about the ordering issue? To quote one of your comments from
>>>>>> SERVLET_SPEC-36:
>>>>>> <quote>
>>>>>> ... excluded jars in absolute-ordering independent of
>>>>>> metadata-complete=true will not be scanned for
>>>>>> ServletContainerInitializers.
>>>>>> </quote>
>>>>>>
>>>>>> I take this to mean "...will not be scanned for classes that match
>>>>>> SCIs"
>>>>>> which works for me.
>>>>> The previous quote in issue tracker is actually in p.67 of Servlet 3.0.
>>>>> Yes, that means the excluded jar (from<absolute-ordering>) will not
>>>>> scan the ServletContainerInitializer.
>>>> Excellent.
>>>>
>>>>> In 8.2.4, I try to clarify the relation between @HandlesTypes and
>>>>> metadata-complete, not about the loading of ServletContainerInitializer.
>>>>> Please let me know whether the spec is clear enough in this case.
>>>> I think we need to clarify the text in 8.2.2.1.d
>>>>
>>>> Currently is states:
>>>> Excluded jars are not scanned for classes to be handled by any
>>>> ServletContainerInitializer.
>>>>
>>>> I think this needs to be:
>>>> Irrespective of the setting of metadata-complete, JARs excluded by an
>>>> <absolute-ordering> element are not scanned for classes to be handled by
>>>> any ServletContainerInitializer.
>>>>
>>>> or something along those lines.
>>> I don't see how or why HandlesTypes is related to metadata. This is not
>>> an annotation which defines metadata.
>> First of all, the spec states that JARs excluded from absolute ordering
>> are excluding from scanning for classes that match classes defined by
>> the HandlesTypes annotation.
>>
>> The query was what happens when metadata-complete is true since one
>> might expect that fragment ordering is irrelevant in that case.
>>
>> The clarification is that regardless of metadata-complete (true or
>> false) if an absolute ordering is present then JARs excluded from the
>> absolute ordered are not scanned for classes that match HandlesTypes.
>>
>> Since there is no way to disable the scanning for SCIs, the
>> clarification is a good thing since it means that you can at least
>> disable the potentially very expensive scanning of every single class in
>> the application (and it's full class hierarchy) checking for
>> HandlesTypes matches. For large applications that don't want the SCIs to
>> handle any classes this can result in a significant time saving on start up.
>>
>> Mark
>>
>