Working with JSON Data in Exadata Express Document Stores


Options



Before You Begin

Purpose

This tutorial covers how to populate an application with information stored as JSON data in Oracle Database Exadata Express Cloud Service document stores.

Time to Complete

Approximately 90 minutes

Overview

In this tutorial, you create a document store in Exadata Express, and then populate a movie ticketing application with information stored as JSON data in the Exadata Express document store.

Context

This tutorial demonstrates an application that combines document-centric application development techniques, JSON based data persistence, and REST Services with an Oracle Database.

The application is a simulation of a system for searching movies and theaters and then purchasing tickets to see a given showing of a movie. It is a single-page web application, built using a decoupled AngularJS front-end that communicates with a set of REST services provided by an application tier developed in Node.js. The application tier uses REST to invoke micro-services provided by Oracle's SODA for REST, a component of Oracle Rest Data Services (ORDS). SODA for REST provides data persistence services for JSON and other kinds of documents.

The Application tier uses SODA for REST and Oracle REST Data Services (ORDS) to communicate with the back-end data store. The back-end data store is an Oracle 12c Database. For this tutorial, the back-end data store resides in the Oracle Database Exadata Express Cloud Service.

The architecture for this version of the movie ticketing application is as follows:
architecture for application
Description of this image

What Do You Need?

Before starting this tutorial, you should have an Oracle Database Exadata Express Cloud Service account. To learn how to sign up for an Exadata Express account, see this tutorial.

Obtain an API Key for TMDb

This tutorial's Movie Ticketing demonstration works with sample data downloaded from publicly available websites. The THEATER collection is populated with data obtained from an RSS feed published by Fandango.com. The Movie and Poster collections are populated using data obtained from the website themoviedatabase.org (TMDb). To obtain data from TMDb, you must register with this site and obtain an API key.

Perform the following steps:

  1. Register for an account with themoviedatabase.org (TMDb) by following the instructions found here.
    register for account with tmdb
    Description of this image
  2. Respond to the verification email, then sign in to your account, and click the API link in the menu.

    click the API link
    Description of this image
  3. In the API page, click the click here link to request an API key.

    click the click here link
    Description of this image
  4. On the next API page, click Developer.

    click developer
    Description of this image
  5. On the Accept API Terms page, click Accept

  6. The Request an API Key dialog appears. Provide a name for the application, such as Movie Ticketing. For the URL, specify Not Applicable. In the Application Summary field, explain that this is for educational purposes, to learn how to create an application that uses movie information stored in a database. Provide your name, email, and address information and click Submit.

    request an API key dialog
    Description of this image
  7. If your request is approved, you will receive an email from TMDb containing your TMDb API Key.
    Make a note of this TMDb API Key, which you will use later in this tutorial.

    approval email with API Key
    Description of this image

Install Node.js

In this section, you install Node.js. Perform the following steps:

  1. Download Node.js from https://nodejs.org/en/download/.
    This tutorial shows the steps for installing Node.js to a Windows PC.  To download and install to other environments like Linux or Mac, please refer to the platform-specific installation instructions at https://docs.npmjs.com/getting-started/installing-node.

    Download the Windows Installer to your PC.

    download nod_js Windows installer to your PC
    Description of this image

    save node_js file
    Description of this image
  2. Install Node.js
    Double click the Windows installer file, which will have a name similar to node-v4.6.1-x64.msi, depending on the version you downloaded. An installation wizard appears. Click Next.

    welcome to node_js wizard
    Description of this image
  3. Accept the terms in the license agreement and click Next.

    accept the terms
    Description of this image
  4. Select the destination folder and click Next.

    select destination folder
    Description of this image
  5. Accept the default settings on the Custom Setup screen, unless you want to customize how the features are installed. Click Next.

    accept default setting
    Description of this image
  6. Click Install.

    click Install
    Description of this image
  7. When the installation finishes, click Finish to exit the wizard.

    click Finish
    Description of this image
  8. The Windows Start menu shows this new folder.

    Windows Start menu shows new folder
    Description of this image

Install the Movie Ticketing Application

Note:  If you are behind a corporate firewall, see the article: "How to setup Node.js and npm behind a corporate web proxy" found at  https://jjasonclark.com/how-to-setup-node-behind-web-proxy
The article provides details for opening a command prompt or terminal session and running the following commands to configure NPM to work with your web proxy. The example below uses proxy.company.com as the address and 8080 as the port. Swap in your company name and port.
Note that the second command uses a hyphen in "https-proxy", not an underscore as in "https_proxy".

npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

use npm config to modify for firewall 
Description of this image

  1. Use NPM to install the movie ticketing application and its dependencies.

    Open a Windows command prompt (or the Node.js command prompt) and use the mkdir command to create a directory, exaExpress, for the application. Change to that directory and run the following command to install this tutorial’s movie ticketing demo:
    npm install oracle-movie-ticket-demo

    use NPM to install
    Description of this image
  2. The installation will take a few moments. When done, it will appear similar to the following:

    demo installation complete
    Description of this image

Create the Exadata Express Document Store to Manage the Movie Tickets Document Collections

Instead of using an Oracle on-premises database schema, you will create an Exadata Express Cloud Service document store to manage this tutorial’s Movie Tickets document collections used in this movie ticketing application.

  1. Log in to your Oracle Exadata Express account, and open the Service Console. Click Create Document Store.

    click Create Document Store
    Description of this image
  2. In the Create Document Store dialog, click New Schema.
    Enter movies as the schema name.
    Enter a password that is at least 8 characters long, with mixed uppercase and lowercase characters, with at least one number, and one special character (for example, Bbbbbb#2).
    Select Enable SODA for REST.
    You do not need to define a new dedicated tablespace for this tutorial.
    Click Create Document Store.

    click Create Document Store
    Description of this image
  3. A success screen appears. Click Done.

    Success
    Description of this image

Modify Node.js Configuration Files

The next steps involve modifying two Node.js configuration files to point to your Exadata Express database and to utilize your TMDb API key.

  1. Navigate to the folder where you installed the movie ticketing application to your Node.js installation.  You will modify config.json to point to your Exadata Express database, and you will modify dataSources.json to specify your TMDb API Key.

    In this example, the screenshots show that Node.js was installed to D:\exaExpress. The movie ticketing application was installed from that directory into the oracle-movie-ticket-demo subdirectory. So for this example, we navigate to the D:\exaExpress\node_modules\oracle-movie-ticket-demo subdirectory.

    navigate to configuration files
    Description of this image
  2. Use Windows Notepad to make 5 edits in the config.json file, as shown in the following screenshot:

    • Protocol: change "http" to "https". 
    • Hostname: This is the name or IP address of the machine hosting the ORDS instance.  Change “localhost” to the hostname of your Exadata Express Cloud Service instance in which you have created the Document Store.  You can find the service instance’s hostname by connecting to your Exadata Express Service Console, and copy/pasting the front portion of the URL without “http://”, up through “.com”
      Note: Alternatively, you can find your Exadata Express service instance’s hostname if you are in the Exadata Express Service Console. Copy/paste the front portion of the URL, up through “.com”.
    • Port: This is the Exadata Express port number that the ORDS instance is listening on. Since we’re running HTTPS, change the port number from “8080” to “443”.
    • Path: This is the endpoint that provides access to the Movie Ticketing document store. Since we’re using a database in Exadata Express, change the path “/ords/movies/soda/latest” to “/apex/movies/soda/latest”.
      (Exadata Express uses APEX, and “movies” is the name we gave to the schema we created when creating the Document Store.) 
    • Username and password: This is the user name and password used by the Node.js server to authenticate with the ORDS server in Exadata Express Cloud Service.
      Change the username and password from “MovieTicketing” to your administrative username and password for connecting to the Exadata Express Service Console.
      Note: This is not the name and password of the database schema you created when you created the Document Store in Exadata Express.
      For the purposes of this tutorial, you can simply use the administrative username and password that you use to connect to the Exadata Express Service Console.
      In your production environment, you would instead create an Exadata Express user with the SODA_APP role. 

    • modify config_json
      Description of this image
  3. Use Windows Notepad to edit the dataSources.json file.
    In the “tmdb” section, specify your TMDb API Key, in place of the “YOUR_TMDB_KEY_GOES_HERE” placeholder.
    Note: You will notice that the dataSources.json file also has sections for “fandango” and “google” sources.
    If you are in the United States, you can specify your zipcode in the fandango section.
    Support for Google geocoding will be enabled in a subsequent release of this Movie Ticketing application.  Please do not alter the value of the key "geocodingService".  Support for geocoding of theaters is planned for a future release of this application. Once Geocoding is enabled the information associated with the keys 'google’, 'usCensus’ and 'mappingService' will become relevant.

    Note:  If you are behind a firewall, you will need to change “useProxy” from false to true, and provide your organization’s proxy “hostname” and “port”.

    modify DataSources_json
    Description of this image

Start the Node.js Application Server

So far, you have:

  • obtained a TMDb API key
  • installed Node.js
  • installed the Movie Ticketing application
  • created a Document Store in Exadata Express
  • modified the config.json and dataSources.json files

The next step is to start the Node.js server on your local computer.  

  1. Start Node.js server by executing the command:  node index.js.  In Windows, run the command from the directory where you installed the MovieTicketing application; in our  example, the D:\exaExpress\node_modules\oracle-movie-ticket-demo subfolder.

    start node_js
    Description of this image
  2. The system should respond with something similar to this:

    result of executing node index_js
    Description of this image

Launch the Application Using a Browser

The final step is to launch the movie ticketing application and load its documents to see results.

  1. The application is configured to run on Port 3000. To navigate to the application start page, open a browser window and enter the following URL:  localhost:3000.
    If you acquired a TMDb API Key in the first step of this tutorial, and specified that key in the dataSources.json file, you will find the key automatically entered in the Application Settings section at the top of the page.
    Before using the application, click the 4 Load buttons in the following order, waiting for each load to complete before moving to the next Load button:

    • Theater Collection - downloads theater information from Fandango.
    • Movie Collection - downloads movie information from TMDb.
    • Poster Collection - downloads movie posters from TMDb.   (The Load button for Poster Collection will appear after Movie Collection is loaded.)
    • Screening Collection - generate 2 weeks' worth of screenings from the current set of theaters and movies.

    Note:  The Movie Collection and Poster Collection loads will run for several minutes, subject to the throughput restrictions imposed by the TMDb website used in this tutorial’s movie ticketing application.

    movie app initial screen
    Description of this image
  2. Once the Posters have been loaded and the Screenings have generated, the application will automatically reload itself and the List Theaters and List Movies tabs will be displayed. The application is now ready for use.

    application ready for use
    Description of this image
  3. Explore the application. In the List Theaters tab, choose a theater and click Movies to see which movies are playing at that theater. In the List Movies tab, choose a movie and click Theaters to see which theaters this movie is playing in.

    explore the application
    Description of this image
  4. To learn details of how the Movie Ticketing application was created, click the documentation link in the upper right corner of the browser window.

Summary

In this tutorial, you have learned how to:

  • Obtain a TMDb API key
  • Install Node.js
  • Install the Movie Ticketing application
  • Create a document store in Oracle Database Exadata Express Cloud Service
  • Populate the Movie Ticketing application with information stored as JSON data in Exadata Express document stores

Want to Learn More?

Credits

  • Curriculum Developer: Rick Green

  • Other Contributors: Mark Drake