migrate docs

Author: Katsute

README.md

@@ -5,8 +5,6 @@
         <a href="https://docs.katsute.dev/simplehttpserver">Documentation</a>
         •
         <a href="https://github.com/KatsuteDev/simplehttpserver/blob/main/setup.md#readme">Setup</a>
-        •
-        <a href="https://github.com/KatsuteDev/simplehttpserver/blob/main/faq.md#readme">FAQ</a>
     </div>
 </div>
 

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

@@ -28,6 +28,49 @@
 
 /**
  * A {@link HttpExchange} with additional extensions to simplify usage.
+ * <h1>Requests</h1>
+ * <h2><code>GET</code> Request</h2>
+ * If a user sends a <code>GET</code> request to the server, a map of keys and values of that request can be retrieved by using the {@link #getGetMap()} method.
+ * <h2><code>POST</code> Request</h2>
+ * If a user sends a <code>POST</code> request to the server, a map of keys and values; or a {@link MultipartFormData} can be retrieved by using {@link #getPostMap()} and {@link #getMultipartFormData()}.
+ *
+ * <h3><code>multipart/form-data</code></h3>
+ * For requests that have content type <code>multipart/form-data</code>, data must be retrieved using {@link #getMultipartFormData()}, which returns a {@link MultipartFormData} using {@link Record}s and {@link FileRecord}s. Files sent through here are sent as a {@link Byte} array and not a {@link File}.
+ *
+ * <h2>Cookies</h2>
+ * A clients browser cookies for the site can be retrieved by using the {@link #getCookie(String)} or {@link #getCookies()} method.
+ * <br>
+ * Cookies can be set by using the {@link #setCookie(HttpCookie)} or {@link #setCookie(String, String)}.
+ * <br>
+ * An exchange must be sent in order to change on the client.
+ *
+ * <h2>Session</h2>
+ * Normally the only "identifier" that we can retrieve from the user is their address and port provided from an exchange. This however, doesn't work across multiple tabs or when the user refreshes the page; instead we use a session cookie to track a user.
+ * <br>
+ * A server must have a {@link HttpSessionHandler} set using {@link SimpleHttpServer#setSessionHandler(HttpSessionHandler)} for this to work.
+ * <br>
+ * The {@link HttpSessionHandler} assigns session IDs to clients and allows the server to retrieve them using {@link SimpleHttpServer#getSession(HttpExchange)}.
+ *
+ * <h1>Response</h1>
+ * To send response headers you must first retrieve then with {@link #getResponseHeaders()}, modify them, then send them using {@link #sendResponseHeaders(int, long)} or any other of the send methods.
+ * <br>
+ * Data can be sent as a {@link Byte} array, {@link String}, or as a {@link File}. Responses can optionally gziped to compress the data sent.
+ * <ul>
+ *      <li>{@link #send(int)}</li>
+ *      <li>{@link #send(byte[])}</li>
+ *      <li>{@link #send(byte[], int)}</li>
+ *      <li>{@link #send(byte[], boolean)}</li>
+ *      <li>{@link #send(byte[], int, boolean)}</li>
+ *      <li>{@link #send(String)}</li>
+ *      <li>{@link #send(String, int)}</li>
+ *      <li>{@link #send(String, boolean)}</li>
+ *      <li>{@link #send(String, int, boolean)}</li>
+ *      <li>{@link #send(File)}</li>
+ *      <li>{@link #send(File, int)}</li>
+ *      <li>{@link #send(File, boolean)}</li>
+ *      <li>{@link #send(File, int, boolean)}</li>
+ * </ul>
+ * <b>Note:</b> An exchange must be sent or closed, otherwise the connection may resend the request until it gets response or times out.
  *
  * @see HttpExchange
  * @since 5.0.0

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

@@ -24,14 +24,21 @@
 import java.io.IOException;
 
 /**
- * A http handler that uses a {@link SimpleHttpExchange}
+ * A http handler that uses a {@link SimpleHttpExchange}. All handlers in this library can be used with a standard {@link com.sun.net.httpserver.HttpServer}.
  * <br>
- * Http handlers will not throw an exception in the main thread, you must use a try-catch to expose them. All requests must be closed with {@link HttpExchange#close()}, otherwise the handler will rerun the request multiple times.
+ * <b>Note:</b> Http handlers will not throw an exception in the main thread, you must use a try-catch to expose them.
  * <br>
- * This handler can be used with a standard {@link com.sun.net.httpserver.HttpServer}.
+ * <b>Note:</b> An exchange must be sent or closed, otherwise the connection may resend the request until it gets response or times out.
  *
  * @see HttpHandler
  * @see SimpleHttpExchange
+ * @see dev.katsute.simplehttpserver.handler.PredicateHandler
+ * @see dev.katsute.simplehttpserver.handler.RedirectHandler
+ * @see dev.katsute.simplehttpserver.handler.RootHandler
+ * @see dev.katsute.simplehttpserver.handler.SSEHandler
+ * @see dev.katsute.simplehttpserver.handler.TemporaryHandler
+ * @see dev.katsute.simplehttpserver.handler.throttler.ThrottledHandler
+ * @see dev.katsute.simplehttpserver.handler.file.FileHandler
  * @since 5.0.0
  * @version 5.0.0
  * @author Katsute

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

@@ -18,14 +18,92 @@
 
 package dev.katsute.simplehttpserver;
 
+import com.sun.net.httpserver.HttpHandler;
 import com.sun.net.httpserver.HttpServer;
+import dev.katsute.simplehttpserver.handler.RootHandler;
 
 import java.io.IOException;
 import java.net.InetSocketAddress;
+import java.util.concurrent.Executor;
+import java.util.concurrent.Executors;
 
 /**
  * A {@link HttpServer} with additional extensions to simplify usage.
  *
+ * <h1>Creating a SimpleHttpServer</h1>
+ * A SimpleHttpServer is created in the same way was a standard HttpServer, by using one of the <code>create</code> methods.
+ * <ul>
+ *     <li>{@link #create()}</li>
+ *     <li>{@link #create(int)}</li>
+ *     <li>{@link #create(int, int)}</li>
+ *     <li>{@link #create(InetSocketAddress, int)}</li>
+ * </ul>
+ *
+ * <h2>Binding to a Port</h2>
+ * A SimpleHttpServer requires a port to become accessible, the port can be defined in the <code>create</code> or <code>bind</code> methods.
+ * <ul>
+ *     <li>{@link #create(int)}</li>
+ *     <li>{@link #create(int, int)}</li>
+ *     <li>{@link #create(InetSocketAddress, int)}</li>
+ *     <li>{@link #bind(int)}</li>
+ *     <li>{@link #bind(int, int)}</li>
+ *     <li>{@link #bind(InetSocketAddress, int)}</li>
+ * </ul>
+ * The backlog parameter in each of these determines the maximum amount of simultaneous connections at any given time.
+ *
+ * <h2>Starting the Server</h2>
+ * The server can be started by using the {@link #start()} method.
+ *
+ * <h2>Stopping the Server</h2>
+ * The server can be stopped by using {@link #stop()} or {@link #stop(int)} methods.
+ * <br>
+ * The delay parameter determines how long the server should wait before forcefully closing the connection, by default this is 0.
+ *
+ * <h1>Adding Pages</h1>
+ * Pages (referred to as a context) are added by using any of the <code>createContext</code> methods.
+ * <ul>
+ *     <li>{@link #createContext(String)}</li>
+ *     <li>{@link #createContext(String, HttpHandler)}</li>
+ * </ul>
+ * Content for each context is determined by using a {@link HttpHandler}. SimpleHttpServer offers some simplified handlers to handle some complex operations, documentation for those can be found in {@link SimpleHttpHandler}.
+ * <br>
+ * Contexts in a server are <b>case sensitive</b> and will resolve to the most specific context available.
+ * <br><br>
+ * <b>Example:</b>
+ * <br>
+ * If a user goes to <code>/this/web/page</code> and there are only handlers for <code>/this</code> and <code>/this/web</code>, then the handler for <code>/this/web</code> would be used because its the most specific context that exists on the server.
+ * <br><br>
+ * This behavior consequentially means that any handler added to the root <code>/</code> context would handle any requests that don't have a handler, since it's the most specific one available. A {@link RootHandler} can be used to mediate this issue.
+ *
+ * <h1>Accessing the Server</h1>
+ * <h2>Accessing on Host Machine</h2>
+ * When a server is started it is immediately available at whatever port was set.
+ * <br>
+ * <b>Example:</b> <code>localhost:8000</code>, <code>127.0.0.1:80</code>
+ * <h2>Accessing on Local Network</h2>
+ * If permitted, the server should also be accessible to all computers on your immediate internet network at your <a href="https://www.google.com/search?q=How+to+find+my+local+ip+address">local IP</a>.
+ * <h2>Accessing Globally</h2>
+ * For clients not connected to your network, they must use your <a href="https://www.whatismyip.com/what-is-my-public-ip-address/">public IP address</a>.
+ * <br>
+ * People outside your network can not connect unless you <b>port forward</b> the port the server is using. This process varies depending on your ISP and can often leave your network vulnerable to attackers. It is not suggested to this unless you know what you are doing.
+ * <br>
+ * You can learn to port forward <a href="https://www.google.com/search?q=How+to+port+forward">here</a> (at your own risk).
+ *
+ * <h1>Multi-threaded Server</h1>
+ * By default the server runs on a single thread. This means that only one clients exchange can be processed at a time and can lead to long queues.
+ * <br>
+ * For a server to be multi-threaded the executor must be changed to one that process threads in parallel. The executor can be changed using the {@link #setExecutor(Executor)} method on the server.
+ * <br>
+ * To process a fixed amount of threads you can use {@link Executors#newFixedThreadPool(int)}.
+ * <br>
+ * To process an unlimited amount of threads you can use {@link Executors#newCachedThreadPool()}.
+ * <h2>Requests are still not being processed in parallel</h2>
+ * Requests to the same context may not run in parallel for a user that is accessing the same page more than once. This issue is caused by the browser, where it will not send duplicate requests to the server at the same time.
+ * <br>
+ * This issue is better explained <a href="https://stackoverflow.com/a/58676470">here</a>.
+ * <br>
+ * If you still need to test multithreading then you must use an older browser like Internet Explorer or Microsoft Edge.
+ *
  * @see HttpServer
  * @since 5.0.0
  * @version 5.0.0

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

@@ -18,20 +18,16 @@
 
 package dev.katsute.simplehttpserver;
 
-import com.sun.net.httpserver.*;
+import com.sun.net.httpserver.HttpsServer;
 
 import java.io.IOException;
 import java.net.InetSocketAddress;
 
 /**
- * A http handler that uses a {@link SimpleHttpExchange}
- * <br>
- * Http handlers will not throw an exception in the main thread, you must use a try-catch to expose them. All requests must be closed with {@link HttpExchange#close()}, otherwise the handler will rerun the request multiple times.
- * <br>
- * This handler can be used with a standard {@link com.sun.net.httpserver.HttpsServer}.
+ * A {@link HttpsServer} with additional extensions to simplify usage. See {@link SimpleHttpServer} for setup documentation.
  *
- * @see HttpHandler
- * @see SimpleHttpExchange
+ * @see SimpleHttpServer
+ * @see HttpsServer
  * @since 5.0.0
  * @version 5.0.0
  * @author Katsute

src/main/java/dev/katsute/simplehttpserver/handler/PredicateHandler.java

@@ -28,7 +28,7 @@
 import java.util.function.Predicate;
 
 /**
- * Handler that process requests based on a predicate.
+ * Handler that process requests based on the result of a predicate.
  *
  * @see Predicate
  * @see SimpleHttpExchange

src/main/java/dev/katsute/simplehttpserver/handler/RootHandler.java

@@ -21,7 +21,9 @@
 import com.sun.net.httpserver.HttpHandler;
 
 /**
- * Handler that process requests for the root <code>/</code> context.
+ * By default, exchanges will look for the closest matching context for their handler, this consequently means that the root index <code>/</code> would catch any requests without a handler instead of returning a code 404.
+ * <br>
+ * The RootHandler resolves this issue by only accepting requests to the exact context <code>/</code> and sending the rest to an alternative handler, typically where a 404 page would reside.
  *
  * @since 5.0.0
  * @version 5.0.0

src/main/java/dev/katsute/simplehttpserver/handler/SSEHandler.java

@@ -32,7 +32,7 @@
 import java.util.concurrent.atomic.AtomicInteger;
 
 /**
- * Send events from the server to the client using an <code>text/event-stream</code>. Events are sent using {@link #push(String)} or {@link #push(String, int, String)}.
+ * A <a href="https://www.w3schools.com/html/html5_serversentevents.asp">Server sent events (SSE)</a> handler sends events from the server to a client using an <code>text/event-stream</code>. Events are sent using {@link #push(String)} or {@link #push(String, int, String)}.
  *
  * @since 5.0.0
  * @version 5.0.0

src/main/java/dev/katsute/simplehttpserver/handler/TemporaryHandler.java

@@ -20,13 +20,16 @@
 
 import com.sun.net.httpserver.HttpExchange;
 import com.sun.net.httpserver.HttpHandler;
+import dev.katsute.simplehttpserver.SimpleHttpServer;
 
 import java.io.IOException;
 import java.util.Objects;
 
 /**
- * Handler that removes itself after a single request, or after a set time, whichever comes first.
+ * Handler that removes itself after a single request, or after a set time, whichever comes first. This can be used for single use downloads or disposable links. A random unused context can be created by using {@link SimpleHttpServer#getRandomContext()} or {@link SimpleHttpServer#getRandomContext(String)}.
  *
+ * @see SimpleHttpServer#getRandomContext()
+ * @see SimpleHttpServer#getRandomContext(String)
  * @since 5.0.0
  * @version 5.0.0
  * @author Katsute

src/main/java/dev/katsute/simplehttpserver/handler/file/FileHandler.java

@@ -31,6 +31,31 @@
 
 /**
  * A file handler can be used to serve single or multiple files on a server with optional pre/post processing using {@link FileAdapter}s.
+ * <br>
+ * <h1>{@link FileAdapter}</h1>
+ * A {@link FileAdapter} determines where a file can be accessed and what content it will return. By default files would be accessible at the file name (including extension) with the file content.
+ *
+ * <h1>Adding Files</h1>
+ * The name parameters in the add methods supersedes the {@link FileAdapter} and makes a file accessible at whatever name you set.
+ *
+ * <h1>{@link FileOptions}</h1>
+ * File options can be added to influence the behavior of added files.
+ * <h2>Context</h2>
+ * The {@link FileOptions#context} property determines at where the file will be located with respect to the file handler. By default this is "" and any added files will be accessible directly after the file handler's context.
+ * <br>
+ * <b>Example:</b> <code>/fileHandlerContext/file.txt</code> by default and <code>/fileHandlerContext/optionsContext/file.txt</code> if a context was set.
+ * <h2>Loading Options</h2>
+ * The {@link FileOptions#loading} option determines how a file should be loaded when added.
+ * <ul>
+ *     <li>{@link FileOptions.FileLoadingOption#PRELOAD} - files are read when added</li>
+ *     <li>{@link FileOptions.FileLoadingOption#MODIFY} - files are read when added and when modified</li>
+ *     <li>{@link FileOptions.FileLoadingOption#CACHE} - files are read when requested and cached for a set time</li>
+ *     <li>{@link FileOptions.FileLoadingOption#LIVE} - files are read when requested</li>
+ * </ul>
+ * <h2>Cache</h2>
+ * If the loading option {@link FileOptions.FileLoadingOption#CACHE} is used, the {@link FileOptions#cache} determines how long to cache files for in milliseconds.
+ * <h2>Walk</h2>
+ * When directories are added, if true, will also include subdirectories; if false, will only include files in the immediate directory.
  *
  * @see FileAdapter
  * @see FileOptions
@@ -154,6 +179,8 @@ public final void addFile(final File file, final String fileName, final FileOpti
         Objects.requireNonNull(file);
         try{
             final FileOptions opts = options == null ? defaultOptions : new FileOptions(options); // dereference to prevent modification
+            Objects.requireNonNull(opts.loading);
+            Objects.requireNonNull(opts.context);
             files.put(
                 ContextUtility.joinContexts(true, false, opts.context, fileName == null ? adapter.getName(file) : fileName),
                 new FileEntry(file, adapter, opts)
@@ -254,6 +281,8 @@ public final void addDirectory(final File directory, final String directoryName,
         Objects.requireNonNull(directory);
         try{
             final FileOptions opts = options == null ? defaultOptions : new FileOptions(options); // dereference to prevent modification
+            Objects.requireNonNull(opts.loading);
+            Objects.requireNonNull(opts.context);
             final String target = ContextUtility.joinContexts(true, false, opts.context, directoryName);
             directories.put(
                 target,