Forwarding this response from janb_at_webtide.com:
It is an excellent idea to clarify the text, as I often find users are
confused about when and why scanning would take place.
During the discussion in the jar for Servlet 3.0, we evolved the
distinction between "introspected" and "discovered" anntotations and I
think this distinction is helpful to understanding what is going on.
Suggested text for Section 8.1:
Annotations can be categorized as "discovered" or "introspected".
Discovered annotations are: @WebServlet, @WebFilter and @WebListener and
the web container must scan class files to find them. Other annotations
covered by this specification as detailed in section 15.5 and including
@HandlesTypes are introspectable, meaning that the web container may find
them by introspecting the annotated class.
In a web application, classes using discovered and introspected annotations
will have their annotations processed only if they are located in the
WEB-INF/classes directory, or if they are packaged in a jar file located in
WEB-INF/lib within the application.
The web application deployment descriptor contains the “metadata-complete”
attribute on the web-app element. 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 discovered annotations, and scan for web
fragments. If “metadata-complete” is set to "true", the deployment tool
will ignore all discoverable annotations and web fragments, although class
scanning may still take place if there is one or more
javax.servlet.ServletContainerInitializers on the classpath with non-empty
@HandlesTypes annotations. The value of "metadata-complete" has no effect
on introspected annotations which are always processed.
regards
Jan
On 29 September 2015 at 03:10, Shing Wai Chan <shing.wai.chan_at_oracle.com>
wrote:
> Then I will add the following before the previous paragraph:
>
> -----
> The following are the annotations in javax.servlet. All of these have
> corresponding deployment descriptor metadata covered by the Web xsd.
>
> from javax.servlet.annotation:
> HttpConstraint
> HttpMethodConstraint
> MultipartConfig
> ServletSecurity
> WebFilter
> WebInitParam
> WebListener
> WebServlet
>
> The following annotations from related packages are also covered
> by the Web descriptor.
>
> from javax.annotation.*
> PostConstruct
> PreDestroy
> Resource
> Resources
> DeclareRoles
> RunAs
> DataSourceDefinition
> DataSourceDefinitions
>
> from javax.jms:
> JMSConnectionFactory
> JMSConnectionFactoryDefinition
> JMSConnectionFactoryDefinitions
> JMSDestinationDefinition
> JMSDestinationDefinitions
>
> from javax.mail:
> MailSessionDefinition
> MailSessionDefinitions
>
> from javax.interceptor:
> AroundConstruct
> AroundInvoke
> AroundTimeout
> ExcludeClassInterceptors
> ExcludeDefaultInterceptors
> Interceptors
>
> from javax.jws:
> WebService
> WebMethod
>
> from javax.persistence:
> PersistenceContext
> PersistenceContexts
> PersistenceUnit
> PersistenceUnits
>
>
> from javax.resource:
> AdministeredObjectDefinition
> AdministeredObjectDefinitions
> ConnectionFactoryDefinition
> ConnectionFactoryDefinitions
>
> from javax.xml.ws:
> WebServiceRef
> WebServiceRefs
>
> -----
>
> Shing Wai Chan
>
>
> On 9/25/15, 1:37 PM, Mark Thomas wrote:
>
>> On 25/09/2015 19:04, Shing Wai Chan wrote:
>>
>>> Since there are some confusion of precise meaning of metadata-complete =
>>> true
>>> with regard to annotation scanning, we would like to made clearer in our
>>> spec what
>>> it means.
>>>
>>> I propose to add the following clarification in Section 8.1 of Servlet
>>> spec:
>>> -----
>>> Annotations that do not have equivalents in the deployment XSD include
>>> javax.annotation.annotation.HandlesTypes and all of the CDI-related
>>> annotations,
>>> and must be processed during annotation scanning.
>>> -----
>>>
>>> Please let me know if you see any problems.
>>>
>> Might it be clearer if we explicitly listed all the annotations that are
>> to be ignored if metadata-complete = true ?
>>
>> Mark
>>
>>
--
Greg Wilkins <gregw@webtide.com> CTO http://webtide.com