Desktop Client Data Model

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

This module defines the shared domain entity hierarchy for all desktop client modules. It provides plain Java (POJO) representations of every clinical data concept — archives, documents, users, persons, organizations, content types, metadata, annotations, discrepancies, and forms. It has no framework annotations, no UI components, and no network logic.

Purpose

suredms-desktop-client-data is the leaf dependency of the desktop module graph. Every other desktop module imports it. The connector module populates entity instances by reading XML (local mode) or deserializing Nuxeo API responses (remote mode). The shell and quality modules consume those instances to build the UI.

Package Structure

Package	Contents
com.sureclinical.suredms.entity	40+ entity classes and interfaces
com.sureclinical.suredms.common	Shared enums, flags, constants, and utility types
com.sureclinical.suredms.endpoints	IEndPoints interface referenced by Archive
com.sureclinical.suredms.util	Entity utility helpers

Entity Hierarchy

IBaseEntity
  └── BaseEntity (abstract)
        └── TaxonEntity (abstract)
              ├── Archive
              │     ├── CloudArchive
              │     ├── ImagingArchive
              │     └── QualityArchive
              ├── Document
              ├── Category / ContentType
              ├── Person
              ├── Organization
              ├── PersonRole / OrganizationRole
              ├── User
              ├── DocDiscrepancy
              ├── Audit
              └── NewsItem

Core Entity Reference

BaseEntity

SC/suredms-desktop-client-data/src/main/java/com/sureclinical/suredms/entity/BaseEntity.java

Abstract root of all entities. Implements IBaseEntity, Comparable<BaseEntity>, and EditableEntity.

Internal infrastructure:

• OBJECT_FACTORIES: Map<String, EntFactory> — registry mapping Nuxeo document type strings to entity constructors. Populated by each entity's static register() block.
• LOADED_OBJECTS: Map<String, BaseEntity> — concurrent cache of all live entities by external ID.
• instanceId — monotonically incrementing AtomicLong used by LeakDetector.

Key fields:

Field	Type	Purpose
entType	String	Nuxeo document type (e.g., "SureDocs_Archive")
dbDoc	org.nuxeo.ecm.automation.client.jaxrs.model.Document	Raw Nuxeo document; null in local mode
dcModified	EDate	DublinCore last-modified date
dcCreated	EDate	DublinCore creation date
dcCreator	String	Username of creator
path	String	Nuxeo repository path
isDetached	boolean	Entity removed from active graph; updates ignored
isModified	boolean	Dirty flag for deferred sync

All entities have a BaseEntity.save(Session) method that writes changes back to Nuxeo in remote mode.

Archive

SC/suredms-desktop-client-data/src/main/java/com/sureclinical/suredms/entity/Archive.java

Extends TaxonEntity. Represents one SureDrive or study container.

Key fields:

Field	Type	Purpose
identifier	String	Internal archive ID
name	String	Display name
duplicationPolicy	DuplicationPolicy	Controls duplicate document behavior
contentModelVersion	ContentModelVersion	CUSTOM by default
contentModelName	String	Named content model
contentModelDate	Date	Last content model update
numberingScheme	NumberingScheme	Document numbering policy
prefetched	boolean	Whether data has been loaded ahead of display
deleted	boolean	Soft-delete flag
locked	boolean	Archive locked from edits
lock	ArchiveLock	Lock metadata (who locked, when)
isSelected	boolean	Whether archive is active in the navigator
copyIndex	int	Appended to name when > 0 to indicate a copied archive
endPoints	IEndPoints	Endpoint reference scoped to this archive
dataLoadingLock	ReentrantLock	Guards concurrent data-load operations

Archive.getName() returns identifier when name == null; appends " Copy N" when copyIndex > 0.

Subtypes: CloudArchive, ImagingArchive, QualityArchive.

Document

SC/suredms-desktop-client-data/src/main/java/com/sureclinical/suredms/entity/Document.java

Extends TaxonEntity. Implements ExtensibleEntity and EditableDocumentEntity. The central clinical document entity.

Key fields:

Field	Type	Purpose
archive	Archive	Owning archive
name	String	Document title
suffix	String	File extension
contentType	ContentType	Folder/section assignment
organization	Organization	Associated organization
person	Person	Associated investigator/person
version	long	Version number
form	DocForm	Custom metadata form
numberOfPages	int	Page count for PDF documents
documentType	DocumentType	DT_DOCUMENT by default
annotations	AnnotationForm	Free-form annotations
sourceDocumentId	String	Original document ID if derived
signature	int	Signature count
signedBy	String	Signer username
signatureDate	Date	Signing date
signatureType	PdfSignatureType	NO_SIGNATURE by default
certificationType	CertificationLevel	NOT_CERTIFIED by default
remoteUrl	String	URL if stored externally
obsolete	boolean	Marked obsolete
documentLocked	boolean	Lock from edits
stickyNotes	boolean	PDF sticky note annotations present
freeTextAnnotations	boolean	PDF free-text annotations present
draft	boolean	Draft state flag
survey	boolean	Survey document flag
siteDocument	boolean	Site-level document flag
reportArchiveIds	List<String>	Archives this report document is linked to
controlled	ControlledType	Controlled document classification
training	TrainingType	Training classification
documentStatus	DocumentLifeCycleStatus	Lifecycle state
reviewed	Date	Review date
approved	Date	Approval date
effective	Date	Effective date
periodicReview	Date	Next periodic review date
documentNumber	String	Assigned document number
DCR	String	Document change request reference

Static constants for original document type: ORIGINAL_DOC_PDF = "PDF", ORIGINAL_DOC_PDF_IMAGE = "PDF Image".

User

SC/suredms-desktop-client-data/src/main/java/com/sureclinical/suredms/entity/User.java

Extends BaseEntity. Implements ArchiveAclUserGroup. Represents the authenticated desktop session user.

Key fields:

Field	Type	Purpose
loginName	String	Username
loginPassword	String	Hashed/stored password (not shown in UI)
firstName / lastName / middleName	String	Name components
fullName	String	Pre-composed display name
legalSigningName	String	Name used on signature blocks
jobTitle	String	Role title
groupsList	PropertyList	Nuxeo group memberships

Nuxeo property key constants used during save/load:

• user:active — whether the account is enabled
• user:verified — email/identity verified
• user:signer — user is authorized to sign documents (isRemoteSigner() checks this)
• user:loginEmailSent — login invitation sent
• user:external — externally managed user

User.isRemoteSigner() is the primary check used by ESignServiceProxy to set remoteEnabled.

DocDiscrepancy

SC/suredms-desktop-client-data/src/main/java/com/sureclinical/suredms/entity/DocDiscrepancy.java

Extends TaxonEntity. Represents a quality issue on a document.

Key fields:

Field	Type	Default
itemNumber	Long	Sequential QC item number
archive	Archive	Owning archive
discrepancyType	DiscrepancyType	DT_DOCUMENT_AND_METADATA_ERROR
docDiscrepancyType	DocDiscrepancyType	Sub-classification
resolved	EDate	Resolution date
reportedBy	String	Username of reporter
resolvedBy	String	Username of resolver
comment	String	Description of the issue
document	Document	The document under review
discrepancyContent	String	Specific content reference
discrepancyStatus	DiscrepancyStatus	Open / resolved / waived
assignedTo	String	Assigned reviewer username
assignedToComment	String	Assignment note
reminderType	EmailReminderType	Reminder schedule

Standard key constants used in the discrepancy form fields: DISCR_KEY_ARCHIVE, DISCR_KEY_CONTENT_TYPE, DISCR_KEY_ORGANIZATION, DISCR_KEY_PERSON, DISCR_KEY_MANUAL_VERSION, DISCR_KEY_PAGE_TEMPLATE (= "Page_%d").

ContentType

SC/suredms-desktop-client-data/src/main/java/com/sureclinical/suredms/entity/ContentType.java

Extends TaxonEntity. Implements IHierarchicalEntity, ILabel, EditableContentTypeEntity.

Key fields:

Field	Type	Purpose
archive	Archive	Owning archive
parent	IHierarchicalEntity	Parent folder in the content model tree
id	long	Numeric ID within the content model
name	String	Internal name
label	String	Display label
reserved	boolean	System-reserved — cannot be deleted (sdms_contenttype:reserved)
required	boolean	Must have at least one document (sdms_contenttype:required)
locked	boolean	Changes locked
metadataAssociations	List<MetadataAssociation>	Linked metadata term definitions
metadataType	MetadataType	MT_CORE by default
manualVersioning	boolean	Read-only; set by server

Person

SC/suredms-desktop-client-data/src/main/java/com/sureclinical/suredms/entity/Person.java

Extends TaxonEntity. Implements ExtensibleEntity, IContactEntity, ILabel, EditablePersonEntity.

Stores investigator and team member identity: firstName, lastName, middleName, fullName, credential, title, email, address1/2, city, state, postalCode, countryCode, phone, fax, mobile, esig (e-signature string), inactive. Contact date range tracked via DATE_ACTIVE_PROPERTY and DATE_INACTIVE_PROPERTY.

Full Entity Inventory

All entity types registered via static register() blocks:

Entity Class	Nuxeo Type	Purpose
Archive	SureDocs_Archive	SureDrive / study container
Document	SureDocs_Document	Clinical document
ContentType	SureDocs_ContentType	Folder in the content model
Category	sdms_category	Grouping category
Person	SureDocs_Person	Investigator or team member
PersonRole	SureDocs_PersonRole	Person's role definition
Organization	SureDocs_Organization	Site or sponsor org
OrganizationRole	SureDocs_OrganizationRole	Org's role definition
User	SureDocs_User	Authenticated system user
UserRole	sdms_userRole	User-level role assignment
DocDiscrepancy	SureDocs_Discrepancy	Quality discrepancy
DocDiscrepancyType	sdms_discrepancyType	Discrepancy classification
Audit	sdms_audit	Audit record
DocumentAuditReview	sdms_docAuditReview	Per-document audit review record
DocQItem	sdms_docQItem	Document quality item
DocForm	(embedded)	Custom metadata form for a document
FormField	(embedded)	Single field value in a form
AnnotationDef	sdms_annotationDef	Annotation field definition
AnnotationField	(embedded)	Single annotation value
AnnotationForm	(embedded)	Collection of annotations
DataPropertyDef	sdms_dataPropertyDef	Custom metadata field definition
MetadataAssociation	(embedded)	Link between content type and metadata field
PropertyDef	sdms_propertyDef	Property definition
PropertyField	(embedded)	Field value for a property
PropertyForm	(embedded)	Collection of property fields
CloudArchive	(extends Archive)	Cloud-hosted archive
ImagingArchive	(extends Archive)	Medical imaging archive
QualityArchive	(extends Archive)	Quality-flagged archive
NewsItem	sdms_news	News or announcement
Registrar	sdms_registrar	Study registrar record

Common Enumerations

Enum	Values / Notes
DiscrepancyType	DT_DOCUMENT_AND_METADATA_ERROR (default), and others
DiscrepancyStatus	Open / Resolved / Waived
DocumentLifeCycleStatus	Lifecycle states (pending, approved, rejected, etc.)
DocumentType	DT_DOCUMENT (default) and specialized types
PdfSignatureType	NO_SIGNATURE (default), and signed variants
CertificationLevel	NOT_CERTIFIED (default)
ControlledType	Controlled document classification
TrainingType	Training document classification
DuplicationPolicy	Controls how duplicate documents are handled
ContentModelVersion	CUSTOM (default)
NumberingScheme	Archive document numbering policy
MetadataType	MT_CORE (default)

Design Notes

• Entities are plain POJOs with no Spring, JPA, or Jackson annotations.
• BaseEntity.OBJECT_FACTORIES is populated by each entity's static { register(); } block. New entity types must call registerObjFactory(TYPE, factory) to be discoverable.
• The LOADED_OBJECTS cache in BaseEntity allows entity deduplication during a parse session. Call BaseEntity.reset() between sessions.
• DocForm and its FormField entries are the mechanism by which custom metadata values (entered via the Content Model Editor) are attached to documents.
• The IHierarchicalEntity interface (implemented by ContentType and Category) provides parent/child traversal for building the content model tree.

Dependencies

This module has no dependencies on other suredms-* desktop modules. It imports only from suredms-common (shared enums and constants) and the Nuxeo client library (for the Session, Document, and PropertyMap types used in persistence methods).

Endpoint Interface Layer

This module (suredms-desktop-client-data) also defines the endpoint interface layer: IEndPoints, IAuth, IDocument, EndPointsType, FetchMode, EndPointListener, EndPointParameters, and TimedReloadService. These interfaces are consumed by the connector module for its NuxeoEndPoints and XMLEndPoints implementations, and by the shell module's EntityDataSource. For full documentation of these interfaces see Data Access Layer — Endpoint Interface Hierarchy.