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.konylabs.middleware.common.JavaService interface or com.konylabs.middleware.common.JavaService2 interface. Quantum 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.

NOTE: You should not modify the result object directly through the Pre-processor code for a Java service. This is because any changes made to the result object may be overridden by the Java service's invoke method. Hence, any modifications to the result object should be done only at the Java service level.

Data Conversion of a Java Adapter

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.konylabs.middleware.common.JavaService interface or com.konylabs.middleware.common.JavaService2 interface.
2. When you implement com.konylabs.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.konylabs.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 Quantum Fabric Integration. For example, if the JDK version on the machine where Quantum Fabric 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 Quantum Fabric 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 Quantum Fabric 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 Quantum Fabric console in terms of Per IP Rate Limit. To override throttling in App Services Console, refer to Override API Throttling Configuration.

   NOTE: All options in the Advanced section are optional.

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

6. 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:
   

Field	Description
Name	It is prepopulated with the operation name. You can change the name if required.
Operation Security Level	It specifies how a client must authenticate to invoke this operation. Select one of the following security operations in the Operation Security Level field. Authenticated App User – It restricts the access to clients who have successfully authenticated using an Identity Service associated with the app. Anonymous App User – It allows the access from trusted clients that have the required App Key and App Secret. Authentication through an Identity Service is not required. Public – It allows any client to invoke this operation without any authentication. This setting does not provide any security to invoke this operation and you should avoid this authentication type if possible. Private - It blocks the access to this operation from any external client. It allows invocation either from an Orchestration/Object Service, or from the custom code in the same run-time environment.



4. For additional configurations of request (or) response operations, provide the following details in the Advanced section:

   Field	Description
   Custom Code Invocation - Preprocessor and Postprocessor (for Java and JavaScript)	You can add pre and post processing logic to services to modify the request inputs. When you test, the services details of various stages in the service execution are presented to you for better debugging. All options in the Advanced section are optional. For more details, refer to Preprocessor and Postprocessor.
   Properties	Additional Configuration Properties allows you to configure service call time out cache response. For information on different types of configuration properties, refer Properties.
   Front End API	Front-end API allows you map your endpoint (or) backend URL of an operation to a front-end URL. For detailed information, refer Custom Front-end URL.
   Server Events	Using Server Events you can configure this service to trigger or process server side events. For detailed information, refer Server Events.

   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:
   

Field	Description
Name	It Contains a Unique Identifier. Change the name if required.
Test Value	Enter a value. A test value is used for testing the service.
Default Value	Enter the value, if required. The default value will be used if the test value is empty.
Scope	Select Request or Session. It is set to Request by default. Request indicates that the value must be retrieved from the HTTP request received from the mobile device. Session indicates that the value must be retrieved from the HTTP session stored on Quantum Fabric. Identity: If this is selected, you can filter the request parameters based on the response from the identity provider. For more details to configure identity filters, refer to Enhanced Identity Filters - Integration Services.
Data Type	Select one of the following data types. String - A combination of alpha-numeric and special characters. Supports all formats including UTF-8 and UTF-16 with no maximum size limit. Boolean - A value that can be true or false. Number - An integer or a floating number. Collection - A group of data, also referred as data set.
Encode	Select the check box to enable encoding of an input parameter. For example, the name New York Times would be encoded as New%20York%20Times when the encoding is set to True. The encoding must also adhere to the HTML URL encoding standards.
Description	Provide a suitable description.

5. 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 services are added as 0.

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 Quantum Visualizer. 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.

NOTE: It is advised to avoid directly inserting Custom Objects into Session or ResultCache within Preprocessors, Postprocessors, and Java Services.

Instead, Custom Objects should be converted to a byte Array before insertion into Session or ResultCache. The Serialization and Deserialization of Custom Objects should be managed by implementation classes to guarantee proper data handling.