Can someone tell me, what DispatcherType is doing?

Seems to be an important configuration.

Class usage didn't helped me as well by pointing to things suc开发者_如何转开发h as ServletContextHandler#addFilter, which is "documented" with the wise words: convenience method to add a filter.

In general, any chance to "understand" the undocumented Jetty API without code-example-search-fun or try-and-fail-and-wonder?

This is also a setting in web.xml; and probably has been in existence for quite some time.

http://download.oracle.com/docs/cd/B32110_01/web.1013/b28959/filters.htm#BCFIEDGB

Configuring Filters for Forward or Include Targets

This section provides a few sample configurations to have a filter act on forward or include targets. We start with the filter declaration, followed by alternative filter mapping configurations:

<filter>
    <filter-name>myfilter</filter-name>
    <filter-class>mypackage.MyFilter</filter-class>
</filter>

To execute MyFilter to filter an include target named includedservlet:

<filter-mapping>
   <filter-name>myfilter</filter-name>
   <servlet-name>includedservlet</servlet-name>
   <dispatcher>INCLUDE</dispatcher>
</filter-mapping>

Note that the include() call can come from any servlet (or other resource) in the application. Also note that MyFilter would not execute for a direct request of includedservlet, unless you have another element with the value REQUEST.

To execute MyFilter to filter any servlet directly requested through a URL pattern "/mypath/", or to execute it to filter any forward target that is invoked through a URL pattern starting with "/mypath/":

<filter-mapping>
   <filter-name>myfilter</filter-name>
   <url-pattern>/mypath/*</url-pattern>
   <dispatcher>FORWARD</dispatcher>
   <dispatcher>REQUEST</dispatcher>
</filter-mapping>

~~~~~~~~~~~~~~~~~~~~~~

Also, the default is Request; read appliesTo(...) method on following page:

http://grepcode.com/file/repo1.maven.org/maven2/org.eclipse.jetty/jetty-servlet/8.0.0.M0/org/eclipse/jetty/servlet/FilterMapping.java#FilterMapping.0_dispatches

Adding to Asad's answer, the dispatcher isn't Jetty specific, it's part of the servlet specification up to version 2.5. Here is the the official description for the dispatcher values from web-app_2_5.xsd:

<xsd:complexType name="dispatcherType">
    <xsd:annotation>
        <xsd:documentation>

The dispatcher has four legal values: FORWARD, REQUEST, INCLUDE,
and ERROR. A value of FORWARD means the Filter will be applied
under RequestDispatcher.forward() calls.  A value of REQUEST
means the Filter will be applied under ordinary client calls to
the path or servlet. A value of INCLUDE means the Filter will be
applied under RequestDispatcher.include() calls.  A value of
ERROR means the Filter will be applied under the error page
mechanism.  The absence of any dispatcher elements in a
filter-mapping indicates a default of applying filters only under
ordinary client calls to the path or servlet.

        </xsd:documentation>
    </xsd:annotation>

    <xsd:simpleContent>
        <xsd:restriction base="javaee:string">
            <xsd:enumeration value="FORWARD"/>
            <xsd:enumeration value="INCLUDE"/>
            <xsd:enumeration value="REQUEST"/>
            <xsd:enumeration value="ERROR"/>
        </xsd:restriction>
    </xsd:simpleContent>
</xsd:complexType>