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 guideFor 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.
