Komet was created to harmonize existing medical terminology and create interoperable data. This file will explain best practices for getting started, building, running, and contributing code in Komet.

Install App Team

This intention of this (Komet) project is to provide a user-friendly interface that lets the user view, analyze, change, create, import and export the various medical terminologies. All the terminology changes and their relationships are saved and can be viewed historically.

1. You should have copy of a local DB available and configured. If not then please request for one.
2. Uninstall any previously installed versions of Komet.

1. To get started with installing and using Komet, browse to the available releases in GitHub. See the documentation about the new features included in each release.
2. Download the appropriate installation file for your machine (example, for Windows OS download Komet-X.X.X-Installer-Windows-Unsigned.msi).
3. Once the download is complete, run the downloaded file and install Komet.
4. Follow the (if-any) installation instructions. For Windows if you get a security alert click on "Run anyway" option.
5. Komet is now installed on your local machine. You can now run Komet from programs or installed directory.

1. Local Git repo and GitBash or similar shell-prompt installed/configured on your local machine.
2. Set up GitHub by following the instructions provided here
3. Download and install Azul's JDK Java 24 or greater latest version
4. Download and install Apache Maven 3.9.11 or greater link here
5. Prior to building Komet, there are additional repositories to clone and build. Please use the tinkar-core README file to build the tinkar-core project and its prerequisites before building komet.

1. Once you have access to komet repository on GitHub, fork the repository using instructions provided in "Fork the Repository" section in GitHub document.

2. Clone the forked Komet repository on your local machine by running the git bash command.

   git clone [email protected]:your-github-username/komet.git

3. Change the local directory location to komet

4. Enter the following command to build the application:

   ./mvnw clean install

5. Run the Komet application with the following command:

   ./mvnw -f application javafx:run

6. You can open Komet code using your favorite IDE like Eclipse or IntelliJ Idea and try running it from there. While running Komet UI from your IDE, you many have to add the following VM arguments:

   -Xmx10g --enable-native-access=org.apache.lucene.core --enable-native-access=javafx.graphics --add-exports javafx.controls/com.sun.javafx.scene.control.behavior=dev.ikm.komet.navigator --add-exports javafx.base/com.sun.javafx.event=one.jpro.platform.file --add-exports javafx.base/com.sun.javafx.event=org.controlsfx.controls
   

First ensure you have an users.ini file created containing user login information.

1. Create a file users.ini in the <user home>/Solor directory.
2. The contents are the following:

[users]
username1 = password1, role1
username2 = password2, role1, role2

Above you'll notice the username = password and remaining fields are possible roles.

After building Komet, you can run it with JPro on your local machine by following these steps:

1. Execute the following command to run the Komet application in your web browser:

   ./mvnw -f application -Pjpro jpro:run

   The default web browser should open automatically, displaying the Komet application. If it doesn't, navigate to http://localhost:8080 in your browser.
2. To stop the application, press Ctrl + C in the terminal where the application is running.
3. To rerun the application, repeat step 1.

To run Komet and all of the other tools you might need in a Docker container, follow these steps:

• Within the extracted directory, find the docker-compose.yml file.

• Start the Docker container with Docker Compose by running:

  docker compose up -d

The application should now be running in the Docker container. Access it by navigating to http://localhost in your web browser. If running on a remote server, replace localhost with the server’s IP address.

Note: On the off chance that you have issues with running on the specific port on your computer, the docker-compose file is configurable to allow for other ports. This can be run in the following way, substituting 8080 for whatever port you would like to assign:

NGINX_PORT=8080 docker compose up -d

The Komet application includes GUI tests built with the TestFX framework. By default, these tests run in headless mode, which is ideal for continuous integration (CI) environments or situations where graphical interaction is unnecessary.

1. Running TestFX Tests in Headless Mode (Default) To execute all TestFX unit tests, in headless mode (without launching a GUI window), run:

   mvn test -DrunUTestFX

2. Running TestFX Tests in Graphical Mode (Non-Headless)

   If you need to observe the GUI during testing—for instance, when debugging UI components—you can disable headless mode by setting the headless property to false. To run all tests in non-headless mode:

   mvn test -DrunUTestFX -Dtestfx.headless=false

3. Running Specific Tests

• To run a specific test class in a specific module, for example the LoginUTestFX class in the kview module:

  mvn test -pl kview -DrunUTestFX -Dtest=LoginUTestFX -Dtestfx.headless=false

• To run a specific test method inside a specific class, for example the testSuccessfulAuthentication method in the LoginUTestFX class in the kview module:

  mvn test -pl kview -DrunUTestFX -Dtest=LoginUTestFX#testSuccessfulAuthentication -Dtestfx.headless=false

In addition to unit tests, Komet includes integration tests to ensure that different components work seamlessly together.

1. Running all Integration Tests in Headless Mode (Default) To execute all TestFX integration tests use the following command:

   mvn verify -DrunITestFX

   This command triggers the verify phase in Maven, running all TestFX integration tests defined in the project. By default, TestFX integration tests run in headless mode, suitable for CI environments.

2. Running all Integration Tests in Graphical Mode If you need to observe the GUI during TestFX integration testing—for example, when debugging UI interactions—you can disable headless mode by setting the testfx.headless property to false:

   mvn verify -DrunITestFX -Dtestfx.headless=false

   This will launch the GUI windows during test execution, allowing you to visually monitor the tests as they run.

3. Running Specific Integration Tests To run a specific integration test class in a specific module, you can specify the module using the -pl parameter and the test class using the -Dit.test parameter. For example, to run the PatternWindowITestFX integration test class:

   mvn verify -pl application -DrunITestFX -Dit.test=PatternWindowITestFX

Important Note on Test Execution

• The tests will only run once after they pass successfully. To trigger the tests again, changes must be made to any part of the project.

• Adding the -Dmaven.build.cache.enabled=false parameter will disable the Maven build cache, preventing tests from being cached and reused, thus forcing fresh test execution. For example:

  mvn test -DrunUTestFX -Dmaven.build.cache.enabled=false

   mvn verify -DrunITestFX -Dmaven.build.cache.enabled=false

This section details on the basic design methodology used for developing nex-gen Komet UI.

1. Komet UI application nex-gen currently make use of the Model-View-View-Model (MVVM) design pattern. Cognitive
2. Komet application design is event-based where the subscriber to an event listens for a particular event and when it is triggered, desired logic can be executed in the listener code.

The below example does not show how to use MVVM. You can refer to the project Cognitive. The example below illustrates how to use tinkar-core library eventbus. Example:

MyController.java - A fictitious JavaFX controller responding to events being published.

    import dev.ikm.tinkar.events.EvtBus;
    import java.util.UUID;
    import javafx.scene.control.Label;
    
    public class MyController {
           
       @FXML
       Label messageLabel;
       
       @FXML
       public void initialize() {
          Subscriber<MyEvent> subscriber = evt -> {
             // a broader event type of the event type's parent
             if (evt.getEventType().getSuperType() == MyEvent.MY_ANY_EVENT) {
                System.out.println("1. Received Event Type's parent is MY_ANY_EVENT. Event type = " + evt.getEventType());
             }
             
             // Some logic to process the event.
             if (evt.getEventType() == MyEvent.SOME_EVENT_1) {
                messageLabel.setText("Some Event 1 received");
                System.out.println("2. Received Event Type's = SOME_EVENT_1");
             } else if (evt.getEventType() == MyEvent.SOME_EVENT_2) {
                System.out.println("2. Received Event Type's = SOME_EVENT_2");
                messageLabel.setText("Some Event 2 received");
             }
          };
          // Register subscriber
          EvtBus.getDefaultEvtBus().subscribe("HELLO_WORLD_TOPIC", MyEvent.class, subscriber);
       }
    }

MyEvent.java - An event object defining event types.

    public class MyEvent extends Evt {
       public static final EvtType<MyEvent> MY_ANY_EVENT = new EvtType<>(Evt.ANY, "MY_ANY_EVENT");
       public static final EvtType<MyEvent> SOME_EVENT_1 = new EvtType<>(MY_ANY_EVENT, "SOME_EVENT_1");
       public static final EvtType<MyEvent> SOME_EVENT_2 = new EvtType<>(MY_ANY_EVENT, "SOME_EVENT_2");
    
       /**
        * Constructs a prototypical Event.
        * You can optionally pass arguments in this constructor and set the value as final in the constructor.
        * The value can be retrived using the getter method for that variable.
        * @param source         the object on which the Event initially occurred
        * @param eventType
        */
       public MyEvent(Object source, EvtType eventType) {
          super(source, eventType);
       }
    }

MyEventEmitter.java - simple object that publishes an event.

    
   public class MyEventEmitter {
      private final String topic;
      public MyEventEmitter(String topic) {
         this.topic = topic;
      }
      public void messageEvent1() {
         EvtBus.getDefaultEvtBus().publish(topic, new MyEvent(this, SOME_EVENT_1));
      }
      public void messageEvent2() {
         EvtBus.getDefaultEvtBus().publish(topic, new MyEvent(this, SOME_EVENT_2));
      }
   }

Main.java

public class Main extends Application {
    
    @Override
    public void start(Stage stage) {
      FXMLLoader fxmlLoader = new FXMLLoader(HelloApplication.class.getResource("hello-view.fxml"));
      Scene scene = new Scene(fxmlLoader.load(), 320, 240);
      stage.setTitle("Event bus fun");
      stage.setScene(scene);
      stage.show();
    }

    public static void main(String[] args) {
       // Code to launch JavaFX Application.
       MyEventEmitter eventEmitter = new MyEventEmitter("HELLO_WORLD_TOPIC");
       eventEmitter.messageEvent1(); // emit some event 1
       eventEmitter.messageEvent2(); // emit some event 2
    }
}

The output to the console should be the following:

    1. Received Event Type's parent is MY_ANY_EVENT. Event type = SOME_EVENT_1
    2. Received Event Type's = SOME_EVENT_1
    1. Received Event Type's parent is MY_ANY_EVENT. Event type = SOME_EVENT_2
    2. Received Event Type's = SOME_EVENT_2

Of course if the JavaFX Application was displayed the Label's text would be set. (Warning: when updating the ui use the Platform.runLater().)

4. Komet's design also includes the cognitive framework to implement MVVM architecture framework. You can find more information along with the examples here.
   1. Gradle:

      implementation 'org.carlfx:cognitive:1.3.0'
      

   2. Maven

      <dependency>
      <groupId>org.carlfx</groupId>
      <artifactId>cognitive</artifactId>
      <version>1.6.1</version>
      </dependency>
      

   3. Project using Java Modules (JPMS) will want to do the following in the consuming module:

      requires org.carlfx.cognitive;
      

1. No specific configuration is required to run the installed version of Komet.

2. To run Komet from an IDE (development environment), you will have to do some VM Options configuration as below:

   -Xmx10g --enable-native-access=org.apache.lucene.core --enable-native-access=javafx.graphics --add-exports javafx.controls/com.sun.javafx.scene.control.behavior=dev.ikm.komet.navigator --add-exports javafx.base/com.sun.javafx.event=one.jpro.platform.file --add-exports javafx.base/com.sun.javafx.event=org.controlsfx.controls 

3. The DB needs to be configured under the 'users -> SOLAR' directory.

4. Komet requires sample data to operate with full functionality

Technical and non-technical issues can be reported to the Issue Tracker.

Contributions can be submitted via pull requests. Please check the contribution guide for more details.