IBM Worklight v5.0.5 > Develop IBM Worklight applications > Develop the server side of an IBM Worklight application

Worklight adapters

Overview

Worklight adapters are server-side JavaScript and XSL used to connect to enterprise application back-end systems, delivering data to and from mobile applications, and performing necessary server-side logic on the data. XSL is used to transform hierarchical back-end data to JSON.

Worklight adapters support read-only and transactional access modes to back-end systems.

Adapters offer control over the identity of the user with whom the connection is made. The user can be a system user, or a user on whose behalf the transaction is made.

Data retrieved from back-end applications is exposed in a uniform manner, so that application developers can access data uniformly, regardless of its source, format, and protocol.

The adapter framework mediates between the mobile apps and the back-end services. The app, the back-end application, and the JavaScript code and XSLT components in the WL server are supplied by the adapter or app developer. The procedure and auto-conversions are part of the IBM Worklight Platform.

1. An adapter exposes a set of services, called procedures.

   Mobile apps invoke procedures by issuing Ajax requests.

2. The procedure retrieves information from the back-end application.

3. The back-end application then returns data in some format.

   • If this format is JSON, the WL server keeps the data intact.

   • If this format is not JSON, the WL server automatically converts it to JSON. Alternatively, the developer can provide an XSL transformation to convert the data to JSON. In such a case, the WL server first converts the data to XML (if it is not in XML already) that serves as input for the XSL transformation.

4. The JavaScript implementation of the procedure receives the JSON data, performs any additional processing, and returns it to the calling app.

Anatomy of adapters

Each Worklight adapter must have the following elements:

One XML file	Connectivity to the back-end system to which the adapter connects, and listing the procedures exposed by the adapter to other adapters and to applications.
One JavaScript file	Implementation of the procedures declared in the XML file.
Zero or more XSL files	Each contains a transformation from the raw XML data retrieved by the adapter to JSON returned by adapter procedures.

The files are packaged in a compressed file with a .adapter suffix, such as...

myadapter.adapter

The root element of the XML configuration files is <adapter>.

The main subelements of the <adapter> element are as follows:

<connectivity>	Connection properties, load constraints, and credentials for the back-end system.
<procedure>	Declares a procedure exposed by the adapter.

The structure of the <adapter> element is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<wl:adapter>
    <description> 
    <connectivity>
        <connectionPolicy> 
        <loadConstraints>
    </connectivity>
    <procedure />  <!-- One or more such elements -->
</wl:adapter>

The HTTP adapter

The Worklight HTTP adapter can be used to invoke RESTful services and SOAP-based services. It can also be used to perform HTML scraping.

Use the HTTP adapter to send GET, POST, PUT, and DELETE HTTP requests and retrieve data from the response body. Data in the response can arrive in XML, HTML, or JSON formats.

Use SSL with mutual authentication in an HTTP adapter to connect to back-end services. However, you cannot configure SSL (trusted back-end certificates and the client key pair) in the adapter. Instead, configure SSL at the JVM level.

Note however that SSL represents transport level security, which is independent of basic authentication. It is possible to do basic authentication either over HTTP or HTTPS.

The SQL adapter

Use the Worklight SQL adapter to execute parameterized SQL queries and stored procedures, in order to retrieve or update data in the database.

The Cast Iron adapter

The Worklight Cast Iron adapter initiates orchestrations in Cast Iron to retrieve and return data to mobile clients.

Cast Iron accesses various enterprise data sources, such as databases, web services, and JMS, and provides validation, aggregation, and formatting capabilities.

The Cast Iron adapter supports two patterns of connectivity:

Outbound pattern.	The invocation of Cast Iron orchestrations from Worklight.
Inbound pattern.	Cast Iron sends notifications to devices through Worklight.

The Cast Iron adapter supports the invocation of a Cast Iron orchestration over HTTP only. Cast Iron Template Integration Foos (TIPs) are provided in Cast Iron as examples of this technique, and for you to use as a basis for your own orchestrations.

Cast Iron uses the standard Worklight notification adapter and event sources to publish notification messages to be delivered to devices using one of the many notification providers.

See: Method WL.Server.createEventSource.

Cast Iron Template Integration Foos (TIPs) are provided in Cast Iron as examples of this technique, and for you to use as a basis for your own notification scenarios.

To protect the notification adapter, use basic authentication.

The JMS adapter

The WorkLight JMS adapter can be used to send and receive messages from a JMS-enabled messaging provider. It can be used to send and receive the headers and body of the messages.

Troubleshooting a Cast Iron adapter – connectivity issues

Symptom: The Worklight adapter cannot communicate with the Cast Iron server.

Causes:

• Cast Iron provides two network interfaces, one for administration and one for data. Ensure that you are using the correct host name or IP address of the Cast Iron data interface.

  You can find this information under the Network menu item in the Cast Iron administrative interface. This information is stored in the adapter-name.xml file for your adapter.

• The invocation fails with a message Failed to parse the payload from backend.

  This failure is typically caused by a mismatch between the data returned by the Cast Iron orchestration and the returnedContentType parameter in the adapter-name.js implementation. For example, the Cast Iron orchestration returns JSON but the adapter is configured to expect XML.

Worklight adapters with Java

JavaScript is the preferred method. Use Java only if you are unable to perform the same work using JavaScript.

Tips for making Java calls from Worklight Adapters...

• Keep exception messages lightweight to ease passage back through the call stack and client. Do not print stack trace.
• For strings use Static members. For concatenations and mutations use StringBuffer and StringBuilder
• For return types on methods, use JSONObject or JSONArray.
• Do lots of code cleanup

Package Java code...

[project]/server/lib/*.jar

...and build and deploy to WL server. Several WL server restarts may be required before new code is fully instantiated.

Create a JavaScript object using the fully-qualified class name of the Java entry class. For example:

function getProjects() {
var params = WL.Server.invokeProcedure({
adapter : "ConnectionAdapter",
procedure : "getConnectionParams",
parameters : []
});

// Java Class here
var projectUtil = new com.rl.automation.ProjectUtil();
var projects = projectUtil.getProjects(params);
projectUtil = null;
return {result: projects};
}

If Java code is not visible in JS, with ECMA script errors. restart and clear out the server folder.

Use Logger class instance write debug and error messages. System.Out debug messages are not printed to Worklight server log.

Parent Develop the server side of an IBM Worklight application

---

+

Search Tips   |   Advanced Search