From the 2nd Public Draft:
"In addition to the ServletContainerInitializer we also have an annotation -
HandlesTypes. The HandlesTypes annotation on the implementation of the
ServletContainerInitializer is used to express interest in classes that may
have anotations (type, method or field level annotations) specified in the value of the
HandlesTypes or if it extends / implements one those classes anywhere in the
class' super types. The HandlesTypes annotation is applied irrespective of the
setting of metadata-complete. The container uses the HandlesTypes annotation
to determine when to invoke the initializer's onStartup method."
Having or not having a @HandlesTypes annotation does not influence when the onStartup method is called at all AFAICT - later on the spec says that the the onStartup method is always called when the application is starting up.
"When examining the classes of an application to see if they match any of the criteria specified by the
HandlesTypes annotation of a ServletContainerInitializer, the container
may run into class loading problems if one or more of the application's optional JAR
files are missing. Since the container is not in a position to decide whether these
types of class loading failures will prevent the application from working correctly, it
must ignore them, while at the same time providing a configuration option that
would log them."
This sentence doesn't fit very well with the preceding one, which is talking about when the onStartup method is called. Mention of potential problems in loading the classes of the HandlesTypes, and a requirement for logging should be in a separate paragraph.
"The onStartup method of the ServletContainerInitializer will be invoked
when the application is coming up before any of the listener's events are fired."
Which listener are we talking about here? A listener has not been previously mentioned in this section at all. Is it supposed to say "any of the ServletContextListener events are fired" ????
"The ServletContainerInitializer's onStartup method get's a Set of Classes
that either extend / implement the classes that the initializer expressed interest in or
if it is annotated with any of the classes specified via the @HandlesTypes
Should this be: " ... onStartup method gets called with a Set of classes ..."? Or even better " ... onStartup method is called with a Set of classes ..."
IMHO section 8.2.4 does not flow very cleanly and could do with a rewrite.