Providing easy data access to Java programs

.pearl-hilighted-word {background-color: #ffffff !important; color: #000000 !important;}

Issue 3, 2016

Download pdf
 

Adabas client for JAVA®

Easily access Adabas data from Java applications without having any knowledge of Adabas. Use Java to access Adabas in the same way you embed other data sources into a Java project. Integrate data smoothly into Web applications and Web services.

Introduction

Java is the de facto standard for programming languages. While many other languages such as C#, Perl, Python and Ruby continue to evolve and be widely used, Java is the most prominent language taught in schools and universities. Almost all young people in IT have solid expertise in Java. In addition, or perhaps the result of, the IT industry invests heavily in Java-based solutions. Therefore, all data stores, including Adabas, are compelled to provide a Java-based interface to access data.

Because users are not willing to code a native low-level interface to provide Java access to data, an interface that operates in accordance with the standard way Java developers expect must be provided. It should include documentation and instructions on how metadata is handled and maintained. Hence, it is compulsory and logical for Software AG to provide a state-of-the-art Java-based interface for Adabas so that users will consider it a data store easily used in projects. 

Adabas Client for Java is our new interface for developers and software designers who work primarily with Java and related concepts such as REpresentational State Transfer (REST). Developers accustom to working with other programming languages can also benefit from this new interface.

Adabas Client for Java makes it easy for anyone to write a Java-based application and interact with an Adabas database. It uses Java classes with methods for data access. It also supports RESTful access from a browser along with JavaScript® Object Notation (JSON™) as a data-interchange language.
 

Benefits

Adabas Client for Java is an easy-to-use interface covering all the functions of a native Adabas call interface that is very powerful but not easy to code. Of course, it is possible to use the Adabas call interface definitions in a Java program, but the new Adabas Client for Java provides a much more sophisticated way to call Adabas data. The software provides two different access methods: one based on Java classes covering the native call interface and one based on the REST architecture that runs over HTTP/HTTPS. Documentation is provided in a style Java programmers expect—as a Javadoc.

Usability in general is an important benefit, especially for developers who are not familiar with Adabas. Using the interface makes it easy to write applications based on data stored in Adabas. Of note, this is not only a topic for Linux®, UNIX® or Windows® (LUW)-based organizations but also for companies running mainframes such as z/OS®.

Performance is not affected by using Adabas Client for Java. The interface is designed to optimally use resources while processing and communicating with Adabas. In addition, it also easily integrates Adabas with other new technologies from Software AG.

Compulsory for an interface, but worth mentioning, Adabas Client for Java fully supports Adabas transactions, the entire set of access methods and most of the descriptors.
 

Technical overview

Figure 1 describes how the Adabas Client for Java works. The client interface provides a set of Java classes that can be used in Java programs. Software components are available to parse the queries and build internal calls based on the Adabas native interface. The transformed requests are sent to Adabas using the normal low-level interface—the Adabas link module. This in turn uses Entire Net-Work as the middleware to reach remote databases. Ideally, the interface runs local to the database. However, to reach a mainframe database, Entire Net-Work is required.

Figure 1: General Overview of how Adabas Client for Java Operates.

The Adabas Client for Java package provides a selection of sample Java programs that demonstrate how the interface can be used. All work is based on the Adabas demo file “Employees”.

Besides using the Java classes of the interface, there is another Web-based option to communicate with an Adabas database that is based on the REST architecture. REST is implemented as a server running in a Jetty (Java HTTP (Web) server and Java Servlet container). It supports the typical HTTP verbs GET, PUT, POST, DELETE, etc. The package contains a sample application using the REST architecture.
 

Using JAVA classes

This section illustrates how to use the classes in a Java-based program with an excerpt from a sample program.

There are two ways of dealing with field (column) names. The classic way is to use the so-called “short names” of Adabas—two-letter codes such as “AA”, “AB”. These are used to name a column within an Adabas record (row) for optimization reasons. The preferred way though is to use meaningful field names that we call “long names” such as “Firstname”, Lastname”.

In order to use long names, a map should be generated using the Adabas Data Designer which is included the package. An introduction to Adabas Data Designer is provided later in this article.

Figure 2 features the sample program that reads data out of a database based on the sort criteria “Firstname”. This means “Firstname” is a descriptor (key) in Adabas terms.


Figure 2: Sample Program Demonstrating “Read” Function.

The program asks for a database containing the Employee file. The Adabas demo file “Employees” must be available in the database as a pre-requisite to run this sample program. The required map “EMPLOYEES-NAT” can be created using the Adabas Data Designer’ import function. The input for the map is a Natural DDM exported with the Natural object handler. 

In order to communicate with Adabas, the appropriate classes must be used. Here is a sample of appropriate classes:

  • AdabasTarget         = get the database ID
  • ReadRequest         = Read data out of Adabas
  • ReadRequest.setSearch     = set value of search criteria

The map demonstrates the use of long names in a Java application rather than Adabas short names. Another option is to provide mapping information (metadata) in a XSD file. In this context, we map data using definitions that map Adabas short names to long names.
 

Javadocs

As illustrated in Figures 3 and 4, Javadocs are available in the same style as any other Java-based solution. Therefore, it is easy for developers using this interface to access data in Adabas from a Java-based application without deep, or really any, knowledge of Adabas

Figure 3: Hints on how to use methods of a class are available in a Java style.


Figure 4: Documentation on how to use the classes and methods are available within Eclipse and is therefore available to the user at any time.
 

Using the RESTful interface

This interface allows any application supporting HTTP protocol to access data stored in Adabas. The requests are based on the URL syntax:

http://<hostname>:<port>/<format>/<type>/<location reference>

The URL consists of more attributes than just the host name and port number. The application takes the URL and extends it by access methods—GET (read), PUT (update), POST (create), DELETE (delete)—to instruct the underlying technology to create the appropriate request to Adabas

The application communicates via the port number with the REST server. Currently, there are two formats to formulate queries and obtain results as a JSON document or XML document. The format can either be DB for classic access with short names or MAP using the long names.

The information provided as location reference is used as input for classes. The REST interface also makes use of the metadata (FDT and map) stored in an Adabas database—see the Adabas Data Designer section. The Java classes of the Adabas Client for Java have to be available to the REST server, because the REST server uses these components to generate the appropriate requests to Adabas

Some configurations (e.g., define user-id and password) must be made and the database which contains the metadata file and the databases containing the business data must be available. The REST server has no transaction support implemented.

The easiest way to explain the functions available in the interface is to use the demo application.

After the Rest server is active, the URL http://localhost:8190 can be used in a browser window to allow application access. This assumes the Adabas Client for Java and Adabas itself is on the same computer.

 
Figure 5: Predefined tabs give users greater capabilities to formulate and view results.

As shown in Figure 5, Adabas Client for Java offers tabs to access predefined queries, to build free forms and to modify data. From this user interface, you can see how the request is formulated and what the results will look like. Figure 6 shows how structured information as well as large objects shall be read, the query and the results.


Figure 6: Example Result of a Query.

The file (table) containing the structured data (File 202) and the LOB data (File 203) are part of the package. The data can be loaded by using the Adabas utility ADABCK restore=202.
 

Adabas Data Designer

Adabas Data Designer is used by developers to create and maintain Adabas files that contain metadata and maps. In Adabas, metadata are stored in so-called Field Description Tables (FDTs). The maps are based on FDTs extended by “long names”.

Developers can import FDTs and maps from the:

  • Metadata from Adabas 
  • Natural DDMs
  • XML structures

It is also possible to create metadata from scratch or adapt maps.

Adabas files and maps of running databases are automatically shown when starting Data Designer as shown in Figure 7 Let’s take a brief look into Adabas Data Designer.

Figure 7: A Look Into Adabas Data Designer

Databases, files, and maps are shown in a tree view on the left side of the screen. By double-clicking an object, for example “TestMapEmployee”, details are displayed on the right upper side. Below that, a data browser show the data contained in an Adabas file. Simply select the fields you want to see in the data browser.
 

Summary

Adabas Client for Java offers easy access to data stored in Adabas on a transactional level. It helps developers work with data in Adabas without having to become an Adabas expert. Java classes enable developers to use Java as a programming language to access Adabas in the same way they embed other data sources into a project. The REST interface integrates data smoothly into Web applications and Web services. Adabas Client for Java will continue to evolve as the Adabas database itself provides new and greater functionality.

Upcoming Adabas & Natural classes

Stay up to date with your Adabas & Natural skills. We offer virtual classes (no travel required) as well as hands-on, in-person training. For a full list of available classes, visit A&N Global Q3 Training Schedule.

Sample of Q3 Virtual Courses      Date
301-65E: Building Applications with Natural (I)       Aug 22-26
107-65E: ADABAS (Mainframe) System Administration Sep 12-16
001-46E: ADABAS Fundamentals  Sep 20-21
111-63E: Adabas (UNIX, Windows) System Administration Sep 26-30