FairCom DB API for Java Overview

This book contains the Java developer tutorials of the FairCom DB API Java API. In these simple steps and about 15 minutes, you’ll be navigating your data.

  1. Install and start up the FairCom Database Engine. See Installing FairCom Products.
  2. Optionally read the overview Introduction to the NAV API for Java.
  3. Compile the tutorials as explained in Compiling Your Projects.
  4. Run the tutorials or read the Tutorials section to see tutorial code with brief explanations.

Tip: To view, edit, and run the source code for the tutorials, you can go directly into the <faircom>\drivers\java.nav\tutorials folder that is installed with the product. Each tutorial has been thoroughly tested on each operating system, interpreter, and compiler to ensure you have an excellent experience.

Resources

c-tree Database API for Other Languages

FairCom allows you to use NAV APIs with the language of your choice:

Note: FairCom supports all actively-supported LTS versions of the Oracle JDK, and the most recent release (non-beta) version of Oracle OpenJDK.

 

Introduction to the NAV API for Java

The FairCom DB Java Language DataBase Interface Technology, commonly referred to as the FairCom DB API Java API (or "JTDB"), provides Java developers a unique record-oriented, non-SQL, navigational ("NAV") Java framework to manage data with the FairCom Database Engine. This interface offers alternatives to the Java developer requiring direct access to data records for performance advantages while still allowing full JDBC SQL access to the same data.

The FairCom DB API Java API makes the FairCom DB API navigational, "NAV", database architecture available to Java programmers.

The FairCom DB API Java API provides libraries that allow Java programs to access the c-tree database core. It provides a simple interface into c-tree that includes the advanced functionality that distinguishes c-tree from other database solutions. FairCom DB API Java offers a method of database creation and maintenance that is easier to use than the FairCom DB ISAM and FairCom Low-Level APIs.

More about the FairCom DB API API

The FairCom DB API API for Java is a record-oriented database API. Its short name is FairCom DB API Java or simply "JTDB". It is in the "NAV" family of APIs because it makes it easy for application developers to navigate data — no matter how complex.

FairCom DB API Java is an object-oriented API that provides precise control over every aspect of data processing. It leverages the familiar concepts of databases, tables, records and fields. For example, it can connect to a database, open a table, find a record by key, and walk records in key order.

The FairCom DB API API makes it easy to navigate and process data very quickly across multiple databases no matter where they are located. Its unique ability is to simultaneously open cursors into multiple databases and remote control them. Applications use cursors to control every detail of record lookup and traversal. There are multiple types of cursors: index, table, filtered, range, metadata, batch query, batch insert, batch update, and batch delete. Each is optimized to make different use cases easy and fast. For example, your application can retrieve a record from one database and use its data to quickly position a cursor in another database to batch retrieve additional records.

 

Because the FairCom Database Engine is optimized specifically for cursors, applications can easily do very complex data processing tasks at high speed. Developers are not limited to using built-in SQL or GQL algorithms. A software developer can easily implement algorithms to traverse data as hierarchies, graphs, objects, tables, etc. A data engineer or data scientist can implement unique algorithms for machine learning, graph analytics, knowledge graphs, big data, etc. A back-end programmer can implement optimized algorithms for real-time transaction processing, high-velocity inserts, specialized microservices, etc.

While navigating records, a developer can do anything with the data, such as insert, update, and delete records. FairCom DB API can find, retrieve, and process field values. Field values can be any common data type: JSON, custom binary structures, arrays, strings, numbers of all types, dates, times, monetary values, Boolean, etc. The database can automatically index fields containing these data types.

FairCom DB API works simultaneously with SQL. Applications can use SQL and FairCom DB API at the same time on the same data. SQL tools can simultaneously work with the same data as an application using FairCom DB API.

SQL is ideal for writing queries that join data. FairCom DB API is ideal for navigating complex data, such as walking hierarchies and graphs or implementing custom data processing algorithms. FairCom DB API is easier than SQL because there is very little to learn and it is 100% predictable.

FairCom DB API makes it easy to process complex data because developers can leverage the full power of their development language to break down complexity into manageable code. FairCom DB API extends a developer's favorite development language directly into the database. In other words, a programmer can use their favorite programming language to remote control the database and directly process data. FairCom DB API eliminates the need to learn a proprietary database language; instead, a developer’s favorite language becomes the database language.

FairCom DB API is ideal for achieving extreme, predictable performance because it gives developers complete control over:

  • Navigating records in any order
    • Index- or table-order
    • Forward or backward
    • Filtered
    • Ranged
    • Partial-key
    • Bulk processed
    • Etc.
  • Saving record positions
  • Jumping back to saved positions
  • Controlling if and how each record is locked
  • Managing which records participate in transactions
  • Using custom algorithms to join data across tables
  • etc.

 

Compiling Your Projects

This chapter explains how to compile the tutorials that guide you through the basic use of the FairCom DB API Java interface technology.

The source code is located in the drivers\java.nav\tutorials folder.

Compiling and Executing the Tutorials

These samples can be compiled in these ways:

See Also:

 

Command Line Compile

To compile the FairCom DB API Java tutorials from the command-line, follow these steps:

This document is oriented toward a Windows command-line environment. The principles are the same for all other environments, such as Linux/Unix.

Note: The FairCom FairCom DB API Java API requires a Java Development Kit (JDK) be installed on your computer. A Java Runtime Environment (JRE) is not sufficient. Note also that the Java compiler (javac.exe) must be in your system path. On Windows, this file typically resides in a path similar to C:\Program Files\Java\jdk_______\bin, and can be set with a command similar to the following: set path=%path%;C:\Program Files\Java\jdk_______\bin

Building and running the tutorials with the batch file:

Move to the drivers\java.nav\tutorials\cmdline directory and execute the BuildTutorials.bat file for Windows, or make for Linux. This file will determine if a Java JDK is installed, and if it is 32-bit or 64-bit. It will then compile all of the tutorials included for this tutorial. Lastly, it will execute each tutorial for you, so be sure you have the FairCom DB SQL Server running on your system.

By default, the output of the first tutorial will look similar to this:

 

INIT
Logon to server...
DEFINE
Open table...
Add fields...
Create table...
MANAGE
Delete records...
Add records...
Display records...
1000 Bryan Williams
 
1001 Michael Jordan
 
1002 Joshua Brown
 
1003 Keyon Dooling
DONE
Close table...
Logout...
 
Press <ENTER> key to exit . . .

 

Troubleshooting

This section lists some errors you may encounter when compiling and running the tutorials using the batch / make file.

JDK not found! Please set environment for the Java JDK.

On Windows, this means that the Java compiler (javac.exe) is not in your system path. Follow the instructions above to put javac.exe in your path.

 

ERROR: [133] - c-tree logon error.

The most common cause of this run-time error is the FairCom Database Engine is not running on your machine. The most likely cause is that the c-tree evaluation license times out after 3 hours and shuts down the server. The solution is to restart the server. See Starting the FairCom Database Engine.

 

Building and running the tutorials by hand:

If you want to build the tutorials manually, run these commands from the drivers\java.nav\tutorials directory:

javac -cp ../ctreeJTDB.jar JTDB_Tutorial1.java

javac -cp ../ctreeJTDB.jar JTDB_Tutorial2.java

javac -cp ../ctreeJTDB.jar JTDB_Tutorial3.java

javac -cp ../ctreeJTDB.jar JTDB_Tutorial4.java

 

Troubleshooting the manual build:

error: package FairCom.CtreeDb does not exist
error: package FairCom.CtreeDb.Types does not exist
error: cannot find symbol

These errors indicate that the ctreeJTDB.jar file was not found. Either your -cp parameter is wrong, or you are executing the javac command from the wrong directory. The -cp parameter should point to the ctreeJTDB.jar file in the drivers/java.nav folder.

 

Executing the Tutorials

You can now execute each example as follows:

java -cp .;../ctreeJTDB.jar -Djava.library.path=../ JTDB_Tutorial1

java -cp .;../ctreeJTDB.jar -Djava.library.path=../ JTDB_Tutorial2

java -cp .;../ctreeJTDB.jar -Djava.library.path=../ JTDB_Tutorial3

java -cp .;../ctreeJTDB.jar -Djava.library.path=../ JTDB_Tutorial4

Note that execution under Linux uses a colon (‘:’) as the classpath (-cp) separator, instead of a semicolon (‘;’).

Also note the classpath (-cp parameter) and java.library.path (-D parameter) tells the JRE where to find the JAR and the shared library files. If you move your project to a new location, you will need to either update those paths or move those files.

Troubleshooting the manual execution / run:

ERROR: [133] - c-tree logon error.

The most common cause of this run-time error is the FairCom Database Engine is not running on your machine. The most likely cause is that the c-tree evaluation license times out after 3 hours and shuts down the server. The solution is to restart the server. See Starting the FairCom Database Engine.

 

Error: Could not find or load main class JTDB_Tutorial1

The most common cause of this runtime error is leaving the current directory "." out of the classpath (specified by the -cp parameter).

 

Error: A JNI error has occurred, please check your installation and try again
Exception in thread "main" java.lang.NoClassDefFoundError: FairCom/CtreeDb/CTException

This error indicates that the ctreeJTDB.jar file was not found. Either your -cp parameter is wrong, or you are doing this from the wrong directory. The -cp parameter should point to the ctreeJTDB.jar file in the drivers/java.nav folder.

 

Exception in thread "main" java.lang.UnsatisfiedLinkError: no mtclijni____ in java.library.path

Exception in thread "main" java.lang.UnsatisfiedLinkError: no libmtclijni____ in java.library.path

This error indicates that the mtclijni shared library / DLL file was not found. Please make sure the folder indicated by your -D parameter contains the mtclijni__.dll (Windows) / libmtclijni__.so (Linux/Unix) / libmtclijni__.dylib (MacOS) file.

 

Usage: java [-options] class [args...]
-bash: ../ctreeJTDB.jar: Permission denied

This is generally caused (on Linux/Unix) by using a semicolon instead of a colon in the list of folders that follows the -cp parameter.

java api faircom

Was this article helpful?

Give feedback about this article

Related Articles