Desktop Connector and Nuxeo Bridge

Module: suredms-desktop-client-connector
Source root: SC/suredms-desktop-client-connector/src/main/java/com/sureclinical/suredms/

This module is the exclusive communication bridge between the desktop shell and all data backends. It owns the endpoint factory, XML local archive parsing, Nuxeo Automation API transport, a connection pool, and all client-side notification services.

Purpose

suredms-desktop-client-connector ensures the rest of the desktop application can operate identically regardless of whether it is connected to a live Nuxeo server, reading a local XML archive, or running against demo data. The endpoint factory abstracts this behind the IEndPoints interface. Callers in the shell and quality modules interact exclusively with EndPoints.getCurrentEndPoints() — they never reference a transport class directly.

Package Structure

Package	Contents
com.sureclinical.suredms.endpoints	EndPoints, EndPointsProxy, EndpointController, IEndPoints, DocumentProxy, DocumentUpdater
com.sureclinical.suredms.xml	XMLParser, ArchiveCollector, ArchiveCtx, XMLEndPoints, XmlDemoEndPoints, SAVEParser, XmlUsersParser, XmlNewsParser, ClientXmlExporter, ClientDBExporter
com.sureclinical.suredms.nuxeo	NuxeoEndPoints, NuxeoClient (interface), NuxeoClientPool, NuxeoDocument, NuxeoAuth, NuxeoUserManager, client services
com.sureclinical.suredms.nuxeo.client	NuxeoClientImpl, SureConnector, SureOperationRequest
com.sureclinical.suredms.nuxeo.exceptions	Typed remote exceptions
com.sureclinical.suredms.search	RemoteClientQuery pattern types
com.sureclinical.suredms.services	Connector-side services: UserActionClientService, TrainingCertificateClientService, EmailReminderClientService, ExpiredDocumentNotificationClientService, DocumentUploadNotificationClientService

Endpoint System

EndPoints (factory)

SC/suredms-desktop-client-connector/src/main/java/com/sureclinical/suredms/endpoints/EndPoints.java

Static factory and registry. Key methods:

Method	Description
getCurrentEndPoints()	Returns the EndPointsProxy singleton (created on first call)
addEndPoints(IEndPoints)	Registers an endpoint into the proxy
createEndPoints(EndPointsType)	Creates a concrete endpoint for the given type
createRemoteEndPoints(String baseURL)	Instantiates and opens a NuxeoEndPoints
createLocalEndPoints(File[])	Creates an XMLEndPoints over a set of root folders

createEndPoints(EndPointsType) dispatches by type:

• EP_LOCAL — splits the root folder path on File.pathSeparator, creates XMLEndPoints.
• EP_REMOTE — creates a NuxeoEndPoints and calls open(baseURL).
• EP_DEMO — creates an XmlDemoEndPoints.

EndPointsProxy

SC/suredms-desktop-client-connector/src/main/java/com/sureclinical/suredms/endpoints/EndPointsProxy.java

Implements IEndPoints. Can hold multiple endpoint registrations simultaneously (e.g., a remote Nuxeo archive alongside a local XML archive).

Key behavior:

• Delegates getAuthSvc() to the primary (first registered) endpoint.
• getDocSvc() returns a DocumentProxy that multiplexes across all registered IDocument instances.
• getPrimaryEndPoints() returns the first registered endpoint.
• getAllEndPoints() returns a defensive copy of all registered endpoints.
• detach(Archive) removes an archive from the DocumentProxy when it is closed.
• getEndPointsType() returns the primary endpoint's type.

IEndPoints (interface)

Contracts:

• getAuthSvc() → IAuth for authentication
• getDocSvc() → IDocument for all document CRUD operations
• getEndPointsType() → EndPointsType enum (EP_LOCAL, EP_REMOTE, EP_DEMO)
• close() → resource cleanup

EndpointController (interface)

SC/suredms-desktop-client-connector/src/main/java/com/sureclinical/suredms/endpoints/EndpointController.java

A secondary interface for background update management:

• setUpdaterThreadPaused(boolean) — suspends the background update poller.
• prefetchArchive(Archive) — pre-loads archive data before the user navigates to it.
• loadUpdates(NuxeoClient) — triggers a pull of changed documents from the server.

XML Parsing (Local Mode)

XMLParser

SC/suredms-desktop-client-connector/src/main/java/com/sureclinical/suredms/xml/XMLParser.java

Extends BaseXmlParser<ArchiveCtx, BaseEntity, ...> and implements the ArchiveParser interface.

Parses standard XML attributes on every entity element via parseCommonMetadata(Element, BaseEntity):

XML Attribute	Entity Field
XML_ATTR_NUXEO_PATH	entity.setPath(...)
XML_ATTR_NUXEO_CREATOR	entity.setDcCreator(...)
XML_ATTR_NUXEO_CREATED	entity.setDcCreated(...)
XML_ATTR_NUXEO_MODIFIED	entity.setDcModified(...)
XML_ATTR_NUXEO_ID	entity.setExternalId(...)

Entity-specific parsing:

• parseEntityDataProperties(Element, Document) — iterates <datapropValues> / <datapropValue> elements, matches property IDs to DataPropertyDefCtx objects, and adds FormField entries to the DocForm.
• Entities with the ILabel interface also have their label attribute read via XML_ATTR_SHORT_LABEL.
• Date strings are parsed via DateUtils.fromXMLString(String).

XMLParser is stateful per parse session. Create a new instance for each archive load; do not share instances across threads.

Supporting XML Classes

Class	Purpose
ArchiveCtx	Parsing context holding the active archive, content type defs, data property defs, and annotation defs
ArchiveCollector	Traverses archive roots and collects the full object graph
ArchiveParsingResultCtx	Holds the result of a complete archive parse
TFileArchive	Represents a local-file-backed archive (SAVE format)
TPortfolioArchive	Represents a portfolio-style local archive
SAVEParser	Parses .save format archives
XmlUsersParser	Parses the users XML export file
XmlNewsParser	Parses the news/articles XML feed
ClientXmlExporter	Generates XML export files from in-memory entities
ClientDBExporter	Export path for database-backed archives
XmlDemoEndPoints	Demo endpoint backed by bundled XML data

Nuxeo Transport (Remote Mode)

NuxeoClient (interface)

SC/suredms-desktop-client-connector/src/main/java/com/sureclinical/suredms/nuxeo/NuxeoClient.java

The comprehensive remote API contract. Key method groups:

Group	Methods
Query	queryDocs(docType), queryDocs(docType, condition), queryDocById(id), executeDocumentQuery(query)
Entity load	loadEntities(docType), loadEntities(docType, prefix, archives), loadEntities(Documents), reloadEntities, loadEntitiesWithoutCaching
CRUD	createOrUpdateEntity(entity), createOrUpdateEntity(entity, parent, deepSave, forceSave), deleteEntity(entity), updateEntityNow(entity)
File I/O	uploadFile(entity, file), downloadFile(entity), downloadAdditionalFiles(entity)
Lifecycle	isDocumentAlive(Collection), loadUpdatedDocuments(since), isOnline(), shutdown()
Identity	getInstanceId()

All methods that perform remote calls throw org.nuxeo.ecm.automation.client.jaxrs.RemoteException.

NuxeoEndPoints

SC/suredms-desktop-client-connector/src/main/java/com/sureclinical/suredms/nuxeo/NuxeoEndPoints.java

Implements IEndPoints for remote mode:

• Holds an HttpAutomationClient (Nuxeo's JAX-RS client) and a static NuxeoAuth singleton.
• open(baseURL) stores the base URL; the HTTP client is created lazily.
• getAuthSvc() returns (or creates) a NuxeoAuth instance for the configured URL; if the URL changes a new NuxeoAuth is created.
• getDocSvc() creates a NuxeoDocument instance lazily.
• close() shuts down the HTTP client and resets NuxeoAuth.

NuxeoClientPool

Manages a pool of NuxeoClientImpl instances with a configurable maximum parallel thread count (key: com.sureclinical.suredms,client.parallel.maxNumberOfThreads).

Provides two execution patterns:

• executeSilentQuery(RemoteClientQuery) — fire-and-forget; swallows RemoteException to a log warning.
• executeSilentRequest(RemoteClientRequest<T>) — returns a result or a provided default on failure.

Client Notification Services

Located in com.sureclinical.suredms.nuxeo and com.sureclinical.suredms.services:

Service	Purpose
UserActionClientService	Records user actions server-side for audit trail
ExportUserActionClientService	Records export actions
TrainingCertificateClientService	Fetches training certificate status
EmailReminderClientService	Triggers email reminders for overdue documents
ExpiredDocumentNotificationClientService	Pushes expired-document notifications
DocumentUploadNotificationClientService	Notifies server of completed uploads
NotificationClientService	General notification dispatch
ArchiveVisibilityProvider	Supplies archive-level visibility rules to the connector

Endpoint Selection Flow

Login dialog → DesktopClient.getInstance()
  │
  └── EndPoints.createEndPoints(EndPointsType)
        ├── EP_LOCAL
        │     └── XMLEndPoints(File[])
        │           └── XMLParser → ArchiveCtx → entities
        │
        ├── EP_REMOTE
        │     └── NuxeoEndPoints.open(baseURL)
        │           ├── NuxeoAuth (authentication)
        │           └── NuxeoDocument → NuxeoClientImpl
        │
        └── EP_DEMO
              └── XmlDemoEndPoints (bundled sample data)

  └── EndPoints.addEndPoints(endpoint)
        └── EndPointsProxy.addEndPoint(endpoint)
              └── DocumentProxy.addIDocument(endpoint.getDocSvc())

Dependencies

Module	Role
suredms-desktop-client-data	All entity types populated by XMLParser and NuxeoClientImpl
suredms-nuxeo-client	Shared Nuxeo API abstractions (Session, RemoteException, model classes)
suredms-parser	ArchiveParser interface implemented by XMLParser

Constraints and Notes

• The EndPointsProxy is a singleton held in EndPoints.defaultEndPoints. It is re-created on each logout/login cycle by clearing and re-initializing the field.
• NuxeoAuth is held as a static field on NuxeoEndPoints and is reset when the endpoint closes. This means the authentication session is application-level, not per-archive.
• XMLParser depends on ArchiveCtx being fully populated before parseEntityDataProperties is called; content type and data property definitions must be parsed before documents.
• NuxeoClientPool parallelism is bounded by the MAX_PARALLEL_THREADS_KEY system property.
• The RemoteClientQuery / RemoteClientRequest patterns ensure Nuxeo connection errors are handled consistently without each caller needing try/catch logic.

Authentication Client Details

For detailed documentation of SureConnector, BasicAuthAutomationClient, FormAuthAutomationClient, and NuxeoClientBuilder (including the two-phase form auth flow, credential caching, and PkAuth-based password derivation), see Data Access Layer — Authentication Clients.

Endpoint Interface Layer

The full endpoint interface hierarchy (IEndPoints, IAuth, IDocument, EndPointsType, FetchMode, EndPointListener, TimedReloadService, EndPointParameters) is defined in suredms-desktop-client-data and documented in Data Access Layer — Endpoint Interface Hierarchy.

OWL / Ontology Integration (GAP-07 / XGAP-03)

Package: com.sureclinical.suredms.owl
Source: SC/suredms-desktop-client-connector/src/main/java/com/sureclinical/suredms/owl/

The OWL package supports import and export of SureDMS content models as OWL ontologies. This allows clinical terminology standards to be imported as archive content models (categories, content types, and metadata property definitions).

Key Classes

Class	Role
OntologyParser	Maps OWL classes → ContentType, CloudFolder, Category; maps OWL data properties → DataPropertyDef; produces an ArchiveCtx aggregator
OntologyExporter	Exports the current archive content model as an OWL ontology
OwlManager	Static utility for loading an OWLOntology from a File, URL, or InputStream
OWLParser	Low-level OWL element parser
BaseOntologyParser	Abstract base class for OntologyParser

Parser Flow

OntologyParser extends BaseOntologyParser and produces an ArchiveCtx from an input OWL ontology:

1. Load OWLOntology via OwlManager.loadOntology(source).
2. Iterate OWL classes: each class becomes a ContentType, CloudFolder, or Category in the SureDMS model.
3. Iterate OWL data properties: each becomes a DataPropertyDef with type and constraints.
4. Construct the ArchiveCtx aggregator holding all parsed entities.

Tests

Test	File
OntologyParserTest	SC/suredms-desktop-client-connector/src/test/java/com/sureclinical/suredms/owl/OntologyParserTest.java
OntologyExporterTest	SC/suredms-desktop-client-connector/src/test/java/com/sureclinical/suredms/owl/OntologyExporterTest.java
OwlParserExporterTest	SC/suredms-desktop-client-connector/src/test/java/com/sureclinical/suredms/cli/test/OwlParserExporterTest.java — round-trip test

---

Search Package (XGAP-03)

Package: com.sureclinical.suredms.search
Source: SC/suredms-desktop-client-connector/src/main/java/com/sureclinical/suredms/search/

The search package implements a provider-based search engine for cross-archive document search.

SearchEngine

SearchEngine is the top-level coordinator. It maintains a list of registered SearchResultsProvider instances and aggregates their results.

Method	Description
addSearchProvider(SearchResultsProvider)	Registers a provider (e.g. NuxeoSearchProvider)
searchAll(String phrase, boolean localOnly)	Executes search across all registered providers; returns List<BasicSearchResult>
filterDocuments()	Filters results against the active endpoint set

The shell module uses SearchEngineWrapper to wrap SearchEngine with additional state management.

NuxeoSearchProvider

Default search provider. Forwards the query to the Nuxeo full-text search index and maps Nuxeo document results to BasicSearchResult objects.

Key Classes

Class	Role
SearchEngine	Provider registry and aggregator
SearchEngineState	Tracks search state (in-progress, results, error)
NuxeoSearchProvider	Nuxeo-backed search implementation
SearchResultsProvider	Interface for search providers
BasicSearchResult	Value object: document ID, name, archive, and relevance data
SearchResultVisibilityServiceImpl	Filters search results based on user visibility / blinding rules