Tutorial: Hello World Java Module

2024-03-28

This tutorial shows you how to create a new Java module and deploy it to the server.

Create a Java Module

The createModule Gradle task
The Gradle task called createModule makes it easy to create a template Java module with the correct file structure and template Controller classes. We recommend using it instead of trying to copy an existing module, as renaming a module requires editing and renaming many files.

Invoke createModule

> gradlew createModule

It will prompt you for the following 5 parameters:

  1. The module name. This should be a single word (or multiple words concatenated together), for example MyModule, ProjectXAssay, etc. This is the name used in the Java code, so you should follow Java naming conventions.
  2. A directory in which to put the files.
  3. Will this module create and manage a database schema? (Y/n)
  4. Create test stubs (y/N)
  5. Create API stubs (y/N)
Enter the following parameters:

1. "JavaTutorial" 
2. "C:\dev\labkey\labkeyHome\server\modules\JavaTutorial"
3. Y
4. N
5. N

The JavaTutorial dir will be created, and the following resources added to it:

JavaTutorial
├── module.properties
├── resources
│   ├── schemas
│   │   ├── dbscripts
│   │   │   ├── postgresql
│   │   │   │   └── javatutorial-<0.00>-<currentver>.sql
│   │   │   └── sqlserver
│   │   │   └── javatutorial-<0.00>-<currentver>.sql
│   │   └── javatutorial.xml
│   └── web
└── src
└── org
└── labkey
└── JavaTutorial
├── JavaTutorialContainerListener.java
├── JavaTutorialController.java
├── JavaTutorialManager.java
├── JavaTutorialModule.java
├── JavaTutorialSchema.java
└── view
└── hello.jsp

ContainerListener class Use this to define actions on the container, such as if the container is moved.

Controller class
This is a subclass of SpringActionController that links requests from a browser to code in your application.

Manager class
In LabKey Server, the Manager classes encapsulate much of the business logic for the module. Typical examples include fetching objects from the database, inserting, updating, and deleting objects, and so forth.

Module class
This is the entry point for LabKey Server to talk to your module. Exactly one instance of this class will be instantiated. It allows your module to register providers that other modules may use.

Schema class
Schema classes provide places to hook in to the LabKey Server Table layer, which provides easy querying of the database and object-relational mapping.

Schema XML file
This provides metadata about your database tables and views. In order to pass the developer run test (DRT), you must have entries for every table and view in your database schema. To regenerate this XML file, see Modules: SQL Scripts. For more information about the DRT, see Check In to the Source Project.

web directory
All of that static web content that will be served by Tomcat should go into this directory. These items typically include things like .gif and .jpg files. The contents of this directory will be combined with the other modules' webapp content, so we recommend adding content in a subdirectory to avoid file name conflicts.

.sql files
These files are the scripts that create and update your module's database schema. They are automatically run at server startup time. See the Modules: SQL Scripts for details on how to create and modify database tables and views. LabKey Server supports these scripts in PostgreSQL and Microsoft SQL Server.

module.properties
At server startup time, LabKey Server uses this file to determine your module's name, class, and dependencies.

Build and Deploy the Java Module

1. In the root directory of the module, add a build.gradle file with this content:

apply plugin: 'java'
apply plugin: 'org.labkey.module'
Or, as of gradlePlugionsVersion 1.22.0:
plugins {
id 'org.labkey.build.module'
}

2. Add the module to your settings.gradle file:

include :server:modules:JavaTutorial

3. In IntelliJ, on the Gradle tab, sync by clicking the (Refresh) button . For details see Gradle: How to Add Modules.

4. To build the module, use the targeted Gradle task:

gradlew :server:modules:tutorial:deployModule

Or use the main deployApp target, which will rebuild all modules.

You can run these Gradle tasks via the command line, or using IntelliJ's Gradle tab.

Either task will compile your Java files and JSPs, package all code and resources into a .module file, and deploy it to your local server.

5. Enable the module in a LabKey folder. The BeginAction (the "home page" for the module) is available at:

or go to (Admin) > Go to Module > JavaTutorial

Add a Module API

A module may define its own API which is available to the implementations of other modules; the createModule task described above will offer to create the required files for you. We declined this step in the above tutorial. If you say yes to the api and test options, the following files and directories are created:

JavaTutorial
│ module.properties

├───api-src
│ └───org
│ └───labkey
│ └───api
│ └───javatutorial
├───resources
│ ├───schemas
│ │ │ javatutorial.xml
│ │ │
│ │ └───dbscripts
│ │ ├───postgresql
│ │ │ javatutorial-0.00-19.01.sql
│ │ │
│ │ └───sqlserver
│ │ javatutorial-0.00-19.01.sql
│ │
│ └───web
├───src
│ └───org
│ └───labkey
│ └───javatutorial
│ │ JavaTutorialContainerListener.java
│ │ JavaTutorialController.java
│ │ JavaTutorialManager.java
│ │ JavaTutorialModule.java
│ │ JavaTutorialSchema.java
│ │
│ └───view
│ hello.jsp

└───test
├───sampledata
└───src
└───org
└───labkey
└───test
├───components
│ └───javatutorial
│ JavaTutorialWebPart.java

├───pages
│ └───javatutorial
│ BeginPage.java

└───tests
└───javatutorial
JavaTutorialTest.java

To add an API to an existing module:

  • Create a new api-src directory in the module's root.
  • In IntelliJ, refresh the gradle settings:
    • Go to the Gradle tab
    • Find the Gradle project for your module in the listing, like ':server:modules:JavaTutorial'
    • Right click and choose Refresh Gradle project from the menu.
  • Create a new package under your api-src directory, "org.labkey.MODULENAME.api" or similar.
  • Add Java classes to the new package, and reference them from within your module.
  • Add a module dependency to any other modules that depend on your module's API.
  • Develop and test.
  • Commit your new Java source files.

Related Topic