Module jdk.httpserver
Package com.sun.net.httpserver

Class HttpServer

java.lang.Object
com.sun.net.httpserver.HttpServer
直接已知的子类:
HttpsServer
public abstract class HttpServer extends Object
这个类实现了一个简单的HTTP服务器。一个HttpServer绑定到一个IP地址和端口号，并监听来自该地址的客户端的传入TCP连接。子类HttpsServer实现了一个处理HTTPS请求的服务器。

一个或多个HttpHandler对象必须与服务器关联，以便处理请求。每个这样的HttpHandler都注册了一个根URI路径，该路径表示应用程序或服务在此服务器上的位置。将处理程序映射到HttpServer由HttpContext对象封装。通过调用createContext(String,HttpHandler)来创建HttpContext。任何找不到处理程序的请求都将被拒绝，并返回404响应。可以通过提供一个Executor对象来外部管理线程。如果未提供，则使用默认实现。

将请求URI映射到HttpContext路径

当收到HTTP请求时，通过找到路径最长匹配前缀的上下文（和处理程序）来定位适当的HttpContext。路径是按字面匹配的，这意味着字符串是区分大小写的，并且没有转换为或从任何编码形式转换。例如，给定以下HttpContext配置的HttpServer：

描述
上下文 上下文路径
ctx1 "/"
ctx2 "/apps/"
ctx3 "/apps/foo/"

以下表格显示了一些请求URI及其可能匹配的上下文：

描述
请求URI 匹配的上下文
"http://foo.com/apps/foo/bar" ctx3
"http://foo.com/apps/Foo/bar" 无匹配，大小写错误
"http://foo.com/apps/app1" ctx2
"http://foo.com/foo" ctx1

关于套接字积压的注意事项

当绑定到地址和端口号时，应用程序还可以指定一个整数backlog参数。这表示系统将在内部排队的最大传入TCP连接数。连接在等待被HttpServer接受时会被排队。当达到限制时，进一步的连接可能会被底层TCP实现拒绝（或可能被忽略）。设置正确的backlog值是在TCP层中有效资源使用和允许足够的传入请求吞吐量之间的折衷（不要设置得太高，也不要设置得太低）。

自从:
1.6

  • Constructor Details

    • HttpServer

      protected HttpServer()
      子类调用的构造函数。

  • Method Details

    • create

      public static HttpServer create() throws IOException
      创建一个最初未绑定到任何本地地址/端口的HttpServer实例。该HttpServer是从当前安装的HttpServerProvider中获取的。在使用之前，必须使用bind(InetSocketAddress,int)将服务器绑定。
      返回:
      HttpServer的一个实例
      抛出:
      IOException - 如果发生I/O错误

    • create

      public static HttpServer create(InetSocketAddress addr, int backlog) throws IOException
      创建一个将绑定到指定InetSocketAddress（IP地址和端口号）的HttpServer实例。还可以指定最大积压。这是允许在监听套接字上排队的最大挂起连接数。超过此限制的排队TCP连接可能会被TCP实现拒绝。HttpServer是从当前安装的HttpServerProvider中获取的。
      参数:
      addr - 要监听的地址，如果为null，则必须调用bind(InetSocketAddress, int)来设置地址
      backlog - 套接字积压。如果此值小于或等于零，则使用系统默认值
      返回:
      HttpServer的一个实例
      抛出:
      IOException - 如果发生I/O错误
      BindException - 如果服务器无法绑定到请求的地址，或者服务器已经绑定

    • create

      public static HttpServer create(InetSocketAddress addr, int backlog, String path, HttpHandler handler, Filter... filters) throws IOException
      创建一个带有初始上下文的HttpServer实例。

      服务器创建时带有一个将URI path映射到交换handler的初始上下文。初始上下文的创建就像通过调用createContext(path)一样。如果有任何filters，则按给定的顺序将其添加到初始上下文中。返回的服务器未启动，因此可以根据需要进一步配置。

      服务器实例将绑定到给定的InetSocketAddress。

      还可以指定最大积压。这是允许在监听套接字上排队的最大挂起连接数。超过此限制的排队TCP连接可能会被TCP实现拒绝。HttpServer是从当前安装的HttpServerProvider中获取的。

      参数:
      addr - 要监听的地址，如果null，则必须调用bind来设置地址
      backlog - 套接字积压。如果此值小于或等于零，则使用系统默认值
      path - 上下文的根URI路径，必须是绝对的
      handler - 上下文的HttpHandler
      filters - 上下文的Filters，可选
      返回:
      HttpServer
      抛出:
      BindException - 如果服务器无法绑定到地址
      IOException - 如果发生I/O错误
      IllegalArgumentException - 如果路径无效
      NullPointerException - 如果任何一个：path，handler，filters，或filters的任何元素为null
      自从:
      18

    • bind

      public abstract void bind(InetSocketAddress addr, int backlog) throws IOException
      将当前未绑定的HttpServer绑定到给定的地址和端口号。还可以指定最大积压。这是允许在监听套接字上排队的最大挂起连接数。超过此限制的排队TCP连接可能会被TCP实现拒绝。
      参数:
      addr - 要监听的地址
      backlog - 套接字积压。如果此值小于或等于零，则使用系统默认值
      抛出:
      BindException - 如果服务器无法绑定到请求的地址，或者服务器已经绑定
      NullPointerException - 如果addr为null
      IOException

    • start

      public abstract void start()
      在新的后台线程中启动此服务器。后台线程继承调用者的优先级、线程组和上下文类加载器。

    • setExecutor

      public abstract void setExecutor(Executor executor)
      设置此服务器的Executor对象。在调用start()之前必须建立一个Executor。所有HTTP请求都将在交给执行器的任务中处理。如果未调用此方法（在调用start()之前）或者使用null Executor调用此方法，则将使用默认实现，该实现使用由start()方法创建的线程。
      参数:
      executor - 要设置的Executor，或者使用null表示默认实现
      抛出:
      IllegalStateException - 如果服务器已经启动

    • getExecutor

      public abstract Executor getExecutor()
      如果使用setExecutor(Executor)指定了此服务器的Executor对象，则返回该对象；如果未指定，则返回null。
      返回:
      为此服务器建立的Executor对象，如果未设置则返回null。

    • stop

      public abstract void stop(int delay)
      通过关闭监听套接字并禁止处理任何新交换来停止此服务器。然后，该方法将阻塞，直到所有当前交换处理程序完成，或者大约delay秒已经过去（以先到者为准）。然后，关闭所有打开的TCP连接，由start()创建的后台线程退出，并返回方法。一旦停止，HttpServer将无法重新使用。
      参数:
      delay - 等待交换完成的最长时间（以秒为单位）
      抛出:
      IllegalArgumentException - 如果延迟小于零

    • createContext

      public abstract HttpContext createContext(String path, HttpHandler handler)
      创建一个HttpContext。一个HttpContext表示从URI路径到此HttpServer上的交换处理程序的映射。一旦创建，服务器接收到的所有针对该路径的请求都将通过调用给定的处理程序对象来处理。上下文由路径标识，并且可以稍后使用removeContext(String)方法从服务器中删除。

      路径指定此上下文的根URI路径。路径的第一个字符必须是'/'。

      类概述描述了如何将传入请求URI映射到HttpContext实例。

      API 注意:
      路径通常应该以'/'结尾，但不是必需的。如果路径不以'/'结尾，例如"/foo"，那么这将匹配路径为"/foobar"或"/foo/bar"的请求。
      参数:
      path - 要将上下文与关联的根URI路径
      handler - 用于处理传入请求的处理程序
      返回:
      HttpContext的实例
      抛出:
      IllegalArgumentException - 如果路径无效，或者如果此路径已存在上下文
      NullPointerException - 如果路径或处理程序为null

    • createContext

      public abstract HttpContext createContext(String path)
      创建一个没有初始指定处理程序的HttpContext。稍后必须使用HttpContext.setHandler(HttpHandler)指定处理程序。一个HttpContext表示从URI路径到此HttpServer上的交换处理程序的映射。一旦创建，并且处理程序已设置，服务器接收到的所有针对该路径的请求都将通过调用处理程序对象来处理。上下文由路径标识，并且可以稍后使用removeContext(String)方法从服务器中删除。

      路径指定此上下文的根URI路径。路径的第一个字符必须是'/'。

      类概述描述了如何将传入请求URI映射到HttpContext实例。

      API 注意:
      路径通常应该以'/'结尾，但不是必需的。如果路径不以'/'结尾，例如"/foo"，那么这将匹配路径为"/foobar"或"/foo/bar"的请求。
      参数:
      path - 要将上下文与关联的根URI路径
      返回:
      HttpContext的实例
      抛出:
      IllegalArgumentException - 如果路径无效，或者如果此路径已存在上下文
      NullPointerException - 如果路径为null

    • removeContext

      public abstract void removeContext(String path) throws IllegalArgumentException
      从服务器中删除由给定路径标识的上下文。删除上下文不会影响当前正在处理的交换，但会阻止接受新的交换。
      参数:
      path - 要删除的处理程序的路径
      抛出:
      IllegalArgumentException - 如果没有与此路径对应的处理程序。
      NullPointerException - 如果路径为null

    • removeContext

      public abstract void removeContext(HttpContext context)
      从服务器中删除给定的上下文。删除上下文不会影响当前正在处理的交换，但会阻止接受新的交换。
      参数:
      context - 要删除的上下文
      抛出:
      NullPointerException - 如果上下文为null

    • getAddress

      public abstract InetSocketAddress getAddress()
      返回此服务器正在侦听的地址
      返回:
      服务器正在侦听的InetSocketAddress