深入Jetty源码之Servlet框架及实现(Servlet、Filter、Registration)

public  interface Servlet {
     // Servlet Container在创建一个Servlet后调用该方法，并传入ServletConfig实例，从而用户可以在这个方法中做一些自定义的初始化工作，如初始化数据库连接等。
    // 并且Servlet Container可以保证一个Servlet实例init方法之后被调用一次，但是对一个Servlet类init方法可能会被多次调用，因而有些Servlet Container可能会在某些情况下将某些
    // Servlet移出Servlet Container，而后又重新加载这些Servlet，如为了在处理Servlet Container资源压力比较大的情况下。
     public  void init(ServletConfig config)  throws ServletException;

     // 返回在init方法中传入的ServletConfig实例。ServletConfig包含了在web.xml配置文件中配置当前Servlet的初始化参数，并且可以使用该ServletConfig实例获取当前ServletContext实例。
     public ServletConfig getServletConfig();
    
     // 当该Servlet对应的请求到来时，Servlet Container会调用这个Servlet的service方法，用于处理请求，并将相应写入ServletResponse参数中，该方法只能在init方法完成后被调用。
    // 在service方法中，可以选择使用ServletResponse定义的方法返回响应给客户端，或只是向ServletResponse中写入响应，最终由Servlet Container根据ServletResponse的信息将响应返回给客户端。
    // 很多情况下，Servlet Container都不会使用多线程来处理客户请求，应该该方法会在多线程环境下被使用，Servlet实现者可以实现SingleThreadMode接口以强制该方法只在单线程的环境下被使用。
    // 但是SingleThreadMode接口已经在Servlet 2.3中被废弃，实现该接口也会影响Servlet的执行性能，而且有些Servlet Container会选择实例或多个Servlet实例，以保证对请求的响应性能，因而此时依然不能保证该方法的单线程特性，因而不建议使用这个SingleThreadMode接口。
     public  void service(ServletRequest req, ServletResponse res)  throws ServletException, IOException;
    
     // 返回当前Servlet的描述信息，如作者、版本号、版权等。在GenericServlet默认实现中，返回空字符串。
     public String getServletInfo();

     // 当Servlet Container销毁当前Servlet时会调用该方法，从而给Servlet提供拥有清理当前Servlet占用的资源的地方，如关闭和数据库的连接等。
    // Servlet Container会保证该方法在所有执行service方法的线程完成或超时后被调用。Servlet Container一般会在三种情况下会调用该方法：
    // 1. Servlet Container当前资源比较紧张，需要将一些不再用或不常用的Servlet移出；2. 实现某些Servlet的热部署；3. 当前Web Application被停止。
     public  void destroy();
}

public  interface ServletConfig {
     // 返回该ServletConfig对应的Servlet的名称，在web.xml文件中定义的Servlet名称或对于没有注册的Servlet为其类名。
     public String getServletName();

     // 返回和其关联的ServletContext。
     public ServletContext getServletContext();
    
     // 返回在web.xml配置文件中定义或者使用ServletRegistration动态定义添加的init-param参数。
     public String getInitParameter(String name);
     public Enumeration<String> getInitParameterNames();
}

public  interface Filter {
     // 由ServletContainer在初始化一个Filter时调用，Filter的实现者可以在该方法中添加一些用户自定义的初始化逻辑，同时可以保存FilterConfig实例，它可以获取定义的init-param初始化参数以及获取ServletContext实例。其他情况和Servlet类似，不赘述。
     public  void init(FilterConfig filterConfig)  throws ServletException;
    
     // 每一次请求到来都会穿越配置的FilterChain，执行配置的Servlet，然后从这个FilterChain中返回。在doFilter方法的实现中，要调用下一个Filter，使用FilterChain的doFilter方法。
    // 在调用FilterChain的doFilter之前为执行请求之前的处理，而之后为请求已经执行完成，在响应返回的路上的逻辑处理。也可以步调用FilterChain的doFilter方法，以阻止请求的进一步处理。
     public  void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
             throws IOException, ServletException;

     // 在Filter被移出Servlet Container时调用，它和Servlet类似，不赘述。**
     public  void destroy();
}

public  interface FilterConfig {
     public String getFilterName();
     public ServletContext getServletContext();
     public String getInitParameter(String name);
     public Enumeration<String> getInitParameterNames();
}

public  interface FilterChain {
     // 调用该方法会调用Filter链中的下一个Filter的doFilter方法，如果当前Filter是这条链中的最后一个Filter，则该方法会调用响应的Servlet的service方法。
     public  void doFilter (ServletRequest request, ServletResponse response)  throws IOException, ServletException;
}

public  interface Registration {
     // 返回这个Registration实例关联的Servlet或Filter的Name，这个Name在向ServletContext注册Servlet或Filter时给定。
     public String getName();

     // 返回这个Registration实例关联的Servlet或Filter的类名。
     public String getClassName();

     // 和这个Registration实例关联的初始化参数的操作。
     public  boolean setInitParameter(String name, String value);
     public String getInitParameter(String name);
     public Set<String> setInitParameters(Map<String, String> initParameters);
     public Map<String, String> getInitParameters();

     interface Dynamic  extends Registration {
         // 配置Registration关联的Servlet或Filter是否支持异步操作。
         public  void setAsyncSupported( boolean isAsyncSupported);
    }
}

public  interface ServletRegistration  extends Registration {
     // 添加URL patterns到这个ServletRegistration关联的Servlet的映射。如果有任意的URL patterns已经映射到其他的Servlet中，则该方法不会执行任何行为。
     public Set<String> addMapping(String... urlPatterns);

     // 获取所有到当前ServletRegistration对应的Servlet的URL patterns。
     public Collection<String> getMappings();

     // 获取当前ServletRegistration对应的Servlet的RunAsRole。
     public String getRunAsRole();

     interface Dynamic  extends ServletRegistration, Registration.Dynamic {
         // 设置当前ServletRegistration对应的Servlet的loadOnStartup等级。如果loadOnStartup大于或等于0，表示Servlet Container要优先初始化该Servlet，
        // 此时Servlet Container要在Container初始化时实例化并初始化该Servlet，即在所有注册的ContextListener的contextInitialized方法调用完成后。
        // 如果loadOnStartup小于0，则表示这个Servlet可以在用到的时候实例化并初始化。默认值为-1。
         public  void setLoadOnStartup( int loadOnStartup);

         // 设置ServletRegistration相关的ServletSecurityElement属性。
         public Set<String> setServletSecurity(ServletSecurityElement constraint);

         // 设置ServletRegistration对应的Servlet的MultipartConfigElement属性。
         public  void setMultipartConfig(MultipartConfigElement multipartConfig);

         // 设置ServletRegistration对应的Servlet的RunAsRole属性。
         public  void setRunAsRole(String roleName);
    }
}

public  interface FilterRegistration  extends Registration {
     // 添加FilterRegistration关联的Filter到Servlet的映射，使用Servlet Name、DispatcherType作为映射。isMatchAfter表示新添加的Mapping是在已有的Mapping之前还是之后。
     public  void addMappingForServletNames(EnumSet<DispatcherType> dispatcherTypes,  boolean isMatchAfter, String... servletNames);

     // 获取当前FilterRegistration关联的Filter已存在的到Servlet Name的映射。
     public Collection<String> getServletNameMappings();

     // 添加FilterRegistration关联的Filter到Servlet的映射，使用URL patterns、DispatcherType作为映射。isMatchAfter表示新添加的Mapping是在已有的Mapping之前还是之后。
     public  void addMappingForUrlPatterns(EnumSet<DispatcherType> dispatcherTypes,  boolean isMatchAfter, String... urlPatterns);

     // 获取当前FilterRegistration关联的Filter已存在的到URL patterns的映射。
     public Collection<String> getUrlPatternMappings();

     interface Dynamic  extends FilterRegistration, Registration.Dynamic {
    }
}

     public  enum Source { EMBEDDED, JAVAX_API, DESCRIPTOR, ANNOTATION };
     final  private Source _source;
     protected  transient Class<?  extends T> _class;
     protected  final Map<String,String> _initParams= new HashMap<String,String>(3);
     protected String _className;
     protected String _displayName;
     protected  boolean _extInstance;
     protected  boolean _asyncSupported= true;
     protected String _name;
     protected ServletHandler _servletHandler;

     private  transient Filter _filter;
     private  transient Config _config;
     private  transient FilterRegistration.Dynamic _registration;

     private  int _dispatches=DEFAULT;
     private String _filterName;
     private  transient FilterHolder _holder;
     private String[] _pathSpecs;
     private String[] _servletNames;

     boolean appliesTo( int type) {
         if (_dispatches==0)
             return type==REQUEST || type==ASYNC && _holder.isAsyncSupported();
         return (_dispatches&type)!=0;
    }

     private  int _initOrder;
     private  boolean _initOnStartup= false;
     private Map<String, String> _roleMap;
     private String _forcedPath;
     private String _runAsRole;
     private RunAsToken _runAsToken;
     private IdentityService _identityService;
     private ServletRegistration.Dynamic _registration;
     private  transient Servlet _servlet;
     private  transient Config _config;
     private  transient  long _unavailable;
     private  transient UnavailableException _unavailableEx;
     public  static  final Map<String,String> NO_MAPPED_ROLES = Collections.emptyMap();

     private String[] _pathSpecs;
     private String _servletName;