SimpleServer

https://github.com/zoommax/simpleserver
Admin
SimpleServer is a lightweight Java library designed for quick and easy usage of an embedded web...
Tokens:14,200
Snippets:51
Trust Score:7
License:Apache-2.0
Update:10 months ago
Show doc for...
Tokens:
Raw
### Initialize and Start Server with Annotations (Java)

Source: https://context7.com/zoommax/simpleserver/llms.txt

Initializes and starts a web server using the `@InitWebServer` annotation for configuration (port, threads). It automatically registers methods annotated with `@Endpoint` as request handlers. This approach simplifies server setup and endpoint definition.

```java
import space.zoommax.SimpleServer;
import space.zoommax.next.Request;
import space.zoommax.next.Response;
import space.zoommax.next.annotation.Endpoint;
import space.zoommax.next.annotation.InitWebServer;
import space.zoommax.next.enums.HttpMethod;

@InitWebServer(port = 8080, threads = 4)
public class MyApplication extends SimpleServer {
    public static void main(String[] args) {
        SimpleServer.start();
        // Server now running on port 8080 with 4 threads
    }

    @Endpoint(path = "/hello", httpMethod = HttpMethod.GET, statusCode = 200)
    public Response hello(Request request) {
        String name = request.getParams().getOrDefault("name", "World");
        return Response.builder()
                .bodyAsString("Hello, " + name + "!")
                .statusCode(200)
                .build();
    }
}
// Test: curl "http://localhost:8080/hello?name=Alice"
// Output: Hello, Alice!
```

--------------------------------

### Start SimpleServer with Annotations and Extension (Java)

Source: https://github.com/zoommax/simpleserver/wiki/en

This code illustrates starting SimpleServer by extending `SimpleServer` and using annotations. The `@InitWebServer` annotation is placed on the class for server configuration. The `@Endpoint` annotation defines the GET endpoint logic. This approach integrates server initialization with class inheritance.

```java
import ru.zoommax.SimpleServer;
import ru.zoommax.next.Request;
import ru.zoommax.next.Response;
import ru.zoommax.next.annotation.Endpoint;
import ru.zoommax.next.annotation.InitWebServer;
import ru.zoommax.next.enums.HttpMethod;

@InitWebServer(port = 12345, threads = 4)
public class AnnotatedStartWithExtends extends SimpleServer {
    public static void main(String[] args) {

    }

    @Endpoint(path = "/test", httpMethod = HttpMethod.GET, statusCode = 200, filterContentLength = -1)
    public Response test(Request request) {
        return Response.builder()
                .bodyAsString(request.getBodyAsString())
                .statusCode(200)
                .build();
    }
}
```

--------------------------------

### Start SimpleServer with Annotations (Java)

Source: https://github.com/zoommax/simpleserver/wiki/en

This snippet demonstrates how to initialize and run SimpleServer using annotations. The `@InitWebServer` annotation configures server port and threads, while `@Endpoint` defines request handlers. It requires `ru.zoommax.SimpleServer` and related annotations. The `main` method starts the server, and the `test` method defines a GET endpoint.

```java
import ru.zoommax.SimpleServer;
import ru.zoommax.next.Request;
import ru.zoommax.next.Response;
import ru.zoommax.next.annotation.Endpoint;
import ru.zoommax.next.annotation.InitWebServer;
import ru.zoommax.next.enums.HttpMethod;

public class AnnotatedStart {
    /*
     * We annotate the method that will start the server using the InitWebServer annotation
     * In the InitWebServer annotation, we specify the port and the number of threads
     * By default, the port is 8080, and the number of threads is 1
     * Inside the method, we start the server using SimpleServer.start()
     * SimpleServer.start() starts reading annotations in all classes inside the package
     * with the subsequent launch of the server (a singleton is created) and the addition of endpoints
     * to the server's endpoint list.
     */
    @InitWebServer(port = 12345, threads = 4)
    public static void main(String[] args) {
        SimpleServer.start();
    }

    /*
     * We annotate the method that implements the endpoint logic using the Endpoint annotation
     * In the Endpoint annotation, we specify the endpoint path, HTTP method, response code, and content length filter
     * By default, the method is GET, the response code is 200, and the content length filter is -1 (do not filter).
     * Inside the method, we implement the endpoint logic.
     * The method should take a Request object and return a Response object.
     * The Request object contains all the information about the request,
     * and the Response object forms the response to the request.
     */
    @Endpoint(path = "/test", httpMethod = HttpMethod.GET, statusCode = 200, filterContentLength = -1)
    public Response test(Request request) {
        //Endpoint logic
        String body = request.getBodyAsString();
        //...

        //Return response
        return Response.builder()
                .bodyAsString(body)
                .statusCode(200)
                .build();
    }
}
```

--------------------------------

### Start Server Programmatically and Add Endpoints (Java)

Source: https://context7.com/zoommax/simpleserver/llms.txt

Starts a web server programmatically with specified port and thread count, allowing for dynamic endpoint registration at runtime. This method provides greater flexibility for configuring the server and its handlers. It supports adding both GET and POST handlers.

```java
import space.zoommax.SimpleServer;
import space.zoommax.next.Response;
import space.zoommax.next.handlers.GetHandlerNew;
import space.zoommax.next.handlers.PostHandlerNew;

import java.util.HashMap;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;

public class ProgrammaticServer {
    public static void main(String[] args) {
        SimpleServer.start(25565, 4);

        // Add GET endpoint
        SimpleServer.addEndpoint("/api/users", new GetHandlerNew() {
            @Override
            public Response response(String request, HashMap<String, String> requestHeaders,
                                   HashMap<String, String> requestParams, String clientIp) {
                String userId = requestParams.getOrDefault("id", "unknown");
                String jsonResponse = "{\"userId\":\"" + userId + "\",\"ip\":\"" + clientIp + "\"}";
                return Response.builder()
                        .bodyAsString(jsonResponse)
                        .statusCode(200)
                        .build();
            }
        });

        // Add POST endpoint
        SimpleServer.addEndpoint("/api/create", new PostHandlerNew() {
            @Override
            public Response response(InputStream requestBody, HashMap<String, String> requestHeaders,
                                   HashMap<String, String> requestParams, String clientIp) {
                try {
                    String body = new String(requestBody.readAllBytes(), StandardCharsets.UTF_8);
                    return Response.builder()
                            .bodyAsString("{\"success\":true,\"received\":\"" + body + "\"}")
                            .statusCode(201)
                            .build();
                } catch (Exception e) {
                    return Response.builder()
                            .bodyAsString("{\"error\":\"Failed to read request\"}")
                            .statusCode(500)
                            .build();
                }
            }
        });
    }
}
// Test GET: curl "http://localhost:25565/api/users?id=123"
// Output: {"userId":"123","ip":"127.0.0.1"}
// Test POST: curl -X POST -d "data" http://localhost:25565/api/create
// Output: {"success":true,"received":"data"}
```

--------------------------------

### Non-annotation SimpleServer Initialization and Endpoint (Java)

Source: https://github.com/zoommax/simpleserver/blob/ossrh/README.MD

Demonstrates starting SimpleServer and adding endpoints programmatically without using annotations. The server is started with `SimpleServer.start(port, threads)`, and endpoints are added using `SimpleServer.addEndpoint()` with a `GetHandlerNew`.

```java
import space.zoommax.SimpleServer;
import space.zoommax.next.Response;
import space.zoommax.next.handlers.GetHandlerNew;

import java.util.HashMap;

public class NotAnnotatedStart {
    //Initialization of server with port 12345 and 4 threads and start it
    public static void main(String[] args) {
        SimpleServer.start(12345, 4);
        test();
    }

    //Add endpoint using SimpleServer.addEndpoint()
    public static void test() {
        SimpleServer.addEndpoint("/test", new GetHandlerNew() {
            @Override
            public Response response(String request, HashMap<String, String> requestHeaders, HashMap<String, String> requestParams, String clientIp) {
                //Endpoint logic
                String body = request;
                //...
                return Response.builder()
                        .bodyAsString(body)
                        .statusCode(200)
                        .build();
            }
        });
    }
}
```

--------------------------------

### Annotation-Based Server Initialization

Source: https://context7.com/zoommax/simpleserver/llms.txt

Initialize and start a web server using the `@InitWebServer` annotation. The server automatically scans for `@Endpoint` annotated methods and registers them.

```APIDOC
## SimpleServer.start() - Annotation-Based Server Initialization

### Description
Initialize and start a web server using the `@InitWebServer` annotation to configure port and thread count. The server automatically scans for `@Endpoint` annotated methods and registers them as request handlers.

### Method
`start()`

### Endpoint
N/A (Server initialization)

### Parameters
No direct parameters for the `start()` method itself. Configuration is done via the `@InitWebServer` annotation.

### Request Body
N/A

### Request Example
```java
import space.zoommax.SimpleServer;
import space.zoommax.next.Request;
import space.zoommax.next.Response;
import space.zoommax.next.annotation.Endpoint;
import space.zoommax.next.annotation.InitWebServer;
import space.zoommax.next.enums.HttpMethod;

@InitWebServer(port = 8080, threads = 4)
public class MyApplication extends SimpleServer {
    public static void main(String[] args) {
        SimpleServer.start();
        // Server now running on port 8080 with 4 threads
    }

    @Endpoint(path = "/hello", httpMethod = HttpMethod.GET, statusCode = 200)
    public Response hello(Request request) {
        String name = request.getParams().getOrDefault("name", "World");
        return Response.builder()
                .bodyAsString("Hello, " + name + "!")
                .statusCode(200)
                .build();
    }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the server has started.

#### Response Example
N/A (Server runs in background)

### Test Example
```bash
curl "http://localhost:8080/hello?name=Alice"
```

### Test Output
```
Hello, Alice!
```
```

--------------------------------

### Start SimpleServer Without Annotations (Java)

Source: https://github.com/zoommax/simpleserver/wiki/en

This Java snippet shows how to initialize SimpleServer programmatically without annotations. The `SimpleServer.start(port, threads)` method is used for server startup, and `SimpleServer.addEndpoint(path, handler)` is used to define request handlers. It requires `ru.zoommax.SimpleServer` and `ru.zoommax.next.handlers.GetHandlerNew`.

```java
import ru.zoommax.SimpleServer;
import ru.zoommax.next.Response;
import ru.zoommax.next.handlers.GetHandlerNew;

import java.util.HashMap;

public class NotAnnotatedStart {
    /*
     * We start the server using SimpleServer.start()
     * SimpleServer.start() starts the server (a singleton is created).
     * Then you can add endpoints to the server's endpoint list.
     * In SimpleServer.start() you need to specify the port and the number of threads.
     */
    public static void main(String[] args) {
        SimpleServer.start(12345, 4);
        test();
    }

    /*
     * We add an endpoint using SimpleServer.addEndpoint()
     * SimpleServer.addEndpoint() takes two parameters: the endpoint path and the handler.
     * Inside the handler, we implement the endpoint logic.
     * We return a Response object.
     */
    public static void test() {
        SimpleServer.addEndpoint("/test", new GetHandlerNew() {
            @Override
            public Response response(String request, HashMap<String, String> requestHeaders, HashMap<String, String> requestParams, String clientIp) {
                //Endpoint logic
                String body = request;
                //...
                return Response.builder()
                        .bodyAsString(body)
                        .statusCode(200)
                        .build();
            }
        });
    }
}
```

--------------------------------

### Programmatic Server Initialization and Endpoint Definition

Source: https://context7.com/zoommax/simpleserver/llms.txt

Start a server programmatically by specifying the port and thread count, and then add endpoints dynamically using `addEndpoint`.

```APIDOC
## SimpleServer.start(int port, int threads) and SimpleServer.addEndpoint()

### Description
Start a server programmatically without annotations, allowing for more flexible configuration and dynamic endpoint registration at runtime. Endpoints can be added for GET and POST requests with custom handler logic.

### Method
`start(int port, int threads)` and `addEndpoint(String path, Handler handler)`

### Endpoint
- `/api/users` (GET)
- `/api/create` (POST)

### Parameters
#### `start(int port, int threads)` Parameters
- **port** (int) - Required - The port number to listen on.
- **threads** (int) - Required - The number of threads in the server's thread pool.

#### `addEndpoint(String path, Handler handler)` Parameters
- **path** (String) - Required - The endpoint path (e.g., `/api/users`).
- **handler** (Handler) - Required - An instance of `GetHandlerNew` or `PostHandlerNew` (or other handler types) to process requests for this path.

### Request Body
- For POST requests to `/api/create`, the request body can contain any string data.

### Request Example
#### GET Request Example
```bash
curl "http://localhost:25565/api/users?id=123"
```

#### POST Request Example
```bash
curl -X POST -d "some data payload" http://localhost:25565/api/create
```

### Response
#### Success Response (200 for GET, 201 for POST)
- **GET `/api/users`**: `{"userId":"(string)","ip":"(string)"}`
- **POST `/api/create`**: `{"success":true,"received":"(string)"}`

#### Error Response (500 for POST on error)
- `{"error":"Failed to read request"}`

#### Response Example
#### GET `/api/users` Response Example
```json
{
    "userId": "123",
    "ip": "127.0.0.1"
}
```

#### POST `/api/create` Response Example
```json
{
    "success": true,
    "received": "some data payload"
}
```

### Code Example for Programmatic Setup
```java
import space.zoommax.SimpleServer;
import space.zoommax.next.Response;
import space.zoommax.next.handlers.GetHandlerNew;
import space.zoommax.next.handlers.PostHandlerNew;

import java.util.HashMap;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;

public class ProgrammaticServer {
    public static void main(String[] args) {
        SimpleServer.start(25565, 4);

        // Add GET endpoint
        SimpleServer.addEndpoint("/api/users", new GetHandlerNew() {
            @Override
            public Response response(String request, HashMap<String, String> requestHeaders,
                                   HashMap<String, String> requestParams, String clientIp) {
                String userId = requestParams.getOrDefault("id", "unknown");
                String jsonResponse = "{\"userId\":\"" + userId + "\",\"ip\":\"" + clientIp + "\"}";
                return Response.builder()
                        .bodyAsString(jsonResponse)
                        .statusCode(200)
                        .build();
            }
        });

        // Add POST endpoint
        SimpleServer.addEndpoint("/api/create", new PostHandlerNew() {
            @Override
            public Response response(InputStream requestBody, HashMap<String, String> requestHeaders,
                                   HashMap<String, String> requestParams, String clientIp) {
                try {
                    String body = new String(requestBody.readAllBytes(), StandardCharsets.UTF_8);
                    return Response.builder()
                            .bodyAsString("{\"success\":true,\"received\":\"" + body + "\"}")
                            .statusCode(201)
                            .build();
                } catch (Exception e) {
                    return Response.builder()
                            .bodyAsString("{\"error\":\"Failed to read request\"}")
                            .statusCode(500)
                            .build();
                }
            }
        });
    }
}
```
```

--------------------------------

### Implement GET Request Handler with URL Decoding and Header Parsing (Java)

Source: https://context7.com/zoommax/simpleserver/llms.txt

Shows how to implement a GET request handler using the `GetHandlerNew` interface in Java. It automatically handles URL decoding, header parsing, and parameter extraction. Dependencies include `space.zoommax.SimpleServer`, `space.zoommax.next.Response`, and `space.zoommax.next.handlers.GetHandlerNew`. The `response` method receives decoded request, headers, parameters, and client IP, returning a `Response` object.

```java
import space.zoommax.SimpleServer;
import space.zoommax.next.Response;
import space.zoommax.next.handlers.GetHandlerNew;

import java.util.HashMap;

public class GetHandlerExample {
    public static void main(String[] args) {
        SimpleServer.start(8080, 4);

        SimpleServer.addEndpoint("/search", new GetHandlerNew() {
            @Override
            public Response response(String request, HashMap<String, String> requestHeaders,
                                   HashMap<String, String> requestParams, String clientIp) {
                // Request is already URL-decoded
                String query = requestParams.getOrDefault("q", "");
                String page = requestParams.getOrDefault("page", "1");
                String limit = requestParams.getOrDefault("limit", "10");

                // Check authentication header
                String apiKey = requestHeaders.get("x-api-key");
                if (apiKey == null || !apiKey.equals("secret123")) {
                    return Response.builder()
                            .bodyAsString("{\"error\":\"Unauthorized\"}")
                            .statusCode(401)
                            .build();
                }

                // Log request
                System.out.println("Search from " + clientIp + ": " + query);

                // Simulate search results
                String results = String.format(
                    "{\"query\":\"%s\",\"page\":%s,\"limit\":%s,\"results\":[{\"id\":1,\"title\":\"Result 1\"}]}",
                    query, page, limit
                );

                return Response.builder()
                        .bodyAsString(results)
                        .statusCode(200)
                        .build();
            }
        });
    }
}
// Test: curl -H "X-Api-Key: secret123" "http://localhost:8080/search?q=java&page=1&limit=20"
// Output: {"query":"java","page":1,"limit":20,"results":[{"id":1,"title":"Result 1"}]}
// Test unauthorized: curl "http://localhost:8080/search?q=java"
// Output: {"error":"Unauthorized"} (HTTP 401)
```

--------------------------------

### Invoice Creation Response JSON Example

Source: https://github.com/zoommax/simpleserver/blob/ossrh/README.MD

Example JSON response for a successfully created invoice. It includes fields like UID, address, amount, dates, and status. The 'status' field can be one of WAITING, PAID, EXPIRED, or NULL.

```json
{
   "UID": "123e4567-e89b-12d3-a456-426614174000-1622542800000",
   "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
   "amount": 0.01,
   "createDate": 1622542800000,
   "expirationDate": 1622546400000,
   "paidDate": 0,
   "status": "WAITING"
}
```

--------------------------------

### GET /search

Source: https://context7.com/zoommax/simpleserver/llms.txt

Implement a GET request handler for searching. This endpoint supports URL decoding, header parsing (including API key authentication), and parameter extraction.

```APIDOC
## GET /search

### Description
This endpoint handles GET requests for search functionality. It automatically decodes URLs, parses headers (including API key authentication), and extracts query parameters. Logs search queries and returns simulated search results.

### Method
GET

### Endpoint
/search

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query term.
- **page** (string) - Optional - The page number for search results. Defaults to '1'.
- **limit** (string) - Optional - The number of results per page. Defaults to '10'.

#### Request Headers
- **X-Api-Key** (string) - Required - The API key for authentication. Must be 'secret123'.

### Request Example
```bash
curl -H "X-Api-Key: secret123" "http://localhost:8080/search?q=java&page=1&limit=20"
```

### Response
#### Success Response (200)
- **body** (string) - A JSON string containing the search query, page, limit, and simulated results.

#### Error Response (401)
- **body** (string) - A JSON string with an error message if the API key is missing or invalid.

#### Response Example (Success)
```json
{
  "query": "java",
  "page": "1",
  "limit": "20",
  "results": [
    {
      "id": 1,
      "title": "Result 1"
    }
  ]
}
```

#### Response Example (Unauthorized)
```json
{
  "error": "Unauthorized"
}
```
```

--------------------------------

### GET /api/resource

Source: https://context7.com/zoommax/simpleserver/llms.txt

This endpoint allows fetching a resource with the ability to specify the desired response format (JSON, XML, or binary) and custom headers.

```APIDOC
## GET /api/resource

### Description
This endpoint allows fetching a resource. The response format (JSON, XML, or binary) can be specified via a query parameter. Custom headers are also supported.

### Method
GET

### Endpoint
/api/resource

### Parameters
#### Query Parameters
- **format** (string) - Optional - The desired response format. Accepted values are 'json', 'xml', or 'binary'. Defaults to 'json'.

### Request Example
```bash
curl -i "http://localhost:8080/api/resource?format=json"
```

### Response
#### Success Response (200)
- **body** (string or bytes) - The response body, content type depends on the 'format' query parameter.
- **headers** (Headers) - Custom headers, including 'Content-Type' and 'X-Custom-Header'.

#### Response Example (JSON)
```json
{
  "id": 1,
  "name": "Resource"
}
```

#### Response Example (XML)
```xml
<resource>
  <id>1</id>
  <name>Resource</name>
</resource>
```

#### Response Example (Binary)
```
Hello
```
```

--------------------------------

### Create Invoice Endpoint Documentation (Java)

Source: https://github.com/zoommax/simpleserver/blob/ossrh/README.MD

This Java code defines the 'createInvoice' endpoint for the SimpleServer API. It handles GET requests, validates parameters like 'newAddress', 'amount', and 'address', and generates an invoice with a unique ID, amount, address, and status. It returns a JSON response containing the invoice details.

```java
@InitWebServer(port = 25565, titleHomePage = "Documentation for WalletAPI",
        descriptionHomePage = "This is a documentation of WalletAPI. You can see all available endpoints and their descriptions.")
@CreateDocumentation(value = true)
public class API extends SimpleServer {
    private static CryptoWallet wallet;
    private static final Logger logger = LoggerFactory.getLogger(API.class);

    public void start(CryptoWallet wallet) {
        API.wallet = wallet;
        SimpleServer.start();
    }

    @Endpoint(path = "/api/v1/createInvoice", httpMethod = HttpMethod.GET)
    @ApiVersion("1.0")
    @PropertyDoc(name = {"newAddress", "amount", "address"},
            description = {"Create new address", "Amount", "Address (required if newAddress is false)"},
            type = {"Boolean", "Double", "String"},
            required = {true, true, false})
    @RequestDoc("Create invoice")
    @ResponseDoc(code = {200}, description = "Invoice created. Returns json with invoice info\n" +
            "\n" +
            "Example: \n" +
            "```json\n" +
            "{\n" +
            "   \"UID\": \"123e4567-e89b-12d3-a456-426614174000-1622542800000\",\n" +
            "   \"address\": \"1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa\",\n" +
            "   \"amount\": 0.01,\n" +
            "   \"createDate\": 1622542800000,\n" +
            "   \"expirationDate\": 1622546400000,\n" +
            "   \"paidDate\": 0,\n" +
            "   \"status\": \"WAITING\"\n" +
            "}\n" +
            "```\n" +
            "UID - Unique ID of invoice\n" +
            "\n" +
            "address - Address to send payment\n" +
            "\n" +
            "amount - Amount of invoice\n" +
            "\n" +
            "createDate - Date of creation\n" +
            "\n" +
            "expirationDate - Date of expiration\n" +
            "\n" +
            "paidDate - Date of payment\n" +
            "\n" +
            "status - Status of invoice\n" +
            "\n" +
            "Statuses: WAITING, PAID, EXPIRED, NULL")
    public static Response createInvoice(Request request) {
        logger.debug(request.getParams() + "");
        InvoicePojo invoicePojo = new InvoicePojo();
        String body = "";
        boolean newAddress = request.getParams().get("newAddress") != null && request.getParams().get("newAddress").equals("true");
        logger.debug("New address: " + newAddress);
        String address = "";
        if (newAddress) {
            address = wallet.getReceiveAddress();
        } else {
            address = request.getParams().get("address");
        }
        logger.debug("Address: " + address);
        double amount = request.getParams().get("amount") != null ? Double.parseDouble(request.getParams().get("amount")) : 0;
        logger.debug("Amount: " + amount);
        if (amount > 0) {
            invoicePojo.setUid(UUID.randomUUID() + "-" + System.currentTimeMillis());
            invoicePojo.setAmount(amount);
            invoicePojo.setAddress(address);
            invoicePojo.setCreateDate(System.currentTimeMillis());
            invoicePojo.setExpirationDate(System.currentTimeMillis() + 3600000);
            invoicePojo.setStatus(InvoiceStatus.WAITING);
            if (invoicePojo.insert()) {
                ObjectMapper objectMapper = new ObjectMapper();
                try {
                    body = objectMapper.writeValueAsString(invoicePojo);
                } catch (Exception e) {
                    logger.error("Error creating payment", e);
                }
            }
        }
        return Response.builder()
                .bodyAsString(body)
                .statusCode(200)
                .build();
    }
}
```

--------------------------------

### Built-in Health Check Endpoint in Java

Source: https://context7.com/zoommax/simpleserver/llms.txt

SimpleServer automatically includes a `/alife` endpoint for liveness checks. This endpoint responds with 'life' and an HTTP 200 status code, facilitating server monitoring and load balancing. It requires starting the server with `SimpleServer.start()`.

```java
import space.zoommax.SimpleServer;

public class HealthCheckExample {
    public static void main(String[] args) {
        SimpleServer.start(8080, 2);
        System.out.println("Server started. Health check available at /alife");
    }
}
// Test: curl http://localhost:8080/alife
// Output: life (HTTP 200)
// This endpoint is automatically created and useful for load balancers and monitoring systems

```

--------------------------------

### GET /api/v1/users

Source: https://context7.com/zoommax/simpleserver/llms.txt

Retrieves a list of users with pagination support. You can specify the page number and the number of results per page.

```APIDOC
## GET /api/v1/users

### Description
Retrieves a list of users with pagination support. You can specify the page number and the number of results per page.

### Method
GET

### Endpoint
/api/v1/users

### Parameters
#### Query Parameters
- **page** (Integer) - Optional - Page number
- **limit** (Integer) - Optional - Results per page
- **sort** (String) - Optional - Sort field

#### Request Body
- **No request body defined**

### Request Example
(No request body for GET request)

### Response
#### Success Response (200)
- **users** (Array) - An array of user objects
- **total** (Integer) - Total number of users available
- **page** (Integer) - Current page number

#### Response Example
```json
{
  "users": [
    {
      "id": "12345",
      "username": "alice"
    }
  ],
  "total": 1,
  "page": 1
}
```
```

--------------------------------

### Annotation-based SimpleServer with Class Extension (Java)

Source: https://github.com/zoommax/simpleserver/blob/ossrh/README.MD

Illustrates initializing SimpleServer and defining endpoints by extending the `SimpleServer` class and using annotations. The `@InitWebServer` annotation is applied directly to the class.

```java
import space.zoommax.SimpleServer;
import space.zoommax.next.Request;
import space.zoommax.next.Response;
import space.zoommax.next.annotation.Endpoint;
import space.zoommax.next.annotation.InitWebServer;
import space.zoommax.next.enums.HttpMethod;

@InitWebServer(port = 12345, threads = 4)
public class AnnotatedStartWithExtends extends SimpleServer {
    public static void main(String[] args) {

    }

    @Endpoint(path = "/test", httpMethod = HttpMethod.GET, statusCode = 200, filterContentLength = -1)
    public Response test(Request request) {
        return Response.builder()
                .bodyAsString(request.getBodyAsString())
                .statusCode(200)
                .build();
    }
}
```

--------------------------------

### Annotation-based SimpleServer Initialization and Endpoint (Java)

Source: https://github.com/zoommax/simpleserver/blob/ossrh/README.MD

Shows how to use annotations to initialize SimpleServer and define endpoints. The `@InitWebServer` annotation sets up the server with a specified port and thread count, while `@Endpoint` defines request mappings.

```java
//Import libraries

import space.zoommax.SimpleServer;
import space.zoommax.next.Request;
import space.zoommax.next.Response;
import space.zoommax.next.annotation.Endpoint;
import space.zoommax.next.annotation.InitWebServer;
import space.zoommax.next.enums.HttpMethod;

public class AnnotatedStart {
    //Initialization of server with port 12345 and 4 threads using annotation InitWebServer
    @InitWebServer(port = 12345, threads = 4)
    public static void main(String[] args) {
        //Start server using SimpleServer.start()
        SimpleServer.start();
    }

    //Add endpoint using annotation Endpoint
    @Endpoint(path = "/test", httpMethod = HttpMethod.GET, statusCode = 200, filterContentLength = -1)
    public Response test(Request request) {
        //Endpoint logic
        String body = request.getBodyAsString();
        //...

        //Return response
        return Response.builder()
                .bodyAsString(body)
                .statusCode(200)
                .build();
    }
}
```

--------------------------------

### Build HTTP Responses with Custom Body, Status, Headers (Java)

Source: https://context7.com/zoommax/simpleserver/llms.txt

Demonstrates building HTTP responses using a builder pattern in Java. It allows setting custom string or byte bodies, status codes, and headers. Dependencies include `com.sun.net.httpserver.Headers`, `space.zoommax.next.Response`, `space.zoommax.next.Request`, and `space.zoommax.next.annotation.Endpoint`. The function takes a `Request` object and returns a `Response` object.

```java
import com.sun.net.httpserver.Headers;
import space.zoommax.next.Response;
import space.zoommax.next.Request;
import space.zoommax.next.annotation.Endpoint;
import space.zoommax.next.enums.HttpMethod;

@Endpoint(path = "/api/resource", httpMethod = HttpMethod.GET, statusCode = 200)
public Response getResource(Request request) {
    String format = request.getParams().getOrDefault("format", "json");

    // Create custom headers
    Headers customHeaders = new Headers();
    customHeaders.add("X-Custom-Header", "CustomValue");
    customHeaders.add("Cache-Control", "no-cache");

    if (format.equals("json")) {
        customHeaders.add("Content-Type", "application/json");
        return Response.builder()
                .bodyAsString("{\"id\":1,\"name\":\"Resource\"}")
                .statusCode(200)
                .headers(customHeaders)
                .build();
    } else if (format.equals("xml")) {
        customHeaders.add("Content-Type", "application/xml");
        return Response.builder()
                .bodyAsString("<resource><id>1</id><name>Resource</name></resource>")
                .statusCode(200)
                .headers(customHeaders)
                .build();
    } else if (format.equals("binary")) {
        byte[] binaryData = new byte[]{0x48, 0x65, 0x6C, 0x6C, 0x6F}; // "Hello"
        customHeaders.add("Content-Type", "application/octet-stream");
        return Response.builder()
                .bodyAsBytes(binaryData)
                .statusCode(200)
                .headers(customHeaders)
                .build();
    }

    return Response.builder()
            .bodyAsString("{\"error\":\"Unsupported format\"}")
            .statusCode(400)
            .build();
}
// Test JSON: curl -i "http://localhost:8080/api/resource?format=json"
// Output: HTTP/1.1 200 OK, Content-Type: application/json, {"id":1,"name":"Resource"}
// Test XML: curl -i "http://localhost:8080/api/resource?format=xml"
// Output: HTTP/1.1 200 OK, Content-Type: application/xml, <resource>...</resource>
```

--------------------------------

### Generate API Documentation with Annotations in Java

Source: https://context7.com/zoommax/simpleserver/llms.txt

Automatically generates Markdown API documentation using annotations. It requires the SimpleServer library and serves documentation at the `/docs` endpoint. The documentation includes request/response specifications, property details, and versioning.

```java
import space.zoommax.SimpleServer;
import space.zoommax.next.Request;
import space.zoommax.next.Response;
import space.zoommax.next.annotation.Endpoint;
import space.zoommax.next.annotation.InitWebServer;
import space.zoommax.next.annotation.documentation.*;
import space.zoommax.next.enums.HttpMethod;

@InitWebServer(port = 8080, threads = 4,
    titleHomePage = "My API Documentation",
    descriptionHomePage = "Comprehensive API documentation for all available endpoints.")
@CreateDocumentation(value = true)
public class DocumentedAPI extends SimpleServer {
    public static void main(String[] args) {
        SimpleServer.start();
    }

    @Endpoint(path = "/api/v1/users", httpMethod = HttpMethod.POST)
    @ApiVersion("1.0")
    @PropertyDoc(
        name = {"username", "email", "password"},
        description = {"User's username", "User's email address", "User's password"},
        type = {"String", "String", "String"},
        required = {true, true, true}
    )
    @RequestDoc("Create a new user account")
    @ResponseDoc(
        code = {201, 400, 409},
        description = {
            "User created successfully. Returns user object with generated ID.",
            "Invalid request. Missing required fields or invalid data format.",
            "Conflict. User with this email already exists."
        }
    )
    public Response createUser(Request request) {
        String body = request.getBodyAsString();
        // Parse JSON and validate
        // For demo, return success
        return Response.builder()
                .bodyAsString("{\"id\":\"12345\",\"username\":\"alice\",\"email\":\"alice@example.com\",\"created\":\"2024-01-15T10:30:00Z\"}")
                .statusCode(201)
                .build();
    }

    @Endpoint(path = "/api/v1/users", httpMethod = HttpMethod.GET)
    @ApiVersion("1.0")
    @PropertyDoc(
        name = {"page", "limit", "sort"},
        description = {"Page number", "Results per page", "Sort field"},
        type = {"Integer", "Integer", "String"},
        required = {false, false, false}
    )
    @RequestDoc("Retrieve list of users with pagination")
    @ResponseDoc(
        code = {200},
        description = {"Returns array of user objects"}
    )
    public Response getUsers(Request request) {
        return Response.builder()
                .bodyAsString("{\"users\":[{\"id\":\"12345\",\"username\":\"alice\"}],\"total\":1,\"page\":1}")
                .statusCode(200)
                .build();
    }
}
// Access documentation: curl http://localhost:8080/docs
// Documentation is automatically generated in Markdown format with tables showing properties, types, and requirements

```

--------------------------------

### Deprecated SimpleServer Usage (Java)

Source: https://github.com/zoommax/simpleserver/blob/ossrh/README.MD

Demonstrates the older way of using SimpleServer by explicitly initializing the server and defining endpoints with GetHandler and PostHandler. This approach requires manual endpoint registration.

```java
// Import libraries

import space.zoommax.EndPoint;
import space.zoommax.GetHandler;
import space.zoommax.PostHandler;
import space.zoommax.SimpleServer;

import java.util.HashMap;

public class Test {
    public static void main(String[] args) {
        // Initialize the server by specifying the port it will listen on
        SimpleServer.init(8080);

        // Create an endpoint that handles GET requests
        // Here's an example of an endpoint that simply returns the request it received
        EndPoint test = EndPoint.builder().handler(new GetHandler() {
            @Override
            public String response(String request, HashMap<String, String> requestHeaders, HashMap<String, String> requestParams, String clientIp) {
                // You can access request headers, request parameters, and client IP address here
                // Customize the response based on the request if needed
                return request;
            }
        }).endPointName("test").build();

        // Add the created endpoint to the server
        test.add();

        // Create another endpoint that handles POST requests
        // Here's an example of an endpoint that simply returns the request body it received
        EndPoint test2 = EndPoint.builder().handler(new PostHandler() {
            @Override
            public String response(String requestBody, HashMap<String, String> requestHeaders, String clientIp) {
                // You can access request headers, request body, and client IP address here
                // Customize the response based on the request if needed
                return requestBody;
            }
        }).endPointName("test2").build();

        // Add the second endpoint to the server
        test2.add();
    }
}
// Additionally, you can pass an HttpHandler to the endpoint builder. GetHandler and PostHandler inherit from HttpHandler.
```

--------------------------------

### POST /api/v1/users

Source: https://context7.com/zoommax/simpleserver/llms.txt

Creates a new user account. This endpoint accepts user details in the request body and returns the created user object upon success.

```APIDOC
## POST /api/v1/users

### Description
Creates a new user account. This endpoint accepts user details in the request body and returns the created user object upon success.

### Method
POST

### Endpoint
/api/v1/users

### Parameters
#### Query Parameters
- **No query parameters defined**

#### Request Body
- **username** (String) - Required - User's username
- **email** (String) - Required - User's email address
- **password** (String) - Required - User's password

### Request Example
```json
{
  "username": "alice",
  "email": "alice@example.com",
  "password": "securepassword123"
}
```

### Response
#### Success Response (201)
- **id** (String) - Description of the user ID
- **username** (String) - Username of the created user
- **email** (String) - Email of the created user
- **created** (String) - Timestamp of user creation

#### Error Response (400)
- **Description**: Invalid request. Missing required fields or invalid data format.

#### Error Response (409)
- **Description**: Conflict. User with this email already exists.

#### Response Example
```json
{
  "id": "12345",
  "username": "alice",
  "email": "alice@example.com",
  "created": "2024-01-15T10:30:00Z"
}
```
```

--------------------------------

### SimpleServer Gradle Dependency

Source: https://github.com/zoommax/simpleserver/blob/ossrh/README.MD

This Groovy snippet demonstrates how to include the SimpleServer library in a Gradle project. Replace '1.9.8' with the desired version.

```groovy
implementation 'space.zoommax:SimpleServer:1.9.8'
```

--------------------------------

### POST /api/submit

Source: https://context7.com/zoommax/simpleserver/llms.txt

Handles POST requests, allowing access to the request body as an InputStream, automatic header parsing, and parameter extraction. Includes request size limits and error handling.

```APIDOC
## POST /api/submit

### Description
This endpoint handles POST requests, providing access to the raw request body as an InputStream, parsed request headers, query parameters, and the client's IP address. It includes logic for handling large requests and processing data based on query parameters.

### Method
POST

### Endpoint
/api/submit

#### Query Parameters
- **action** (string) - Optional - Specifies the action to perform (defaults to 'create').

#### Request Body
- **(InputStream)** - The raw request body.

### Request Example
```bash
curl -X POST -H "Content-Type: application/json" -d '{"user":"alice","email":"alice@example.com"}' "http://localhost:8080/api/submit?action=register"
```

### Response
#### Success Response (201)
- **success** (boolean) - Indicates if the request was processed successfully.
- **action** (string) - The action that was performed.
- **contentType** (string) - The Content-Type header of the request.
- **size** (integer) - The size of the request body in bytes.

#### Error Response (413)
- **error** (string) - Description of the error (e.g., "Request too large").

#### Error Response (500)
- **error** (string) - Description of the internal server error.

### Response Example (Success)
```json
{
  "success": true,
  "action": "register",
  "contentType": "application/json",
  "size": 45
}
```
```

--------------------------------

### POST /api/v1/createInvoice

Source: https://github.com/zoommax/simpleserver/blob/ossrh/README.MD

Creates an invoice with specified details. It can generate a new address or use a provided one, and sets the payment amount and other invoice properties.

```APIDOC
## GET /api/v1/createInvoice

### Description
Creates an invoice with specified details. It can generate a new address or use a provided one, and sets the payment amount and other invoice properties.

### Method
GET

### Endpoint
/api/v1/createInvoice

### Parameters
#### Query Parameters
- **newAddress** (Boolean) - Required - Create new address
- **amount** (Double) - Required - Amount
- **address** (String) - Optional - Address (required if newAddress is false)

### Request Example
```json
{
  "example": "N/A - GET request with query parameters"
}
```

### Response
#### Success Response (200)
- **UID** (String) - Unique ID of invoice
- **address** (String) - Address to send payment
- **amount** (Double) - Amount of invoice
- **createDate** (Long) - Date of creation
- **expirationDate** (Long) - Date of expiration
- **paidDate** (Long) - Date of payment
- **status** (String) - Status of invoice (WAITING, PAID, EXPIRED, NULL)

#### Response Example
```json
{
   "UID": "123e4567-e89b-12d3-a456-426614174000-1622542800000",
   "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
   "amount": 0.01,
   "createDate": 1622542800000,
   "expirationDate": 1622546400000,
   "paidDate": 0,
   "status": "WAITING"
}
```
```

--------------------------------

### Implement POST Request Handler with PostHandlerNew in Java

Source: https://context7.com/zoommax/simpleserver/llms.txt

This Java code defines a POST request handler for a SimpleServer application. It demonstrates reading the request body from an InputStream, accessing request headers like 'content-type' and 'content-length', extracting query parameters, and handling potential request size limits. The handler returns a JSON response indicating success, the action performed, content type, and size, or an error message if processing fails.

```java
import space.zoommax.SimpleServer;
import space.zoommax.next.Response;
import space.zoommax.next.handlers.PostHandlerNew;

import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.util.HashMap;

public class PostHandlerExample {
    public static void main(String[] args) {
        SimpleServer.start(8080, 4);

        SimpleServer.addEndpoint("/api/submit", new PostHandlerNew() {
            @Override
            public Response response(InputStream requestBody, HashMap<String, String> requestHeaders,
                                   HashMap<String, String> requestParams, String clientIp) {
                try {
                    // Read request body
                    byte[] bodyBytes = requestBody.readAllBytes();
                    String bodyString = new String(bodyBytes, StandardCharsets.UTF_8);

                    // Check content type
                    String contentType = requestHeaders.getOrDefault("content-type", "");

                    // Check content length
                    String contentLength = requestHeaders.get("content-length");
                    int length = contentLength != null ? Integer.parseInt(contentLength) : 0;

                    if (length > 1048576) { // 1MB limit
                        return Response.builder()
                                .bodyAsString("{\"error\":\"Request too large\"}")
                                .statusCode(413)
                                .build();
                    }

                    // Parse query parameters
                    String action = requestParams.getOrDefault("action", "create");

                    // Process request
                    System.out.println("Received from " + clientIp + ": " + bodyString);

                    // Build response
                    String response = String.format(
                        "{\"success\":true,\"action\":\"%s\",\"contentType\":\"%s\",\"size\":%d}",
                        action, contentType, bodyBytes.length
                    );

                    return Response.builder()
                            .bodyAsString(response)
                            .statusCode(201)
                            .build();

                } catch (Exception e) {
                    return Response.builder()
                            .bodyAsString("{\"error\":\"" + e.getMessage() + "\"}")
                            .statusCode(500)
                            .build();
                }
            }
        });
    }
}
// Test: curl -X POST -H "Content-Type: application/json" -d '{"user":"alice","email":"alice@example.com"}' "http://localhost:8080/api/submit?action=register"
// Output: {"success":true,"action":"register","contentType":"application/json","size":45}
```

--------------------------------

### SimpleServer Maven Dependency

Source: https://github.com/zoommax/simpleserver/blob/ossrh/README.MD

This XML snippet shows how to add the SimpleServer library as a dependency in a Maven project. Ensure you are using the correct version for compatibility.

```xml
<dependencies>
    <dependency>
        <groupId>space.zoommax</groupId>
        <artifactId>SimpleServer</artifactId>
        <version>1.9.8</version>
    </dependency>
</dependencies>
```
Tokens:
Raw