For up-to-date product documentation, see the IBM MobileFirst Foundation Developer Center.

Java server-side API

Java™ adapters can use the IBM MobileFirst™ Platform Server Java API to perform server-related operations such as: calling other adapters, getting values of configuration properties, reporting activities to IBM MobileFirst Analytics, and getting the identity of the request issuer.

The Java API has four interfaces, corresponding to four categories: authentication, adapters, configuration, and analytics:

• AdapterSecurityContext
• AdaptersAPI
• ConfigurationAPI
• AnalyticsAPI

To access an interface, use the @ annotation. For example, to access the AdaptersAPI interface, write:

@Context
AdaptersAPI adaptersApi;

Examples of the use of the API are provided in the following sections.

AdapterSecurityContext

The security API provides access to the security context of the client, and the client registration data. To use the API, add an instance of AdapterSecurityContext with the @Context annotation. The following sample uses the API to get the display name of the authenticated user:

@Context
AdapterSecurityContext securityContext;

@OAuthSecurity(scope = "userLogin")
@GET
@Produces(MediaType.TEXT_PLAIN)
public String sayHello() {
   AuthenticatedUser user = securityContext.getAuthenticatedUser();
   return "Hello " + user.getDisplayName();
}

AdaptersAPI

The adapters API makes it easy to perform requests to other adapters in the same server.

The following example shows how to use the adapters API to call a JavaScript adapter:

@Path("/")
public class JavaAdapter1Resource {
    static Logger logger = Logger.getLogger(JavaAdapter1Resource.class.getName());
     
    // Get access to AdaptersAPI     
    @Context AdaptersAPI adaptersAPI; 
    @GET
    @Path("/calljs")
    @Produces("application/json")
    public JSONObject callJSAdapterExample() throws Exception {
        //Using helper method to create a request to the JS adapter
        HttpUriRequest req = adaptersAPI.createJavascriptAdapterRequest("JSAdapter", "getStories");
        //Execute the request and get the response
        HttpResponse resp = adaptersAPI.executeAdapterRequest(req);
        //Convert the response to JSON since we know that JS adapters always return JSON
        JSONObject json = adaptersAPI.getResponseAsJSON(resp);
        //Return the json response as the response of the current request
        return json;
    }

ConfigurationAPI

The configuration API enables the adapter to read server-side configuration properties. These properties are defined in one of two places: as adapter configuration or as JNDI entries.

For example, assume you have a user-defined property, databaseName. To get its value, you could write the following code:

String databaseName = configurationApi.getPropertyValue("databaseName");

For more information, see Configure adapters.

AnalyticsAPI

The Analytics API reports information to IBM MobileFirst Analytics.

For example, to send the string Getting account balance, you might write:

@Context
AnalyticsAPI analyticsApi; 
@GET 
public String customScopeProtected() {
    analyticsApi.logActivity("Getting account balance");  
    // perform operation
    }

Implementing connectivity in Java adapters

Unlike JavaScript adapters, Java adapters are not provided with built-in connectivity. We can implement connectivity by using custom properties in the adapter descriptor file. For more information, see Configure adapters. The Java Adapters tutorial on the Developer Center website demonstrates this feature.

Parent topic: Develop Java adapter code