View Source

Overview

Documents setting up code, config, and data in a development environment using Eclipse.

Prerequisites

Git client
Java Use OpenJDK-11u - https://github.com/AdoptOpenJDK/openjdk11-upstream-binaries (click on "releases")
Mysql 5.7 installed
Maven 3.6.+ installed
Tomcat 9+ installed and configured
Eclipse
- Use 2020-XX - J2EE edition
- Jautodoc - import configuration from Code and XML Formatting in Eclipse
- FindBugs (static code analysis)

Details

Step 1 - Create directories

Setup for Windows

Create a data directory to hold your data files (e.g. c:/refset/data)
Create a config directory to hold your config files (e.g. c:/refset/config)
Create a code directory to hold the code (e.g. c:/workspace/ihtsdo-refset-tool)
Make sure the "mvn" executable for your local maven installation is in the path
- On Windows this means adding to the PATH variable so that it runs in a "cmd" shell without fully qualified path.

Setup for Unix/Linux/Mac

Create a data directory to hold your data files (e.g. ~/data)
Create a config directory to hold your config files (e.g. ~/config)
Create a code directory to hold the code (e.g. ~/code)
Make sure the "mvn" executable for your local maven installation is in the path

Step 2 - Clone repository

Clone the Github repository to the directory created to hold the code.

Step 3 - Build project

Build all project modules with "mvn clean install" at the top level - either through Eclipse or via the command line.

NOTE: this uses the standard "dev-windows" configuration by default. To use a different configuration artifact pass the following three parameters (this is not commonly needed):
- -Dconfig.groupId=...
- -Dconfig.artifactId=...
- -Dconfig.version=...
For most dev deployments, the default build is fine because the only setting really used for the rest/webapp packages is the "base.url" which by default is set to http://localhost:8080/refset-rest
For a production deployment, you would want to use a different setting. For example, see PROD Deploy Instructions

Step 4 - Setup Configuration

Choose a "dev-windows" or "prod" config project target and unzip it into the directory created to hold your config files.

config/dev-windows/target/refset-config-dev-windows.*.zip (e.g. unzip to c:/refset/config)
config/prod/target/refset-config-prod.*.zip (e.g. unzip to ~/refset/config)

Unzip the config/target/refset-config.*.zip file into the directory created to hold your data files (these are the sample data artifacts). For example, unzip to c:/refset/data when building a dev environment on Windows.

Step 5 - Edit configuration

Edit the "config.properties" file in your config files directory to set correctly for your environment. In particular, edit these:

javax.persistence.jdbc.url (contains the database name)
javax.persistence.jdbc.user
javax.persistence.jdbc.password
hibernate.search.default.indexBase ( recommend choosing something in your data dir, e.g. c:/refset/data/indexes or ~/refset/indexes)
mail.smtp.* (list for automated system emails)
identifier.assignment.handler.
- If you have a Snomed-provided IMS account, you can put your name and password below to access the Snomed identifier service:
  - identifier.assignment.handler.DEFAULT.url=http://dev-cis.ihtsdotools.org:3000/api
    identifier.assignment.handler.DEFAULT.userName=EDIT_THIS
    identifier.assignment.handler.DEFAULT.password=EDIT_THIS
- If you do NOT have a Snomed-provided IMS account, you can use the provided simple identifier handler:
  - identifier.assignment.handler=DEFAULT
    identifier.assignment.handler.DEFAULT.class=org.ihtsdo.otf.refset.jpa.services.handlers.DummyComponentIdentifierServiceHandler
    #identifier.assignment.handler.DEFAULT.class=org.ihtsdo.otf.refset.jpa.services.handlers.IhtsdoComponentIdentifierServiceHandler
    #identifier.assignment.handler.DEFAULT.url=https://cis.ihtsdotools.org/api
    #identifier.assignment.handler.DEFAULT.userName=EDIT_THIS
    #identifier.assignment.handler.DEFAULT.password=EDIT_THIS
terminology.handler, e.g.
- terminology.handler=BROWSER,SNOWOWL,SNOWOWL-SE
  terminology.handler.BROWSER.class=org.ihtsdo.otf.refset.jpa.services.handlers.BrowserTerminologyHandler
  terminology.handler.BROWSER.defaultUrl=https://sct-rest.ihtsdotools.org/api
  terminology.handler.BROWSER.apiKey=EDIT_THIS
  terminology.handler.SNOWOWL.class=org.ihtsdo.otf.refset.jpa.services.handlers.SnowowlTerminologyHandler
  terminology.handler.SNOWOWL.defaultUrl=https://authoring.ihtsdotools.org/snowowl/snomed-ct/v2
  terminology.handler.SNOWOWL.authHeader=Basic EDIT_THIS
  terminology.handler.SNOWOWL.apiKey=EDIT_THIS
  terminology.handler.SNOWOWL-SE.class=org.ihtsdo.otf.refset.jpa.services.handlers.SnowowlTerminologyHandler
  terminology.handler.SNOWOWL-SE.defaultUrl=https://se-authoring.ihtsdotools.org/snowowl/snomed-ct/v2
  terminology.handler.SNOWOWL-SE.apiKey=EDIT_THIS
base.url=EDIT_THIS (e.g. http://localhost:8080/refset-rest)
logout.url=EDIT_THIS (e.g. http://localhost:8080/refset-rest/index.html)

Step 6 - Create database

Create a MySQL UTF8 database. e.g.

CREATE database refsetdb CHARACTER SET utf8 default collate utf8_unicode_ci;

Step 7 - Generate sample data

Run the admin tool for generating sample data. Here is a sample command line invocation that clears the database and indexes, then loads the sample data. It assumes the config.properties file has been properly edited as described above.

# from top-level code directory
cd admin
mvn install -PSample -Drefset.config=/home/ihtsdo/config/config.properties -Dmode=create >&! mvn.log

Following is a sample Eclipse run configuration for the same thing.

SNOMED CT Refset Management & Translation Tooling > Building and Deploying in Eclipse > image2019-5-31_9-35-50.png

Step 8 - Deploy application, Launch Server

Deploy the refset-rest.war file to a Tomcat server - either through Eclipse or a standalone tomcat installation. NOTE: It should also be deployable to a simple Jetty container as an alternative.

Setting up Tomcat in Eclipse is very easy, you follow these steps.

Download and install apache tomcat 7 (or higher) in c:/apache-tomcat-XXXX
In Eclipse use the J2EE perspective and click on the "Servers" tab.
From here, you can add a server which simply involves pointing Eclipse to the install directory for Tomcat.
You can right-click on refset-rest.war file and use "Run As->Run on Server" to deploy to Tomcat.
The Tomcat server needs to be able to find the run configuration. Double-click on the Tomcat server you installed, open the launch configuration and add this setting:
-Drefset.config=c:/refset/config/config.properties

Setting up Jetty in Eclipse is also very easy. Follow these steps:

Install the "Jetty Eclipse" plugin from the Eclipse marketplace
- http://marketplace.eclipse.org/content/eclipse-jetty
Create a "Jetty Webapp" run configuration
- Choose the "context path" (e.g. /umls-term-server).
- In the "Arguments" tab, specify your run.config.umls setting as a VM argument, e.g.:
  -Drefset.config=c:/refset/config/config.properties
Launch the run configuration to star the server.
See screenshots for Jetty/Eclipse configuration

Step 9 - Test application

Check that it all works by going to

http://localhost:8080/refset-rest/index.html

This should be a demo app that contains a basic terminology browser and (in the header) a link to a "swagger" Api documenting the service calls available. You should be able to log in to either the application or the Swagger services by authenticating with "guest" username and "guest" password.

NOTE: in the Eclipse dev environment, the swagger API does not load properly because Eclipse m2e is unable to handle the maven plugin executions that handle the interpolation of ${base.url} in the swagger files. Building and deploying the actual umls-server-rest.war file is needed for this to work properly.

Step 10 - Run the Examples

See the examples project for some sample code on using the REST APIs in a variety of different ways. You can run the examples against the standard dev database load through Maven.

cd /path/to/examples/
mvn install -DskipTests=false -Drefset.config=/path/to/config.properties

NOTE: the examples require the server to be running, they do not access the database directly.

Overview

Prerequisites

Details

References/Links