Minimal doc on spi API

jknack · jknack · commit dd627efa7dea · 2015-03-04T14:56:35.000-03:00
diff --git a/jooby/src/main/java/org/jooby/spi/NativeRequest.java b/jooby/src/main/java/org/jooby/spi/NativeRequest.java
@@ -34,36 +34,113 @@
  */
 public interface NativeRequest {
   /**
-   * @return Http method.
+   * @return The name of the HTTP method with which this request was made, for example, GET, POST,
+   *         or PUT.
    */
   String method();
 
+  /**
+   * @return The part of this request's URL from the protocol
+   *         name up to the query string in the first line of the HTTP request
+   */
   String path();
 
+  /**
+   * @return List with all the parameter names from query string plus any other form/multipart param
+   *         names (excluding file uploads). This method should NOT returns null, absence of params
+   *         is represented by an empty list.
+   * @throws Exception If param extraction fails.
+   */
   List<String> paramNames() throws Exception;
 
+  /**
+   * Get all the params for the provided name or a empty list.
+   *
+   * @param name Parameter name.
+   * @return Get all the params for the provided name or a empty list.
+   * @throws Exception If param parsing fails.
+   */
   List<String> params(String name) throws Exception;
 
+  /**
+   * Get all the headers for the provided name or a empty list.
+   *
+   * @param name Header name.
+   * @return Get all the headers for the provided name or a empty list.
+   */
   List<String> headers(String name);
 
-  Optional<String> header(String name);
+  /**
+   * Get the first header for the provided name or a empty list.
+   *
+   * @param name Header name.
+   * @return The first header for the provided name or a empty list.
+   */
+  default Optional<String> header(final String name) {
+    List<String> headers = headers(name);
+    return headers.size() == 0 ? Optional.empty() : Optional.of(headers.get(0));
+  }
 
+  /**
+   * @return All the header names or an empty list.
+   */
   List<String> headerNames();
 
+  /**
+   * @return All the cookies or an empty list.
+   */
   List<Cookie> cookies();
 
+  /**
+   * Get all the files for the provided name or an empty list.
+   *
+   * @param name File name.
+   * @return All the files or an empty list.
+   * @throws IOException If file parsing fails.
+   */
   List<NativeUpload> files(String name) throws IOException;
 
+  /**
+   * Input stream that represent the body.
+   *
+   * @return Body as an input stream.
+   * @throws IOException If body read fails.
+   */
   InputStream in() throws IOException;
 
+  /**
+   * @return The IP address of the client or last proxy that sent the request.
+   */
   String ip();
 
+  /**
+   * The fully qualified name of the client or the last proxy that sent the request.
+   * If the engine cannot or chooses not to resolve the hostname (to improve performance),
+   * this method returns the dotted-string form of the IP address
+   *
+   * @return The fully qualified name of the client or the last proxy that sent the request.
+   */
   String hostname();
 
+  /**
+   * @return The name and version of the protocol the request uses in the form
+   *         <i>protocol/majorVersion.minorVersion</i>, for example, HTTP/1.1
+   */
   String protocol();
 
+  /**
+   * @return True if this request was made using a secure channel, such as HTTPS.
+   */
   boolean secure();
 
+  /**
+   * Upgrade the request to something else...like a web socket.
+   *
+   * @param type Upgrade type.
+   * @return A instance of the upgrade.
+   * @throws Exception If the upgrade fails or it is un-supported.
+   * @see NativeWebSocket
+   */
   <T> T upgrade(Class<T> type) throws Exception;
 
 }
diff --git a/jooby/src/main/java/org/jooby/spi/NativeResponse.java b/jooby/src/main/java/org/jooby/spi/NativeResponse.java
@@ -25,33 +25,96 @@
 
 import org.jooby.Cookie;
 
+/**
+ * Minimal/basic implementation of HTTP request. A server implementor must provide an implementation
+ * of {@link NativeResponse}.
+ *
+ * @author edgar
+ * @since 0.5.0
+ */
 public interface NativeResponse {
 
-
-
+  /**
+   * Set a response cookie.
+   *
+   * @param cookie A cookie to add.
+   */
   void cookie(Cookie cookie);
 
+  /**
+   * Clear a cookie and force a client to expire and delete it.
+   *
+   * @param name Cookie's name.
+   */
   void clearCookie(String name);
 
+  /**
+   * Get a response header (previously set).
+   *
+   * @param name Header's name.
+   * @return Header.
+   */
   default Optional<String> header(final String name) {
     List<String> headers = headers(name);
     return headers.size() == 0 ? Optional.empty() : Optional.of(headers.get(0));
   }
 
+  /**
+   * Get all the response headers for the provided name.
+   *
+   * @param name A header's name
+   * @return All the response headers.
+   */
   List<String> headers(String name);
 
+  /**
+   * Set a response header.
+   *
+   * @param name Header's name.
+   * @param value Header's value.
+   */
   void header(String name, String value);
 
+  /**
+   * Get an output stream and prepare to send a response. You need to make sure status and headers
+   * are set beforing calling this method. Attempt to set status and headers after calling output
+   * stream if undefined and might result in error or just ignored.
+   *
+   * @param bufferSize The preferred buffer size for sending a response. Default buffer size is:
+   *        <code>16k</code>. Default buffer size by setting the:
+   *        <code>server.http.ResponseBufferSize</code> property in your <code>*.conf property file.
+   *        If the <code>Content-Length</code> header was set and it is less than buffer size, the
+   *        the <code>Content-Length</code> will be used it as buffer size.
+   * @return
+   * @throws IOException
+   */
   OutputStream out(int bufferSize) throws IOException;
 
+  /**
+   * @return HTTP response status.
+   */
   int statusCode();
 
+  /**
+   * Set the HTTP response status.
+   *
+   * @param code A HTTP response status.
+   */
   void statusCode(int code);
 
+  /**
+   * @return True if response was committed to the client.
+   */
   boolean committed();
 
+  /**
+   * End a response and clean up any resources used it.
+   */
   void end();
 
+  /**
+   * Reset the HTTP status, headers and response buffer is need it.
+   */
   void reset();
 
 }
diff --git a/jooby/src/main/java/org/jooby/spi/NativeUpload.java b/jooby/src/main/java/org/jooby/spi/NativeUpload.java
@@ -24,14 +24,41 @@
 import java.util.List;
 import java.util.Optional;
 
+/**
+ * File upload from multipart/form-data post.
+ *
+ * @author edgar
+ * @since 0.5.0
+ */
 public interface NativeUpload extends Closeable {
 
+  /**
+   * @return File name.
+   */
   String name();
 
+  /**
+   * File header, like <code>Content-Type</code>, <code>Content-Transfer-Encoding</code>, etc.
+   *
+   * @param name Header's name.
+   * @return A header value or empty optional.
+   */
   Optional<String> header(String name);
 
+  /**
+   * Get all the file headers for the given name.
+   *
+   * @param name A header's name.
+   * @return All available values or and empty list.
+   */
   List<String> headers(String name);
 
+  /**
+   * Get the actual file link/reference and do something with it.
+   *
+   * @return A file from local file system.
+   * @throws IOException If file failed to read/write from local file system.
+   */
   File file() throws IOException;
 
 }
diff --git a/jooby/src/main/java/org/jooby/spi/NativeWebSocket.java b/jooby/src/main/java/org/jooby/spi/NativeWebSocket.java
@@ -26,30 +26,96 @@
 
 import org.jooby.WebSocket;
 
+/**
+ * A web socket upgrade created from {@link NativeRequest#upgrade(Class)}.
+ *
+ * @author edgar
+ * @since 0.5.0
+ */
 public interface NativeWebSocket {
 
+  /**
+   * Close the web socket.
+   *
+   * @param status A web socket close status.
+   * @param reason A close reason.
+   */
   void close(int status, String reason);
 
+  /**
+   * Resume reads.
+   */
   void resume();
 
+  /**
+   * Set the onconnect callback. It will be execute once per each client.
+   *
+   * @param callback A callback.
+   */
   void onConnect(Runnable callback);
 
+  /**
+   * Set the ontext message callback. On message arrival the callback will be executed.
+   *
+   * @param callback A callback.
+   */
   void onTextMessage(Consumer<String> callback);
 
+  /**
+   * Set the onbinary message callback. On message arrival the callback will be executed.
+   *
+   * @param callback A callback.
+   */
   void onBinaryMessage(Consumer<ByteBuffer> callback);
 
+  /**
+   * Set the onclose message callback. It will be executed when clients close a connection and/or
+   * connection idle timeout.
+   *
+   * @param callback A callback.
+   */
   void onCloseMessage(BiConsumer<Integer, Optional<String>> callback);
 
+  /**
+   * Set the onerror message callback. It will be executed on errors.
+   *
+   * @param callback A callback.
+   */
   void onErrorMessage(Consumer<Throwable> callback);
 
+  /**
+   * Pause reads.
+   */
   void pause();
 
+  /**
+   * Terminate immediately a connection.
+   *
+   * @throws IOException If termination fails.
+   */
   void terminate() throws IOException;
 
+  /**
+   * Send a binary message to the client.
+   *
+   * @param data Message to send.
+   * @param success Success callback.
+   * @param err Error callback.
+   */
   void send(ByteBuffer data, WebSocket.SuccessCallback success, WebSocket.ErrCallback err);
 
+  /**
+   * Send a text message to the client.
+   *
+   * @param data Message to send.
+   * @param success Success callback.
+   * @param err Error callback.
+   */
   void send(String data, WebSocket.SuccessCallback success, WebSocket.ErrCallback err);
 
+  /**
+   * @return True if the websocket connection is open.
+   */
   boolean isOpen();
 
 }
diff --git a/jooby/src/main/java/org/jooby/spi/Server.java b/jooby/src/main/java/org/jooby/spi/Server.java
@@ -40,6 +40,11 @@ public interface Server {
    */
   void stop() throws Exception;
 
+  /**
+   * Waits for this thread to die.
+   *
+   * @throws InterruptedException If wait didn't success.
+   */
   void join() throws InterruptedException;
 
 }
