Objective
The JAVA Middleware provides the ability to modernize existing API with SOAJS when this API is built using JAVA as a development language.
The middleware exposes several functionality and configuration that SOAJS offers and which can be consumed by the API upon initialization or during runtime when requests arrive.
This page explains the JAVA middleware; the functionality and configuration that it offers, how to install it and how to use it.
Scenario
- How to Install
- Features
- Configuration
- Functionality
- How does it work
- on init
- on request
- Using the Middleware
- Initialization State
- Runtime State
- Examples
- JAXRS Jersey Express
1- How to Install
The SOAJS Java middleware is open source and is available under Github, you can use the following reference to pull the source code → https://github.com/soajs/soajs.java
The middleware is also available as an NPM package and can be download for free.
# install from npm npm install soajs.java
2- Features
Once the middleware is initialized, the following functionality becomes available:
| Function | Type | Input | Output | Remarks |
|---|---|---|---|---|
| getDatabases | Method | dbName (optional) |
| Mongo Client Driver |
| getServiceConfig | Method | - | returns service configuration object | Services Config |
| getDeployer | Method | - | returns deployer object | Registry |
| getCustom | Method | - | returns custom object | Services Config |
| getResources | Method | resourceName (optional) |
| Registry |
| getServices | Method | serviceName (optional) |
| Service |
| getDaemons | Method | daemonName (optional) |
| Daemon |
| reload | Method | - | void (reload registry only) | Registry |
This middleware functionality is accessible via the request that is made to the API. The middleware traps the request once it hits the API, injects its functionality and then hands it back to you to add your business logic.
3-How does it work
On Init
The Middleware requires the following environment variables to be set prior to starting your service
| Environment Variable | Description | Example | Reference |
|---|---|---|---|
SOAJS_REGISTRY_API | The location of the SOAJS API Gateway along with the maintenance port value that it is using in the environment where the service will run in | 127.0.0.1:5000/ | Environment Variables |
SOAJS_ENV | environment code that this service will run in | DEV | Environment Variables |
Once your service starts, the middleware will make a call to the SOAJS API Gateway and retrieve the registry of the environment, it will cache it in memory.
From this registry, it uses variable autoReloadRegistry (which represents the auto reload duration in seconds) and every time this value is met, the middleware automatically pulls the new version of the registry and updates its cached version.
On request
SOAJS midlleware augments your service by trapping all arriving requests and injecting additional data then hands the updated version of request to your business logic.
The following table illustrates the data that gets injected by the middleware on every request:
| Property | Code Snippet | Description | Reference |
|---|---|---|---|
| Tenant | req.soajs.tenant tenant : {
id : '',
code : ''
}
| Represents the tenant that is making the call to the API. | Multitenancy |
Key Device Geo | req.soajs[ key | device | geo ] key : {
config : {},
iKey : '',
eKey : ''
},
device : '',
geo : {}
| Represents the key configuration which belongs to the tenant making the call to the API. | |
| Application | req.soajs.application application : {
product : '',
package : '',
appId : '',
acl : {},
acl_all_env : {}
}
| Represents the application information which belongs to the tenant making the call to the API. | |
| Package | req.soajs.package package :{
acl :{},
acl_all_env : {}
}
| Represents the Productization that the tenant making the call to the API is using. | |
| URAC | req.soajs.urac urac : {}
| Represents the User whose access token was found in the request. | URAC v2 |
| Awareness | req.soajs.awareness awareness : {
host : '',
port : '',
getHost : 'function'
}
| Represents the SOAJS API Gateway internal network host & port based on the environment where the API is deployed and running in. | Request |
4- Using the Middleware
Once you download the middleware, simply instruct your application to use it by adding it as a library to the restful service as an external jar file soajs.java.jar OR using a POM.xml file
<dependency>
<groupId>soajs</groupId>
<artifactId>soajs.java</artifactId>
<version>1.0.0</version>
</dependency>
Then make sure to initialize it in your servlet tag under web.xml as follow:
<init-param>
<param-name>com.sun.jersey.spi.container.ContainerRequestFilters</param-name>
<param-value>soajs.filters.SoajsContainerRequestFilter</param-value>
</init-param>
Consequently, anywhere in your web application you can wire your context to access the data and function that it offers
(@Context HttpHeaders headers)
headers.getRequestHeader("soajs")
5- Examples
JAXRS Jersey
The following code snippets shows a basic example built using Java and how the SOAJS Java Middleware was added to the code to augment the web server created.
Full Example on: https://github.com/soajs/soajs.java.jaxrs_jersey
package soajs.test.rest;
import java.util.List;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.ws.rs.Consumes;
import javax.ws.rs.DELETE;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.json.JSONObject;
//Import Filters from SOAJS Java Middleware
import soajs.filters.SoajsRegistry;
import soajs.filters.SoajsRequestUtilities;
@Path("/hello")
public class Hello {
//Invoke the middleware and use it in the App
@GET
@Produces(MediaType.APPLICATION_JSON)
public Response getTest(
@QueryParam("username") String username,
@QueryParam("lastname") String lastname
) {
JSONObject response = new JSONObject();
response.put("message", "Hello, I am a JAVA service, you are [" + username + "] and your last name is : [" + lastname + "]");
response.put("dbs", SoajsRegistry.getDatabases() );
return Response.status(200).entity(response.toString()).build();
}
//Invoke the middleware and use it in the App
@POST
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public Response postTest(String data,
@Context HttpHeaders headers,
@Context HttpServletRequest httpServletRequest,
@Context HttpServletResponse httpServletResponse
) {
JSONObject soajs = new JSONObject();
try{
System.out.println("Post service reached: trying to fetch request header at SOAJS ...");
System.out.println("Soajs request header length = ["+headers.getRequestHeader("soajs").size()+"]");
soajs = new JSONObject(headers.getRequestHeader("soajs").get(0));
String host = SoajsRequestUtilities.getHost(soajs);
soajs.put("controller", host);
}
catch(Exception e){
e.printStackTrace();
}
return Response.status(200).entity(soajs.toString()).build();
}
}
Add Comment