basic documentation, nonnull checks, fixes

Author: Katsute

pom.xml

@@ -246,6 +246,7 @@
                     <excludes>
                         <exclude/>
                     </excludes>
+                    <reuseForks>false</reuseForks> <!-- required to prevent server binding issues -->
                     <trimStackTrace>false</trimStackTrace>
                 </configuration>
             </plugin>

src/main/java/dev/katsute/simplehttpserver/FileRecord.java

@@ -21,6 +21,16 @@
 import java.nio.charset.StandardCharsets;
 import java.util.*;
 
+/**
+ * Represents a file in a multipart/form-data request.
+ *
+ * @see MultipartFormData
+ * @see Record
+ *
+ * @since 5.0.0
+ * @version 5.0.0
+ * @author Katsute
+ */
 public class FileRecord extends Record {
 
     final String fileName, contentType;
@@ -34,14 +44,35 @@ public class FileRecord extends Record {
         bytes       = getValue().getBytes(StandardCharsets.UTF_8);
     }
 
+    /**
+     * Returns the file name.
+     *
+     * @return file name
+     *
+     * @since 5.0.0
+     */
     public final String getFileName(){
         return fileName;
     }
 
+    /**
+     * Returns the file content type.
+     *
+     * @return content type
+     *
+     * @since 5.0.0
+     */
     public final String getContentType(){
         return contentType;
     }
 
+    /**
+     * Returns the file content as a byte array
+     *
+     * @return file in bytes
+     *
+     * @since 5.0.0
+     */
     public final byte[] getBytes(){
         return Arrays.copyOf(bytes, bytes.length); // dereference
     }

src/main/java/dev/katsute/simplehttpserver/HttpServerExtensions.java

@@ -24,34 +24,137 @@
 import java.net.InetSocketAddress;
 import java.util.Map;
 
+/**
+ * Additional extensions provided to a {@link SimpleHttpServer}.
+ *
+ * @see SimpleHttpServer
+ * @see SimpleHttpsServer
+ * @since 5.0.0
+ * @version 5.0.0
+ * @author Katsute
+ */
 interface HttpServerExtensions {
 
+    /**
+     * Binds the server to a port.
+     *
+     * @param port port to bind to
+     * @return server address
+     * @throws IOException internal error
+     * @throws java.net.BindException if server could not be bounded
+     *
+     * @see HttpServer#bind(InetSocketAddress, int)
+     * @see #bind(int, int)
+     * @since 5.0.0
+     */
     InetSocketAddress bind(final int port) throws IOException;
 
+    /**
+     * Binds the server to a port.
+     *
+     * @param port port to bind to
+     * @param backlog maximum amount of inbound connections at any given time
+     * @return server address
+     * @throws IOException internal error
+     * @throws java.net.BindException if server could not be bounded
+     *
+     * @see HttpServer#bind(InetSocketAddress, int)
+     * @see #bind(int, int)
+     * @since 5.0.0
+     */
     InetSocketAddress bind(final int port, final int backlog) throws IOException;
 
     //
 
+    /**
+     * Sets as session handler to use for the server.
+     *
+     * @param sessionHandler session handler
+     *
+     * @see HttpSessionHandler
+     * @see #getSessionHandler()
+     * @since 5.0.0
+     */
     void setSessionHandler(final HttpSessionHandler sessionHandler);
 
     HttpSessionHandler getSessionHandler();
 
+    /**
+     * Returns the session for a given exchange.
+     *
+     * @param exchange http exchange
+     * @return session associated with an exchange
+     *
+     * @see HttpSession
+     * @since 5.0.0
+     */
     HttpSession getSession(final HttpExchange exchange);
 
     //
 
+    /**
+     * Returns the handler for a given context.
+     *
+     * @param context context
+     * @return handler for context
+     *
+     * @see #getContextHandler(HttpContext)
+     * @see #getContexts()
+     * @since 5.0.0
+     */
     HttpHandler getContextHandler(final String context);
 
+    /**
+     * Returns the handler for a given context.
+     *
+     * @param context http context
+     * @return handler for context
+     *
+     * @see #getContextHandler(String)
+     * @see #getContexts()
+     * @since 5.0.0
+     */
     HttpHandler getContextHandler(final HttpContext context);
 
+    /**
+     * Returns a map of all the contexts registered to the server.
+     * @return map of contexts
+     *
+     * @see #getContextHandler(String)
+     * @see #getContextHandler(HttpContext)
+     * @since 5.0.0
+     */
     Map<HttpContext,HttpHandler> getContexts();
 
+    /**
+     * Returns a random context that doesn't yet exist on the server.
+     *
+     * @return random unused context
+     *
+     * @see #getRandomContext(String)
+     * @since 5.0.0
+     */
     String getRandomContext();
 
+    /**
+     * Returns a random context prefixed by a set context.
+     *
+     * @param context context to prefix
+     * @return random unused context with prefix
+     *
+     * @see #getRandomContext()
+     * @since 5.0.0
+     */
     String getRandomContext(final String context);
 
     //
 
+    /**
+     * Stops the server immediately without waiting.
+     *
+     * @see HttpServer#stop(int)
+     * @since 5.0.0
+     */
     void stop();
 
 }

src/main/java/dev/katsute/simplehttpserver/HttpSession.java

@@ -18,16 +18,52 @@
 
 package dev.katsute.simplehttpserver;
 
+/**
+ * A session keeps track of a single client across multiple exchanges.
+ *
+ * @see HttpSessionHandler
+ * @since 5.0.0
+ * @version 5.0.0
+ * @author Katsute
+ */
 public abstract class HttpSession {
 
     HttpSession(){ }
 
+    /**
+     * Returns the session ID.
+     *
+     * @return session ID
+     *
+     * @since 5.0.0
+     */
     public abstract String getSessionID();
 
+    /**
+     * Returns when the session was created as milliseconds since epoch.
+     *
+     * @return session creation time
+     *
+     * @since 5.0.0
+     */
     public abstract long getCreationTime();
 
+    /**
+     * Returns when the session was last accessed as milliseconds since epoch.
+     *
+     * @return session last accessed time
+     *
+     * @see #update()
+     * @since 5.0.0
+     */
     public abstract long getLastAccessed();
 
+    /**
+     * Refreshes when the session was last accessed to now.
+     *
+     * @see #getLastAccessed()
+     * @since 5.0.0
+     */
     public abstract void update();
 
 }

src/main/java/dev/katsute/simplehttpserver/HttpSessionHandler.java

@@ -24,20 +24,48 @@
 import java.net.HttpCookie;
 import java.util.*;
 
+/**
+ * The session handler is used to assign sessions to exchanges.
+ *
+ * @see HttpSession
+ * @since 5.0.0
+ * @version 5.0.0
+ * @author Katsute
+ */
 public class HttpSessionHandler {
 
     private final Map<String,HttpSession> sessions = Collections.synchronizedMap(new HashMap<>());
 
     private final String cookie;
 
+    /**
+     * Creates a session handler using the cookie <code>__session-id</code>.
+     *
+     * @since 5.0.0
+     */
     public HttpSessionHandler(){
         this("__session-id");
     }
 
+    /**
+     * Creates a session handler using a specified cookie.
+     *
+     * @param cookie cookie to use for session ID
+     *
+     * @since 5.0.0
+     */
     public HttpSessionHandler(final String cookie){
-        this.cookie = cookie;
+        this.cookie = Objects.requireNonNull(cookie);
     }
 
+    /**
+     * Assigns a unique session ID to an exchange.
+     *
+     * @param exchange http exchange
+     * @return unique session ID
+     *
+     * @since 5.0.0
+     */
     public synchronized String assignSessionID(final HttpExchange exchange){
         String id;
         do id = UUID.randomUUID().toString(); // assign session ID
@@ -53,12 +81,20 @@ private String getSetSession(final Headers headers){ // get session that will be
        return null;
     }
 
+    /**
+     * Returns the session associated with a particular exchange.
+     *
+     * @param exchange http exchange
+     * @return session associated with exchange
+     *
+     * @since 5.0.0
+     */
     public final HttpSession getSession(final HttpExchange exchange){
         final String sessionID;
         final HttpSession session;
 
         @SuppressWarnings("SpellCheckingInspection")
-        final String rcookies = exchange.getRequestHeaders().getFirst("Cookie");
+        final String rcookies = Objects.requireNonNull(exchange).getRequestHeaders().getFirst("Cookie");
         final Map<String,String> cookies = new HashMap<>();
 
         if(rcookies != null && !rcookies.isEmpty()){

src/main/java/dev/katsute/simplehttpserver/MultipartFormData.java

@@ -18,9 +18,18 @@
 
 package dev.katsute.simplehttpserver;
 
-import java.util.HashMap;
-import java.util.Map;
+import java.util.*;
 
+/**
+ * Representation of a multipart/form-data body.
+ *
+ * @see FileRecord
+ * @see Record
+ * @see SimpleHttpExchange#getMultipartFormData()
+ * @since 5.0.0
+ * @version 5.0.0
+ * @author Katsute
+ */
 public class MultipartFormData {
 
     private final Map<String,Record> data;
@@ -29,10 +38,31 @@ public class MultipartFormData {
         this.data = new HashMap<>(data);
     }
 
+    /**
+     * Returns the record for a particular key. If the record is supposed to be a file use {@link Record#asFile()}.
+     *
+     * @param name record key
+     * @return record
+     *
+     * @see Record
+     * @see FileRecord
+     * @see #getEntries()
+     * @since 5.0.0
+     */
     public final Record getEntry(final String name){
-        return data.get(name);
+        return data.get(Objects.requireNonNull(name));
     }
 
+    /**
+     * Returns all the records in the response body.
+     *
+     * @return map of all records
+     *
+     * @see Record
+     * @see FileRecord
+     * @see #getEntry(String)
+     * @since 5.0.0
+     */
     public final Map<String,Record> getEntries(){
         return new HashMap<>(data);
     }