Service (JCS) provides a platform to develop and deploy business applications in the cloud. In Fusion Applications Cloud deployments customers do not have the option to deploy custom applications developed with JDeveloper to ensure the integrity and supportability of the hosted application service. Instead the custom applications can be deployed to the JCS and integrated to the Fusion Application Cloud instance.

This series of articles will go through the features of JCS, provide end-to-end examples on how to develop and deploy applications on JCS and how to integrate them with the Fusion Applications instance.

In this article a custom application integrating with REST service will be implemented. We will use REST services provided by Taleo as an example; however the same approach will work with any REST service. In this example the data from the REST service is used to populate a dynamic table.

Pre-requisites

Access to Cloud instance

In order to deploy the application access to a JCS instance is needed, a free trial JCS instance can be obtained from Oracle Cloud site. To register you will need a credit card even if the credit card will not be charged. To register simply click "Try it" and choose the "Java" option. The confirmation email will contain the connection details. See this video for example of the registration.
Once the request is processed you will be assigned 2 service instances; Java and Database. Applications deployed to the JCS must use Oracle Database Cloud Service as their underlying database. So when JCS instance is created a database instance is associated with it using a JDBC data source.
The cloud services can be monitored and managed through the web UI. For details refer to Getting Started with Oracle Cloud.

JDeveloper

JDeveloper contains Cloud specific features related to e.g. connection and deployment. To use these features download the JDeveloper from JDeveloper download site by clicking the "Download JDeveloper 11.1.1.7.1 for ADF deployment on Oracle Cloud" link, this version of JDeveloper will have the JCS integration features that will be used in this article. For versions that do not include the Cloud integration features the Oracle Java Cloud Service SDK or the JCS Java Console can be used for deployment.
For details on installing and configuring the JDeveloper refer to the installation guide
For details on SDK refer to Using the Command-Line Interface to Monitor Oracle Java Cloud Service and Using the Command-Line Interface to Manage Oracle Java Cloud Service.

Access to a local database

The database associated with the JCS instance cannot be connected to with JDBC.  Since creating ADFbc business component requires a JDBC connection we will need access to a local database.

3rd party libraries

This example will use some 3rd party libraries for implementing the REST service call and processing the input / output content. Other libraries may also be used, however these are tested to work.

Jersey 1.x

Jersey library will be used as a client to make the call to the REST service. JCS documentation for supported specifications states:

Java API for RESTful Web Services (JAX-RS) 1.1

So Jersey 1.x will be used. Download the single-JAR Jersey bundle; in this example Jersey 1.18 JAR bundle is used.

Json-simple

Jjson-simple library will be used to process the json objects. Download the  JAR file; in this example json-simple-1.1.1.jar is used.

Accessing data in Taleo

Before implementing the application it is beneficial to familiarize oneself with the data in Taleo. Easiest way to do this is by using a RESTClient on your browser. Once added to the browser you can access the UI:

The client can be used to call the REST services to test the URLs and data before adding them into the application. First derive the base URL for the service this can be done with:

• Method: GET
• URL: https://tbe.taleo.net/MANAGER/dispatcher/api/v1/serviceUrl/<company name>
  

The response will contain the base URL to be used for the service calls for the company. Next obtain authentication token with:

• Method: POST
• URL: https://ch.tbe.taleo.net/CH07/ats/api/v1/login?orgCode=<company>&userName=<user name>&password=<password>
  

The response includes an authentication token that can be used for few hours to authenticate with the service:

{
  "response": {
    "authToken": "webapi26419680747505890557"
  },
  "status": {
    "detail": {},
    "success": true
  }
}

To authenticate the service calls navigate to "Headers -> Custom Header":

And add a new request header with:

• Name: Cookie
• Value: authToken=webapi26419680747505890557
  

Once authentication token is defined the tool can be used to invoke REST services; for example:

• Method: GET
• URL: https://ch.tbe.taleo.net/CH07/ats/api/v1/object/candidate/search.xml?status=16
  

This data will be used on the application to be created. For details on the Taleo REST services refer to the Taleo Business Edition REST API Guide.

Create Application

First Fusion Web Application is created and configured. Start JDeveloper and click "New Application":

• Application Name: JcsRestDemo
• Application Package Prefix: oracle.apps.jcs.test
• Application Template: Fusion Web Application (ADF)
  

Configure Local Cloud Connection

Follow the steps documented in the "Java Cloud Service ADF Web Application" article to configure a local database connection needed to create the ADFbc objects.

Configure Libraries

Add the 3rd party libraries into the class path. Create the following directory and copy the jar files into it:

<JDEV_USER_HOME>/JcsRestDemo/lib

 Select the "Model" project, navigate "Application -> Project Properties -> Libraries and Classpath -> Add JAR / Directory" and add the 2 3rd party libraries:

Accessing Data from Taleo

To access data from Taleo using the REST service the 3rd party libraries will be used. 2 Java classes are implemented, one representing the Candidate object and another for accessing the Taleo repository

Candidate

Candidate object is a POJO object used to represent the candidate data obtained from the Taleo repository. The data obtained will be used to populate the ADFbc object used to display the data on the UI. The candidate object contains simply the variables we obtain using the REST services and the getters / setters for them: Navigate "New -> General -> Java -> Java Class", enter "Candidate" as the name and create it in the package "oracle.apps.jcs.test.model".  Copy / paste the following as the content:

import oracle.jbo.domain.Number;

public class Candidate {
    private Number candId;
    private String firstName;
    private String lastName;

    public Candidate() {
        super();
    }
    public Candidate(Number candId, String firstName, String lastName) {
        super();
        this.candId = candId;
        this.firstName = firstName;
        this.lastName = lastName;
   }
    public void setCandId(Number candId) {
        this.candId = candId;
    }
    public Number getCandId() {
        return candId;
    }
    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }
    public String getFirstName() {
        return firstName;
    }
    public void setLastName(String lastName) {
        this.lastName = lastName;
    }
    public String getLastName() {
        return lastName;
    }
}

Taleo Repository

Taleo repository class will interact with the Taleo REST services. The logic will query data from Taleo and populate Candidate objects with the data. The Candidate object will then be used to populate the ADFbc object used to display data on the UI. Navigate "New -> General -> Java -> Java Class", enter "TaleoRepository" as the name and create it in the package "oracle.apps.jcs.test.model".  Copy / paste the following as the content (for details of the implementation refer to the documentation in the code):

import com.sun.jersey.api.client.Client;
import com.sun.jersey.api.client.ClientResponse;
import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.core.util.MultivaluedMapImpl;

import java.io.StringReader;

import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import java.util.Map;

import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.MultivaluedMap;

import oracle.jbo.domain.Number;

import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import org.json.simple.parser.JSONParser;

/**
 * This class interacts with the Taleo REST services
 */
public class TaleoRepository {
    /**
     * Connection information needed to access the Taleo services
     */
    String _company = null;
    String _userName = null;
    String _password = null;

    /**
     * Jersey client used to access the REST services
     */
    Client _client = null;

    /**
     * Parser for processing the JSON objects used as
     * input / output for the services
     */
    JSONParser _parser = null;

    /**
     * The base url for constructing the REST URLs. This is obtained
     * from Taleo with a service call
     */
    String _baseUrl = null;

    /**
     * Authentication token obtained from Taleo using a service call.
     * The token can be used to authenticate on subsequent
     * service calls. The token will expire in 4 hours
     */
    String _authToken = null;

    /**
     * Static url that can be used to obtain the url used to construct
     * service calls for a given company
     */
    private static String _taleoUrl =
        "https://tbe.taleo.net/MANAGER/dispatcher/api/v1/serviceUrl/";

    /**
     * Default constructor for the repository
     * Authentication details are passed as parameters and used to generate
     * authentication token. Note that each service call will
     * generate its own token. This is done to avoid dealing with the expiry
     * of the token. Also only 20 tokens are allowed per user simultaneously.
     * So instead for each call there is login / logout.
     *
     * @param company the company for which the service calls are made
     * @param userName the user name to authenticate with
     * @param password the password to authenticate with.
     */
    public TaleoRepository(String company, String userName, String password) {
        super();
        _company = company;
        _userName = userName;
        _password = password;
        _client = Client.create();
        _parser = new JSONParser();
        _baseUrl = getBaseUrl();
    }

    /**
     * This obtains the base url for a company to be used
     * to construct the urls for service calls
     * @return base url for the service calls
     */
    private String getBaseUrl() {
        String result = null;
        if (null != _baseUrl) {
            result = _baseUrl;
        } else {
            try {
                String company = _company;
                WebResource resource = _client.resource(_taleoUrl + company);
                ClientResponse response =
                    resource.type(MediaType.APPLICATION_FORM_URLENCODED_TYPE).get(ClientResponse.class);
                String entity = response.getEntity(String.class);

                JSONObject jsonObject =
                    (JSONObject)_parser.parse(new StringReader(entity));
                JSONObject jsonResponse =
                    (JSONObject)jsonObject.get("response");
                result = (String)jsonResponse.get("URL");
            } catch (Exception ex) {
                ex.printStackTrace();
            }
        }
        return result;
    }

    /**
     * Generates authentication token, that can be used to authenticate on
     * subsequent service calls.  Note that each service call will
     * generate its own token. This is done to avoid dealing with the expiry
     * of the token. Also only 20 tokens are allowed per user simultaneously.
     * So instead for each call there is login / logout.
     * @return authentication token that can be used to authenticate on
     * subsequent service calls
     */
    private String login() {
        String result = null;
        try {
            MultivaluedMap<String, String> formData = new MultivaluedMapImpl();
            formData.add("orgCode", _company);
            formData.add("userName", _userName);
            formData.add("password", _password);
            WebResource resource = _client.resource(_baseUrl + "login");
            ClientResponse response =
                resource.type(MediaType.APPLICATION_FORM_URLENCODED_TYPE).post(ClientResponse.class,
                                                                               formData);
            String entity = response.getEntity(String.class);
            JSONObject jsonObject =
                (JSONObject)_parser.parse(new StringReader(entity));
            JSONObject jsonResponse = (JSONObject)jsonObject.get("response");
            result = (String)jsonResponse.get("authToken");
        } catch (Exception ex) {
            throw new RuntimeException("Unable to login ", ex);
        }
        if (null == result)
            throw new RuntimeException("Unable to login ");
        return result;
    }

    /**
     * Releases a authentication token. Each call to login must be followed
     * by call to logout after the processing is done. This is required as
     * the tokens are limited to 20 per user and if not released the tokens
     * will only expire after 4 hours.
     * @param authToken
     */
    private void logout(String authToken) {
        WebResource resource = _client.resource(_baseUrl + "logout");
        resource.header("cookie", "authToken=" + authToken).post(ClientResponse.class);
    }

    /**
     * This method is used to obtain a list of candidates using a REST
     * service call. At this example the query is hard coded to query
     * based on status. The url constructed to access the service is:
     *  <_baseUrl>/object/candidate/search.xml?status=16
     * @return List of candidates obtained with the service call
     */
    public List<Candidate> getCandidates() {
        List<Candidate> result = new ArrayList<Candidate>();
        try {
            // First login, note that in finally block we must have logout
            _authToken = "authToken=" + login();

            /**
             * Construct the URL, the resulting url will be:
             * <_baseUrl>/object/candidate/search.xml?status=16
             */
            MultivaluedMap<String, String> formData = new MultivaluedMapImpl();
            formData.add("status", "16");
            JSONArray searchResults =
                (JSONArray)getTaleoResource("object/candidate/search",
                                            "searchResults", formData);

            /**
             * Process the results, the resulting JSON object is something like
             * this (simplified for readability):
             *
             * {
             *    "response":
             *    {
             *        "searchResults":
             *        [
             *            {
             *                "candidate":
             *                {
             *                    "candId": 211,
             *                    "firstName": "Mary",
             *                    "lastName": "Stochi",
             * logic here will find the candidate object(s), obtain the desired
             * data from them, construct a Candidate object based on the data
             * and add it to the results.
             */
            for (Object object : searchResults) {
                JSONObject temp = (JSONObject)object;
                JSONObject candidate =
                    (JSONObject)findObject(temp, "candidate");

                Long candIdTemp = (Long)candidate.get("candId");
                Number candId =
                    (null == candIdTemp ? null : new Number(candIdTemp));
                String firstName = (String)candidate.get("firstName");
                String lastName = (String)candidate.get("lastName");

                result.add(new Candidate(candId, firstName, lastName));
            }
        } catch (Exception ex) {
            ex.printStackTrace();
        } finally {
            if (null != _authToken)
                logout(_authToken);
        }
        return result;
    }

    /**
     * Convenience method to construct url for the service call, invoke the
     * service and obtain a resource from the response
     * @param path the path for the service to be invoked. This is combined
     * with the base url to construct a url for the service
     * @param resource the key for the object in the response that will be
     * obtained
     * @param parameters any parameters used for the service call. The call
     * is slightly different depending whether parameters exist or not.
     * @return the resource from the response for the service call
     */
    private Object getTaleoResource(String path, String resource,
                                    MultivaluedMap<String, String> parameters) {
        Object result = null;
        try {
            WebResource webResource = _client.resource(_baseUrl + path);
            ClientResponse response = null;
            if (null == parameters)
                response =
                        webResource.header("cookie", _authToken).get(ClientResponse.class);
            else
                response =
                        webResource.queryParams(parameters).header("cookie", _authToken).get(ClientResponse.class);
            String entity = response.getEntity(String.class);
            JSONObject jsonObject =
                (JSONObject)_parser.parse(new StringReader(entity));
            result = findObject(jsonObject, resource);
        } catch (Exception ex) {
            ex.printStackTrace();
        }
        return result;
    }

    /**
     * Convenience method to recursively find a object with an key
     * traversing down from a given root object. This will traverse a
     * JSONObject / JSONArray recursively to find a matching key, if found
     * the object with the key is returned.
     * @param root root object which contains the key searched for
     * @param key the key for the object to search for
     * @return the object matching the key
     */
    private Object findObject(Object root, String key) {

        Object result = null;
        if (root instanceof JSONObject) {
            JSONObject rootJSON = (JSONObject)root;

            if (rootJSON.containsKey(key)) {
                result = rootJSON.get(key);
            } else {
                Iterator children = rootJSON.entrySet().iterator();
                while (children.hasNext()) {
                    Map.Entry entry = (Map.Entry)children.next();
                    Object child = entry.getValue();
                    if (child instanceof JSONObject ||
                        child instanceof JSONArray) {
                        result = findObject(child, key);
                        if (null != result)
                            break;
                    }
                }
            }
        } else if (root instanceof JSONArray) {
            JSONArray rootJSON = (JSONArray)root;
            for (Object child : rootJSON) {

                if (child instanceof JSONObject ||
                    child instanceof JSONArray) {
                    result = findObject(child, key);
                    if (null != result)
                        break;
                }
            }
        }
        return result;
    }
}
 

Creating Business Objects

While JCS application can be created without a local database, the local database is required when using ADFbc objects even if database objects are not referred. For this example we will create a "Transient" view object that will be programmatically populated based the data obtained from Taleo REST services.

Creating ADFbc objects

Choose the "Model" project and navigate "New -> Business Tier : ADF Business Components : View Object". On the "Initialize Business Components Project" choose the local database connection created in previous step. On Step 1 enter "JcsRestDemoVO" on the "Name" and choose "Rows populated programmatically, not based on query":

On step 2 create the following attributes:

• CandId
• Type: Number
• Updatable: Always
• Key Attribute: checked
• Name
• Type: String
• Updatable: Always
  

On steps 3 and 4 accept defaults and click "Next".  On step 5 check the "Application Module" checkbox and enter "JcsRestDemoAM" as the name:

Click "Finish" to generate the objects.

Populating the VO

To display the data on the UI the "transient VO" is populated programmatically based on the data obtained from the Taleo REST services. Open the "JcsRestDemoVOImpl.java". Copy / paste the following as the content (for details of the implementation refer to the documentation in the code):

import java.sql.ResultSet;
import java.util.List;
import java.util.ListIterator;

import oracle.jbo.server.ViewObjectImpl;
import oracle.jbo.server.ViewRowImpl;
import oracle.jbo.server.ViewRowSetImpl;
// ---------------------------------------------------------------------
// ---    File generated by Oracle ADF Business Components Design Time.
// ---    Tue Feb 18 09:40:25 PST 2014
// ---    Custom code may be added to this class.
// ---    Warning: Do not modify method signatures of generated methods.
// ---------------------------------------------------------------------
public class JcsRestDemoVOImpl extends ViewObjectImpl {
    /**
     * This is the default constructor (do not remove).
     */
    public JcsRestDemoVOImpl() {
    }

    @Override
    public void executeQuery() {
        /**
         * For some reason we need to reset everything, otherwise
         * 2nd entry to the UI screen may fail with 
         * "java.util.NoSuchElementException" in createRowFromResultSet
         * call to "candidates.next()". I am not sure why this is happening
         * as the Iterator is new and "hasNext" is true at the point 
         * of the execution. My theory is that since the iterator object is
         * exactly the same the VO cache somehow reuses the iterator including
         * the pointer that has already exhausted the iterable elements on the
         * previous run. Working around the issue 
         * here by cleaning out everything on the VO every time before query
         * is executed on the VO.
         */
        getViewDef().setQuery(null);
        getViewDef().setSelectClause(null);
        setQuery(null);
        this.reset();
        this.clearCache();
        super.executeQuery();
    }

    /**
     * executeQueryForCollection - overridden for custom java data source support.
     */
    protected void executeQueryForCollection(Object qc, Object[] params,
                                             int noUserParams) {

        /**
         * Integrate with the Taleo REST services using TaleoRepository class.
         * A list of candidates matching a hard coded query is obtained. 
         */
        TaleoRepository repository = new TaleoRepository(<company>, <username>, <password>);
        List<Candidate> candidates = repository.getCandidates();

        
        /**
         * Store iterator for the candidates as user data on the collection.
         * This will be used in createRowFromResultSet to create rows based on 
         * the custom iterator.
         */
        ListIterator<Candidate> candidatescIterator =
            candidates.listIterator();
        setUserDataForCollection(qc, candidatescIterator);
        super.executeQueryForCollection(qc, params, noUserParams);
    }

    /**
     * hasNextForCollection - overridden for custom java data source support.
     */
    protected boolean hasNextForCollection(Object qc) {
        boolean result = false;

        /**
         * Determines whether there are candidates for which to create a row
         */
        ListIterator<Candidate> candidates =
            (ListIterator<Candidate>)getUserDataForCollection(qc);
        result = candidates.hasNext();
        /**
         * If all candidates to be created indicate that processing is done
         */
        if (!result) {
            setFetchCompleteForCollection(qc, true);
        }
            
        return result;
    }

    /**
     * createRowFromResultSet - overridden for custom java data source support.
     */
    protected ViewRowImpl createRowFromResultSet(Object qc,
                                                 ResultSet resultSet) {
        /**
         * Obtain the next candidate from the collection and create a row
         * for it.
         */
        ListIterator<Candidate> candidates =
            (ListIterator<Candidate>)getUserDataForCollection(qc);
        ViewRowImpl row = createNewRowForCollection(qc);
        try {
            Candidate candidate = candidates.next();
            row.setAttribute("CandId", candidate.getCandId());
            row.setAttribute("Name", candidate.getFirstName() + " " + candidate.getLastName());
        } catch (Exception e) {
            e.printStackTrace();
        }
        return row;
    }

    /**
     * getQueryHitCount - overridden for custom java data source support.
     */
    public long getQueryHitCount(ViewRowSetImpl viewRowSet) {
        /**
        * For this example this is not implemented rather we always return 0.
        */
        return 0;
    }
}

Creating UI

Choose the "ViewController" project and navigate "New -> Web Tier : JSF : JSF Page". On the "Create JSF Page" enter "JcsRestDemo" as name and ensure that the "Create as XML document (*.jspx)" is checked.  Open "JcsRestDemo.jspx" and navigate to "Data Controls -> JcsRestDemoAMDataControl -> JcsRestDemoVO1" and drag & drop the VO to the "<af:form> " as a "ADF Read-only Table":

Accept the defaults in "Edit Table Columns". To execute the query navigate to to "Data Controls -> JcsRestDemoAMDataControl -> JcsRestDemoVO1 -> Operations -> Execute" and drag & drop the operation to the "<af:form> " as a "Button":

Deploying to JCS

Follow the same steps as documented in previous article"Java Cloud Service ADF Web Application". Once deployed the application can be accessed with URL:

https://java-[identity domain].java.[data center].oraclecloudapps.com/JcsRestDemo-ViewController-context-root/faces/JcsRestDemo.jspx

The UI displays a list of candidates obtained from the Taleo REST Services:

Summary

In this article we learned how to integrate with REST services using Jersey library in JCS. In future articles various other integration techniques will be covered.