RESTful Services

Table of Contents

2. DOCUMENT SCOPE

The Introduction to jAgent REST Services document serves as a starting point for Administrators that are new to jBASE and would like to setup RESTful Services for integration of web services into their jBASE system.

3. ABOUT jBASE DATABASE MANAGEMENT SYSTEM

jBASE is a world class Database Management System comprising development tools, middleware and a multi-dimensional database. jBASE takes the best points of the relational database model and adds to it several significant benefits including ease of use, superb performance, small footprint and all the rich multivalue features, making it ideally suited to all business uses from the Internet to OLAP to transactional applications. The architecture is uniquely designed to allow all and any application development tools and backend databases to form part of a jBASE solution.

jBASE utilizes a highly flexible multidimensional data model. The fundamental architecture of this data model is one that enables the database to be designed as quickly as you can design forms. So no longer is a crew of DBAs or an army of consultants needed to implement and keep it running. Because the database allows tables embedded within other tables, you do not need to design your application around the database, but rather design it around your business and solving the business requirement at hand.

More than twenty five years of innovation and determination has led to the evolution of a product that is perfectly placed for today and tomorrows application needs. Explore what this robust platform has to offer multivalue applications.

4. PREREQUISITES

To perform this steps in this walkthrough document, you will need an installed and licensed system running jBASE 5.6. If you need to complete this task, please review jBASE 5.6 Installation Guide for Windows or Linux.
You should also have reviewed Introduction to jBASE, for knowledge of commands and utilities used in this walkthrough.

5. jAGENT SYNOPSIS

jAgent is a server-side jBASE component responsible for accepting and processing incoming client requests. jAgent was introduced in jBASE 5.2 release.

Communication is established via TCP socket connections and by means of a well defined protocol. jAgent is a socket server listening on a user-defined TCP port and has the capability to serve a wide range of client applications as long as they speak the same protocol.

This protocol is currently implemented by the following jBASE components:

6. CONFIGURING jAGENT

COMMAND SYNTAX:

jbase_agent [service options] [options]

COMMAND ELEMENTS:

Option

Description

--config=[config file name]

Use [config file name] to specify jagent options. When using the jBASE HTTP API (RESTful services), a configuration file is required, as it specifies how HTTP requests are handled. E.g. jbase_agent --config=$JBCRELEASEDIR/config/ jagent_config

-A [mode]
--authentication=[mode]

[mode] = the mode (none|user|account) used to authenticate client connections. This option is ignored for jBASE HTTP connections. E.g. jbase_agent -A user

-b [interfaceName]
--bind_address=[interfaceName]

Bind to a specific local interface. If not specified then bind to all local interfaces. E.g. jbase_agent -b 1.2.3.4

-c [path to certificate]
--certificate=[path to certificate]

[path to certificate] = the path to a valid x509 certificate. Note --private_key is mandatory with this option.

-F

Create log files for each client connection (P[pid].log)

-h

Print this screen

-k [path to private key]
--private_key=[path to private key]

[path to privatekey] = the path to a valid private key. Certificate is mandatory with this option. E.g. jbase_agent --private_key=key.pem --certificate=cert.pem

L [logLevel]
--loglevel=[logLevel]

[logLevel] = a numeric log level that determines the detail to be logged (default level is LOG_NOTICE).
0 NO LOGGING
1 LOG_TRACE
2 LOG_DEBUG
3 LOG_INFO
4 LOG_NOTICE
5 LOG_WARNING
6 LOG_ERROR
7 LOG_CRITICAL
8 LOG_ALERT
9 LOG_EMERGENCY

-n [serviceName]
--service_name=[serviceName]

[serviceName] = name of the service to install, start, stop or remove.

-N

Do not set TCP_NO_DELAY. Useful for performance tuning.

-p [listenPort]
--port=[listenPort]

[listenPort] = theport that will listen for client connections. E.g. jbase_agent -p 20003

-R [bufferSize]
--read_buf_size=[bufferSize]

Set read buffer size (in bytes) to [bufferSize]. If not specified uses default buffer size.

-W [bufferSize]
--write_buf_size=[bufferSize]

Set write buffer size (in bytes) to [bufferSize]. If not specified uses default buffer size.

  • Windows will receive prompt to allow access to ports for OS firewall

  • Linux will need to open ports for OS firewall

Creating your demo account and REST file
1. Create the jBASE account DEMO_REST

  • JBASEADM ~ -->CREATE-ACCOUNT DEMO_REST

  • Account 'DEMO_REST' created.jsh 
  • JBASEADM ~ -->LOGTO DEMO_REST

  • jsh DEMO_REST ~ -->PWD

  • C:\jBASE\DEMO_REST
  • jsh DEMO_REST ~ -->

2. Create WDB.RESOURCE file in the DEMO_REST account

  • jsh DEMO_REST ~ -->CREATE-FILE WDB.RESOURCE 1 51

  • [ 417 ] File WDB.RESOURCE]D created , type = J4
  • [ 417 ] File WDB.RESOURCE created , type = J4

3. Edit the WDB.RESOURCE file with JED.  Enter edit mode by pressing Enter and adding the highlighted data below:

  • jsh DEMO_REST ~ -->JED WDB.RESOURCE API*HELLOWORLD

  • File WDB.RESOURCE , Record 'API*HELLOWORLD' Insert 14:26:12
  • Command->

  • 0001 P
  • 0002 TEST HELLO WORLD
  • 0003 HELLOWORLD
  • 0004
  • 0005 1
  • 0006 1

End Of Record


4. Save and exit by pressing Esc and entering FI into the command line

WDB.RESOURCE File Attributes:

Attribute

Description

1

Type

2

Description

3

Controller

4

Program

5

Parse CGI Switch

6

Enabled

CONFIGURE JAGENT
1. Identify the path of your demo account, keep note of it for step #3

  • jsh DEMO_REST ~ -->PWD

  • C:\jBASE\DEMO_REST
  • jsh DEMO_REST ~ -->

2. Open jSHELL  and change directories to the Current Version directory

  • jsh DEMO_REST ~ -->CD C:\JBASE\CURRENTVERSION\CONFIG

3. Open JED and edit JAGENT_CONFIG file, adding the highlighted information below in lines 100-102

  • jsh DEMO_REST C:\JBASE\CURRENTVERSION\CONFIG -->JED JAGENT_CONFIG

  • File . , Record 'JAGENT_CONFIG'         Insert 15:14:36
  • Command->

  • 0001 #
  • 0002 # Configuration file for jAgent
  • 0003 #
  • 0004
  • 0005 [MAIN]
  • **Skip to line 98**
  • 0098 ; Set up the "account" environment variables.
  • 0099 HOME=%CURDIR%
  • 0100 PATH=%HOME%\bin;%PATH%;C:\JBASE\DEMO_REST\BIN
  • 0101 JBCOBJECTLIST=%HOME%\lib;C:\JBASE\DEMO_REST\LIB
  • 0102 JEDIFILEPATH=%HOME%;C:\JBASE\DEMO_REST
  • 0103 JEDIFILENAME_MD=%HOME%\MD

4. Save and exit by pressing Esc and entering FI into the command line

Create your REST Program 1. Create your REST program file

  • jsh DEMO_REST ~ -->CREATE-FILE BP TYPE=UD

  • [ 417 ] File BP]D created , type = UD
  • [ 417 ] File BP created , type = UD

2. Create your REST program record

  • JED BP HELLOWORLD
  • NEW *File BP , Record 'HELLOWORLD' Insert 14:46:48
  • Command->0001 CALL WSEND("HELLO FROM LINE ":@USER.NO)

  • 0002

3.Save and exit by pressing Esc and entering FI into the command line

4. Compile and catalog your program BP HELLOWORLD

  • jsh DEMO_REST ~ -->BASIC BP HELLOWORLD

  • HELLOWORLD
  • BASIC_10.c
  • Source file HELLOWORLD compiled successfully
  • jsh DEMO_REST ~ -->CATALOG BP HELLOWORLD

  • HELLOWORLD
  • Object HELLOWORLD cataloged successfully

4. Verify program BP HELLOWORLD runs

  • jsh DEMO_REST ~ -->HELLOWORLD

  • Content-type: application/json
  • Cache-Control: no-cache
  • HELLO FROM LINE 10

5. Initiate jAgent session

  • jsh DEMO_REST ~ -->CD C:\JBASE\CURRENTVERSION\

  • jsh DEMO_REST C:\JBASE\CURRENTVERSION -->JBASE_AGENT 

  • --config CONFIG\JAGENT_CONFIG
  • (5756|12660) NOTICE starting up jAgent, 
  • Process Per Connection mode, listening on port 20002
  • , c:\zumasys\src\international\5.6.x\jagent\
  • SocketAcceptor.h +63

6. Keep the terminal session open and open an Internet browser and browse to:

7. Once finished, close the browser and enter Ctrl + C to terminate jAgent session

7. SUPPORT

Contact jBASE support in the United States at 866 582 8447 and from the United Kingdom at 0808 189 3266. You may also email [email protected] and visit http://www.jbase.com/support/ for more support options.

8. GLOSSARY

jBASE

An open database product that brings the strengths of MultiValue technology into the mainstream computing market; providing a multidimensional database, a development environment including a development language, and a middleware component allowing other mainstream and standards-based products to communicate with the jBASE products.

jED

The jBASE Editor. jED is a fully featured screen editor, which can be used for creating, modifying, or deleting records.

jSHELL

The jBASE shell. It can be invoked as your login shell by using the normal system administration software supplied with the platform. Either via .bat files (Windows) or .profiles (Unix ).

CREATE-ACCOUNT

The CREATE-ACCOUNT command creates a new jBASE account directory. The new account is registered in the SYSTEM file.

CREATE-FILE

The CREATE-FILE command enables the user to create a new file for use within the jBASE system.