Creating a New Java Module: /Documentation/Archive/17.3

Creating a New 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.

When you invoke createModule, it will prompt you for two things:

The module name. This should be a single word (or multiple words concatenated together), for example MyModule, ProjectXAssay, etc.
A directory in which to put the files.

Example. Following the conventions used in the existing modules, entering:

"Test"
"C:\labkey\server\localModules\Test"

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

C:\labkey\server\localModules\Test
│   module.properties
│   Test.iml
│
├───lib
├───resources
│   ├───schemas
│   │   │   test.xml
│   │   │
│   │   └───dbscripts
│   │       ├───postgresql
│   │       │       test-XX.XX-YY.YY.sql 
│   │       │
│   │       └───sqlserver
│   │               test-XX.XX-YY.YY.sql
│   │
│   └───web
└───src
    └───org
        └───labkey
            └───test
                │   TestContainerListener.java
                │   TestController.java
                │   TestManager.java
                │   TestModule.java
                │   TestSchema.java
                │
                └───view
                        hello.jsp

IntelliJ .iml file
If you are using IntelliJ, you can import MyModule.iml as an IntelliJ module to add your LabKey Server module to the IntelliJ project.

lib directory
JAR files required by your module but not already part of the LabKey Server distribution can be added to the ./lib directory. At compile time and run time, they will be visible to your module but not to the rest of the system. This means that different modules may use different versions of library JAR files.

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: Database Transition Scripts. For more information about the DRT, see Check in to the Source Project.

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

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 currently supports Postgres and Microsoft SQL Server.

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

Deploy the Java Module

The main build target will build and deploy your custom module, assuming its source directory is referenced in the "standard.modules" file (either explicitly or implicitly via wildcards). The main build will compile your Java files and JSPs, package all code and resources into a .module file, and deploy it to the server.

Add a Module API

A module may define its own API which is available to the implementations of other modules. To add an API to an existing module:

Create a new api-src directory in the module's root.
In IntelliJ, File->New Module. Choose Java as the module type. Call it MODULENAME-API, make the module's api-src directory the content root, and use the root of the module as the module file location.
In IntelliJ, File->Project Structure. Select your new API module from the list. In the Sources tab, remove the "src" directory as a source root, and make the api-src directory as a source root. In the Dependencies tab, add a Module Dependency on the "Internal" module and check the box to Export it. Find your original module from the list. Remove the dependency on the Internal module, and add a Module Dependency on your new API module.
Remove the "src" directory under the api-src directory.
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, the new .IML file, any .IML files for existing modules that you changed, and the reference to your new .IML API in LabKey.ipr.

LabKey Support

LabKey Support