IntelliJ IDEA tutorial¶
IntelliJ IDEA by JetBrains is the Interactive Development Environment (IDE) used by most of the Egeria developers. The community edition is free to use and covers all the function needed by an Egeria developer.
See the overview video of IntelliJ on its homepage.
Managing your IntelliJ environment¶
Installing Intellij¶
Link to the download page and follow the instructions.
Start up IntelliJ.
Set up Java ...
Validate that the project is set up with the right level of Java - you need Java 17. Select File and then Project Structure.... When the wizard opens select Project and ensure the SDK is Java 17.
Set up Maven ...
Set up Maven to the version that you downloaded by selecting Preferences ... from the IntelliJ IDEA menu and then Build, Execution, Deployment followed by Build Tools followed by Maven in the left-hand menu of the resulting wizard. Ensure the Maven Home Directory points to a level of Maven that is at least version 3.5.0.
The three dots after the directory name enables you to select your Maven install directory.
Ensure you have enough memory ...
Update your memory settings for IntelliJ to ensure you have at least 2GB of memory. This is the option Change Memory Settings that is under the Help menu. In some editions it is nested under Diagnostics.
Check your lombok setup
Egeria makes use of Project Lombok . If using JetBrains IntelliJ IDEA ensure it has the required plugin configured .
Don't detect generated sources
Before running a Maven build, please choose Don't detect from the Generated sources folders dropdown in Preferences -> Build, Execution, Deployment -> Build Tools -> Maven -> Importing. This will avoid triggering a duplicate classes build error caused by the delomboked sources folders being added as source folders for the Maven module.
If this wasn't set when your project was initially setup, you may find that delombok directories are already present in IntelliJ's source path for some modules, leading to errors with duplicate classes.
To check for any modules still refering to delombok you can run this at the command line, from your top-level source tree:
Find any existing delombok source entries in IntelliJ
find . -name '*.iml' | xargs -n50 grep -y delombok
If you find any hits such as:
./open-metadata-implementation/access-services/data-engine/data-engine-api/data-engine-api.iml: <sourceFolder url="file://$MODULE_DIR$/target/delombok" isTestSource="false" />
then either remove those lines without IntelliJ running, or go into File -> Project Structure -> Modules, and remove target/delombok from the Source Folders list
Explanation: in addition to importing module defintions from the Maven pom.xml, IntelliJ also tries to look for any generated source. It finds the delombok directory, causing duplicates: in fact we only use this directory for generating Javadoc of lombok-enabled modules. Switching the setting / removing these source folders prevents these duplicate classes.
Raise an issue or comment below
Loading Egeria into IntelliJ IDEA¶
Once you have a copy of a git repository on your local disk you can load the contents into IntelliJ.
Go to the File menu and select Open
Then select the top-level directory that was created when you cloned the git repository.
You may be warned about loading egeria in which case select Trust Project:
If asked which build approach to use, select Maven:
IntelliJ will then start reading the git repository and creating a project. This may take a few minutes so be patient.
Validate that the project is set up with the right level of Java - you need Java 17. Select File and then Project Structure.... When the wizard opens select Project and ensure the SDK is Java 17.
Building Egeria in IntelliJ IDEA¶
The build process is different for each git repository. Click on the table for the repository that you are building:
Building egeria.git¶
Maven is accessed from a sidebar menu in IntelliJ.
When you click on the Maven label, a panel opens with the list of modules in the git repository is displayed.
Chose the build option for your work ...
The egeria.git repository has a top-level pom file so all the modules can be built using one command.
Select the M button at the top of the maven panel for Execute Maven Goal.
Then the Execute Maven Goal dialog box opens to enter your command clean install command.
The egeria.git repository has a top-level pom file so all of the modules can be built using one command.
Select the M button at the top of the maven panel for Execute Maven Goal.
Then the Execute Maven Goal dialog box opens to enter your command clean install -P quick -D skipFVT. This skips all of the verification of the project files and running tests. It is suitable for development projects (such when running the dojo). However, if you are experiencing problems with building this repository, use the full build option to verify the project directories.
If you are making small changes, you may wish to simply rebuild a single module.
Goto the maven sidebar panel and find the module you are interested in. Open up the content for the module and then the lifecycle folder.
First double-click on clean and the build of that module runs.
Once the clean is complete, double-click on install and the build of that module starts.
Note: this option does not rebuild the assembly and so if you are using the OMAG Server Platform from the assembly to test your changes, you may need to do a full build to incorporate your change into the platform.
The build kicks off in a new pane (typically at the bottom of your IntelliJ window).
The build can take 15 minutes to over an hour depending on the build method and speed/load on your machine. However eventually you will see the message:
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 54:54 min
[INFO] Finished at: 2020-01-29T09:33:17Z
[INFO] Final Memory: 171M/3510M
[INFO] ------------------------------------------------------------------------
Process finished with exit code 0
Raise an issue or comment below
Building egeria-samples.git¶
Maven is accessed from a sidebar menu in IntelliJ.
When you click on the Maven label, a panel opens with the list of modules in the git repository is displayed. The maven:
The egeria-samples.git repository does not have a top-level pom file. Each sample is built separately.
Go to the module of the sample that you are interested in. Open up the content for the module and then the lifecycle folder.
First double-click on clean and the build of that module runs.
Once the clean is complete, double-click on install and the build of that module starts.
The build kicks off in a new pane (typically at the bottom of your IntelliJ window).
The build takes a few minutes depending on the speed/load on your machine. However eventually you will see the message:
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 54:54 min
[INFO] Finished at: 2020-01-29T09:33:17Z
[INFO] Final Memory: 171M/3510M
[INFO] ------------------------------------------------------------------------
Process finished with exit code 0
Raise an issue or comment below
Building egeria-dev-projects.git¶
Maven is accessed from a sidebar menu in IntelliJ.
When you click on the Maven label, a panel opens with the list of modules in the git repository is displayed. The maven:
The egeria-dev-projects.git repository has a top-level pom file so all of the modules can be built using one command.
Select the M button at the top of the maven panel for Execute Maven Goal.
Then the Execute Maven Goal dialog box opens to enter your command clean install and press Execute.
The build kicks off in a new pane (typically at the bottom of your IntelliJ window).
The build can take a few minutes depending on the speed/load on your machine. However eventually you will see the message:
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 54:54 min
[INFO] Finished at: 2020-01-29T09:33:17Z
[INFO] Final Memory: 171M/3510M
[INFO] ------------------------------------------------------------------------
Process finished with exit code 0
Raise an issue or comment below
Using maven rather than using the IntelliJ build?¶
While you are working on code in IntelliJ, it will be continuously rebuilding your code so that it is discovering syntax other coding errors as you type. This is useful in getting a first pass of your code.
However, IntelliJ does not understand the egeria structure - only Maven does, so the Maven build is important to to verify your changes are OK at the project level.
Installing Egeria¶
If your development work is using the main Egeria libraries rather than developing its contents, you may wish to install Egeria into a more convenient location on your local disk.
Click on the Terminal tab - typically at the bottom of your IntelliJ window - to open the terminal window. The working directory is positioned at the top of your project.
The egeria build process creates the distribution files for Egeria in the open-metadata-distribution/open-metadata-assemblies project. To see its contents, after a full gradle build completes, use the following cd command to change to its build/distributions directory:
cd open-metadata-distribution/open-metadata-assemblies/build/distributions
ls
{{release}}-distribution.tar.gz or egeria-4.1-distribution.tar.gz in this example.
egeria-4.1-distribution.tar.gz
Create a directory for the install and copy the tar file into it. The two commands shown below create an install directory in your home directory and then copies the egeria distribution file into it.
mkdir ~/egeria-install
cp egeria*-distribution.tar.gz ~/egeria-install
These next commands change to the new directory and lists its contents.
cd ~/egeria-install
It is now possible to unpack the tar file with the following steps.
gunzip egeria*-distribution.tar.gz
tar -xf egeria*-distribution.tar
{{release}}-distribution.tar.gz or egeria-4.1-distribution.tar.gz in this example. Change to this new directory and list its contents as shown below.
cd egeria*gz
ls
LICENSE content-packs samples user-interface
NOTICE keystore.p12 server utilities
conformance-suite sample-data truststore.p12
As before, you may notice different files as Egeria evolves.
Under server is a directory for the OMAG Server Platform that is used to run open metadata and governance services. This is the server-chassis-spring-4.1.jar.
ls server
lib server-chassis-spring-4.1.jar
lib directory is where the jar files for connectors, samples and new registered services are installed. The initial list includes the connectors that are located in the egeria.git repository.
ls server/lib
audit-log-console-connector-4.1.jar
audit-log-event-topic-connector-4.1.jar
audit-log-file-connector-4.1.jar
audit-log-slf4j-connector-4.1.jar
avro-file-connector-4.1.jar
basic-file-connector-4.1.jar
cohort-registry-file-store-connector-4.1.jar
configuration-encrypted-file-store-connector-4.1.jar
configuration-file-store-connector-4.1.jar
csv-file-connector-4.1.jar
data-folder-connector-4.1.jar
discovery-service-connectors-4.1.jar
dynamic-archiver-connectors-4.1.jar
elasticsearch-integration-connector-4.1.jar
files-integration-connectors-4.1.jar
governance-action-connectors-4.1.jar
governance-services-sample-4.1.jar
graph-repository-connector-jar-with-dependencies-4.1.jar
inmemory-open-metadata-topic-connector-4.1.jar
inmemory-repository-connector-4.1.jar
kafka-integration-connector-4.1.jar
kafka-open-metadata-topic-connector-4.1.jar
omrs-rest-repository-connector-4.1.jar
open-lineage-janus-connector-4.1.jar
open-metadata-archive-directory-connector-4.1.jar
open-metadata-archive-file-connector-4.1.jar
open-metadata-security-samples-4.1.jar
openapi-integration-connector-4.1.jar
openlineage-integration-connectors-4.1.jar
spring-rest-client-connector-4.1.jar
Copy the jar files for any additional connectors you want to use into the lib directory. The connectors available for Egeria are listed in the Connector Catalog.
The content-packs directory contains Open Metadata Archives that provide sample open metadata content. The README.md describes their content.
ls content-packs
CloudInformationModel.json DataStoreConnectorTypes.json
CocoBusinessSystemsArchive.json OpenConnectorsArchive.json
CocoClinicalTrialsTemplatesArchive.json OpenMetadataTypes.json
CocoComboArchive.json README.md
CocoGovernanceEngineDefinitionsArchive.json SimpleAPICatalog.json
CocoGovernanceProgramArchive.json SimpleDataCatalog.json
CocoOrganizationArchive.json SimpleEventCatalog.json
CocoSustainabilityArchive.json SimpleGovernanceCatalog.json
CocoTypesArchive.json
sample-data directory contains sample data that is used in various labs and samples.
ls sample-data/*
sample-data/oak-dene-drop-foot-weekly-measurements:
week1.csv week3.csv week5.csv week7.csv week9.csv
week2.csv week4.csv week6.csv week8.csv
sample-data/old-market-drop-foot-weekly-measurements:
week1.csv week3.csv week5.csv week7.csv week9.csv
week2.csv week4.csv week6.csv week8.csv
Raise an issue or comment below
Developing new function with IntelliJ IDEA¶
Creating a new project¶
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 17 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.
Adding changes to Git¶
Any changes, additions and deletions that you make to the files under the git repository directory are automatically detected by git. It is possible to add these changes to your clone using the Add option on the Git right-mouse menu.
Raise an issue or comment below