Skip to content

Commit 211670d

Browse files
mgerthmgerth
committed
initial commit
0 parents  commit 211670d

File tree

79 files changed

+3042
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

79 files changed

+3042
-0
lines changed

‎.project‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<projectDescription>
3+
<name>art-user-targets</name>
4+
<comment></comment>
5+
<projects>
6+
</projects>
7+
<buildSpec>
8+
</buildSpec>
9+
<natures>
10+
</natures>
11+
</projectDescription>

‎README.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# User Targets
2+
3+
## What's a User Target
4+
The *Event Replicator Target Adapter* replicates the data from Adabas on Mainframes to popular SQL databases (like Microsoft SQL Server, Oracle, DB2, etc.), Adabas, JMS, and some other systems. For most use cases, the existing targets are sufficient. However, it was hard to get scenarios to properly work in which targets were natively not supported by the *Event Replicator Target Adapter* or required another data format.
5+
6+
With User Targets, the user can extend the *Event Replicator Target Adapter* with seamlessly integrated custom targets. User Targets have the same look and feel as the predefined targets.
7+
8+
## How the User Target works
9+
The *Event Replicator Server* writes the changes of the Adabas data to a messaging queue. This messaging queue is the source for the *Event Replicator Target Adapter*.
10+
11+
The data is processed by reading the replicated Adabas data, transforming the data, and sending the data to the target. When the target is a User Target, the processing is very similar, but instead of sending the data to the target, the *Event Replicator Target Adapter* passes the transformed data to the customized User Target, which is responsible for the further processing of the data. Depending on the operation in Adabas (insert, update or delete), different User Target methods are called.
12+
13+
## Requirements
14+
User Targets are available as of *Event Replicator Target Adapter* version 3.7 and above. Implementation of User Targets must be in Java. The provided examples use Gradle to build the User Targets.
15+
16+
## Creating a User Targets
17+
The *Event Replicator Target Adapter* requires User Targets to be a POJO (Plain Old Java Object). User Targets must implement a Java Interface with the name **IUserTarget**.
18+
19+
To ease the implementation, the abstract class **AbstractTarget** is available. If the User Target extends from this class, then only the required methods have to be overridden.
20+
21+
For details on how to create a User Target, check the Javadoc and the provided examples projects.
22+
23+
### Constructor
24+
During the instantiation of the User Target by the *Event Replicator Target Adapter*, the parameterless constructor is called.
25+
26+
### Parameter
27+
User Targets may require additional parameters, for instance, a connection string to connect to a server or options that control the behavior of the User Target.
28+
29+
Parameter types:
30+
31+
* String - input field
32+
* Number - input field that accepts only numeric values
33+
* Boolean - check box
34+
* File - file selection control
35+
* Directory - directory selection control
36+
* Group - parameter group
37+
38+
The *Event Replicator Target Adapter Administration* reads the parameter and creates an editor for the User Target. The editor allows for parameters to be entered.
39+
The following is an example that shows all parameter types:
40+
41+
![User Targets parameter types](./images/user-targets-parameter.png "Parameter Types")
42+
43+
Like the regular targets, the User Targets parameters are stored in the context.xml that Event *Replicator Target Adapter* reads during startup.
44+
45+
With the method **getMetadata** the User Target parameters can be defined.
46+
47+
The parameters for the User Target that are set in the configuration file and read by the *Event Replicator Target Adapter* during startup are passed over to the User Target by the method **setParameter.**
48+
49+
### Properties
50+
Properties are another option for User Target parameters that resemble tables.
51+
52+
The following is an example for a User Target with Properties:
53+
54+
![User Targets properties](./images/user-targets-properties.png "Properties")
55+
56+
These parameters are **not** stored in configuration files. Instead, they are written to a file in the directory located along with the User Target. The file extension is *.properties*.
57+
The User Targets have to read these properties files to access the values.
58+
59+
### Adabas events
60+
The *Event Replicator Server* sends changes to the Adabas source data as events containing metadata and payload data to the *Event Replicator Target Adapter*. The metadata contains information concerning the transaction, i.e., file name, subscription, database number, file number, and operation.
61+
62+
#### Operations
63+
Operations are the changes on the Adabas data sent to the Event Replicator Target Adapter. The different operations are
64+
* insert - an Adabas record has been inserted
65+
* update - an Adabas record has been updated
66+
* delete - an Adabas record has been deleted
67+
* populate - initial state data
68+
* create - metadata information for the file sent during an initial state
69+
70+
For each operation, a method can be implemented to handle changes of the data on the target.
71+
72+
#### Data
73+
Adabas data is wrapped in a class capable of handling the Adabas-specific field types, multiple fields, and periodic groups. The class is called **AdabasObject**.
74+
75+
The following is an example of an Adabas record represented as an **AdabasObject**:
76+
77+
```
78+
1 ISN {class java.lang.Long}: 593
79+
1 PERSONNEL_ID {class java.lang.String}: 20010600
80+
1 FIRST_NAME {class java.lang.String}: DAN
81+
1 MIDDLE_NAME {class java.lang.String}: M
82+
1 NAME {class java.lang.String}: HENRY
83+
1 MARSTAT {class java.lang.String}: M
84+
1 SEX {class java.lang.String}: M
85+
1 ADDRESS_LINE
86+
1 [0] {class java.lang.String}: 101 MARINE AVENUE
87+
1 [1] {class java.lang.String}: TULSA
88+
1 [2] {class java.lang.String}: OK
89+
1 CITY {class java.lang.String}: TULSA
90+
1 POSTCODE {class java.lang.String}: 74150
91+
1 COUNTRY {class java.lang.String}: USA
92+
1 AREACODE {class java.lang.String}: 918
93+
1 PHONE {class java.lang.String}: 703-4729
94+
1 DEPT {class java.lang.String}: TECH10
95+
1 JOBTITLE {class java.lang.String}: ANALYST
96+
1 INCOME[0]:
97+
2 CURRCODE {class java.lang.String}: USD
98+
2 SALARY {class java.lang.Long}: 40000
99+
1 INCOME[1]:
100+
2 CURRCODE {class java.lang.String}: USD
101+
2 SALARY {class java.lang.Long}: 36800
102+
1 INCOME[2]:
103+
2 CURRCODE {class java.lang.String}: USD
104+
2 SALARY {class java.lang.Long}: 34200
105+
1 INCOME[3]:
106+
2 CURRCODE {class java.lang.String}: USD
107+
2 SALARY {class java.lang.Long}: 32100
108+
1 INCOME[4]:
109+
2 CURRCODE {class java.lang.String}: USD
110+
2 SALARY {class java.lang.Long}: 33440
111+
1 LEAVE_DUE {class java.lang.Short}: 26
112+
1 LEAVE_TAKEN {class java.lang.Short}: 4
113+
1 LEAVE_BOOKED[0]:
114+
2 LEAVE_START {class java.lang.Integer}: 19980112
115+
2 LEAVE_END {class java.lang.Integer}: 19980112
116+
1 LEAVE_BOOKED[1]:
117+
2 LEAVE_START {class java.lang.Integer}: 19980605
118+
2 LEAVE_END {class java.lang.Integer}: 19980607
119+
1 LEAVE_BOOKED[2]:
120+
2 LEAVE_START {class java.lang.Integer}: 19980916
121+
2 LEAVE_END {class java.lang.Integer}: 19980918
122+
1 LANG
123+
1 [0] {class java.lang.String}: ENG
124+
1 [1] {class java.lang.String}: CHI
125+
```
126+
127+
Regular Adabas fields are Java standard types (String, Integer, Short, Long, etc.) that correspond to the Adabas type and length. Multiple Fields (like ADDRESS_LINE) are arrays of Java standard types, and Periodic groups (like INCOME) are arrays of **AdabasObject**.
128+
129+
#### Transaction
130+
Adabas operations are based on transactions, meaning that multiple operations (such as insert, update, delete) can be grouped into one transaction. At the end of a transaction, the **commit** method of the User Target is called.
131+
132+
#### Command
133+
Some actions of the *Event Replicator Server*, such as refresh file or start server, are sent to the *Event Replicator Target Adapter Administration* as commands. These commands are propagated to the User Targets by the **command** method to perform required actions.
134+
135+
#### Status
136+
During startup, the *Event Replicator Target Adapter* checks the status of the User Target by calling the method **isServiceOkay**. The result is printed as the **State** in the *sqlrep.log*.
137+
138+
### Close
139+
When the *Event Replicator Target Adapter* has shut down, the **close** method of each User Target is called. It allows the User Targets to clean up, for instance, to disconnect the server connection properly.
140+
141+
### Icon
142+
The User Targets can have an icon displayed in the tree-view and the editors. The icon must be in the *Portable Network Graphics (PNG)* or *Graphics Interchange (GIF)*-Format, with 16 by 16 size, have the same name as the User Target class, and be in the same directory as the User Target jar.
143+
144+
### Javadoc
145+
The SDK Javadoc is available as a zip file in the doc folder.
146+
147+
## Installation
148+
User Targets are installed from the *Event Replicator Target Adapter Administration*.
149+
Start the *Event Replicator Target Adapter Administration* and select from the menu
150+
Window > Preferences > Target Adapter.
151+
152+
*Note: The registered User Targets are environment-specific. If the User Target is required for multiple environments, it must be registered for each environment.*
153+
154+
Edit the Target Adapter to specify you want to add the User Targets:
155+
156+
![Target Adapter Environment](./images/user-targets-installation-1.png "Target Adapter Environment")
157+
158+
Register the User Target by clicking on the Register button of the User Targets group, and selecting the User Target jar:
159+
160+
![Select User Target jar](./images/user-targets-installation-2.png "Select User Target jar")
161+
162+
The classes that implement the **IUserTargets** interface are found and listed.
163+
164+
After saving the Target Adapter environment, the new registered User Target is available as Target:
165+
166+
![User Target](./images/user-targets-installation-3.png "User Target")
167+
168+
All files required by the User Targets (User Target jar, dependent jars, images, etc.) must be in the same directory as the registered User Target jar. Otherwise, the *Event Replicator Target Adapter* may not find these files.
169+
170+
## Information at startup
171+
The *Event Replicator Target Adapter* prints information on the User Targets during startup to the *sqlrep.log*:
172+
```
173+
ART0411I: User/Generic Target information at startup:
174+
175+
Type : Console Dump
176+
Name : Dump
177+
Description : Dump
178+
Version : 3.7 [2021-06-17 12:03:18]
179+
License Details
180+
Serial Number : 0000000000
181+
License Key : xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
182+
Customer ID : ADA RnD - Test ARTUT
183+
Customer Name : ADA RnD - Test ARTUT
184+
Operating System : Linux S390,Linux,win
185+
Product Name : Event Rep. Target Adapter for User Targ
186+
Product Code : ARTUT
187+
Product Version : 3.7
188+
Expiration Date : 2021/12/31 (93 days remaining)
189+
State : Active
190+
```
191+
192+
* Type - the type of the User Target, as listed in the *Administration* tree view
193+
* Name - the name of the User Target's instance
194+
* Description - description of User Target instance as entered in *Administration*
195+
* License Details - information about the license
196+
* Version - the version information derived from the *Bundle-Version* and the *Build-Date* of the **MANIFEST.MF** of the User Target jar
197+
* State - the result of the **isServiceOkay** call
198+
199+
## Disclaimer
200+
Utilities and samples shown here are not official parts of the Software AG products. These utilities and samples are not eligible for technical assistance through Software AG Global Support. Software AG makes no guarantees pertaining to the functionality, scalability , robustness, or degree of testing of these utilities and samples. Customers are strongly advised to consider these utilities and samples as "working examples" from which they should build and test their own solutions.

‎examples/README.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Example Projects
2+
In this folder are some User Target examples.
3+
4+
## Minimal User Target
5+
This is the example for a minimal User Target. You could use it as a base for creating own User Targets.
6+
7+
## Console Dump
8+
Console Dump is an User Target that reads the events and print the data to the console.
9+
10+
## Kafka
11+
This User Target sends the Adabas data as JSON messages to Kafka.
12+
13+
## Amazon S3
14+
The Amazon S3 User Target stores the Adabas data in Amazon S3 using the Parquet format.
15+
16+
## Disclaimer
17+
Utilities and samples shown here are not official parts of the Software AG products. These utilities and samples are not eligible for technical assistance through Software AG Global Support. Software AG makes no guarantees pertaining to the functionality, scalability , robustness, or degree of testing of these utilities and samples. Customers are strongly advised to consider these utilities and samples as "working examples" from which they should build and test their own solutions.

‎examples/amazon-s3/.classpath‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<classpath>
3+
<classpathentry kind="src" output="bin/main" path="src/main/java">
4+
<attributes>
5+
<attribute name="gradle_scope" value="main"/>
6+
<attribute name="gradle_used_by_scope" value="main,test"/>
7+
</attributes>
8+
</classpathentry>
9+
<classpathentry kind="src" output="bin/main" path="src/main/resources">
10+
<attributes>
11+
<attribute name="gradle_scope" value="main"/>
12+
<attribute name="gradle_used_by_scope" value="main,test"/>
13+
</attributes>
14+
</classpathentry>
15+
<classpathentry kind="src" output="bin/test" path="src/test/java">
16+
<attributes>
17+
<attribute name="gradle_scope" value="test"/>
18+
<attribute name="gradle_used_by_scope" value="test"/>
19+
<attribute name="test" value="true"/>
20+
</attributes>
21+
</classpathentry>
22+
<classpathentry kind="src" output="bin/test" path="src/test/resources">
23+
<attributes>
24+
<attribute name="gradle_scope" value="test"/>
25+
<attribute name="gradle_used_by_scope" value="test"/>
26+
<attribute name="test" value="true"/>
27+
</attributes>
28+
</classpathentry>
29+
<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.8/"/>
30+
<classpathentry kind="con" path="org.eclipse.buildship.core.gradleclasspathcontainer"/>
31+
<classpathentry kind="output" path="bin/default"/>
32+
</classpath>

‎examples/amazon-s3/.gitattributes‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#
2+
# https://help.github.com/articles/dealing-with-line-endings/
3+
#
4+
# These are explicitly windows files and should use crlf
5+
*.bat text eol=crlf
6+

‎examples/amazon-s3/.gitignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Ignore Gradle project-specific cache directory
2+
.gradle
3+
4+
# Ignore Gradle build output directory
5+
build
6+
7+
# Ignore Java bin directory
8+
bin

‎examples/amazon-s3/.project‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<projectDescription>
3+
<name>amazons-s3</name>
4+
<comment>Project amazon-s3 created by Buildship.</comment>
5+
<projects>
6+
</projects>
7+
<buildSpec>
8+
<buildCommand>
9+
<name>org.eclipse.jdt.core.javabuilder</name>
10+
<arguments>
11+
</arguments>
12+
</buildCommand>
13+
<buildCommand>
14+
<name>org.eclipse.buildship.core.gradleprojectbuilder</name>
15+
<arguments>
16+
</arguments>
17+
</buildCommand>
18+
</buildSpec>
19+
<natures>
20+
<nature>org.eclipse.jdt.core.javanature</nature>
21+
<nature>org.eclipse.buildship.core.gradleprojectnature</nature>
22+
</natures>
23+
</projectDescription>

‎examples/amazon-s3/.settings/org.eclipse.buildship.core.prefs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
connection.project.dir=
2+
eclipse.preferences.version=1

‎examples/amazon-s3/README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Amazon S3
2+
The Amazon S3 User Target stores the Adabas data in Amazon S3 using the Parquet format.
3+
4+
## Build
5+
Change directory to the example root directory and enter on a command prompt
6+
```
7+
gradle installDist
8+
```
9+
The jar with all dependencies will be in build/install directory.
10+
11+
## Disclaimer
12+
Utilities and samples shown here are not official parts of the Software AG products. These utilities and samples are not eligible for technical assistance through Software AG Global Support. Software AG makes no guarantees pertaining to the functionality, scalability , robustness, or degree of testing of these utilities and samples. Customers are strongly advised to consider these utilities and samples as "working examples" from which they should build and test their own solutions.

‎examples/amazon-s3/build.gradle‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
/*
2+
* This build file was generated by the Gradle 'init' task.
3+
*
4+
* This generated file contains a sample Java Library project to get you started.
5+
* For more details take a look at the Java Libraries chapter in the Gradle
6+
* user guide available at https://docs.gradle.org/4.3/userguide/java_library_plugin.html
7+
*/
8+
9+
// Apply the java-library plugin to add support for Java Library
10+
apply plugin: 'java-library'
11+
// Apply the distribution plugin to build the package distribution
12+
apply plugin: 'distribution'
13+
14+
// In this section you declare where to find the dependencies of your project
15+
repositories {
16+
// Use jcenter for resolving your dependencies.
17+
// You can declare any Maven/Ivy/file repository here.
18+
jcenter()
19+
}
20+
21+
/* Package distribution of Adabas target */
22+
distributions {
23+
/* Package java archives */
24+
main {
25+
baseName = project.baseName
26+
contents {
27+
from configurations.runtime {
28+
exclude('target-adapter-sdk.jar')
29+
exclude('sqlrep.jar')
30+
}
31+
from jar
32+
from {'icon'}
33+
}
34+
}
35+
}
36+
37+
dependencies {
38+
compile platform('software.amazon.awssdk:bom:2.13.29')
39+
compile 'software.amazon.awssdk:s3'
40+
41+
compile group: 'org.apache.avro', name: 'avro', version: '1.9.2'
42+
compile group: 'org.apache.parquet', name: 'parquet-avro', version: '1.10.1'
43+
compile group: 'org.apache.hadoop', name: 'hadoop-core', version: '1.2.1'
44+
45+
46+
compile files('../../lib/target-adapter-sdk.jar')
47+
compile files('lib/sqlrep.jar')
48+
49+
}
50+
51+
sourceCompatibility = 1.8
52+
53+
jar {
54+
archivesBaseName = 'art-' + baseName
55+
version = project.version
56+
manifest {
57+
attributes(
58+
"Implementation-Title": productName,
59+
"Implementation-Version": version,
60+
"Implementation-Vendor": vendor,
61+
"Specification-Title": productName,
62+
"Specification-Version": version,
63+
"Specification-Vendor": vendor,
64+
'Main-Class': 'com.softwareag.adabas.target.AmazonS3',
65+
"Bundle-Version": version,
66+
'Build-JDK': System.getProperty('java.version'),
67+
"Build-Date":new Date().format("yyyy-MM-dd' 'HH:mm:ss"),
68+
"Copyright": copyrightString
69+
)
70+
}
71+
}

0 commit comments

Comments
 (0)