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 issue http://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
>