We have new tool from Oracle which can help to simplify offline logic implementation for JS apps. In this post I will describe how to use Oracle Offline Persistence Toolkit with Oracle JET. However Offline Persistence is not constrained by JET usage only, this toolkit is available on NPM and can be integrated with other JS solutions.
I should emphasise - offline toolkit primary role is to enable mobile hybrid apps to work offline. In my opinion, toolkit usage doesn't stop here. It can enable user to continue his work, when internet connection is available, but back-end server goes down. Technically user would remain online in this case, but in practice application will be broken - no response from back-end for REST calls. Offline persistence toolkit could help to solve such cases - user could continue working with local cache, until back-end is down.
If you want to learn how offline toolkit works and how to use its API, go to GitHub page - check readme, add it to your JET app and try to run/test. Hands-on is the best way to learn something new.
I will share few hints and sample app.
As per readme, first of all you should add Offline Persistence Toolkit and PouchDB modules from NPM. Run these commands within JET app directory:
1. npm install @oracle/offline-persistence-toolkit
2. npm install pouchdb pouchdb-find
Next you should follow four simple configuration steps and enable JET app to be able to access offline toolkit API.
Step 1 (standard, when adding any additional module)
Add paths to newly added modules in main.js require block:
Step 2 (standard, when adding any additional module)
Add paths to newly added modules in main-release-paths.js:
Step 3 (standard, when adding any additional module)
Added modules would not be copied to build directory automatically. We need to define copying in oraclejet-build.js. Modules should go to build directory. If you need to copy files from given folder and subfolders, use ** for src:
Build content is located in web directory. Offline toolkit and PouchDB modules should be copied to build directory:
Step 4
Initialize window.PouchDB variable in main.js:
Configuration is complete, now we can use Offline Persistence Toolkit API. Add persistence store manager and other modules:
Simplest option is to rely on default fetch listener from offline toolkit. We need to register store factory and map endpoint which we want to cache with persistence manager. When back-end is available - call will go to back-end and response will be cached. Next time, of back-end is not available - data will be fetched from cache. Toolkit intercepts HTTP(-S) request and stores response, if end-point was configured to be listened:
I'm testing offline toolkit with simple Employees REST end-point call from JET. Toolkit allows to execute this call successfully, even if there is no back-end or no connection (of course - if same call was executed at least once before):
UI part is simple - displaying list, when data is fetched:
Data is fetched, we are online:
Offline toolkit will work, if REST response doesn't include Cache-Control header. Make sure there is no Cache-Control header set in response:
ADF BC REST by default sets Cache-Control header, you can remove it in Filter class (defined in ADF BC REST app):
Now I turned my connection to be offline, clicked on Get List button - JS calls REST and instead of getting network error, it executes successfully and returns data from cache through offline toolkit functionality:
You should open details for network call and check initiator. You will see that all calls mapped to offline endpoint are going through persistenceManager.js:
Let's double check - may be we are tricked somehow? Remove offline toolkit registration API in the code and re-run application:
As expected - network error is received and fetch fails. This proves - offline toolkit works :)
Sample JET application with offline toolkit configuration is available on GitHub (run ojet restore and ojet serve).
I should emphasise - offline toolkit primary role is to enable mobile hybrid apps to work offline. In my opinion, toolkit usage doesn't stop here. It can enable user to continue his work, when internet connection is available, but back-end server goes down. Technically user would remain online in this case, but in practice application will be broken - no response from back-end for REST calls. Offline persistence toolkit could help to solve such cases - user could continue working with local cache, until back-end is down.
If you want to learn how offline toolkit works and how to use its API, go to GitHub page - check readme, add it to your JET app and try to run/test. Hands-on is the best way to learn something new.
I will share few hints and sample app.
As per readme, first of all you should add Offline Persistence Toolkit and PouchDB modules from NPM. Run these commands within JET app directory:
1. npm install @oracle/offline-persistence-toolkit
2. npm install pouchdb pouchdb-find
Next you should follow four simple configuration steps and enable JET app to be able to access offline toolkit API.
Step 1 (standard, when adding any additional module)
Add paths to newly added modules in main.js require block:
Step 2 (standard, when adding any additional module)
Add paths to newly added modules in main-release-paths.js:
Step 3 (standard, when adding any additional module)
Added modules would not be copied to build directory automatically. We need to define copying in oraclejet-build.js. Modules should go to build directory. If you need to copy files from given folder and subfolders, use ** for src:
Build content is located in web directory. Offline toolkit and PouchDB modules should be copied to build directory:
Step 4
Initialize window.PouchDB variable in main.js:
Configuration is complete, now we can use Offline Persistence Toolkit API. Add persistence store manager and other modules:
Simplest option is to rely on default fetch listener from offline toolkit. We need to register store factory and map endpoint which we want to cache with persistence manager. When back-end is available - call will go to back-end and response will be cached. Next time, of back-end is not available - data will be fetched from cache. Toolkit intercepts HTTP(-S) request and stores response, if end-point was configured to be listened:
I'm testing offline toolkit with simple Employees REST end-point call from JET. Toolkit allows to execute this call successfully, even if there is no back-end or no connection (of course - if same call was executed at least once before):
UI part is simple - displaying list, when data is fetched:
Data is fetched, we are online:
Offline toolkit will work, if REST response doesn't include Cache-Control header. Make sure there is no Cache-Control header set in response:
ADF BC REST by default sets Cache-Control header, you can remove it in Filter class (defined in ADF BC REST app):
Now I turned my connection to be offline, clicked on Get List button - JS calls REST and instead of getting network error, it executes successfully and returns data from cache through offline toolkit functionality:
You should open details for network call and check initiator. You will see that all calls mapped to offline endpoint are going through persistenceManager.js:
Let's double check - may be we are tricked somehow? Remove offline toolkit registration API in the code and re-run application:
As expected - network error is received and fetch fails. This proves - offline toolkit works :)
Sample JET application with offline toolkit configuration is available on GitHub (run ojet restore and ojet serve).
No comments:
Post a Comment