abas Software AG

This is the documentation for the ESDK Project Initializer.

Introduction

The ESDK Project Initializer is an application to generate the initial project structure of an ESDK App project.

The application offers various options to define the environment settings and initialize the project structure of an ESDK App project. It is possible to specify:

  • the abas Essentials environment properties

  • the Nexus Sonatype Artifact Server environment properties

  • the name, Vendor ID and App ID of the ESDK App

  • the ESDK version to use for creating the ESDK App

  • the namespace of the ESDK App

  • the abas Essentials version ranges supported by the ESDK App

  • all components belonging to the ESDK App

It is also possible to interactively initialize the following ESDK App components:

  • data.json

  • fop.json

The project generated by the ESDK Project Initializer contains a ZipCodeEventHandler class, which validates whether a zip code entered in the Customer screen is valid. Additionally in src/integTest/java you can find an exemplary integration test for this functionality and in src/test/java there is an exemplary unit test for the zip code validation class.

This code is meant to show you how to set up main, test and integration test logic for your App.

download admonition The current version of the ESDK Project Initializer can be downloaded as a ZIP file.

To use it execute the following steps:

  • Unzip the file.

  • Change into the unzipped folder.

  • Change into the bin folder.

  • Run the script init-project or init-project.bat according to your operating system.

You can also add the bin folder of the unzipped ESDK Project Initializer to your $PATH variable. Then you can run init-project from any directory on your machine.

Usage

This is the usage of the ESDK Project Initializer:

usage: ./init-project
       --abas-host <abas-host>                      Hostname of abas Essentials client
       --app-id <app-id>                            App ID
       --app-name <app-name>                        ESDK App Name
    -d,--dir <arg>                                  target directory
       --data                                       Data Objects
       --enums <enums>                              Enumerations
       --essentials-version <essentials-version>    abas Essentials Version used for development
       --essentials-versions <essentials-versions>  Essentials Version Ranges
       --event-registration                         EventHandler registration
    -h,--help                                       show usage
       --infosystems <infosystems>                  Infosystems
       --languages <languages>                      Languages
       --name-space <name-space>                    ESDK App Namespace (= java package name)
       --named-types <named-types>                  Named Types
       --nexus-host <nexus-host>                    Hostname of Sonatype Nexus Artifact Server
       --nexus-version <nexus-version>              Sonatype Nexus Artifact Server Version (2 or 3)
       --screens <screens>                          Screens
       --tables <tables>                            Variable Tables
    -v,--version                                    show version
       --vendor-id <vendor-id>                      Vendor ID
For more information visit: https://documentation.abas.cloud/en/esdk-project-initializer

For further information on single options refer to the following chapters.

1.1. Option --abas-host

This option specifies the hostname/IP address used for connecting to the abas Essentials client.

If not specified it is not interactively asked for. Instead the current IP address of the local machines hostname is used.

Currently the abas Essentials host property is the only property that can be changed by the ESDK Project Initializer. All other connection properties are fixed and configured to match the standard settings for working with a dockerized abas Essentials client. If this is not desired, the connection properties in the gradle.properties and possibly also the gradle.properties.template files have to be altered manually after the ESDK App project is initialized.

1.2. Option --app-id

This option specifies the App ID of the ESDK App project.

This is a required option, if not specified it is interactively asked for.

The App ID must be exactly five characters long and can consist of numbers and/or alpha-numeric characters.

To ensure the App ID is still available and to reserve it for your ESDK App project, you should notify the abas Essentials Team at abas Software AG as soon as possible. We will then register the App ID for you free of charge.

1.3. Option --app-name

This option specifies the App name of the ESDK App project.

This is a required option, if not specified it is interactively asked for.

The App name must start with a lower case alpha-numeric character and can consist of any number of alpha-numeric characters and numbers.

The App name will also be used as the name of the generated project, as well as the JFOP Server App name your App’s logic resides in.

When registering an EventHandler for an Infosystem or in the fop.txt, you therefore need to add @<appName> to the registration, e.g. java:your.package.Class@yourAppName.

1.4. Option -d/--dir

This option specifies the parent directory of the generated ESDK App project.

If not specified the current directory is used.

1.5. Option --data

This option specifies whether data objects are a part of the ESDK App’s scope.

This is not a required option, but if a console is available it is asked for interactively.

If the option is specified a data.json file will be created in the src/main/resources/data folder of the ESDK App project. The data.json file will also be registered in the data property in the build.gradle file.

1.6. Interactive mode

In interactive mode you can specify root selections that will then be added to the data.json file in src/main/resources/data of your ESDK App project.

The following input:

Data Objects ([]) (N/y): y
Data Objects ([]) enter dbnr: 0
Data Objects ([]) enter grnr: 1
Data Objects ([]) enter identifier: guid
Data Objects ([]) enter headfields: nummer, guid, such, name
Data Objects ([]) enter tablefields:
Data Objects ([]) enter criteria: such==TEST

Will generate a data.json that looks like this:

data.json
{
  "roots": [{
    "dbnr": 0,
    "grnr": 1,
    "identifier": "guid",
    "headfields": ["nummer", "guid", "such", "name"],
    "tablefields": [],
    "criteria": "such==TEST"
  }]
}

1.7. Option --enums

This option specifies whether enumerations are a part of the ESDK App’s scope. The option takes a list of enumeration class names as argument. For the enumeration class names FileFormat and UserInfo the following input is valid:

--enums FileFormat,UserInfo
--enums 'FileFormat, UserInfo'
--enums [FileFormat,UserInfo]
--enums ["FileFormat","UserInfo"]

This is not a required option, but if a console is available it is asked for interactively.

If the option is specified the enumeration class names passed as argument will be registered in the enums property in the build.gradle file.

1.8. Option --esdk-version

This option specifies the ESDK version used for building the ESDK App.

This is a required option, if not specified it is interactively asked for.

The specified ESDK version is validated against all available ESDK versions. The default value is always the latest ESDK version.

1.9. Option --essentials-version

This option specifies the abas Essentials version used for development of the ESDK App.

This is a required option, if not specified it is interactively asked for.

The abas Essentials version must be a valid version number for abas Essentials (e.g. 2017r4n16p02) or image name (e.g. 2018r4n13).

The specified version will be used as the image version in the docker-compose.yml file. It should therefore be available as a version of an image for abas Essentials in the Partner Docker Registry.

It is not currently checked, that the abas Essentials image version is available in the Partner Docker Registry. Any valid version number or image name will be accepted.

1.10. Option --essentials-versions

This option specifies the abas Essentials versions supported by your ESDK App. The option takes a list of abas Essentials version ranges as argument. For the version ranges 2017r1-2017r4 and 2018r1-2018r1 the following input is valid:

--essentials-versions 2017r1-2017r4,2018r1-2018r1
--essentials-versions '2017r1-2017r4, 2018r1-2018r1'
--essentials-versions [2017r1-2017r4,2018r1-2018r1]
--essentials-versions ["2017r1-2017r4","2018r1-2018r1"]

This is a required option, if not specified it is interactively asked for.

Each version specified in a version range must be a valid abas Essentials version.

1.11. Option --event-registration

This option specifies whether fop.txt entries are a part of the ESDK App’s scope.

This is not a required option, but if a console is available it is asked for interactively.

If the option is specified a fop.json file will be created in the src/main/resources folder of the ESDK App project.

1.12. Interactive mode

In interactive mode you can specify each fop.txt entry that will then be added to the fop.json file in src/main/resources of your ESDK App project.

The following input:

fop.txt changes ([]) (N/y): y
fop.txt changes ([]) enter databaseName: (Sales)
fop.txt changes ([]) enter groupName: (PackingSlip)
fop.txt changes ([]) enter editorMode: new
fop.txt changes ([]) enter event: ScreenEnd
fop.txt changes ([]) enter field: *
fop.txt changes ([]) enter headOrTable: Head
fop.txt changes ([]) enter handler: java:de.abas.esdk.app.Test@atest

Will generate a fop.json that looks like this:

fop.json
[{
  "databaseName": "(Sales)",
  "groupName": "(PackingSlip)",
  "editorMode": "neu",
  "event": "maskend",
  "key": "*",
  "field": "*",
  "headOrTable": "K",
  "isContinue": "[C]",
  "handler": "java:de.abas.esdk.app.Test@atest"
}]

1.13. Option -h,--help

This option shows the Usage.

1.14. Option --infosystems

This option specifies whether infosystems are a part of the ESDK App’s scope. The option takes a list of Infosystem classifiers as argument. For the Infosystem classifiers IS.OW1.SPARE and IS.OW1.REPLACEMENT the following input is valid:

--infosystems IS.OW1.SPARE,IS.OW1.REPLACEMENT
--infosystems 'IS.OW1.SPARE, IS.OW1.REPLACEMENT'
--infosystems [IS.OW1.SPARE,IS.OW1.REPLACEMENT]
--infosystems ["IS.OW1.SPARE","IS.OW1.REPLACEMENT"]

This is not a required option, but if a console is available it is asked for interactively.

If the option is specified the Infosystem classifiers passed as argument will be registered in the infosystems property in the build.gradle file.

1.15. Option --languages

This option specifies what languages are supported by your ESDK App. The option takes a list of languages as argument. For German and American English the following input is valid:

--languages DA
--languages 'D A'
--languages 'German, American English'

This is a required option, if not specified it is interactively asked for.

The specified languages will be registered in the languages property in the build.gradle file.

1.16. Option --name-space

This option specifies the namespace of your ESDK App. It is used as base package name of all your classes in src/main/java, src/test/java and src/integTest/java.

This is a required option, if not specified it is interactively asked for.

1.17. Option --named-types

This option specifies whether Named types are a part of the ESDK App’s scope. The option takes a list of Named type class names as argument. For the Named type class names FileDate and UserInfo the following input is valid:

--named-types FileDate,UserInfo
--named-types 'FileDate, UserInfo'
--named-types [FileDate,UserInfo]
--named-types ["FileDate","UserInfo"]

This is not a required option, but if a console is available it is asked for interactively.

If the option is specified the Named type class names passed as argument will be registered in the named-types property in the build.gradle file.

1.18. Option --nexus-host

This option specifies the hostname/IP address used for connecting to the Sonatype Nexus Artifact Server.

If not specified it is not interactively asked for. Instead the current IP address of the local machines hostname is used.

Currently the Nexus host and version properties are the only properties that can be changed by the ESDK Project Initializer. All other connection properties are fixed and configured to match the standard settings for working with a dockerized Nexus Artifact Server. If this is not desired, the connection properties in the gradle.properties and possibly also the gradle.properties.template files have to be altered manually after the ESDK App project is initialized.

1.19. Option --nexus-version

This option specifies the Sonatype Neuxs Artifact Server version used for building the ESDK App project. Supported versions are 2 and 3.

If not specified it is not interactively asked for. Instead the Sonatype Nexus Artifact Server version 2 is used.

Currently the Nexus host and version properties are the only properties that can be changed by the ESDK Project Initializer. All other connection properties are fixed and configured to match the standard settings for working with a dockerized Nexus Artifact Server. If this is not desired, the connection properties in the gradle.properties and possibly also the gradle.properties.template files have to be altered manually after the ESDK App project is initialized.

1.20. Option --screens

This option specifies whether screens are a part of the ESDK App’s scope. The option takes a map of database class name and priorities as argument. For the database class names Customer:Customer and priorities A, D the following input is valid:

--screens `[ Customer:Customer : [A, D]]`
--screens `[ "Customer:Customer" : ["A", "D"]]`

This is not a required option, but if a console is available it is asked for interactively.

If the option is specified the screens passed as argument will be registered in the screens property in the build.gradle file.

1.21. Interactive mode

In interactive mode you can specify each screen database and its priorities that will then be added to the screens property in the build.gradle file.

The following input:

Screens ([]) (N/y): y
Screens ([]) enter table: Customer:Customer
Screens ([]) enter priorities: A, D

Will generate a screens property entry that looks like this:

screens = ["Customer:Customer" : ["A", "D"]]

1.22. Option --tables

This option specifies whether variable tables are a part of the ESDK App’s scope. The option takes a list of variable table names as argument. For the variable table names Kunde and CustomTable the following input is valid:

--tables Kunde,CustomTable
--tables 'Kunde, CustomTable'
--tables [Kunde,CustomTable]
--tables ["Kunde","CustomTable"]

This is not a required option, but if a console is available it is asked for interactively.

If the option is specified the variable table names passed as argument will be registered in the tables property in the build.gradle file.

1.23. Option -v,--version

This option shows the version of the ESDK Project Initializer.

1.24. Option --vendor-id

This option specifies the Vendor ID of the ESDK App project.

This is a required option, if not specified it is interactively asked for.

The Vendor ID must be exactly two characters long, must start with an alpha-numeric character and can consist of numbers and/or alpha-numeric characters.

You should use the same Vendor ID throughout all ESDK App projects in your company.

Project structure

The generated project structure looks like this:

yourAppProject
├── documentation (1)
│   └── src
│       └── ...
├── gradle (2)
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── src (3)
│   ├── integTest
│   │   └── java
│   │       └── <your package>
│   ├── main
│   │   ├── java
│   │   │   └── <your package>
│   │   └── resources
│   │       ├── <your components>
│   │       └── logging.custom.properties
│   └── test
│       └── java
│           └── <your package>
├── build.gradle (4)
├── docker-compose.yml (5)
├── .gitignore
├── gradle.properties (6)
├── gradle.properties.template (6)
├── gradlew (2)
├── gradlew.bat (2)
├── initGradleProperties.sh (6)
├── Jenkinsfile (7)
├── README.md (8)
└── settings.gradle (2)
1 The documentation folder is where you write your ESDK App’s documentation. Detailed instructions can be found in the Documentation chapter.
2 These files are necessary to execute Gradle tasks in your project.
3 The src folder is where your ESDK App’s logic resides. More information can be found in the App Logic chapter.
4 The build.gradle file contains your build configuration, you might have to re-configure your project during development. Refer to the ESDK Documentation
5 The docker-compose.yml contains the configuration for your abas Essentials and Sonatype Nexus Artifact Server containers. You can start them by executing docker-compose up.
6 The gradle.properties file contains all configuration to access the abas Essentials and Sonatype Nexus Artifact Server. Refer to the Initialize Configuration chapter for more information.
7 The Jenkinsfile contains a Jenkins Job configuration template for building and testing your app in a Jenkins Job.
8 The README.md is where you put information on how to build and run your app for other ESDK App developers in your company.

1.1. Documentation

The documentation folder contains the following files:

src/main
├── asciidoc
│   ├── additionalpage.adoc (2)
│   ├── index.adoc (1)
│   └── subpage.adoc (2)
└── resouces
    └── images (3)
1 The index.adoc is the main file of your documentation. All files with additional content are included here.
2 To have more structure in your documentation source files all chapters of your documentation should go into separate files. They are then referenced in the right order in your index.adoc file.
3 This is where you put images you want to display in your documentation.

1.1.1. Writing ESDK App documentation

You write your ESDK App’s documentation by adding .adoc files to the documentation/src/main/asciidoc folder and referencing them in your index.adoc file.

There are already two example .adoc files: subpage.adoc and additionalpage.adoc. Both are already referenced in the index.adoc and you can use them as a starting point.

The formatting is provided by Asciidoctor, refer to the Asciidoctor documentation for help on how to format your documentation with headings, lists, images, etc.

For more information on the ESDK App documentation tasks refer to abas Essentials SDK Documentation.

1.2. App Logic

The src folder contains all test and production logic and all components of your app.

The src/integTest/java folder is meant to be used for integration tests (e.g. to test drive your Infosystem via AJO).

The src/test/java folder is meant to be used for unit tests (e.g. to check that methods of a class work as expected).

The src/main/java folder later contains all of your production logic.

The src/main/resources folder later contains all of your ESDK Apps components. After initializing your project it will at least contain the logging.custom.properties file. Additionally it may contain more folders depending on what components you configured during project initialization (e.g. vartabs, IS, …​).

For more information on the components of your ESDK App and Gradle tasks for testing refer to the ESDK documentation.

1.3. Initialize Configuration

When initializing your ESDK App project a gradle.properties file is created using your IP address as host for accessing abas Essentials and Sonatype Nexus Artifact Server. It also configures all ports to be used with the Docker containers.

If you do not want to use the Docker containers, you need to edit the gradle.properties file manually, to match your development environment.

At any point you can execute ./initGradleProperties.sh to regenerate the initial gradle.properties file.

If you develop against the dockerized environment we recommend not to track the gradle.properties file with Git, since it needs to be edited for another developer. Instead just run ./initGradleProperties.sh to create the gradle.properties file on the developer’s computer.

About

Version: 0.1.14

abas Essentials SDK