Oracle MCS with ADF BC REST Connector

We already learned how to deploy and access ADF BC REST services from Oracle Java Cloud - ADF BC REST 12.2.1.0 Running Live in Oracle Java Cloud. It's time to see how ADF BC REST can be consumed by Oracle Mobile Cloud Service (MCS). In my point of view, key benefit of MCS is ability to simplify Web Service access for mobile clients, by aggregating these Web Services from different sources and simplifying them. I will try to describe it in very structure way, how to define MCS interface based on ADF BC REST.

Let's start from the top - MCS Web Service interface visible to mobile clients. I have defined four endpoints in MCS, based on ADF BC REST service - list of employees, new employee, employee by ID and update employee. As you can see from MCS tester, implementation details are hidden from the user and you would not know there is ADF BC REST is working in the background.

POST

Create new record. Data is supplied through Body:

You should see newly created record data in the response:

PATCH

Update existing record by ID. If value is invalid, ADF BC REST returns validation message:

When we fix value and try to update again, attribute value is changed:

GET by ID

This can be used to fetch resource by key:

GET

Returns a list of resources

At this point you should be familiar with implemented endpoints. Next I will describe how REST Connector, Custom API and Mobile Backend are configured in MCS.

REST Connector

Connector is defined to point to ADF BC REST service deployed on Oracle Java Cloud. We need connector in order to be able to call external Web Service. Connector is named as EmployeesList:

ADF BC REST service is protected by ADF Security. For this reason there is one rule defined to provide authorization header for REST requests:

Custom API

This is a proxy between connector calling external Web Service and service exposed to mobile client. Here we define available endpoints and implement calls to connectors or other MCS services (storage, notifications, etc.) through Node.js:

Endpoints for REST service are defined here, same ones as described above in MCS tester. We have /employees and /employees/{employeeId} endpoints:

Endpoint /employees is suppose to return a list of employees, without specifying a key or to execute POST to create new employee. GET method is defined to return list of employees:

POST method is defined for /employees and is supposed to create new employee:

GET method for /employees/{employeeid} is supposed to return employee by ID:

PATCH method for /employees/{employeeid} is supposed to update attributes for given employee:

Next important thing in custom API is implementation. This is the place where Node.js transformation between Web Service connector and MCS interface is defined. It can't be edited directly in the cloud, you should download JavaScript package to your environment and edit there. Upload it back when done. Download implementation for my sample app - employees_v3.0.zip:

Let's check implementation. This is the structure of implementation archive. JavaScript file employees.js contains implementation for MCS endpoint interaction with REST connector. JSON file package.json provides metadata for the implementation:

Endpoint GET method is implemented to call EmployeeList connector and to retrieve Employees resource (by calling GET). ADF BC REST supports onlyData=true parameter to return data only, we can pass it through HTTP parameters. Callback for successful result transfers data from REST connector to MCS:

GET by ID is implemented in similar way. Only difference - we add EmployeeId to Employees resource, this constructs REST URL Employees/100:

PATCH is a bit more complex. It needs to set Employee ID, pass request body (with JSON String including attributes to update) and specify ADF BC REST supported Content-Type. This makes it easy for mobile consumer, no need to worry about such things as Content-Type, etc. There is also option to log data, it could be useful for debugging purposes:

POST is pretty much similar to PATCH, it calls post method through connector:

Read more about Connector API in developer guide - Calling Connector APIs from Custom Code.

You must explicitly register Connector to be accessible from API implementation, this is done in package.json:

Mobile Backend

I will show how to read debug messages logged in Mobile Backend, when testing endpoints defined by Custom API. We execute PATCH:

All operations are executed through Mobile Backend, this is the place where we can check statistics and see the flow of REST calls and other actions:

These five actions where invoked during PATCH. You can see payload body content printed, this is done from Custom API implementation function:

ADF BC REST 12.2.1.0 Running Live in Oracle Java Cloud

It passed almost two years since my previous post about Oracle Java Cloud and ADF - End-To-End ADF Cloud Deployment Process. There is huge improvement in Oracle Cloud, great progress done in these two years by Oracle. Access and management of Oracle Cloud environment is so smooth now, it is even hard to say you are working with your own on premise servers or cloud machines. This is great, I'm impressed - well done Oracle.

I have implemented ADF BC REST application with JDEV 12.2.1.0 and deployed it to Java Cloud. You can access REST service yourself from this URL: http://140.86.3.179/restapp/rest/1/Employees (username: redsam, password: welcome1).

I can monitor deployed application with ADF BC REST through Enterprise Manager in the Cloud. ADF BC REST request/response is going through Oracle RESTServlet, this is visible in the statistics:

There are no changes required to ADF application to be deployed to the Cloud. Simply make sure to provide correct datasource name, to be able to load data from Database Cloud. I have created jdbc/HrDS data source in Java Cloud, to point to Database Cloud. Using the same data source for AM configuration, this AM will be responsible to return data from ADF BC for REST requests:

Database Cloud offers public IP, it can be used to access DB from outside. If you want to reference DB schema from data source created in Java Cloud, instead of using public IP you should use DB instance name (example: RedSamuraiDB) and service name for pluggable DB created in Database Cloud (example: PDB1.ltredsamurai.oraclecloud.internal):

ADF applications deployed on Java Cloud will be fetching data from Database Cloud through data source.

Make sure to define WAR deployment profile for ADF application and specify context root:

ADF application should contain EAR deployment profile, which will reference WAR profile:

Uncheck "Auto Generate and Synchronize WebLogic JDBC Descriptors During Deployment" option in Application Properties (we don't need to deploy internal JDBC connection to Cloud):

Oracle Cloud offers services control dashboard. Here we can monitor active services, create new ones or stop existing ones. There is a list of options how to manage Java Cloud instance. Since my ADF BC REST application is enabled with ADF Security, I could go to WebLogic Server Console and create test user directly in DefaultAuthenticator:

Test user can be created exactly in the same way as on WebLogic running on-premise:

You can deploy ADF app on Oracle Cloud through EAR, using Enterprise Manager (don't forget to activate changes and start application). Application status can be reviewed from deployments list:

Try to access ADF BC REST service http://140.86.3.179/restapp/rest/1/Employees and enter redsam/welcome1 for login:

You should see JSON format data in response from ADF BC REST:

Download sample ADF BC REST application, the one I was using to deploy to Java Cloud - ADFBCRestApp_v9.zip.

Serving Oracle JET Application from WebLogic

Oracle JET application can be served from WebLogic as static content (HTML/JavaScript), JET code will be downloaded and executed on the client. Read more about packaging and deploying JET applications in developer guide - Packaging and Deploying Web Applications.

Here is demo JET application served on WebLogic server, port 7101. JET index.html page is referenced through application context root, registered on WebLogic during deployment of static content:

Required steps:

1. Generate JET application from basic template (use sudo on Mac OS):

yo oraclejet RSJETDemoApp --template=basic

2. Navigate to JET application folder and run grunt command to generate minified JET app structure under release folder:

grunt build:release

Grunt creates release structure and updates JS content, main.js contains merged JS content:

3. In order to serve JET as static content from WebLogic, we need to add WEB-INF folder and web.xml file. This will allow to deploy it as application to WebLogic. Create web.xml file with empty structure:

4. Final structure should look like this, web.xml and WEB-INF folder inside release:

5. Go to WebLogic Console and in deployment screen navigate to folder location, where release is located:

6. As for any other Web application deployment, choose Install this deployment as an application:

7. Provide application name and specify deployment accessible for the folder location:

8. Deployment should be completed without errors:

There is no other job for the server as to transfer HTML and JavaScript to the client. Code is running on the client.

Workaround for ADF BC REST Custom Method Configuration

This post is based on JDEV 12.2.1.1, it seems like there is issue with ADF BC REST custom method definition in this release. I'm glad it is not runtime issue, but related to design time JDEV wizard incorrect functionality. I will explain how to bypass it, when you want to expose custom REST method in 12.2.1.1.

Sample application (ADFBCRestApp_v8.zip) implements custom method, exposed through ADF BC REST - calculateEmployees. This method is created in VO Implementation class and it accepts two parameters - firstName and lastName. Method works correctly, I can execute it through POST, by passing predefined payload with method name and parameters (read more in developer guide - 22.12.5 Executing a Custom Action):

Make sure not to forget to specify Content-Type, otherwise POST request to ADF BC REST will fail:

Let's see custom method implementation and where workaround is required. Custom method is using View Criteria to filter VO and return estimated row count. All fine here:

Method should be exposed through VO client interface:

We should generate custo method binding registry in REST resource custom methods section (client interface). In JDEV 12.2.1 this works by clicking checkbox for Enable, but in JDEV 12.2.1.1 the same throws error (can't enable custom method to be called through REST):

Luckily there is a workaround. We can define method binding manually, go to source mode in REST resource definition dialog and add methodAction for custom method. You can replace method name, ID, instance name, etc. REST resource definition looks very similar to page definition file we are using to define bindings available for ADF Faces. ADF BC REST interface seems to be designed on common principles with ADF bindings, at least from definition point of view:

ADF BC REST Authentication with JSESSIONID Cookie

I have described how to apply ADF Security for ADF BC REST in my previous post - Oracle JET and ADF BC REST Basic Authentication. I will show how you can authenticate on first request and for the next requests rely on JSESSIONID cookie from the first request. This is useful for mobile clients and JET, there is no need to keep user credentials during requests (enough to keep cookie), as this is sensitive data.

Let's see how it works. In the first request we must authenticate. We are going to use basic authentication with GET operation and provide user credentials:

Request is authenticated and data is returned:

Along with data, extra information is returned with response - cookie and header. Cookie JSESSIONID value identifies authenticated session context. We can use this value for the next requests, this way server would assume us as trusted and would not ask to authenticate again (similar principle as in ADF web). Copy cookie value:

Now you can close and open Postman, to guarantee nothing is shared from previous request. Remove authentication header and add new header variable called Cookie. Value must be set as JSESSIONID=Cookie Value. Execute GET operation:

If session associated to this cookie is still active on the server, you will get response data, as it would be expected (no need to provide user credentials again):

ADF BC REST sample application - ADFBCRESTApp_v7.zip is protected by ADF Security with authentication and authorization:

REST servlet is mapped with appropriate security constraint in web.xml:

ADF 12.2.1.1 Improved Support for Programmatic View Object

ADF 12.2.1.1 brings improved support for programmatic VO creation. Such VO's are handy, when we want to base VO on alternative data source, such as PL/SQL ref cursor. In ADF 12.2.1.1 developer don't need to worry which framework methods to override, now it is enough to extend from Programmatic View Object Implementation class. This is special framework helper class, designed for programmatic VO support. See example below.

Sample application (ADF12211App.zip) is based on one regular VO, which renders employees table. Programmatic VO renders data for tag cloud component, located below table:

Steps to create programmatic VO are much more simple in ADF 12.2.1.1. Select data source option to be Programmatic in VO creation wizard:

JDEV will create VO with Java implementation classes, extended from ProgrammaticViewObjectImpl class and ProgrammaticViewRowImpl class. These classes will take care for special lifecycle required for programmatic VO behavior. See extends part:

Generated class contains getScrollableData extended method. This is the place to supply data collection for the VO. In my example, I'm creating ArrayList (VO rows) of HashMap's (one HashMap, represents row data of attribute/value pair). Attributes are populated with values and collection is returned back to the framework to manage it. Method is being called automatically by the framework. There are other methods available, to retrieve row by key, etc.:

New framework class allows to work with programmatic VO's easier and leverage framework features. I would expect it would provide better support for programmatic VO data filtering.

VO data is accessed on UI through regular binding expressions:

Initialized by ADF bindings layer: