Build and Installation

This document describes how to build the SureClinical desktop client from source, how the launch JAR is assembled, what runtime prerequisites are required, and how the UI integration test suite is structured.

Prerequisites

Requirement	Value
Java	Java 8 (`maven.compiler.target=1.8`)
Maven	3.x (any version supported by the parent POM plugins)
Source encoding	UTF-8
Default locale	`Locale.US` (enforced at startup via `WebLauncher` static initializer)

The parent POM (suredms-project) sets the compiler target to 1.8. The surefire plugin is configured with -Xms256m -Xmx8G -XX:+UseG1GC defaults and a Tomcat-compatible serialization filter. Java 11+ compatibility is maintained via a SubstanceLookAndFeel workaround in the UI test base class.

Module Dependency Tree

The launch assembly is owned by suredms-web-start. Its pom.xml declares the full set of runtime dependencies that get copied into the web deployment directory.

suredms-web-start
├── suredms-common
├── suredms-xls-parser
├── suredms-desktop-client-connector
├── suredms-desktop-client
├── suredms-report
├── suredms-desktop-client-quality
├── suredms-desktop-client-signing
├── suredms-workflow-platform
├── suredms-workflow-platform-core
├── org.icepdf.os:icepdf-pro
├── org.icepdf.os:icepdf-pro-intl
└── org.apache.pdfbox:jbig2-imageio

icepdf-pro and icepdf-pro-intl are the in-process PDF rendering engine (version 6.2.5-java6). The default icepdf.pro.version property is stub; only selected builds enable the full font engine.

Building the Project

All build commands run from the root SC/ directory (where the root pom.xml lives).

Signed build (production)

mvn clean
mvn install -DskipTests

mvn clean install in a single invocation is documented as not working at time of writing. Run the two phases separately.

Unsigned build

mvn clean
mvn install -DskipTests -Dskip.jar.signing

Quick test build (~15 minutes)

mvn clean install -PJenkins

Full integration test build (5+ hours)

mvn clean package -PJenkins,IntegrationTests

Running a single integration test

mvn -Dtest=CmisClientIntegrationTest -PSonar,IntegrationTests,Jenkins test

License check

mvn clean verify -PLicenseCheck -DskipTests

License and dependency check

mvn clean verify -PLicenseCheck,DependencyCheck,Jenkins -DskipTests

Update file headers

# suredms-web is excluded due to a known plugin error in that module
mvn clean verify -PUpdateHeaders,Jenkins,CustomerData -DskipTests -pl !suredms-web

Deployment Output

During the verify phase, the maven-dependency-plugin copies all non-test JARs from suredms-web-start and its transitive runtime dependencies into:

suredms-web/target/SureClinical/

This directory is the deployment root for the Nuxeo/Java Web Start delivery, as controlled by the suredms.contextPath property (SureClinical by default).

The maven-jar-plugin sets the assembled JAR's manifest Main-Class to:

com.sureclinical.suredms.WebLauncher

Launch Path

The entry point for the desktop application is WebLauncher.main() in the suredms-web-start module.

com.sureclinical.suredms.WebLauncher
  └── extends BaseLauncher (suredms-desktop-client)
        └── creates WebEntryPoint (via createEntryPoint())

com.sureclinical.suredms.WebEntryPoint
  └── extends BaseEntryPoint (suredms-desktop-client)
        └── init() calls DesktopClient.launch(DesktopClientEditor.class, args)

`WebLauncher`

Located at: suredms-web-start/src/main/java/com/sureclinical/suredms/WebLauncher.java

public class WebLauncher extends BaseLauncher {
    static {
        // Enforces US locale for number/date formatting — SURE-355
        Locale.setDefault(Locale.US);
    }

    public static void main(String[] args) {
        new WebLauncher(args);
    }

    @Override
    protected JApplet createEntryPoint(Map<String, String> parameters) {
        return new WebEntryPoint(parameters);
    }
}

The static initializer runs before any UI or service code. The Locale.US default prevents locale-specific number parsing errors in Nuxeo XML responses (tracked as SURE-355).

`WebEntryPoint`

Located at: suredms-web-start/src/main/java/com/sureclinical/suredms/WebEntryPoint.java

@Override
public void init() {
    setInstance(this);
    super.init();
    DesktopClient.launch(DesktopClientEditor.class, new String[]{});
}

BaseEntryPoint.init() configures service host, authentication, and connection parameters before calling DesktopClient.launch(). After launch() returns, the BSAF application lifecycle takes over: it creates the DesktopClientEditor (a SingleFrameApplication) and shows the main window.

Runtime defaults

The BaseEntryPoint singleton defaults:

Parameter	Default
`serviceHost`	`http://127.0.0.1:8080`
`servicePath`	`/nuxeo/site/automation-ext`
Max open archives	5 (`MAX_NUMBER_OF_ACTIVE_ARCHIVES`)

These defaults apply when no launch parameters are passed — for example, during local development or test mode.

Local Development Quickstart

This section gives a single reproducible path for building and running the client locally for iterative development — no integration test build required.

Prerequisites checklist

Java 8 JDK on PATH and JAVA_HOME set
Maven 3.x on PATH
A local Nuxeo server running at http://127.0.0.1:8080 (default serviceHost)
Maven can resolve all dependencies (local .m2 cache or a reachable artifact repository)

Step 1 — Build (from `SC/`)

mvn clean
mvn install -DskipTests

Run the two phases separately. A single mvn clean install is documented as not working reliably. The unsigned build flag (-Dskip.jar.signing) is recommended for local dev:

mvn clean
mvn install -DskipTests -Dskip.jar.signing

Output lands in suredms-web/target/SureClinical/ — this directory contains all runtime JARs.

Step 2 — Run

The desktop client is launched by WebLauncher.main(). To run without a JNLP deployment, launch the class directly from an IDE or using the assembled classpath:

From an IDE (recommended):

Open the suredms-web-start module.
Set the run configuration main class to com.sureclinical.suredms.WebLauncher.
Apply the VM arguments below and run.

From the command line:

java -cp "suredms-web/target/SureClinical/*" com.sureclinical.suredms.WebLauncher

Recommended debug VM arguments

-Xms256m
-Xmx2G
-XX:+UseG1GC
-ea
-Dfile.encoding=UTF-8
-Duser.language=en
-Duser.country=US

Use -Xmx4G or higher if working with large archives or running multiple concurrent connections.

Step 3 — Connect to Nuxeo

The default serviceHost is http://127.0.0.1:8080 and servicePath is /nuxeo/site/automation-ext. No arguments are required if your Nuxeo server listens at those defaults. To override, pass launch parameters:

-DserviceHost=http://your-nuxeo-host:8080
-DservicePath=/nuxeo/site/automation-ext

Common failure signatures

Symptom	Likely cause	Fix
`ClassNotFoundException: com.sun.awt.AWTUtilities$Translucency`	Running on Java 11+ without the Substance LAF workaround	Ensure `SubstanceLookAndFeel.WINDOW_ROUNDED_CORNERS_PROPERTY = false` is set, or run on Java 8
`NumberFormatException` parsing XML responses	Default JVM locale is not `en_US`	Add `-Duser.language=en -Duser.country=US` to VM args
`iText license key missing`	License resource not on classpath	Ensure the iText license file is in the expected classpath location
Connection refused to `127.0.0.1:8080`	Nuxeo server is not running	Start Nuxeo before launching the desktop client
`OutOfMemoryError` after opening multiple archives	`MAX_NUMBER_OF_ACTIVE_ARCHIVES` (5) exceeded or heap too small	Increase `-Xmx` or close archives before opening new ones
Test build fails with `PrivateConstructorTest`	A utility class gained a public constructor	Add `private` no-arg constructor to the offending class

Build Feature Flags

The parent POM defines Maven properties that control product variants compiled into each build:

Property	Default	Purpose
`project.build.preview`	`false`	Enables preview/beta features
`project.build.mobile-application`	`false`	Mobile application variant
`project.build.test-mode`	`false`	Test mode build
`project.build.shared`	`false`	Shared (multi-tenant) mode
`project.build.multi-tenant`	`false`	Multi-tenant mode
`project.build.application.ETMF`	`false`	SureETMF application
`project.build.application.EISF`	`false`	EISF application
`project.build.application.CTMS`	`false`	SureCTMS application
`project.build.application.QMS`	`false`	QMS application

Brand identity (title, icons, colours, domain, logo) is also injected at build time via project.brand.* properties defined in suredms-project/pom.xml.

Key Third-Party Library Versions

These versions are managed in suredms-project/pom.xml and apply across all modules:

Library	Managed Version	Role in desktop client
BSAF	1.9.2	Application framework (`org.jdesktop.application.Application`)
IcePDF (core)	6.2.5-20220318	In-process PDF rendering
IcePDF (pro)	`stub` (or `6.2.5-java6`)	Font engine (client-specific)
Bibliothek DockingFrames	1.1.2p14	Gadget docking layout
dom4j	2.1.4	XML parsing in connector module
Guava	33.3.1-jre	Caching (`LoadingCache` in signing module)
OWL API + HermiT	1.3.6	OWL content model import (alternative format)
dcm4che	3.3.5	DICOM / medical imaging support
Bouncy Castle	1.79	Cryptographic operations in signing
DSS	5.13	Digital signature standards
Camunda BPM	7.19.0	Workflow process engine (last Java 8 version)

UI Integration Test Infrastructure

UI integration tests live in:

suredms-web-start/src/test/java/com/sureclinical/suredms/ui/test/

Test classes

Test class	Coverage area
`BaseWebStartUiIntegrationTest`	Abstract base class; initialises `XmlDemoEndPoints`, sets Substance LAF workaround
`UiInitIntegrationTest`	Core application startup
`UiInit2IntegrationTest`	Secondary launch scenarios
`DesktopClientUiIntegrationTest`	`DesktopClient` view and state
`DialogUiIntegrationTest` (Parts 1–7)	Modal dialog rendering
`GadgetUiIntegrationTest`	Home view gadget initialisation
`GadgetDocNavIntegrationTest`	Document navigator gadget
`GadgetIcePdfViewerIntegrationTest`	IcePDF viewer gadget
`QualityUiIntegrationTest`	Quality review flows
`UploadWizardBuilderUiIntegrationTest`	Upload wizard
`WorkflowWizardBuilderUiIntegrationTest`	Workflow wizard
`SignLocalFileWizardBuilderUiIntegrationTest`	Sign local file wizard
`RequiredDocumentWizardBuilderUiIntegrationTest`	Required document wizard
`UploadMedicalImageBuilderUiIntegrationTest`	Medical imaging upload wizard
`MedicalImageDirectoryViewerDialogUiIntegrationTest`	DICOM directory viewer
`ModuleUiIntegrationTest`	Module loading
`ContentModelPopupMenuHandlerUiIntegrationTest`	Content model popup menu
`LinkMetadataTermUiIntegrationTest`	Metadata term linking
`DocumentNavigatorUtilsUiIntegrationTest`	Navigator utility functions
`BarcodeDetectUiIntegrationTest`	Barcode detection/acquisition
`ArchiveParserTest`	Archive parsing (non-UI)
`QuickFindTest`	Quick find functionality
`WebStartUiThreadIntegrationTest`	EDT threading safety
`PrivateConstructorTest`	Ensures utility classes have private constructors
`CountryCodeProviderTest`	Country code lookup
`ModelTest`	Entity model validation
`PdfThumbnailUiIntegrationTest`	PDF thumbnail generation
`UploadFileServiceUiIntegrationTest`	File upload service

Base class mechanics

BaseWebStartUiIntegrationTest provides:

XmlDemoEndPoints: Created via Init.initLocalTestMode(). This is an XML-backed stub implementation of the endpoint interfaces that replaces live Nuxeo calls with local XML fixtures — allowing full UI tests without a running server.
JUnit Timeout rule: 5 minutes per test method, enforced via @Rule public Timeout globalTimeout.
Substance LAF workaround: Sets SubstanceLookAndFeel.WINDOW_ROUNDED_CORNERS_PROPERTY = false to avoid a ClassNotFoundException for com.sun.awt.AWTUtilities$Translucency on Java 11+.
testWizard(WizardBuilder, mode, step): Helper forwarding to TestUtils.testWizard() for exercising wizard flows.
Temp file cleanup: @AfterClass calls FileUtils.deleteTempFiles() to clean up test fixtures.
@Before initDataSource(): Applies the DeploymentUtils.applySubstanceFix() workaround on each test run.

Test profiles

Maven profile	Purpose
`-PJenkins`	Fast CI build including unit tests (~15 minutes)
`-PJenkins,IntegrationTests`	Full test suite including UI tests (5+ hours)

Prerequisites​

Module Dependency Tree​

Building the Project​

Signed build (production)​

Unsigned build​

Quick test build (~15 minutes)​

Full integration test build (5+ hours)​

Running a single integration test​

License check​

License and dependency check​

Update file headers​

Deployment Output​

Launch Path​

WebLauncher​

WebEntryPoint​

Runtime defaults​

Local Development Quickstart​

Prerequisites checklist​

Step 1 — Build (from SC/)​

Step 2 — Run​

Recommended debug VM arguments​

Step 3 — Connect to Nuxeo​

Common failure signatures​

Build Feature Flags​

Key Third-Party Library Versions​

UI Integration Test Infrastructure​

Test classes​

Base class mechanics​

Test profiles​