· jtc is the first and only key-value store that uses tables as its keys. jtc provides the...

JTC

Fastest Java Table AccessJTC

Manual for Windows 64-bit

Last updated on 2018-12-21

JTC DEMO PACKAGE

BOI GmbHSpazgasse 4

4040 LinzAustria

Phone: +43 (0) 732 / 736423 - 0Fax: +43 (0) 732 / 736423 - 2Email: [email protected]

© BOI Software GmbH, Austria. All rights reserved.

2

JTC



Convincing QualityEfficient and audit-proof.

High-performance and ultra-fast.Company-wide use for all

databases and operating systems.

BOI – FOR YOUR BETTER ORGANIZED INFORMATIONEfficient Service40 years of experience.Excellent, dedicated team.One-stop consulting, technology and implementation.

BOI Software Entwicklung und Vertrieb GmbH40 years of success and innovation.Your expert for data management.

BOI LINZSpazgasse 4

4040 Linz, Austria

Phone: +43 (0) 732 736423 - 0E-Mail: [email protected]

BOI GRAZFriedrichgasse 30/18010 Graz, Austria

Fax: +43 (0) 732 736423 - 2https://www.boi.at

3

JTC



Contents

1 What is this manual about? 4

2 Introduction 5

2.1. JTC – concept overview 5

2.2. JTC – your benefits 7

2.3. What is the purpose of this JTC demo package? 8

3 Components and Prerequisites 8

4 Installation and Execution of the Samples 9

5 Samples 12

5.1. Sample Data 12

5.2. How writing to JTC works 13

5.3. Description of the Samples 15

5.3.1. BOITestRead 15

5.3.2. BOITestWriteAndSync and BOITestIntegrate 16

5.3.3. BOITestUserRecord 18

5.3.4. BOITestUpdateRecord 18

6 Managing PostgreSQL using pgAdmin4 19

7 ConfigurationofJTCinPostgreSQL 20

4

JTC



1 What is this manual about?

This manual is the documentation for the JTC demo package for Windows 64-bit.

Chapter 2 gives an overview of the concept and benefits of JTC.

Before you start to setup and run JTC, please read the required components and prerequisites in Chapter 3.

A description of how to setup and run JTC will be given in Chapter 4. For a quick-start, please read at least this chapter.

This JTC demo package provides several samples, which show how to use the JTC API and how to benefit from JTC. The sample data, some technical details about the write API of JTC, and the samples are described in Chapter 5.

This JTC demo package uses PostgreSQL as data source for initially loading data to the enterprise cache used by JTC. For managing PostgreSQL, the browser-based GUI pgAdmin4 is used. Chapter 6 shows how to use pgAdmin4 in order to display sample data and configuration of this JTC demo package.

Finally, Chapter 7 addresses the configuration of JTC stored in PostgreSQL.

5

JTC



2 Introduction

Your tables are our keys!

JTC is the first and only key-value store that uses tables as its keys. JTC provides the world‘s fastest readandwriteJavaaccesstotabledata. JTC extends the concept of the key-value store to entire tables. This opens the use of tables in an in-memory key-value store without dealing with the complexity and limitations of an in-memory database.

JTC is the ideal choice for modern applications in robotics, industry 4.0 and other application fields, where scalability and access performance in combination with sophisticated key-value concepts are essential.

2.1. JTC–conceptoverviewIf you asked us to summarize JTC in a few sentences, we would probably do it in the following way:

JTC is a complete Java data handling system using a supported enterprise cache for data storage and data synchronization. JTC supports enterprise caches such as Hazelcast, Infinispan, Terracotta Ehcache, Apache Ignite, Redis/Redisson, Java EE JCache and others.

JTC constructs a multi-tenant, persistent in-memory Java cache in each access environment connected to the enterprise cache. We call them JTCCaches. A JTC Cache may be defined as shared resource (per Java Virtual Machine), which might be used for all applications in this JVM or as a separate resource for each application. JTC in-memory caches are special:

• They hold tables as Java objects • They are persistent multi-tenant caches allowing to organize your tables according to your

organizational needs • They are able to manage bi-temporal tables and provide easy read and write APIs • They provide advanced synchronization to minimize data traffic through the enterprise cache • They provide world-fastest Java table access

JTC manages data synchronization. Based upon your needs and configurations, modified data is synchronized via the enterprise cache at defined events and data is updated in each JTC Cache automatically. You may also configure, that data synchronization stops at the enterprise cache level and that data is updated in the JTC Cache at next table access, as JTC always checks the up-to-dateness of JTC Cache tables with tables in the enterprise cache.

In addition, you may use all advanced features of the enterprise cache like security, fail-safe, etc.

In Figure 1, we have summarized the JTC architectural schema for you.

6

JTC



In the following paragraphs, we want to give you a more detailed overview on the distinct features of JTC:

JTC is the first and only key-value store, which uses tables as its keys. The table is our basic module and allows to largely extend the use of enterprise caches. JTC allows providing entire tables to your applications instead of simple key-value pairs and still having incredible fast data access. JTC allows inserting, updating and deleting data of its tables. How does JTC work?

1. Data is stored in an enterprise cache of different third parties or open source and it secures data synchronization. JTC allows an initial data load of tables from different SQL databases, like PostgreSQL, DB2, Oracle, MySQL, Informix, Progress, and others. Data may be backed up to a SQL database in pre-determined time intervals to prevent data loss in the unlikely event that the enterprise cache stalls.

2. JTCallowsworld-fastestJavatableaccess.JTC allows to process data faster than any other relational database and in-memory database – e.g. over 500 times faster than relational databases and up to 40 times faster than the in-memory database H2.

3. JTCallowsdefiningapplication-optimizedtables.JTC offers an easy way to define multiple views on tables to enhance data access. For example, table sorting based on keys used by your application enhances table access.

4. JTCallowsyourapplicationstomodifytabledataintheJTCCache.To allow for parallel read and write access to a table, JTC offers a configurable update mode. JTC writes modified or new table records into a separate map, which we call local user map, and the original table stays unchanged, preventing time consuming table insertion routines. At configurable events like for example number of entries, time or a “commit” by the application, the records of the local user map are integrated into the tables of the local JTC Cache and get synchronized to all JTC Caches.

Figure 1 JTC architectural schema

7

JTC



5. JTCreducesdatatraffictoaminimum.Based on the data concept, JTC only synchronizes the delta of modified tables. JTC gives you full flexibility to balance enterprise cache traffic and data up-to-dateness by configuration of update time intervals.

6. JTCprovidesamulti-tenant,persistentJTCCache.Define multiple environments and assign JTC tables to the environments. You may define different tenancies to represent your organizational needs, for example, for different affiliates, for test, integration and production. Each JTC Cache tenant can hold tables of identic names and different table data, allowing using identic applications for processes on different data, as for example to execute an advanced analysis on the data of different affiliations of your company.

7. JTCisabletousebi-temporaldata.You may use bi-temporal table data loaded from your relational database and access it using the validity time or the creation time. All needed access functions are provided by JTC classes.

To summarize, JTC is the first and only key-value store which uses tables as its keys. The table is our basic module and it allows us for sorting, configuring different views of the same data, defining composed keys and many more, which you cannot use with existing key-value stores. By combining the key-value store approach with table access, JTC combines the better of two worlds: key-value stores and relational databases.

2.2. JTC–yourbenefitsIn this section, we summarize the main benefits of JTC.

Benefit 1: JTC provides tables with a flexible structure for your applications. Give your business processes a head start: JTC provides all sorts of tables to your applications – and thus offer great advantages for your daily business processes. JTC is distinctly different from all other cache solutions available on the market.

Benefit2:JTC saves a lot of programming effort and is easy to use. Enjoy the convenience: JTC provides all query logics for finding and returning searched values or value ranges from tables. The intuitive API, which specializes in high-performance access, makes data search in tables simple and convenient.

Benefit3:Let your applications update JTC. Load tables from different databases into JTC or create the tables with the required table structures directly in JTC. Write table data directly from your applications into the Java Table Cache using the configurable JTC write API. Thus, your data is always available for access at maximum speed.

Benefit4: JTC searches faster than any in-memory database. Take advantage of the world‘s fastest Java access: JTCs innovative technology provides your applications with tables for high-performance Java read access. You can also define derived index tables with a different sort sequence. This enables JTC to process data faster than any other in-memory database – e.g. over 500 times faster than relational databases and up to 40 times faster than the in-memory database H2.

Benefit5: JTC is a bi-temporal in-memory store. Define different versions of your tables and their validity period. JTC automatically searches for the valid table version for the timeframe that you have specified, and returns the data that is valid at the effective date. Snapshots ensure that data access is consistent over time and across tables.

8

JTC



2.3. WhatisthepurposeofthisJTCdemopackage?As described in the previous sections, JTC allows to access tabular data stored in an enterprise cache. JTC is the underlying framework connecting all required components. In order to give you an idea of JTC and how it works, we decided to implement this demo package. The main purpose of this demo package is to show you how JTC offers you benefits 1 to 3 of Section 2.2

For sure, you will also experience the world-fastest Java table access, but we have not included an access performance determination routine. But please feel free to challenge the JTC access performance!

The benefits 1 to 3 are illustrated by several samples including the source code, described later on in this manual. The demo package provides all components needed for running JTC and the samples. As enterprise cache Hazelcast is used and as relational database PostgreSQL is used. More details about the components and about the prerequisites of this demo package can be found in Chapter 3.

3 Components and Prerequisites

The demo package is delivered as a zip file with the name jtcdemo-yyyymmdd-win.zip.

For your convenience, the demo package contains JTC and all additional components required.These are the following:

• JTC compiled with Oracle Java 8 • Hazelcast 3.11 • Oracle JRE 1.8.0_192 for Windows 64-bit • PostgreSQL 11.0-2 including pgAdmin4 3.4, both for Windows 64-bit. pgAdmin4 is the GUI for

managing PostgreSQL.

Note:JTCisapproximately13MBlarge,whereasHazelcast,JREandPostgreSQLneedover900MBintotal.Pleasemakesuretoreserveatleast400MBspaceonyourharddriveforstoringthezipfileandatleast1GBforstoringtheunpackeddemopackage.Pleasenote,thatcopyingandunpackingthezipfilemaytakeawhile.

The demo package requires Windows 64-bit to run. Windows 32-bit won’t work, because components like the JRE require a 64-bit-based Windows.

The demo package can be used for a specified period of time limited by a trial licence. The trial licence allows JTC to establish a connection to the PostgreSQL server of the demo package and allows to replicate the tables boi.station and boi.weather.

Among others, the following fixed values are used: • app server id: APPSRV01 • connection: jdbc:postgresql://localhost:5432/postgres • driver: org.postgresql.Driver • password: postgres • user: postgres

9

JTC



In comparison to the trial license of this demo package, a full version of JTC allows to establish a connection to an arbitrary PostgreSQL database and allows to replicate arbitrary tables. If you are interested in a full version of JTC, please contact BOI.

4 Installation and Execution of the Samples

Follow the steps below to setup and run JTC on your computer:

Step1:Copyandunpackthedemopackage. Copy and unpack jtcdemo-yyyymmdd-win.zip to a directory of your choice, for example to C:\temp\jtcdemo\. The demo package contains the following folders and files:

Figure 2 Folders and files of the JTC demo package

Step2:StartJTCandtheadditionalcomponents. Start JTC and the additional components by double clicking on the file startall.bat. startall.bat calls the script envall.bat which sets several environment variables for running the components mentioned in Chapter 3. Furthermore, startall.bat starts the PostgreSQL server, Hazelcast, and pgAdmin4. For PostgreSQL and Hazelcast respectively, a new command line is opened. When pgAdmin4 is started, a new browser window opens automatically and the pgAdmin4 GUI loads. Note that startall.bat should be kept open while JTC and the additional components are running.

Step3:AllowaccesstoPostgreSQLserverandJRE. The PostgreSQL server and the execution of the JRE may be blocked by your Windows Defender Firewall. If this is the case, allow executing these components by clicking on „Allow access“:

Figure 3 Allow access to PostgreSQL server and JRE

10

JTC



If everything went well, three command lines and a browser window are now open. The command lines show the log messages of startall.bat, Hazelcast and PostgreSQL. Please keep them open while you work with this demo package. Only the command lines of the samples and the command line of the cache replication can be closed while working with the JTC demo package.

Step4(optional): Ifwindowspopupindicatingthatmsvcp140.dllorvcruntime140.dllaremissing,installMicrosoftVisualC++Redistributablepackages. PostgreSQL and pgAdmin4 are based on C / C++ and, thus, require specific Microsoft C Runtime Libraries (dlls).Among others, PostgreSQL (postgres.exe) requires the following dlls:

• ucrtbase.dll • vcruntime140.dll

Among others, pgAdmin4 (pgAdmin4.exe) requires the following dlls: • msvcp140.dll • ucrtbase.dll • vcruntime140.dll

msvcp140.dll and vcruntime140.dll are installed when you install Microsoft Visual C++ Redistributable packages on your Windows machine. These dlls have already been included by Oracle in the JRE used, cf. the directory „jre1.8.0_192\bin\“. Therefore, there should be no need to install them extra. If you nevertheless receive an error that msvcp140.dll or vcruntime140.dll are missing, please install the following Redistributable packages located in „postgre11\dbserver\11\installer\“:

• vcredist_x64.exe = Microsoft Visual C++ 2017 Redistributable (x64) – 14.15.26706

• vcredist_x86.exe = Microsoft Visual C++ 2017 Redistributable (x86) – 14.15.26706

• vcredist_x86_2013.exe = Microsoft Visual C++ 2013 Redistributable (x86) – 12.0.40660

Afterwards, try to execute startall.bat again. If you still receive an error, please contact BOI.

Step5:ExecutethecachereplicationofJTC.After all components have sucessfully been started, the enterprise cache used by JTC has to be loaded with the data. This is done by starting the cache replication of JTC. The cache replication replicates data from the PostgreSQL database to the enterprise cache. The data to be replicated is described in Section 5.1. In order to start the cache replication, double click on the script „1_doonereplication.bat“ located in „jtc\bin\”. The cache replication should finish with the message „CRE-STR014(I): replication ended successfully“. If you receive the message „CRE-LIC004(*): No valid license installed.“, please contact BOI.

11

JTC



Step6:Executethesamples.

Note:WestronglyadvisetoreadChapter 5beforeexecutingtheprovidedsamples,astheusecaseandtheprovidedsamplesarepresentedindetail.

Execute the samples of this JTC demo package by double clicking on the scripts located in „jtc\bin\“ and study the corresponding source code under „jtc\samples\“. The demo package contains the following samples:

• 2_testread.bat + BOITestRead.java: BOITestRead shows different ways of accessing the tables „station“ and „weather“ of the enterprise cache. It shows the possibilities of the read API of JTC.

• 3_testwriteandsync.bat + BOITestWriteAndSync.java and 4_testintegrate.bat + BOITestIntegrate.java: BOITestWriteAndSync and BOITestIntegrate show how to write, synchronize and integrate records into the enterprise cache.

• 5_testuserrecord.bat + BOITestUserRecord.java: BOITestUserRecord shows how to use the methods findKey and readUserRecord to read a record from the local user map of an accessor and/or read the record from the table in the enterprise cache.

• 6_testupdaterecord.bat + BOITestUpdateRecord.java: BOITestUpdateRecord shows how to update a record in the enterprise cache.

The samples are described in detail in Chapter 5. A description of the methods of the JTC API can be found in the JavaDoc located in „jtc\doc\“.

Step7:StoptheJTCdemopackage.If you want to stop the JTC demo package again, simply close all open command lines and the browser window of pgAdmin4. Note that it may be the case that startall.bat can be closed only, if the other command lines and the browser window have already been closed.If you take a look at the processes currently running (e.g. by using the Process Explorer of the Microsoft department Windows Sysinternals), the following processes should no longer exist:

• pgAdmin4.exe for pgAdmin4 • cmd.exe and postgres.exe for PostgreSQL server • cmd.exe for startall.bat • java.exe and conhost.exe for hazelcast-3.11

If one or multiple of the processes are still running, make sure that they belong to the JTC demo package you have started and then terminate the processes manually.

12

JTC



5 Samples

The demo package includes several samples, which show how to use the read and write API of JTC. This chapter shows the data replicated to the enterprise cache, gives a deeper insight into JTC, and provides a more detailed description of the samples.

5.1. Sample DataTo show the benefits of JTC we have chosen a use case in which sensors are writing data to the caching system, whereas other applications read the data. The JTC use case are weather stations, which use sensors to track parameters of the weather in specific regions. Parameters are the temperature, the humidity, the direction or the speed of the wind, and many more. We believe this is an easy use case to show the working principle of JTC and its benefits.

The PostgreSQL database of the demo package contains two tables – „station“ and „weather“. Table „station“ contains information about weather stations located in Austria, whereas table „weather“ contains measurements of these stations. Both tables belong to the schema „boi“ located in database „postgres“. In the course of the cache replication (cf. Chapter 4, Step 5), these tables are replicated to the enterprise cache.

Figure 4 Table boi.station

Figure 5 Table boi.weather

13

JTC



Note:Thesetablesarebasedon"KatalogMeteorologischeMessdatenderZAMG"bydata.gv.at(https://www.data.gv.at/katalog/dataset/9b40a0af-a6fe-47ff-9624-2ea8f40c746f)andZAMG,used under CC BY 3.0 AT (https://creativecommons.org/licenses/by/3.0/at/deed.de). Theoriginaldatacanbedownloadedfromwww.zamg.ac.at/ogd/.

5.2. HowwritingtoJTCworksIn order to better understand the purpose of the samples included in this demo package, it is necessary to understand how writing data to JTC works.

As described in Section 2.1 and Figure 1, the initial load (cache replication) of JTC replicates data from a PostgreSQL database to the enterprise cache Hazelcast. For replicating data to the enterprise cache and for accessing the data afterwards, the JTC API is used. The enterprise cache is accessed by different applications (samples). The sample „BOITestRead“ (cf. Section 5.3.1) solely reads data, whereas the other samples write data to the enterprise cache as well. Please have a look at the figure below for the components and the technical details.

Figure 6 The components and technical details of JTC

If an application wants to write data to the enterprise cache, this means that one or multiple tables of the cache have to be updated. If multiple applications want to write data, updating a single table at each write operation would lead to a performance bottleneck. To avoid such a performance bottleneck, thus, JTC implements a specific update process described in the following.

14

JTC



HowdoesJTCwritetabledata?

If you examine the source code of the samples, you will repeatedly come across the terms „local user map“ and „distributed user map“. Each application writes new data records/table rows only to a so-called local user map, a sort of table data buffer present in each JTC Cache. No changes are performed directly in the tables of the local JTC Caches or in the tables of the enterprise cache. Local user maps are unique per table and per JTC Cache, so all changes of one table are stored in the appropriate local user map in the respective JTC Cache. Local user maps are available only on JTC Cache level. Thus, if an application writes data to a local user map of a JTC Cache, the original table is still present in all other JTC Caches. The table modification is only present in the local user map of the concerned JTC Cache. In a separate step, the records of the local user maps are synchronized to a so-called distributed user map present in the enterprise cache. Distributed user maps are only available on the enterprise cache level. The distributed user map is the synchronization carrier. For one table, local user maps may exist in several JTC Caches but only one corresponding distributed user map exists for this table in the enterprise cache. If a new status of a distributed user map is available, the corresponding local user map in the JTC Caches is updated and the new records are inserted into the table of the enterprise cache and into the table of the JTC Caches. This process is performed in each JTC Cache to minimize data traffic: Not the rows of the entire table are inserted into the table of the JTC Caches. Only the table deltas (the records of the distributed user map) are synchronized to the JTC Caches.

JTC offers total flexibility for its update process: You may define synchronization time intervals or events for synchronization between JTC Caches and the enterprise cache. The process of writing records into the local user map of a JTC Cache and its synchronization to the distributed user map is shown in sample “BOITestWriteAndSync”. The integration of the records of the distributed user map into the table of the enterprise cache is shown in sample “BOITestIntegrate” in Section 5.3.2.If required, JTC also allows to immediately integrate the records from the local user map into the table of the enterprise cache, avoiding the usage of the distributed user map.

If an application wants to access a table of the enterprise cache, the application has to create a so-called „accessor“. If an application wants to access multiple different tables, thus, the application has to create an accessor per table. JTC differentiates between two types of accessors: BOITableKeyAccessor and BOITableMassAccessor. A key accessor always returns a single result when accessing data of the enterprise cache, whereas a mass accessor may also return multiple results.An accessor contains information about the accessed table and contains a reference to the local and distributed user map of the table. JTC stores the accessors in an accessor hashmap to be able to re-use them with high-performance.

The samples of this demo package demonstrate how to write and integrate records and how to read them again. Therefore, especially pay attention to the following methods contained in the source code of the samples:

• findKey

• writeUserRecord

• readUserRecord

• synchronizeUserMaps

• integrateUserRecords

A description of the methods can be found in the JavaDoc located in „jtc\doc\“.

15

JTC



5.3. Description of the SamplesThe following sections describe the samples of this demo package. To get the expected results per sample, it is advisable to examine and execute the samples from first to last, starting with BOITestRead (2_testread.bat) and ending with BOITestUpdateRecord (6_testupdaterecord.bat).

5.3.1. BOITestReadBOITestRead (2_testread.bat) shows different ways of accessing the tables „station“ and „weather“ of the enterprise cache. BOITestRead shows the possibilities of the read API of JTC.

ThefollowingqueriesandmethodsareshowninBOITestRead: • Get the current number of rows of the tables „station“ and „weather“ by using method getCurrentAccessibleDataTable().getNumRows().

• Find station 12 by using method findKey. • Find all measurements of station 12, but maximally return 10 results. The usage of methods findAndStoreMassResults and fetchMassResultRowRange is shown.

• Find all measurements of stations with an id in the range [12, 14]. A simple range search using the methods setSimpleRangeSearchOps,createSimpleRangeSearchArgs etc. is shown.

• Find all measurements of station 12 in the time interval [lowerBound, upperBound]. An extended range search using the methods setExtendedRangeSearchOps,createExtendedRangeSearchArgs etc. is shown.

• Find all stations in Linz: These are all rows of table "station" which have a name starting with "Linz" (case-sensitive). Again, the usage of methods findAndStoreMassResults and fetchMassResultRowRange is shown.

Figure 7 BOITestRead

16

JTC



Expectedresults:

no.rowsstation:11no.rowsweather:15

---findStation

[12,Kremsmünster,48.05436,14.126188,383]

---findMeasurementsByStation

5

[12, 2018-07-26 13:57:22.73235, 18.2, 85, 150, 10.8, 0.0, 5]

[12, 2018-07-27 12:57:22.73235, 18.1, 81, 260, 15.3, 0.0, 0]

[12, 2018-07-27 13:57:22.73235, 18.0, 82, 250, 15.8, 0.0, 0]

[12, 2018-07-27 14:57:22.73235, 18.4, 80, 220, 15.1, 0.0, 0]

[12, 2018-07-28 13:57:22.73235, 14.3, 79, 220, 15.8, 3.0, 0]

---findMeasurementsByStationRange

7

[12, 2018-07-26 13:57:22.73235, 18.2, 85, 150, 10.8, 0.0, 5]

[12, 2018-07-27 12:57:22.73235, 18.1, 81, 260, 15.3, 0.0, 0]

[12, 2018-07-27 13:57:22.73235, 18.0, 82, 250, 15.8, 0.0, 0]

[12, 2018-07-27 14:57:22.73235, 18.4, 80, 220, 15.1, 0.0, 0]

[12, 2018-07-28 13:57:22.73235, 14.3, 79, 220, 15.8, 3.0, 0]

[13, 2018-07-27 13:57:22.73235, 17.6,84,306,18.7, 0.0, 0]

[14, 2018-07-27 13:57:22.73235, 17.8,90,300,24.1, 1.2, 0]

---findMeasurementsByStationAndTimeInterval

4

[12, 2018-07-26 13:57:22.73235, 18.2, 85, 150, 10.8, 0.0, 5]

[12, 2018-07-27 12:57:22.73235, 18.1, 81, 260, 15.3, 0.0, 0]

[12, 2018-07-27 13:57:22.73235, 18.0, 82, 250, 15.8, 0.0, 0]

[12, 2018-07-27 14:57:22.73235, 18.4, 80, 220, 15.1, 0.0, 0]

---findStationsByName

2

[11,Linz/Hörsching]

[21,Linz/Stadt]

17

JTC



First, start BOITestWriteAndSync (3_testwriteandsync.bat) and then start BOITestIntegrate (4_ testintegrate.bat) so that they run concurrently.

Every second, BOITestWriteAndSync writes a new record to the local user map of table „weather“ (1). After three records written, it synchronizes the local and distributed user map by copying the records from the local to the distributed one and removing the records from the local one (2).

BOITestIntegrate copies the records from the distributed user map to its local user map every five seconds by synchronizing the user maps (3). Afterwards, it integrates the records into the table of the enterprise cache and removes them from the user maps (4).

Expectedresults:

BOITestWriteAndSync:

write:[12, 2018-11-07 15:31:47.259000,-0.1,28,313,32.3,3.3,67]

write:[12, 2018-11-07 15:31:48.323000,18.5,5,88,11.2,4.5,47]

write:[12, 2018-11-07 15:31:49.326000,-2.2,38,334,21.1,4.0,78]

sync...

write:[12, 2018-11-07 15:31:50.340000,29.9,12,150,2.2,2.1,39]

write:[12, 2018-11-07 15:31:51.344000,-9.8,86,358,4.2,4.2,76]

write:[12, 2018-11-07 15:31:52.356000,-2.4,49,96,11.8,4.7,53]

sync...

5.3.2. BOITestWriteAndSyncandBOITestIntegrateThe samples BOITestWriteAndSync and BOITestIntegrate show how to write, synchronize and integrate records into the enterprise cache.

Figure 8 BOITestWriteAndSync, BOITestIntegrate

18

JTC



BOITestIntegrate:

no. recordsof table(15),userMap(-1),userMapDist(-1)

[12, 2018-11-07 15:31:47.259000,-0.1,28,313,32.3,3.3,67]

[12, 2018-11-07 15:31:49.326000,-2.2,38,334,21.1,4.0,78]

[12, 2018-11-07 15:31:48.323000,18.5,5,88,11.2,4.5,47]

no. recordsof table(18),userMap(-1),userMapDist(3)

[12, 2018-11-07 15:31:51.344000,-9.8,86,358,4.2,4.2,76]

[12, 2018-11-07 15:31:50.340000,29.9,12,150,2.2,2.1,39]

[12, 2018-11-07 15:31:52.356000,-2.4,49,96,11.8,4.7,53]

The output of BOITestIntegrate shows the integrated records and the following information: • no. records of table: getCurrentAccessibleDataTable().getNumRows() returns the number of

records of table „weather“ in the local JTC Cache. After new records were integrated into the table of the enterprise cache using integrateUserRecords(true,true), it is necessary to do a dummy access in order to update the table in the local JTC Cache. The dummy access is done by calling initAndCheck(). Without the dummy access, getCurrentAccessibleDataTable() will return null after calling integrateUserRecords(true,true).

• userMap (<size of local user map>): By calling getUserMapSize(false), the number of entries currently present in the local user map for table „weather“ is returned. Immediatelly after calling integrateUserRecords(true,true), the size of the local user map is 0, because the local user map is cleaned after integrating records into the enterprise cache. After the dummy access using initAndCheck(), the local user map is set to null. In this case, the size of the local user map is -1. If the table in the local JTC Cache is identical to the table in the enterprise cache, the table in the local JTC Cache is not refreshed by the dummy access and the local user map is not set to null. In this case, the size of the local user map is 0. When executing BOITestWriteAndSync and BOITestIntegrate concurrently, the value printed for userMap should always be -1.

• userMapDist(<size of distributed user map>): By calling getUserMapSize(true), the number of entries currently present in the distributed user map for table „weather“ is returned. If no records are present in the distributed user map, for example because BOITestWriteAndSync has not been started yet, the value printed for userMapDist is 0. When executing BOITestWriteAndSync and BOITestIntegrate concurrently, the value printed for userMap should always be greater than 0.

5.3.3. BOITestUserRecordBOITestUserRecord (5_testuserrecord.bat) shows how to use the methods findKey and readUserRecord to read a record from the local user map of an accessor and/or read the record from the table in the enterprise cache. readUserRecord enables to read a record from the local user map, but not from the distributed user map and not from the table in the enterprise cache. findKey enables to read a record either from the table or from the local user map. If the record shell be searched using a key index or if it shell be searched in the table and/or in the local user map can be defined by setting the parameters useIndex, scanData, scanUserMap, and userMapBeforeData of findKey. Please pay attention to how these parameters are set within BOITestUserRecord. For more details on findKey and readUserRecord, please cf. the JavaDoc.

19

JTC



Figure 9 BOITestUserRecord

Furthermore, please note that if the table “station” already contains a row with id=99, the results of the sample BOITestUserRecord may differ from the results shown in the following.

Expectedresults:

(1)[99,Linz/Urfahr,48.319111,14.291085,266]

(2)null

(3)null

(4)[99,Linz/Urfahr,48.319111,14.291085,266]

(5)null

(6)null

(7)[99,Linz/Urfahr,48.319111,14.291085,266]

(8)[99,Linz/Urfahr,48.319111,14.291085,266]

(9)[99,Linz/Urfahr2,48.319111,14.291085,266]

5.3.4. BOITestUpdateRecordBOITestUpdateRecord (6_testupdaterecord.bat) shows how to update a record in the enterprise cache. In the sample, the first row of table “station” is updated by an accessor (the “writer”) and two other accessors (the “readers” readerMass and readerKey) access the updated record by calling findSingleRow or findAndStoreMassResults.

20

JTC



Figure 10 BOITestUpdateRecord

Expectedresults:

(1)[11,Linz/Hörsching,48.226981,14.176168,298]

(2)[11,Linz/HörschingUPDATED,48.226981,14.176168,298]

(3)[11,Linz/HörschingUPDATED,48.226981,14.176168,298]

(4)[11,Linz/HörschingUPDATED2,48.226981,14.176168,298]

(5)[11,Linz/HörschingUPDATED2,48.226981,14.176168,298]

21

JTC



Figure 11 pgAdmin version message

It indicates that there is a newer version of pgAdmin4 available. We tried to include the newest pgAdmin4 version in our demo package, but, as new versions of pgAdmin4 are released on a monthly base, a newer one may already exist.

If it is the first time you install or use PostgreSQL on your computer, it is necessary to tell pgAdmin4 towhich PostgreSQL server you want to connect to.To connect to the PostgreSQL server started on your localhost, right-click on „Servers“ and create a new server:

Figure 12 Create server connection

Next, type in the values shown below and click on „Save“. The highlighted values have to be filled in. The other values are already pre-defined. For the password, the value „postgres“ has to be set.

Figure 13 Create server connection

6 Managing PostgreSQL using pgAdmin4

As mentioned in Chapter 4 startall.bat starts different components of the demo package including the managing GUI of PostgreSQL named „pgAdmin4“. You can use pgAdmin4 to examine the configuration of JTC stored in PostgreSQL, cf. Chapter 7.Don’t worry, if you receive the following or a similar message at the top right corner of pgAdmin4:

22

JTC



7 ConfigurationofJTCinPostgreSQL

If you connect to the server created in pgAdmin4, you should see a database named „postgres“. postgres contains two schemas – boi and boijtcc:

Figure 14 Database „postgres“ with schemas „boi“ and „boijtcc“

Schema „boi“ contains the sample data (station and weather), whereas schema „boijtcc“ contains theconfiguration of JTC.boijtcc contains the control tables boijtcc.sqrcaccen, boijtcc.sqrcasprp, boijtcc.sqrcseasp, boijtcc. sqrctables_reptdb, the views boijtcc.sqrvasprp, boijtcc.sqrvseasp and a trigger function inc_closecount. boijtcc.sqrctables_reptdb defines which tables of the PostgreSQL database should be replicated to the enterprise cache:

Figure 15 Table boijtcc.sqrctables_reptdb

In our example, the tables „boi.station“ and „boi.weather“ will be replicated to JTC as „station“ and„weather“.

Please use pgAdmin4 to examine the tables, views and the trigger function. For executing the demo package, however, adapting them is not allowed. If you change the configuration, the cache replication will deny replicating data to the enterprise cache. Please contact BOI, if you are interested in a full version of JTC or if you have questions concerning the configuration of JTC.

· jtc is the first and only key-value store that uses tables as its keys. jtc provides the...

Documents