Building utilities with Egeria¶

To create a Java utility that calls Egeria's OMAG Server Platform:

• To configure it or the OMAG Servers that run on it - using the administration services clients, such as MetadataAccessStoreConfigurationClient and ViewServerConfigurationClient.
• To start or stop servers - using PlatformServicesClient (activateWithStoredConfig, shutdownServer, ...).
• To query the status of the platform and its servers - using PlatformServicesClient and ServerOperationsClient.
• To retrieve or update metadata - using the Open Metadata Framework (OMF) handlers and the EgeriaOpenMetadataStoreClient.

it is necessary to create a Java program with a main() method that includes the appropriate clients and API modules from Egeria and is packaged in a jar file. The clients are described in Java clients. If your utility is not written in Java, call the REST APIs of the view services directly, or use the python client.

The sections that follow take you through the common tasks involved in building a utility using the IntelliJ IDEA IDE and Apache Maven. Egeria's own build uses Gradle, and the published Egeria libraries work equally well from a Gradle build - see the tip at the end of Creating a Maven POM file.

Creating a new project¶

The project manages the files for your utility.

To add a new project to intellij, select New then Project from the File top-level menu of IntelliJ.

Select Java then set up the project SDK by selecting your Java 21 installed JDK and then click the Next button. If this is the first time you are using IntelliJ you may need to click on the New... button and navigate to your install directory.

Leave the Create project from template option blank and simply click the Next button.

Add the name of the project in Project name and the directory where you want the project files to be stored in Project location.

Click on the Finish button. If the directory is new, you may get this pop-up to confirm that the directory should be created. Click OK.

Once the wizard completes IntelliJ will open up your new project, ready to begin coding. The src directory is where your code will go.

Creating a new java package¶

To add a new Java package to your project, right-mouse click on the java directory.

Select New then Package on the sub menu.

A pop-up box appears asking for the name of the package. Enter your new package name and press the OK button. Java package names are in lowercase and are dot (.) separated.

The new package appears under src in the project list.

Creating a new java class¶

To add a new Java class to your project, right-mouse click on the package name and select New then Java Class on the sub menu.

A pop-up box appears asking for the name of the class. Enter your new class name and press the OK button.

The new class appears in the project list and the source file is open in the editor.

Creating a Maven POM file¶

A pom.xml is the file that controls an Apache Maven build. From IntelliJ, select the top level directory for the module (egeria-dojo in this case) and using the right-mouse menu, select New and then File from the sub menu.

Enter pom.xml as the file name and click OK.

Egeria's libraries are published to Maven Central under the group org.odpi.egeria. Egeria also publishes a BOM (bill of materials) with the artifact name egeria. Importing it into the dependencyManagement section of your pom.xml sets the version of every Egeria module and of the third-party libraries that Egeria is built and tested with, so the individual dependencies do not need a version.

The example below is a starting point for a utility that calls the platform services. Change the groupId, artifactId and Egeria version to suit your utility, and add the client modules for the services you need to call (see Java clients).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>egeria-dojo</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.release>21</maven.compiler.release>
        <open-metadata.version>6.2</open-metadata.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.odpi.egeria</groupId>
                <artifactId>egeria</artifactId>
                <version>${open-metadata.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <dependency>
            <groupId>org.odpi.egeria</groupId>
            <artifactId>platform-services-client</artifactId>
        </dependency>
        <dependency>
            <groupId>org.odpi.egeria</groupId>
            <artifactId>open-metadata-framework</artifactId>
        </dependency>
        <dependency>
            <groupId>org.odpi.egeria</groupId>
            <artifactId>open-connector-framework</artifactId>
        </dependency>
        <dependency>
            <groupId>org.odpi.egeria</groupId>
            <artifactId>audit-log-framework</artifactId>
        </dependency>
        <dependency>
            <groupId>org.odpi.egeria</groupId>
            <artifactId>yaml-secrets-store-connector</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>org.odpi.egeria</groupId>
            <artifactId>http-helper</artifactId>
        </dependency>
        <dependency>
            <groupId>ch.qos.logback</groupId>
            <artifactId>logback-classic</artifactId>
        </dependency>
    </dependencies>
</project>

Egeria requires Java 21, hence maven.compiler.release is set to 21. The Java clients declare their own Egeria dependencies with runtime scope, so the frameworks whose classes appear in a client's method signatures are listed explicitly: open-metadata-framework (for example org.odpi.openmetadata.frameworks.openmetadata.ffdc.InvalidParameterException), open-connector-framework (SecretsStoreConnector) and audit-log-framework (AuditLog). The yaml-secrets-store-connector provides YAMLSecretsStoreProvider, a secrets store that the clients can use to obtain their bearer token (see secrets store connector). The HTTP Helper and Logback dependencies are explained on their own pages.

dependencies {
    implementation platform("org.odpi.egeria:egeria:6.2")
    implementation 'org.odpi.egeria:platform-services-client'
    implementation 'org.odpi.egeria:open-metadata-framework'
    implementation 'org.odpi.egeria:open-connector-framework'
    implementation 'org.odpi.egeria:audit-log-framework'
    runtimeOnly 'org.odpi.egeria:yaml-secrets-store-connector'
    implementation 'org.odpi.egeria:http-helper'
    implementation 'ch.qos.logback:logback-classic'
}

Add as Maven Project in IntelliJ¶

Once you have your pom.xml file completed, select it in the list of files for your project and use the right-mouse menu to select Add as Maven Project.

The pom.xml file will change its icon to show it is recognized as a Maven pom file.

Configuring logging and certificate checking¶

Most utilities also need a logging destination and, in a development environment, a way to accept the platform's self-signed certificate:

• Configuring Logback
• Using HTTP Helper

Raise an issue or comment below