Add comments

Author: simonwep

src/express/Express.java

@@ -15,55 +15,129 @@
 import java.util.Collections;
 import java.util.List;
 
+/**
+ * @author Simon Reinisch
+ * @implNote Core modul, don't change anything.
+ *
+ * An NodeJS like clone written in Java, see README for more information.
+ */
 public class Express {
 
   private final List<Filter> MIDDLEWARE = Collections.synchronizedList(new ArrayList<>());
   private final List<Filter> FILTER = Collections.synchronizedList(new ArrayList<>());
+
+  // Index of last middleware to keep it sorted
   int middlewareIndex = 0;
 
   private HttpServer httpServer;
   private HttpContext httpContext;
   private HttpRequest request404;
 
+  /**
+   * Add an middleware which will be firea BEFORE EACH request-type listener will be fired.
+   *
+   * @param request An listener which will be fired on every equestmethod- and  path.
+   */
   public void use(HttpRequest request) {
     addFilter(true, "*", "*", request);
   }
 
+  /**
+   * Add an middleware which will be firea BEFORE EACH request-type listener will be fired.
+   *
+   * @param context The context where the middleware should listen, see README for information about placeholder.
+   * @param request An listener which will be fired if the context matches the requestpath.
+   */
   public void use(String context, HttpRequest request) {
     addFilter(true, "*", context, request);
   }
 
+  /**
+   * Add an middleware which will be firea BEFORE EACH request-type listener will be fired.
+   *
+   * @param context       The context where the middleware should listen, see README for information about placeholder.
+   * @param requestMethod And type of request-method eg. GET, POST etc.
+   * @param request       An listener which will be fired if the context matches the requestmethod- and  path.
+   */
   public void use(String context, String requestMethod, HttpRequest request) {
     addFilter(true, requestMethod.toUpperCase(), context, request);
   }
 
+  /**
+   * Add an listener for request types.
+   *
+   * @param context The context, see README for information about placeholder.
+   * @param request An listener.
+   */
   public void all(String context, HttpRequest request) {
     addFilter(false, "*", context, request);
   }
 
+  /**
+   * Add an listener for GET request's.
+   *
+   * @param context The context, see README for information about placeholder.
+   * @param request An listener which will be fired if the context matches the requestpath.
+   */
   public void get(String context, HttpRequest request) {
     addFilter(false, "GET", context, request);
   }
 
+  /**
+   * Add an listener for POST request's.
+   *
+   * @param context The context, see README for information about placeholder.
+   * @param request An listener which will be fired if the context matches the requestpath.
+   */
   public void post(String context, HttpRequest request) {
     addFilter(false, "POST", context, request);
   }
 
+  /**
+   * Add an listener for PUT request's.
+   *
+   * @param context The context, see README for information about placeholder.
+   * @param request An listener which will be fired if the context matches the requestpath.
+   */
   public void put(String context, HttpRequest request) {
     addFilter(false, "PUT", context, request);
   }
 
+  /**
+   * Add an listener for DELETE request's.
+   *
+   * @param context The context, see README for information about placeholder.
+   * @param request An listener which will be fired if the context matches the requestpath.
+   */
   public void delete(String context, HttpRequest request) {
     addFilter(false, "DELETE", context, request);
   }
 
+  /**
+   * Add an listener for PATCH request's.
+   *
+   * @param context The context, see README for information about placeholder.
+   * @param request An listener which will be fired if the context matches the requestpath.
+   */
   public void patch(String context, HttpRequest request) {
     addFilter(false, "PATCH", context, request);
   }
 
+  /**
+   * Internal method to add an filter
+   *
+   * @param middleware    If the filter is an middleware
+   * @param requestMethod The request-method
+   * @param context       The url-path
+   * @param request       An listener which will be fired if the given context is matching
+   */
   private void addFilter(boolean middleware, String requestMethod, String context, HttpRequest request) {
     ExpressFilter handler = new ExpressFilter(requestMethod, context, request);
+
+    // Check if the server is already active
     if (httpContext == null) {
+
+      // Middleware needs an seperated list because it will ALWAYS fired before each request handler
       if (middleware) {
         MIDDLEWARE.add(handler);
       } else {
@@ -73,46 +147,70 @@ private void addFilter(boolean middleware, String requestMethod, String context,
       List<Filter> filters = httpContext.getFilters();
 
       if (middleware) {
+
+        // Insert middleware after the last middleware
         filters.add(middlewareIndex, handler);
         middlewareIndex++;
       } else filters.add(handler);
     }
   }
 
-  private void addFirst(String requestMethod, String context, HttpRequest request) {
-    ExpressFilter handler = new ExpressFilter(requestMethod, context, request);
-    if (httpContext == null) {
-      MIDDLEWARE.add(handler);
-    } else {
-      httpContext.getFilters().add(handler);
-    }
+  /**
+   * Set an extra lisener for 404 (not found) requests, also request where no context
+   * match the given request path (or method).
+   *
+   * @param request An listener.
+   */
+  public void set404(HttpRequest request) {
+    this.request404 = request;
   }
 
+  /**
+   * Start the HTTP-Server on port 80.
+   * This method is asyncronous so be sure to add an listener or keep it in mind!
+   *
+   * @throws IOException - If an IO-Error occurs, eg. the port is already in use.
+   */
   public void listen() throws IOException {
-    launch(null, 80);
+    listen(null, 80);
   }
 
+  /**
+   * Start the HTTP-Server on a specific port
+   * This method is asyncronous so be sure to add an listener or keep it in mind!
+   *
+   * @param port The port.
+   * @throws IOException - If an IO-Error occurs, eg. the port is already in use.
+   */
   public void listen(int port) throws IOException {
-    launch(null, port);
-  }
-
-  public void listen(Action action) throws IOException {
-    launch(action, 80);
+    listen(null, port);
   }
 
-  public void listen(int port, Action action) throws IOException {
-    launch(action, port);
+  /**
+   * Start the HTTP-Server on port 80.
+   * This method is asyncronous so be sure to add an listener or keep it in mind!
+   *
+   * @param onStart An listener which will be fired after the server is stardet.
+   * @throws IOException - If an IO-Error occurs, eg. the port is already in use.
+   */
+  public void listen(Action onStart) throws IOException {
+    listen(onStart, 80);
   }
 
-  public void set404(HttpRequest request) {
-    this.request404 = request;
-  }
-
-  private void launch(Action action, int port) throws IOException {
+  /**
+   * Start the HTTP-Server on a specific port.
+   * This method is asyncronous so be sure to add an listener or keep it in mind!
+   *
+   * @param onStart An listener which will be fired after the server is stardet.
+   * @param port    The port.
+   * @throws IOException - If an IO-Error occurs, eg. the port is already in use.
+   */
+  public void listen(Action onStart, int port) throws IOException {
     new Thread(() -> {
       try {
         httpServer = HttpServer.create(new InetSocketAddress("localhost", port), 0);
         httpServer.setExecutor(null);
+
         httpContext = httpServer.createContext("/", httpExchange -> {
           if (request404 != null) {
             Request request = new Request(httpExchange);
@@ -127,14 +225,26 @@ private void launch(Action action, int port) throws IOException {
         httpContext.getFilters().addAll(FILTER);
 
         httpServer.start();
-        action.action();
+
+        // Fire listener
+        onStart.action();
       } catch (IOException e) {
         // TODO: Handle errors
         e.printStackTrace();
       }
     }).start();
   }
 
+  /**
+   * This method serves an entire folder which can contains static file for your
+   * web application, it automatically detect the content type and will send it to
+   * the Client.
+   * <p>
+   * To use it simply put it in the <code>app.use()</code> method!
+   *
+   * @param path The root directory
+   * @return An HttpRequest interface with the service.
+   */
   public static HttpRequest statics(String path) {
     return (req, res) -> {
       File reqFile = new File(path + req.getURI().getPath());

src/express/ExpressFilter.java

@@ -11,6 +11,12 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+/**
+ * @author Simon Reinisch
+ * @implNote Core modul of express, don't change anything.
+ *
+ * Filter to handle request handling & parsing.
+ */
 public class ExpressFilter extends Filter {
 
   private final HttpRequest REQUEST;
@@ -54,9 +60,11 @@ public void doFilter(HttpExchange httpExchange, Chain chain) throws IOException
       return;
     }
 
+    // Parse params, see README
     HashMap<String, String> params = new HashMap<>();
     Matcher matcher = CONTEXT_PATTERN.matcher(requestPath);
 
+    // Match all params
     if (matcher.find()) {
 
       for (int i = 1; i <= matcher.groupCount() && i < CONTEXT_PARAMS.length; i++) {

src/express/ExpressUtils.java

@@ -3,16 +3,27 @@
 import com.sun.net.httpserver.Headers;
 import express.cookie.Cookie;
 
-import java.io.*;
+import java.io.UnsupportedEncodingException;
 import java.net.URI;
 import java.net.URLDecoder;
 import java.util.HashMap;
 import java.util.List;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+/**
+ * @author Simon Reinisch
+ * <p>
+ * A few utils which are used by express.
+ */
 public class ExpressUtils {
 
+  /**
+   * Extract the cookies from the 'Cookie' header.
+   *
+   * @param headers The Headers
+   * @return An hashmap with the cookie name as key and the complete cookie as value.
+   */
   public static HashMap<String, Cookie> parseCookies(Headers headers) {
     HashMap<String, Cookie> cookieList = new HashMap<>();
     List<String> headerCookies = headers.get("Cookie");
@@ -34,6 +45,12 @@ public static HashMap<String, Cookie> parseCookies(Headers headers) {
     return cookieList;
   }
 
+  /**
+   * Method to extract the querys from an url.
+   *
+   * @param uri The uri.
+   * @return An list with key-values which are encoded in UTF8.
+   */
   public static HashMap<String, String> parseRawQuery(URI uri) {
     HashMap<String, String> querys = new HashMap<>();
     String rawQuery = uri.getRawQuery();
@@ -55,6 +72,12 @@ public static HashMap<String, String> parseRawQuery(URI uri) {
     return querys;
   }
 
+  /**
+   * Returns the MIME-Type of an filename.
+   *
+   * @param fileExtension The file extension.
+   * @return The MIME-Type.
+   */
   public static String getContentType(String fileExtension) {
     String ct = MIMETypes.get().get(fileExtension);
 

src/express/MIMETypes.java

@@ -2,6 +2,12 @@
 
 import java.util.HashMap;
 
+/**
+ * @author Simon Reinisch
+ *
+ * Full list of mime-types to handle static served files.
+ * List-link: https://www.freeformatter.com/mime-types-list.html
+ */
 public class MIMETypes {
 
   private final static HashMap<String, String> MIME = new HashMap<>();

src/express/cookie/Cookie.java

@@ -3,6 +3,10 @@
 
 import java.time.Instant;
 
+/**
+ * @author Simon Reinisch
+ * @implNote Can be reused
+ */
 public class Cookie {
 
   private String name, value;

src/express/cookie/SameSite.java

@@ -1,5 +1,8 @@
 package express.cookie;
 
+/**
+ * @author Simon Reinisch
+ */
 public enum SameSite {
    STRICT, LAX
 }

src/express/events/Action.java

@@ -1,5 +1,8 @@
 package express.events;
 
+/**
+ * @author Simon Reinisch
+ */
 public interface Action {
   void action();
 }

src/express/events/HttpRequest.java

@@ -3,6 +3,9 @@
 import express.http.Request;
 import express.http.Response;
 
+/**
+ * @author Simon Reinisch
+ */
 public interface HttpRequest {
 
   /**