### Start Light-4j Server from Command Line

Source: https://github.com/networknt/light-4j/blob/master/README.md

Use this command to start the Light-4j server after building the project. Ensure the JAR file path is correct.

```bash
java -jar target/demo-0.1.0.jar
```

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

### Datasource Configuration Example (datasource.yml)

Source: https://github.com/networknt/light-4j/blob/master/data-source/README.md

This file defines the datasource configuration, referencing values from values.yml.

```yaml
MysqlDataSource: ${datasource.MysqlDataSource:}
```

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

### Service Singleton Configuration Example (service.yml)

Source: https://github.com/networknt/light-4j/blob/master/data-source/README.md

This file configures service singletons, including datasource configurations.

```yaml
singletons:
  - com.networknt.decrypt.Decryptor:
      - com.networknt.decrypt.AESDecryptor

  - com.networknt.db.GenericDataSource:
      - com.networknt.db.MysqlDataSource:
          - java.lang.String:

  - com.networknt.accountservic.dao.AccountDao:
      - com.networknt.accountservic.dao.AccountDaoImpl
```

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

### Register Custom Module with Configuration

Source: https://github.com/networknt/light-4j/wiki/Info

Example of how to register a custom module and its configuration using ModuleRegistry. This is typically done during server startup.

```java
ModuleRegistry.registerModule(ValidatorHandler.class.getName(), Config.getInstance().getJsonMapConfigNoCache(ValidatorHandler.CONFIG_NAME), null);
```

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

### Values Configuration Example (values.yml)

Source: https://github.com/networknt/light-4j/blob/master/data-source/README.md

This file contains detailed configuration for datasources, including connection details, HikariCP settings, and additional parameters.

```yaml
# Service Singletons
service.singletons:
  - com.networknt.decrypt.Decryptor:
      - com.networknt.decrypt.AESDecryptor

  - com.networknt.db.GenericDataSource:
      - com.networknt.db.MysqlDataSource:
          - java.lang.String:

  - com.networknt.accountservic.dao.AccountDao:
      - com.networknt.accountservic.dao.AccountDaoImpl


# datasource.yml
datasource.MysqlDataSource:
  DriverClassName: com.mysql.jdbc.Driver
  jdbcUrl: jdbc:mysql://localhost:3308/account_db?useSSL=false
  username: account_user
  password: CRYPT:e6e1b4a099902a2106509e87df909de4:cd9153addc755eb7e00d817c:e499d4501d0372fe37073d88a1025f1970a30cbd9acec7d5
  maximumPoolSize: 2
  connectionTimeout: 5000
  settings:
    idleTimeout: 50000
    minimumIdle: 1
  parameters:
    useServerPrepStmts: 'true'
    cachePrepStmts: 'true'
    cacheCallableStmts: 'true'
    prepStmtCacheSize: '4096'
    prepStmtCacheSqlLimit: '2048'
    verifyServerCertificate: 'false'
    useSSL: 'true'
    requireSSL: 'true'
```

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

### Database Configuration Example (db-provider.yml)

Source: https://github.com/networknt/light-4j/blob/master/db-provider/README.md

This configuration file provides all necessary information to create a HikariCP datasource. It supports environment variable overrides for sensitive or environment-specific settings.

```yaml
# For postgres database running in a docker container, you have to use the driverClassName.
# By using the dataSourceClassName, you cannot connect to the database from another docker container.
driverClassName: ${db.driverClassName:org.postgresql.Driver}
jdbcUrl: ${db.jdbcUrl:jdbc:postgresql://timescale:5432/configserver}
username: ${db.username:postgres}
password: ${db.password:secret}
maximumPoolSize: ${db.maximumPoolSize:3}
```

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

### Consul Client and Registry Configuration

Source: https://github.com/networknt/light-4j/blob/master/client/README.md

Example configuration for setting up Consul client and registry within the service.yml or values.yml file. This defines the necessary components for service discovery and load balancing.

```yaml
- com.networknt.registry.URL:
  - com.networknt.registry.URLImpl:
      parameters:
        registryRetryPeriod: '30000'
- com.networknt.consul.client.ConsulClient:
  - com.networknt.consul.client.ConsulClientImpl
- com.networknt.registry.Registry:
  - com.networknt.consul.ConsulRegistry
- com.networknt.balance.LoadBalance:
  - com.networknt.balance.RoundRobinLoadBalance
- com.networknt.cluster.Cluster:
  - com.networknt.cluster.LightCluster
```

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

### Datasource Configuration Example (values.yml)

Source: https://github.com/networknt/light-4j/blob/master/db-provider/README.md

This section within values.yml defines a specific MySQL datasource, including connection details, pool settings, and HikariDataSource parameters. It demonstrates how to use encrypted passwords and configure advanced JDBC properties.

```yaml
datasource.MysqlDataSource:
  DriverClassName: com.mysql.jdbc.Driver
  jdbcUrl: jdbc:mysql://localhost:3308/account_db?useSSL=false
  username: account_user
  password: CRYPT:e6e1b4a099902a2106509e87df909de4:cd9153addc755eb7e00d817c:e499d4501d0372fe37073d88a1025f1970a30cbd9acec7d5
  maximumPoolSize: 2
  connectionTimeout: 5000
  settings:
    idleTimeout: 50000
    minimumIdle: 1
  parameters:
    useServerPrepStmts: 'true'
    cachePrepStmts: 'true'
    cacheCallableStmts: 'true'
    prepStmtCacheSize: '4096'
    prepStmtCacheSqlLimit: '2048'
    verifyServerCertificate: 'false'
    useSSL: 'true'
    requireSSL: 'true'
```

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

### Controller JWKS Endpoint Example

Source: https://github.com/networknt/light-4j/blob/master/portal-registry/controller-rs-backend-plan.md

Example of a controller's JWKS endpoint used for verifying service JWTs. This endpoint provides the public keys necessary for token validation.

```text
http://localhost:6881/oauth2/AZZRJE52eXu3t1hseacnGQ/keys
```

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

### PostgreSQL Driver Dependency

Source: https://github.com/networknt/light-4j/blob/master/db-provider/README.md

Add a database driver dependency for your specific database. This example shows the PostgreSQL driver.

```xml
<dependency>
            <groupId>org.postgresql</groupId>
            <artifactId>postgresql</artifactId>
        </dependency>
```

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

### Get DataSource via DataSourceFactory

Source: https://github.com/networknt/light-4j/blob/master/db-provider/README.md

This Java code demonstrates how to obtain a DataSource instance using the SingletonServiceFactory and the DataSourceFactory, specifying the desired datasource name.

```java
DataSource dataSource = SingletonServiceFactory.getBean(DataSourceFactory.class).getDataSource("OracleDataSource");
```

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

### Get Inventory

Source: https://github.com/networknt/light-4j/wiki/Info

Retrieves a map of pet statuses to their quantities.

```APIDOC
## GET /store/inventory

### Description
Returns pet inventories by status. Provides a map of status codes to quantities.

### Method
GET

### Endpoint
/store/inventory

### Parameters
None

### Responses
#### Success Response (200)
- **object** - successful operation. Contains additional properties where keys are status codes (string) and values are quantities (integer).

### Security
- **api_key**
```

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

### Get User By Name

Source: https://github.com/networknt/light-4j/wiki/Info

Retrieves user information by their username. Requires a username as a path parameter.

```APIDOC
## GET /user/{username}

### Description
Get user by user name.

### Method
GET

### Endpoint
/user/{username}

### Parameters
#### Path Parameters
- **username** (string) - Required - The name that needs to be fetched. Use user1 for testing. 

### Request Example

### Response
#### Success Response (200)
- schema: User object

#### Response Example

```

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

### Get Order By ID

Source: https://github.com/networknt/light-4j/wiki/Info

Finds a purchase order by its unique ID.

```APIDOC
## GET /store/order/{orderId}

### Description
Find purchase order by ID. For valid response try integer IDs with value >= 1 and <= 10. Other values will generated exceptions.

### Method
GET

### Endpoint
/store/order/{orderId}

### Parameters
#### Path Parameters
- **orderId** (integer) - Required - ID of pet that needs to be fetched. Must be between 1 and 10.

### Responses
#### Success Response (200)
- **Order** - successful operation
```

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

### Constructing Status Object from Configuration

Source: https://github.com/networknt/light-4j/wiki/Status

Demonstrates how to construct a Status object using a predefined error code from a configuration, such as status.json.

```java
static final String STATUS_METHOD_NOT_ALLOWED = "ERR10008";
.
.
.
Status status = new Status(STATUS_METHOD_NOT_ALLOWED);
```

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

### Load Config When Used

Source: https://github.com/networknt/light-4j/wiki/Config

Loads a specific configuration object when it is first accessed. This approach is suitable for configurations that are not immediately required or are specific to certain modules.

```java
ValidatorConfig config = (ValidatorConfig)Config.getInstance().getJsonObjectConfig(CONFIG_NAME, ValidatorConfig.class);
```

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

### Constructing Status Object with Contextual Description

Source: https://github.com/networknt/light-4j/wiki/Status

Shows how to create a Status object with additional context by passing arguments, allowing for a more detailed error description.

```java
return new Status("ERR11000", queryParameter.getName(), swaggerOperation.getPathString().original());
```

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

### Enable Server Info Handler

Source: https://github.com/networknt/light-4j/wiki/Info

Configuration for the server info endpoint. Set 'enableServerInfo' to true to activate it. If disabled, an error ERR10013 will be returned.

```json
{
  "description": "Server info endpoint that can output environment and component along with configuration",
  "enableServerInfo": true
}
```

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

### Configuration Interface Methods

Source: https://github.com/networknt/light-4j/wiki/Config

Abstract methods for retrieving configuration data in various formats like HashMaps, JsonNodes, POJOs, strings, and InputStreams. Also includes methods for accessing a shared ObjectMapper and clearing the configuration cache.

```java
// Returns a HashMap by a config name (without .json)     
public abstract Map<String, Object> getJsonMapConfig(String configName);

// Load config for server info so that the result can be masked with out impact the cached verison
public abstract Map<String, Object> getJsonMapConfigNoCache(String configName);

// Return a JsonNode by a config name (without .json)
public abstract JsonNode getJsonNodeConfig(String configName);

// Map the json to a POJO from a config name and class name
public abstract Object getJsonObjectConfig(String configName, Class clazz);

// Load config into a string by providing the full filename
public abstract String getStringFromFile(String filename);

// Load config into a InputStream by providing full filename
public abstract InputStream getInputStreamFromFile(String filename);

// A cached Jackson ObjectMapper that is shared to other modules
public abstract ObjectMapper getMapper();

// Clean up the config cache if there are any
public abstract void clear();

```

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

### Create Users with List Input

Source: https://github.com/networknt/light-4j/wiki/Info

Creates a list of users from a given input array.

```APIDOC
## POST /user/createWithList

### Description
Creates a list of users with the provided input array.

### Method
POST

### Endpoint
/user/createWithList

### Parameters
#### Request Body
- **body** (array[User]) - Required - List of user objects

### Responses
#### Success Response (200)
- **description** (string) - Successful operation
```

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

### Create Users with Array Input

Source: https://github.com/networknt/light-4j/wiki/Info

Creates a list of users from a given input array.

```APIDOC
## POST /user/createWithArray

### Description
Creates a list of users with the provided input array.

### Method
POST

### Endpoint
/user/createWithArray

### Parameters
#### Request Body
- **body** (array[User]) - Required - List of user objects

### Responses
#### Success Response (200)
- **description** (string) - Successful operation
```

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

### Discovery Lookup Request

Source: https://github.com/networknt/light-4j/blob/master/portal-registry/controller-rs-contract.md

Send a discovery/lookup request to find available service instances. Specify the service ID, environment tag, and protocol.

```json
{
  "jsonrpc": "2.0",
  "id": "lookup-1",
  "method": "discovery/lookup",
  "params": {
    "serviceId": "com.networknt.user-1.0.0",
    "envTag": "prod",
    "protocol": "https"
  }
}
```

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

### getStringFromFile

Source: https://github.com/networknt/light-4j/wiki/Config

Loads the entire content of a file into a String. Useful for text-based configuration files.

```APIDOC
## getStringFromFile

### Description
Loads the content of a file specified by its full filename into a String.

### Method Signature
`String getStringFromFile(String filename)`

### Parameters
#### Path Parameters
- **filename** (String) - Required - The full path to the file to be loaded.

### Response
- **String** - The content of the file as a String.
```

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

### Login User

Source: https://github.com/networknt/light-4j/wiki/Info

Logs a user into the system.

```APIDOC
## GET /user/login

### Description
Logs a user into the system.

### Method
GET

### Endpoint
/user/login

### Parameters
#### Query Parameters
- **username** (string) - Required - The username for login
- **password** (string) - Required - The password for login in clear text

### Responses
#### Success Response (200)
- **description** (string) - Successful operation
```

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

### Client SSL Trust Store Configuration

Source: https://github.com/networknt/light-4j/blob/master/client/README.md

Configure client-side SSL trust stores for HTTPS requests. Options include loading default system certificates, a custom trust store, or both.

```yaml
  # indicate of system load default cert.
  loadDefaultTrustStore: ${client.loadDefaultTrustStore:false}
  # trust store contains certifictes that server needs. Enable if tls is used.
  loadTrustStore: ${client.loadTrustStore:true}
  # trust store location can be specified here or system properties javax.net.ssl.trustStore and password javax.net.ssl.trustStorePassword
  trustStore: ${client.trustStore:client.truststore}
```

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

### Gracefully Stop Server with PID

Source: https://github.com/networknt/light-4j/blob/master/README.md

Use this command to send a TERM signal to the server process, allowing it to perform a clean shutdown. This is recommended for production environments.

```bash
kill -s TERM <pid>
```

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

### Place Order

Source: https://github.com/networknt/light-4j/wiki/Info

Places an order for a pet.

```APIDOC
## POST /store/order

### Description
Place an order for a pet.

### Method
POST

### Endpoint
/store/order

### Parameters
#### Request Body
- **body** (Order) - Required - order placed for purchasing the pet

### Responses
#### Success Response (200)
- **Order** - successful operation
#### Error Response (400)
- **description** - Invalid Order
```

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

### Discovery Lookup

Source: https://github.com/networknt/light-4j/blob/master/portal-registry/controller-rs-contract.md

Allows clients to look up available service instances based on service ID, environment tag, and protocol.

```APIDOC
## Discovery Lookup

### Description
Retrieves a list of available nodes for a given service.

### Method
POST

### Endpoint
/ws/discovery

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - JSON-RPC protocol version.
- **id** (string) - Required - Unique identifier for the request.
- **method** (string) - Required - The method to call, should be `discovery/lookup`.
- **params** (object) - Required - Parameters for the lookup.
  - **serviceId** (string) - Required - The ID of the service to look up.
  - **envTag** (string) - Required - The environment tag (e.g., 'prod', 'dev').
  - **protocol** (string) - Required - The protocol of the service (e.g., 'https', 'http').

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": "lookup-1",
  "method": "discovery/lookup",
  "params": {
    "serviceId": "com.networknt.user-1.0.0",
    "envTag": "prod",
    "protocol": "https"
  }
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - JSON-RPC protocol version.
- **id** (string) - Unique identifier for the response.
- **result** (object) - The result of the lookup.
  - **serviceId** (string) - The ID of the service.
  - **envTag** (string) - The environment tag.
  - **protocol** (string) - The protocol of the service.
  - **nodes** (array) - An array of service nodes.
    - **runtimeInstanceId** (string) - Unique ID of the runtime instance.
    - **serviceId** (string) - The ID of the service.
    - **envTag** (string) - The environment tag.
    - **environment** (string) - The environment name.
    - **version** (string) - The version of the service.
    - **protocol** (string) - The protocol of the service.
    - **address** (string) - The IP address of the node.
    - **port** (integer) - The port of the node.
    - **tags** (object) - Key-value pairs of tags.
    - **connectedAt** (string) - Timestamp when the node was connected.
    - **lastSeenAt** (string) - Timestamp when the node was last seen.
    - **connected** (boolean) - Indicates if the node is currently connected.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": "lookup-1",
  "result": {
    "serviceId": "com.networknt.user-1.0.0",
    "envTag": "prod",
    "protocol": "https",
    "nodes": [
      {
        "runtimeInstanceId": "0195b1d4-4b3e-7f6b-9f88-47d8b11b0c15",
        "serviceId": "com.networknt.user-1.0.0",
        "envTag": "prod",
        "environment": "prod",
        "version": "1.0.0",
        "protocol": "https",
        "address": "10.0.1.25",
        "port": 8443,
        "tags": {},
        "connectedAt": "2026-03-27T14:00:00Z",
        "lastSeenAt": "2026-03-27T14:00:04Z",
        "connected": true
      }
    ]
  }
}
```
```

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

### Datasource Factory Configuration (service.yml)

Source: https://github.com/networknt/light-4j/blob/master/data-source/README.md

Configures the DataSourceFactory for obtaining datasources.

```yaml
- com.networknt.db.factory.DataSourceFactory:
    - com.networknt.db.factory.DefaultDataSourceFactory
```

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

### getJsonMapConfig

Source: https://github.com/networknt/light-4j/wiki/Config

Retrieves a configuration as a HashMap based on the provided config name. The '.json' extension is automatically handled.

```APIDOC
## getJsonMapConfig

### Description
Returns a HashMap representation of a configuration file identified by its name. The '.json' extension is not required in the `configName` parameter.

### Method Signature
`Map<String, Object> getJsonMapConfig(String configName)`

### Parameters
#### Path Parameters
- **configName** (String) - Required - The name of the configuration file (without the .json extension).

### Response
- **Map<String, Object>** - A HashMap containing the configuration data.
```

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

### clear

Source: https://github.com/networknt/light-4j/wiki/Config

Clears the internal configuration cache, ensuring that subsequent requests fetch fresh configuration data.

```APIDOC
## clear

### Description
Clears any cached configuration data. This method should be used when configuration changes need to be reflected immediately.

### Method Signature
`void clear()`

### Response
- None (void method).
```

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

### getJsonMapConfigNoCache

Source: https://github.com/networknt/light-4j/wiki/Config

Retrieves a configuration as a HashMap, ensuring that cached versions are not used. This is useful for dynamic configurations.

```APIDOC
## getJsonMapConfigNoCache

### Description
Loads and returns a configuration as a HashMap, bypassing any cached versions. This ensures the latest configuration is retrieved, which is important for server info masking.

### Method Signature
`Map<String, Object> getJsonMapConfigNoCache(String configName)`

### Parameters
#### Path Parameters
- **configName** (String) - Required - The name of the configuration file (without the .json extension).

### Response
- **Map<String, Object>** - A HashMap containing the fresh configuration data.
```

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

### Create User

Source: https://github.com/networknt/light-4j/wiki/Info

Creates a new user. This operation can only be performed by the currently logged-in user.

```APIDOC
## POST /user

### Description
Creates a new user.

### Method
POST

### Endpoint
/user

### Parameters
#### Request Body
- **body** (User) - Required - Created user object

### Responses
#### Success Response (200)
- **description** (string) - Successful operation
```

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

### Discovery Subscribe Request

Source: https://github.com/networknt/light-4j/blob/master/portal-registry/controller-rs-contract.md

Send a discovery/subscribe request to register for live updates about a specific service. This enables subsequent discovery/changed notifications.

```json
{
  "jsonrpc": "2.0",
  "id": "subscribe-1",
  "method": "discovery/subscribe",
  "params": {
    "serviceId": "com.networknt.user-1.0.0",
    "envTag": "prod",
    "protocol": "https"
  }
}
```

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

### Load Config into Static Variable

Source: https://github.com/networknt/light-4j/wiki/Config

Loads the JSON configuration into a static map variable. This is useful for configurations that are needed globally and early in the application lifecycle.

```java
static final Map<String, Object> config = Config.getInstance().getJsonMapConfig(JwtHelper.SECURITY_CONFIG);
```

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

### getInputStreamFromFile

Source: https://github.com/networknt/light-4j/wiki/Config

Loads the content of a file as an InputStream, suitable for binary files or large text files.

```APIDOC
## getInputStreamFromFile

### Description
Loads the content of a file specified by its full filename into an InputStream.

### Method Signature
`InputStream getInputStreamFromFile(String filename)`

### Parameters
#### Path Parameters
- **filename** (String) - Required - The full path to the file to be loaded.

### Response
- **InputStream** - An InputStream representing the file content.
```

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

### Undertow Swagger-Codegen Petstore API Output

Source: https://github.com/networknt/light-4j/wiki/Info

This JSON represents the output from the undertow swagger-codegen petstore specification. It includes environment details, runtime information, system properties, and the API specification structure.

```json
{
  "environment": {
    "host": {
      "ip": "127.0.0.1",
      "hostname": "joy",
      "dns": "localhost"
    },
    "runtime": {
      "availableProcessors": 4,
      "freeMemory": 430837608,
      "totalMemory": 504889344,
      "maxMemory": 7486832640
    },
    "system": {
      "javaVendor": "Oracle Corporation",
      "javaVersion": "1.8.0_66",
      "osName": "Linux",
      "osVersion": "4.2.0-42-generic",
      "userTimezone": "America/Toronto"
    }
  },
  "specification": {
    "basePath": "/v2",
    "paths": {
      "/pet": {
        "post": {
          "tags": [
            "pet"
          ],
          "summary": "Add a new pet to the store",
          "description": "",
          "operationId": "addPet",
          "consumes": [
            "application/json",
            "application/xml"
          ],
          "produces": [
            "application/xml",
            "application/json"
          ],
          "parameters": [
            {
              "in": "body",
              "name": "body",
              "description": "Pet object that needs to be added to the store",
              "required": true,
              "schema": {
                "$ref": "#/definitions/Pet"
              }
            }
          ],
          "responses": {
            "405": {
              "description": "Invalid input"
            }
          },
          "security": [
            {
              "petstore_auth": [
                "write:pets",
                "read:pets"
              ]
            }
          ],
          "x-accepts": "application/json",
          "x-contentType": "application/json"
        },
        "put": {
          "tags": [
            "pet"
          ],
          "summary": "Update an existing pet",
          "description": "",
          "operationId": "updatePet",
          "consumes": [
            "application/json",
            "application/xml"
          ],
          "produces": [
            "application/xml",
            "application/json"
          ],
          "parameters": [
            {
              "in": "body",
              "name": "body",
              "description": "Pet object that needs to be added to the store",
              "required": true,
              "schema": {
                "$ref": "#/definitions/Pet"
              }
            }
          ],
          "responses": {
            "400": {
              "description": "Invalid ID supplied"
            },
            "404": {
              "description": "Pet not found"
            },
            "405": {
              "description": "Validation exception"
            }
          },
          "security": [
            {
              "petstore_auth": [
                "write:pets",
                "read:pets"
              ]
            }
          ],
          "x-accepts": "application/json",
          "x-contentType": "application/json"
        }
      },
      "/pet/findByStatus": {
        "get": {
          "tags": [
            "pet"
          ],
          "summary": "Finds Pets by status",
          "description": "Multiple status values can be provided with comma separated strings",
          "operationId": "findPetsByStatus",
          "produces": [
            "application/xml",
            "application/json"
          ],
          "parameters": [
            {
              "name": "status",
              "in": "query",
              "description": "Status values that need to be considered for filter",
              "required": true,
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "available",
                  "pending",
                  "sold"
                ],
                "default": "available"
              },
              "collectionFormat": "multi"
            }
          ],
          "responses": {
            "200": {
              "description": "successful operation",
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/definitions/Pet"
                }
              }
            },
            "400": {
              "description": "Invalid status value"
            }
          },
          "security": [
            {
              "petstore_auth": [

```

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

### HikariCP Dependency

Source: https://github.com/networknt/light-4j/blob/master/db-provider/README.md

Include HikariCP as the base for your datasource configuration. This is a lightweight Java DB connection library.

```xml
<dependency>
            <groupId>com.zaxxer</groupId>
            <artifactId>HikariCP</artifactId>
        </dependency>
```

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

### Service Registration Acknowledgment

Source: https://github.com/networknt/light-4j/blob/master/portal-registry/controller-rs-contract.md

This is the JSON response from the controller acknowledging a successful service registration. It provides a unique runtime instance ID and the status.

```json
{
  "jsonrpc": "2.0",
  "id": "register-1",
  "result": {
    "runtimeInstanceId": "0195b1d4-4b3e-7f6b-9f88-47d8b11b0c15",
    "status": "registered"
  }
}
```

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

### Sending JSON Response with Status Object

Source: https://github.com/networknt/light-4j/wiki/Status

Illustrates how to send a JSON response using a Status object, setting the HTTP status code and sending the object's string representation.

```java
Status status = new Status(STATUS_METHOD_NOT_ALLOWED);
exchange.setStatusCode(status.getStatusCode());
exchange.getResponseSender().send(status.toString());
```

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

### getJsonObjectConfig

Source: https://github.com/networknt/light-4j/wiki/Config

Maps a configuration JSON to a specified Plain Old Java Object (POJO) class.

```APIDOC
## getJsonObjectConfig

### Description
Maps the JSON content of a configuration file to a Plain Old Java Object (POJO) of the specified class.

### Method Signature
`Object getJsonObjectConfig(String configName, Class clazz)`

### Parameters
#### Path Parameters
- **configName** (String) - Required - The name of the configuration file (without the .json extension).
- **clazz** (Class) - Required - The class to which the JSON configuration should be mapped.

### Response
- **Object** - An instance of the provided class populated with the configuration data.
```

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

### Mask Sensitive Data in Configuration

Source: https://github.com/networknt/light-4j/wiki/Info

This snippet demonstrates how to register a module with sensitive configuration keys masked. It uses a Java ArrayList to store the keys that need to be masked.

```java
List<String> masks = new ArrayList<String>();
masks.add("trustPass");
masks.add("keyPass");
ModuleRegistry.registerModule(Client.class.getName(), Config.getInstance().getJsonMapConfigNoCache(CONFIG_NAME), masks);
```

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

### Direct HTTP/2 API Call

Source: https://github.com/networknt/light-4j/blob/master/client/README.md

Use this for making a direct HTTP/2 connection and sending a request. Ensure the URL is valid and handle potential exceptions during connection and request.

```java
        final Http2Client client = Http2Client.getInstance();
        final CountDownLatch latch = new CountDownLatch(1);
        final ClientConnection connection;
        try {
            connection = client.connect(new URI(url), Http2Client.WORKER, Http2Client.SSL, Http2Client.BUFFER_POOL,  OptionMap.create(UndertowOptions.ENABLE_HTTP2, true)).get();
        } catch (Exception e) {
            throw new ClientException(e);
        }
        final AtomicReference<ClientResponse> reference = new AtomicReference<>();
        try {
            ClientRequest request = new ClientRequest().setPath("/v1/pets").setMethod(Methods.GET);

            connection.sendRequest(request, client.createClientCallback(reference, latch));

            latch.await();
        } catch (Exception e) {
            logger.error("Exception: ", e);
            throw new ClientException(e);
        } finally {
            IoUtils.safeClose(connection);
        }
```

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

### Performance Comparison: String Concatenation vs. Jackson ObjectMapper

Source: https://github.com/networknt/light-4j/wiki/Status

Compares the performance of string concatenation against Jackson ObjectMapper for serializing one million objects to JSON, highlighting string concatenation's speed advantage.

```text
Jackson Perf 503
ToString Perf 65
```

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

### Parallel Asynchronous API Calls with CompletableFuture

Source: https://github.com/networknt/light-4j/blob/master/client/README.md

Enhance system performance and responsiveness by making parallel API calls using Java 8 CompletableFuture. This approach avoids blocking threads and improves throughput.

```java
 ServiceDef serviceDef = new ServiceDef(“”https, “com.networknt.petstore1”, null, null);

 Http2ServiceRequest request1 = Http2ServiceRequest(serviceDef, “/get”, HttpVerb.valueOf(“GET”);
 Http2ServiceRequest request2 = Http2ServiceRequest(serviceDef, “/getById/1” “GET”);

 Collection<CompletableFuture<?>> completableFutures = new HashSet<>();
 CompletableFuture<Map> futureResponse1 = request1.callForTypedObject(Map.class);
 CompletableFuture<Map> futureResponse2 = request2.callForTypedObject(Map.class);

 completableFutures.add(futureResponse1);
 completableFutures.add(futureResponse2);
 CompletableFuture.allOf(completableFutures.toArray(new CompletableFuture[0])).join();
```

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

### Update pet with form data

Source: https://github.com/networknt/light-4j/wiki/Info

Updates a pet in the store with form data.

```APIDOC
## POST /pet/{petId}

### Description
Updates a pet in the store with form data.

### Method
POST

### Endpoint
/pet/{petId}

### Parameters
#### Path Parameters
- **petId** (integer) - Required - ID of pet that needs to be updated

#### Request Body
- **name** (string) - Optional - Updated name of the pet
- **status** (string) - Optional - Updated status of the pet

### Request Example
```
{
  "example": "application/x-www-form-urlencoded"
}
```
```

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

### Discovery Subscribe

Source: https://github.com/networknt/light-4j/blob/master/portal-registry/controller-rs-contract.md

Subscribes to receive live notifications for service changes.

```APIDOC
## Discovery Subscribe

### Description
Registers a live subscription to receive `discovery/changed` notifications for a specific service.

### Method
POST

### Endpoint
/ws/discovery

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - JSON-RPC protocol version.
- **id** (string) - Required - Unique identifier for the request.
- **method** (string) - Required - The method to call, should be `discovery/subscribe`.
- **params** (object) - Required - Parameters for the subscription.
  - **serviceId** (string) - Required - The ID of the service to subscribe to.
  - **envTag** (string) - Required - The environment tag (e.g., 'prod', 'dev').
  - **protocol** (string) - Required - The protocol of the service (e.g., 'https', 'http').

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": "subscribe-1",
  "method": "discovery/subscribe",
  "params": {
    "serviceId": "com.networknt.user-1.0.0",
    "envTag": "prod",
    "protocol": "https"
  }
}
```

### Response
#### Success Response (200)
- The response shape is the same as `discovery/lookup`.
```

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

### Store API Operations

Source: https://github.com/networknt/light-4j/wiki/Info

Operations related to the pet store orders.

```APIDOC
## GET /store/order/{orderId}

### Description
Find purchase order by ID

### Method
GET

### Endpoint
/store/order/{orderId}

### Parameters
#### Path Parameters
- **orderId** (integer) - Required - ID of order that needs to be fetched

### Response
#### Success Response (200)
- **Order** (Order) - Successful operation

### Response Example
{
  "example": "{\n  \"id\": 10,\n  \"petId\": 10,\n  \"quantity\": 1,\n  \"shipDate\": \"2023-10-27T10:00:00Z\",\n  \"status\": \"delivered\",\n  \"complete\": true\n}"
```

```APIDOC
## POST /store/order

### Description
Places an order for a pet.

### Method
POST

### Endpoint
/store/order

### Request Body
- **Order** (Order) - order placed for a pet

### Request Example
{
  "example": "{\n  \"id\": 10,\n  \"petId\": 10,\n  \"quantity\": 1,\n  \"shipDate\": \"2023-10-27T10:00:00Z\",\n  \"status\": \"placed\",\n  \"complete\": false\n}"
```

```APIDOC
## DELETE /store/order/{orderId}

### Description
Deletes purchase order by ID.

### Method
DELETE

### Endpoint
/store/order/{orderId}

### Parameters
#### Path Parameters
- **orderId** (integer) - Required - ID of the order that needs to be deleted

### Response
#### Success Response (200)
- **ApiResponse** (ApiResponse) - Successful operation
```

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

### Find pet by ID

Source: https://github.com/networknt/light-4j/wiki/Info

Returns a single pet by its ID.

```APIDOC
## GET /pet/{petId}

### Description
Returns a single pet by its ID.

### Method
GET

### Endpoint
/pet/{petId}

### Parameters
#### Path Parameters
- **petId** (integer) - Required - ID of pet to return

### Response
#### Success Response (200)
- (object) - successful operation (schema: #/definitions/Pet)

#### Response Example
{
  "example": "#/definitions/Pet"
}
```

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

### Discovery Lookup Response

Source: https://github.com/networknt/light-4j/blob/master/portal-registry/controller-rs-contract.md

The response to a discovery/lookup request contains the service details and a list of connected nodes.

```json
{
  "jsonrpc": "2.0",
  "id": "lookup-1",
  "result": {
    "serviceId": "com.networknt.user-1.0.0",
    "envTag": "prod",
    "protocol": "https",
    "nodes": [
      {
        "runtimeInstanceId": "0195b1d4-4b3e-7f6b-9f88-47d8b11b0c15",
        "serviceId": "com.networknt.user-1.0.0",
        "envTag": "prod",
        "environment": "prod",
        "version": "1.0.0",
        "protocol": "https",
        "address": "10.0.1.25",
        "port": 8443,
        "tags": {},
        "connectedAt": "2026-03-27T14:00:00Z",
        "lastSeenAt": "2026-03-27T14:00:04Z",
        "connected": true
      }
    ]
  }
}
```