Package org.spincast.core.server

Interface Server

All Known Implementing Classes:
SpincastUndertowServer
public interface Server
The interface a HTTP server implementation must implement.

The "exchange" object is a request scoped object provided by the HTTP server to identify the request.

A Server implementation has to receive FrontController as a dependency and call handle(...) on it when a new request is made.

Note that the server will automatically remove any cache buster codes from the request's path.

  • Method Details

    • start

      void start()
      Starts the server.

    • stop

      void stop()
      Stops the server

      Will try to send a "closing" message to any WebSocket peer before closing their connections.

    • stop

      void stop(boolean sendClosingMessageToPeers)
      Stops the server
      Parameters:
      sendClosingMessageToPeers - if true, Spincast will try to send a "closing" message to any WebSocket peer before closing their connections.

    • isRunning

      boolean isRunning()
      Is this server running (started)?

    • addStaticResourceToServe

      void addStaticResourceToServe(StaticResource<?> staticResource)
      Adds a static resource to serve directly by the server.

    • removeStaticResourcesServed

      void removeStaticResourcesServed(StaticResourceType staticResourceType, String urlPath)
      Removes a static resource served directly by the server.

    • removeAllStaticResourcesServed

      void removeAllStaticResourcesServed()
      Removes all static resources served directly by the server.

    • getStaticResourceServed

      StaticResource<?> getStaticResourceServed(String urlPath)
      Gets a static resource served directly by the server, using its path.

    • getStaticResourcesServed

      Set<StaticResource<?>> getStaticResourcesServed()
      Gets all static resource served directly by the server.

    • getHttpMethod

      HttpMethod getHttpMethod(Object exchange)
      Gets the HTTP method associated with the request.

    • getFullUrlOriginal

      String getFullUrlOriginal(Object exchange)
      The full encoded URL of the original, non proxied, request, including the queryString. Cache buster codes are removed, if there were any.

      This is going to be the *original* URL, as seen by the user, even if a reverse proxy is used (such as Nginx or Apache).

      Even if the request is forwarded elsewhere in the framework, this URL won't change, it will still be the original one.

    • getFullUrlOriginal

      String getFullUrlOriginal(Object exchange, boolean keepCacheBusters)
      The full encoded URL of the original, non proxied, request, including the queryString.

      This is going to be the *original* URL, as seen by the user, even if a reverse proxy is used (such as Nginx or Apache).

      Even if the request is forwarded elsewhere in the framework, this URL won't change, it will still be the original one.

      Parameters:
      keepCacheBusters - if true, the returned URL will contain the cache buster codes, if there were any. The default behavior is to automatically remove them.

    • getFullUrlProxied

      String getFullUrlProxied(Object exchange)
      The full encoded URL of the potentially proxied request, including the queryString. Cache buster codes are removed, if there were any.

      Is a reverse proxy is used (such as Nginx or Apache), this is going to be the proxied URL, as forwarded by the reverse proxy. If no reverse proxy is used, this is going to be the original URL, as seen by the user.

      Even if the request is forwarded elsewhere in the framework, this URL won't change, it will still be the original one.

    • getFullUrlProxied

      String getFullUrlProxied(Object exchange, boolean keepCacheBusters)
      The full encoded URL of the potentially proxied request, including the queryString.

      Is a reverse proxy is used (such as Nginx or Apache), this is going to be the proxied URL, as forwarded by the reverse proxy. If no reverse proxy is used, this is going to be the original URL, as seen by the user.

      Even if the request is forwarded elsewhere in the framework, this URL won't change, it will still be the original one.

      Parameters:
      keepCacheBusters - if true, the returned URL will contain the cache buster codes, if there were any. The default behavior is to automatically remove them.

    • getContentTypeBestMatch

      ContentTypeDefaults getContentTypeBestMatch(Object exchange)
      Gets the best Content-Type to use for the current request.

    • setResponseHeaders

      void setResponseHeaders(Object exchange, Map<String,List<String>> headers)
      Sets the response headers. Override any existing ones.

    • setResponseHeader

      void setResponseHeader(Object exchange, String name, List<String> values)
      Sets a response header. Override any existing one with the same name.

    • getResponseHeaders

      Map<String,List<String>> getResponseHeaders(Object exchange)
      Gets the response headers.

    • removeResponseHeader

      void removeResponseHeader(Object exchange, String name)
      Removes a response header.

    • addCookies

      void addCookies(Object exchange, Map<String,Cookie> cookies)
      Adds cookies.

    • getCookies

      Map<String,String> getCookies(Object exchange)
      Gets the request cookies values.

    • getQueryStringParams

      Map<String,List<String>> getQueryStringParams(Object exchange)
      Gets the queryString parameters.

    • setResponseStatusCode

      void setResponseStatusCode(Object exchange, int statusCode)
      Sets the response status code.

    • flushBytes

      void flushBytes(Object exchange, byte[] bytes, boolean end)
      Flushes some bytes to the response.
      Parameters:
      end - if true, the exchange will be closed and nothing more can be send.

    • end

      void end(Object exchange)
      Ends the exchange. Nothing more can be send.

    • isResponseClosed

      boolean isResponseClosed(Object exchange)
      Is the response closed?

    • isResponseHeadersSent

      boolean isResponseHeadersSent(Object exchange)
      Are the response headers sent?

    • getRequestScheme

      String getRequestScheme(Object exchange)
      Gets the request scheme, "http" for example.

    • getRawInputStream

      InputStream getRawInputStream(Object exchange)
      The raw InputStream of the current request.

    • getFormData

      Map<String,List<String>> getFormData(Object exchange)
      The form data, if any.

    • getUploadedFiles

      Map<String,List<UploadedFile>> getUploadedFiles(Object exchange)
      The uploaded files, if any. The key of the map if the HTML's name attribute.

    • forceRequestSizeValidation

      boolean forceRequestSizeValidation(Object exchange)
      Is the request size valid?

    • getRequestHeaders

      Map<String,List<String>> getRequestHeaders(Object exchange)
      The headers from the request. The keys will be case insensitive.

    • createHttpAuthenticationRealm

      void createHttpAuthenticationRealm(String pathPrefix, String realmName)
      Creates HTTP authentication protection (realm) for the specified path prefix.
      Parameters:
      realmName - The name of the realm. Must be unique on this server, otherwise an exception is thrown. This allows the application to add user to the realm using its name.

    • getHttpAuthenticationRealms

      Map<String,String> getHttpAuthenticationRealms()
      Returns the existing HTTP authentication realms, the key being the realm's name and the value being the prefix path associated to this realm.

      The map is immutable.

    • addHttpAuthentication

      void addHttpAuthentication(String realmName, String username, String password)
      Adds a user to an HTTP protected realm.

    • removeHttpAuthentication

      void removeHttpAuthentication(String username, String realmName)
      Removes a user to an HTTP protected realm.

    • removeHttpAuthentication

      void removeHttpAuthentication(String username)
      Removes a user from all HTTP protected realms.

    • websocketCreateEndpoint

      WebsocketEndpointManager websocketCreateEndpoint(String endpointId, WebsocketEndpointHandler endpointHandler)
      Creates a new Websocket endpoint.
      Returns:
      the manager for this endpoint.

    • websocketCloseEndpoint

      void websocketCloseEndpoint(String endpointId)
      Closes a Websocket endpoint. No more connections will be accepter

    • websocketCloseEndpoint

      void websocketCloseEndpoint(String endpointId, int closingCode, String closingReason)
      Closes the entire Websocket endpoint. All peer connections of this endpoint will be closed.
      Parameters:
      closingCode - The closing code.
      closingReason - The closing reason.

    • websocketConnection

      void websocketConnection(Object exchange, String endpointId, String peerId)
      Transforms the request to a peer Websocket connection on the endpoint 'endpointId'.

    • getWebsocketEndpointManagers

      List<WebsocketEndpointManager> getWebsocketEndpointManagers()
      Returns the managers of the existing Websockets endpoints.

    • getWebsocketEndpointManager

      WebsocketEndpointManager getWebsocketEndpointManager(String endpointId)
      Returns the manager for a Websockets endpoint.
      Returns:
      the manager or null if not found.

    • getIp

      String getIp(Object exchange)
      Gets the IP of the current request.

    • push

      void push(Object exchange, Set<ResourceToPush> resourcesToPush)
      If HTTP/2 is used, you can push extra resources at the same time you response to a request.

      If the embedded server deals with a HTTTP/2 request, it will push the extra resources by itself. If it deals with an HTTP/1.X request (for example if it is behind a reverse-proxy) it will send Link headers to the potential proxy in front of it and it is the proxy that will be in charge of doing the actual push.

      Beware that pushing resources does not always result in an increase of performance and may lead to wasted bandwidth (the client may decide to not use the pushed resources).