User Guide: Integration > Configure the Integration Service > Java Adapter

Java Adapter

With Java service, you can interact with your software application that does not support restful APIs. A service that uses a custom Java adapter is a Java service. The Java adapter is a custom Java class and you can create a Java adapter either by implementing com.hcl.voltmx.middleware.common.JavaService interface or com.hcl.voltmx.middleware.common.JavaService2 interface. Volt MX recommends to use JavaService2 as you can get an access to DataControllerRequest and DataControllerResponse objects.

You must load the required JAR files to define a Java service. The JAR files contain the Java classes. The Java classes contain the Java methods. These methods have the logic defined that is required for a service. Java services are mostly used with Webconnector Services.

Note: The middleware-system.jar helps you to develop a Java adapter. You can download the middleware-system.jar from Admin Console’s download page.

Note: You should not modify JVM timezone through custom code as modifying it can result in app server outage.

Data Conversion of a Java Adapter

 //Sample: Original JSON Data:
  
{"booking":[
{"amount":-254.6,"description":"Paiement carte BIM STORES PALMIER  le 21/02/2016 à 18:54","doc_id":17150820,"value_date":"2016-02-19","temporary":false,"date":"2016-02-21"},{"amount":-44.26,"description":"Paiement internet LYDEC ECOM  le 19/02/2016 à 13:04","doc_id":17146660,"value_date":"2016-02-18","temporary":false,"date":"2016-02-19"},{"amount":-37.26,"description":"Paiement internet LYDEC ECOM  le 19/02/2016 à 13:19","doc_id":17146835,"value_date":"2016-02-18","temporary":false,"date":"2016-02-19"},{"amount":-14.34,"description":"Paiement internet LYDEC ECOM  le 19/02/2016 à 13:11","doc_id":17146744,"value_date":"2016-02-18","temporary":false,"date":"2016-02-19"}
]}
  
**Sample: Data converted to VOLTMX Object:**  
Dataset [id=booking, index=-1, 
	records=[
		Record [index=-1, order=0, id=, 
			params=[
				Param [name=amount, value=-254.6], 
				Param [name=description, value=Paiement carte BIM STORES PALMIER  le 21/02/2016 à 18:54], 
				Param [name=doc_id, value=17150820], 
				Param [name=value_date, value=2016-02-19], 
				Param [name=temporary, value=false], 
				Param [name=date, value=2016-02-21]
			], datasets=[], records=[]
			], Record [index=-1, order=0, id=, 
			params=[
				Param [name=amount, value=-44.26], 
				Param [name=description, value=Paiement internet LYDEC ECOM  le 19/02/2016 à 13:04], 
				Param [name=doc_id, value=17146660], 
				Param [name=value_date, value=2016-02-18], 
				Param [name=temporary, value=false], 
				Param [name=date, value=2016-02-19]
			], datasets=[], records=[]
			], 
  
  
//Sample: Data converted only limited unnamed records into an object in Volt MX Foundry:  
"booking": {
            "": {
                "date": "2016-02-21",
                "temporary": "false",
                "amount": "-254.6",
                "description": "Paiement carte BIM STORES PALMIER  le 21/02/2016 à 18:54",
                "doc_id": "17150820",
                "value_date": "2016-02-19"
            }
		}

Writing a Java Class

To write a Java class for a Java adapter, follow these steps:

1. Create a Java adapter either by implementing the com.hcl.voltmx.middleware.common.JavaService interface or com.hcl.voltmx.middleware.common.JavaService2 interface.
2. When you implement com.hcl.voltmx.middleware.common.JavaService, you have to implement the following invoke() method with the signature:

   public Object invoke(String paramString, Object[] paramArrayOfObject) throws Exception; 
   

3. When you implement com.hcl.voltmx.middleware.common.JavaService2, you have to implement the following invoke() method with the signature:

 public Object invoke(String methodID, Object[] objectArray, DataControllerRequest request, DataControllerResponse response) throws Exception;
    

Middleware API to get Output parameters in a Java Service

A middleware API is provided to get the output params/records/datasets configured as part of a service definition of a Java service.

The following is a sample code:

    ServiceOutputWrapper serviceOutputWrapper =  request.getServicesManager().getOperationData()
    .getServiceOutputWrapper();

Note: Request is an instance of data controller request.

Configure Java Endpoint Adapter

To configure Java service in the Integration Service Definition tab, follow these steps:

1. In the Name field, provide a unique name for your service.
2. From the Service Type list, select Java.

3. From the Java Connector JARs list, select the required JAR file that contains the classes that implement the JavaService interface for this Integration Service from existing JARs in the account or click UploadNew to select the JARs from your local machine.

   Note: You can select multiple JAR files from the Java Connector JARs list if required.

   Important: To upload an updated JAR file, upload the new file, which must have the same name as the old JAR file. The new JAR file overrides the existing file.dsd

4. For additional configuration of your service definition, provide the following details in the Advanced section:

   Field	Description
   Custom Code	Custom Code enables you to specify dependent JAR. To specify dependent JAR, select the JAR containing preprocessor or postprocessor libraries from the drop-down list, or click Upload New to browse the JAR file from your local system. This step allows you to further filter the data sent to the back end. You can select multiple JAR files if required. Important: Make sure that you upload a custom JAR file that is built on the same JDK version used for installing Volt MX Foundry Integration.For example, if the JDK version on the machine where Volt MX Foundry Integration is installed is 1.6, you must use the same JDK version to build your custom jar files. If the JDK version is different, an unsupported class version error will appear when a service is used from a device. You can download the uploaded jars to your local system.
   Throttling	API throttling enables you to limit the number of request calls within a minute. If an API exceeds the throttling limit, it will not return the service response. To specify throttling in Volt MX Foundry Console, follow these steps: In the Total Rate Limit text box, enter a required value. With this value, you can limit the number of requests configured in your Volt MX Foundry console in terms of Total Rate Limit. In the Rate Limit Per IP text box, enter a required value. With this value, you can limit the number of IP address requests configured in your Volt MX Foundry console in terms of Per IP Rate Limit. To override throttling in App Services Console, refer to Override API Throttling Configuration.

</details>

Note: All options in the Advanced section are optional.

1. In the Description field, provide a suitable description for the service.

2. Click Save to save your service definition.

Create Operations for Java

The Operation List tab appears when you click Add Operation in the Service Definition page.

Note: Click Operations List tab > Configure Operation. The Configured Operations list appears.

To create an operation, follow these steps:

1. Click SAVE & ADD OPERATION in your service definition page to save your service definition and display the NewOperation tab for adding operations.
                       OR
   Click Add Operation to add a new operation or from the tree in the left pane, click Add > Add New Operation.

   Click to View image

   

   Note: To use an existing integration service, refer to How to Use an Existing Integration Service.

2. In the Operation Modal tab, follow these steps:

   This tab contains the request input, response output, and advanced sections. The input values are data types, scope, and format types. By default, the system will display the Request Input tab.

   Note: You can add an entry by clicking the Add button if entries for the input and the output tabs do not exist.

   You can also delete an entry. Select the check box for an entry, and then click Delete .

3. To configure an operation, provide the following details:

1. </details>

Note: All options in the Advanced section are optional.

Configure Request Operation for Java

Integration services accept only form-url-encoded inputs for all the input parameters provided in the service input parameters (request input).

To forward the body of the client’s request to backend as it is, select the Enable pass-through input body check box. For more details on API Proxy service, refer to How to Enable Pass-through Proxy for Operations.

You can perform the following actions in Request Input tab:

1. Click Add Parameter to add an entry (if the entries for input and the output tabs does not exist).
2. To make duplicate entries, select the check box for the entry, click Copy and Paste.
3. To delete an entry, select the check box for an entry and click Delete .
4. To configure the request input tab, provide the following details:

1. To validate the operation details, click Save and Test. For more details, refer to Test a Service Operation.

Configure Response Operation for Java

1. Click the Response Output tab, and enter the values for required fields such as name, scope, data type, collection ID, record ID, format and format value.

   Note: If you define parameters inside a record as the session, the session scope will not get reflected for the parameters.

   In Java service, the response (output) from a backend is not parsed based on the response values. The complete response from the backend is sent to the client device.

   Note: By default, the opStatus and httpStatusCode values for Java and JavaScript services are added as 0 and 200.

2. To validate the operation details, click Save and Test. For more details, refer to Test a Service Operation.

3. Click SAVE OPERATION to save the operation. The system updates the operation definition.

   If you click Cancel, the Edit Service Parameters window will close without saving any information.

   Note: To add more operations for your Java service, repeat Step 3 through Step 4.

   Note: You can view the service in the Data Panel feature of Volt MX Iris. By using the Data Panel, you can link back-end data services to your application UI elements seamlessly with low-code to no code. For more information on Data Panel, click here.

How to Edit an Existing Java Adapter

If you want to edit an existing Java service, you can edit details such as service name, JAR files, operation modal details. While editing a Java service, you can change the Java service type. A Java service must be available in the Integration home screen. To add an existing Integration service, refer to Use an Existing Service.

To edit an existing Java service, follow these steps:

1. In the Integration page, click one of your Java services.

2. Under Operations > Configured Operations, hover your cursor over the required service, click the Settings button, and then click Edit.

   The operation details are displayed in the Edit Service Parameters dialog.

3. Make the necessary changes in the Service Definition section, and click Update.
   For more details, refer to How to Configure Service Definition for Java Service.
4. Under the Operation section, hover your cursor over the required service, click the Settings button, and then click Edit to display the Operation Modal tab.
   To modify Java operations, refer to How to Configure and Edit Operation Modal.
5. Click Done to update your Java service. The Integration page is displayed.