Class AnnotationSetServiceImpl

java.lang.Object

ubic.gemma.persistence.service.common.auditAndSecurity.curation.AnnotationSetServiceImpl

All Implemented Interfaces:

AnnotationSetService

@Service
public class AnnotationSetServiceImpl
extends Object
implements AnnotationSetService

Default AnnotationSetService implementation.

attach(Investigation, AnnotationSetRole, AnnotationSetSource, AgentCurationKind, String, String, String, String, Date, String, AnnotationSet) carries @AuditedConditional: an event is emitted only on actual insert (the result.created flag), not on the idempotent same-(role, runId) retry path. The audit note carries the row id so the audit trail links to the row without inlining the JSON payload.

Nested Class Summary

Nested classes/interfaces inherited from interface AnnotationSetService

AnnotationSetService.AttachedAnnotationSet, AnnotationSetService.RunProvenance

Field Summary

Fields inherited from interface AnnotationSetService

PRE_COMMIT_SNAPSHOT_RUN_ID_PREFIX

Constructor Summary

Constructors

Constructor	Description
AnnotationSetServiceImpl(AnnotationSetDao annotationSetDao)

Method Summary

Modifier and Type	Method	Description
AnnotationSetService.AttachedAnnotationSet	attach(Investigation investigation, AnnotationSetRole role, AnnotationSetSource source, AgentCurationKind kind, String runId, String createdBy, String agentVersion, String model, Date ranAt, String payloadJson, AnnotationSet parent)	Attach (or return existing) an annotation set to the given investigation.
AnnotationSetService.AttachedAnnotationSet	attach(Investigation investigation, AnnotationSetRole role, AnnotationSetSource source, AgentCurationKind kind, String runId, String createdBy, AnnotationSetService.RunProvenance runProvenance, String payloadJson, AnnotationSet parent)	As AnnotationSetService.attach(Investigation, AnnotationSetRole, AnnotationSetSource, AgentCurationKind, String, String, String, String, Date, String, AnnotationSet), but carrying the full run provenance rather than the agentVersion / model / ranAt triple.
long	countByInvestigation(Investigation investigation, AnnotationSetRole roleFilter)
Map<AnnotationSetRole, Long>	countByRoleSince(Date since)
long	countDistinctRunIdsSince(Date since, AnnotationSetRole roleFilter)
long	countSince(Date since, AnnotationSetRole roleFilter)
long	countSummaries(AnnotationSetRole roleFilter, AnnotationSetSource sourceFilter, String createdByFilter, AgentCurationKind kindFilter, String statusFilter, List<Long> investigationIds)
boolean	delete(Long id)	Delete the row with the given id.
AnnotationSet	finalizeSet(Long id, String finalizedBy, String notes)	Stamp finalizedAt + finalizedBy on the row, marking a DRAFT as "done editing" or a SNAPSHOT as the polished canonical view.
List<AnnotationSet>	findByInvestigation(Investigation investigation, AnnotationSetRole roleFilter)
AnnotationSet	findByInvestigationAndRoleAndRunId(Investigation investigation, AnnotationSetRole role, String runId)
AnnotationSet	findLatestByInvestigation(Investigation investigation, AnnotationSetRole roleFilter)
Date	findLatestCreatedAt(AnnotationSetRole roleFilter)
List<AnnotationSetSummaryValueObject>	findSummariesByInvestigation(Investigation investigation, AnnotationSetRole roleFilter)	Thin metadata projection.
List<AnnotationSetSummaryValueObject>	listSummaries(AnnotationSetRole roleFilter, AnnotationSetSource sourceFilter, String createdByFilter, AgentCurationKind kindFilter, String statusFilter, List<Long> investigationIds, int offset, int limit, AnnotationSetDao.SummarySort sort, boolean descending)
AnnotationSet	load(Long id)
int	rebindInvestigation(Investigation from, Investigation to)
AnnotationSet	reopenSet(Long id)	Clear finalizedAt + finalizedBy + finalizedNotes on the row, reopening a finalized DRAFT or unblessing a polished SNAPSHOT.
AnnotationSet	updateProvenance(Long id, AnnotationSetService.RunProvenance provenance)	Correct the run-provenance envelope on an existing row in place, so a mis-stamped agentVersion / model / agentName / runSha / ranAt is fixed without the delete-and-recreate that mints a new id.
AnnotationSet	updateStatus(AnnotationSet annotationSet, String status)	Record where a proposal stands with its reviewer, and return the updated set.
AnnotationSet	upsertDraft(Investigation investigation, String createdBy, String payloadJson, String parkedElements, AnnotationSet parent)	Convenience overload for the common DRAFT-upsert path used by the curation-UI: ensures one DRAFT per (investigation, curator) by deriving runId as "draft-{createdBy}".

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

AnnotationSetServiceImpl

@Autowired
public AnnotationSetServiceImpl(AnnotationSetDao annotationSetDao)

Method Details

attach

@Transactional
@AuditedConditional(value=AnnotationSetEvent.class,
                    when="#result != null and #result.created and #result.annotationSet.role.name() != 'SNAPSHOT' and #result.annotationSet.role.name() != 'COMMIT'",
                    messageSpel="'AnnotationSet#' + #result.annotationSet.id + ' role=' + #result.annotationSet.role.dbValue + ' source=' + #result.annotationSet.source.dbValue + (#result.annotationSet.kind != null ? ' kind=' + #result.annotationSet.kind.dbValue : '') + ' run=' + #result.annotationSet.runId + (#result.annotationSet.agentName != null ? ' agent=' + #result.annotationSet.agentName : '') + (#result.annotationSet.agentVersion != null ? ' version=' + #result.annotationSet.agentVersion : '') + (#result.annotationSet.model != null ? ' model=' + #result.annotationSet.model : '') + (#result.annotationSet.runSha != null ? ' sha=' + #result.annotationSet.runSha : '')")
public AnnotationSetService.AttachedAnnotationSet attach(Investigation investigation,
 AnnotationSetRole role,
 AnnotationSetSource source,
 @Nullable
 AgentCurationKind kind,
 @Nullable
 String runId,
 @Nullable
 String createdBy,
 @Nullable
 String agentVersion,
 @Nullable
 String model,
 @Nullable
 Date ranAt,
 @Nullable
 String payloadJson,
 @Nullable
 AnnotationSet parent)

Description copied from interface: AnnotationSetService

Attach (or return existing) an annotation set to the given investigation. The runId semantic depends on role and is the caller's responsibility:

• PROPOSAL — pass the agent runner's unique id.
• DRAFT — pass "draft-{createdBy}" (or the service derives it if blank; see AnnotationSetService.upsertDraft(Investigation, String, String, String, AnnotationSet)).
• SNAPSHOT — pass a generated UUID, or let the service generate one when runId is null/blank.

Specified by:

attach in interface AnnotationSetService

Returns:

the persisted row plus a flag noting whether it was created (true) or returned as existing (false).

attach

@Transactional
@AuditedConditional(value=AnnotationSetEvent.class,
                    when="#result != null and #result.created and #result.annotationSet.role.name() != 'SNAPSHOT' and #result.annotationSet.role.name() != 'COMMIT'",
                    messageSpel="'AnnotationSet#' + #result.annotationSet.id + ' role=' + #result.annotationSet.role.dbValue + ' source=' + #result.annotationSet.source.dbValue + (#result.annotationSet.kind != null ? ' kind=' + #result.annotationSet.kind.dbValue : '') + ' run=' + #result.annotationSet.runId + (#result.annotationSet.agentName != null ? ' agent=' + #result.annotationSet.agentName : '') + (#result.annotationSet.agentVersion != null ? ' version=' + #result.annotationSet.agentVersion : '') + (#result.annotationSet.model != null ? ' model=' + #result.annotationSet.model : '') + (#result.annotationSet.runSha != null ? ' sha=' + #result.annotationSet.runSha : '')")
public AnnotationSetService.AttachedAnnotationSet attach(Investigation investigation,
 AnnotationSetRole role,
 AnnotationSetSource source,
 @Nullable
 AgentCurationKind kind,
 @Nullable
 String runId,
 @Nullable
 String createdBy,
 @Nullable
 AnnotationSetService.RunProvenance runProvenance,
 @Nullable
 String payloadJson,
 @Nullable
 AnnotationSet parent)

Description copied from interface: AnnotationSetService

As AnnotationSetService.attach(Investigation, AnnotationSetRole, AnnotationSetSource, AgentCurationKind, String, String, String, String, Date, String, AnnotationSet), but carrying the full run provenance rather than the agentVersion / model / ranAt triple.

An overload rather than two more parameters on the method above: that signature already takes eleven arguments, six of which would then be adjacent nullable strings meaning different things (runId, createdBy, agentVersion, model, runSha, agentName). Transposing two of those compiles silently and mis-files provenance in a way nothing would catch. AnnotationSetService.RunProvenance makes that impossible and leaves the existing callers untouched.

Specified by:

attach in interface AnnotationSetService

upsertDraft

@Transactional
public AnnotationSet upsertDraft(Investigation investigation,
 String createdBy,
 String payloadJson,
 @Nullable
 String parkedElements,
 @Nullable
 AnnotationSet parent)

Description copied from interface: AnnotationSetService

Convenience overload for the common DRAFT-upsert path used by the curation-UI: ensures one DRAFT per (investigation, curator) by deriving runId as "draft-{createdBy}". If a row already exists, its payloadJson / parkedElements / updatedAt are updated in place; otherwise a new row is created.

Specified by:

upsertDraft in interface AnnotationSetService

Parameters:

parent - optional PROPOSAL this draft was seeded from (forms the lineage edge for diff-derived dispositions).

findByInvestigation

@Transactional(readOnly=true)
public List<AnnotationSet> findByInvestigation(Investigation investigation,
 @Nullable
 AnnotationSetRole roleFilter)

Specified by:

findByInvestigation in interface AnnotationSetService

Returns:

all sets attached to the given investigation matching the role filter (or all roles if null), newest first.

findSummariesByInvestigation

@Transactional(readOnly=true)
public List<AnnotationSetSummaryValueObject> findSummariesByInvestigation(Investigation investigation,
 @Nullable
 AnnotationSetRole roleFilter)

Description copied from interface: AnnotationSetService

Thin metadata projection.

Specified by:

findSummariesByInvestigation in interface AnnotationSetService

findLatestByInvestigation

@Nullable
@Transactional(readOnly=true)
public AnnotationSet findLatestByInvestigation(Investigation investigation,
 @Nullable
 AnnotationSetRole roleFilter)

Specified by:

findLatestByInvestigation in interface AnnotationSetService

load

@Nullable
@Transactional(readOnly=true)
public AnnotationSet load(Long id)

Specified by:

load in interface AnnotationSetService

findByInvestigationAndRoleAndRunId

@Nullable
@Transactional(readOnly=true)
public AnnotationSet findByInvestigationAndRoleAndRunId(Investigation investigation,
 AnnotationSetRole role,
 String runId)

Specified by:

findByInvestigationAndRoleAndRunId in interface AnnotationSetService

countByInvestigation

@Transactional(readOnly=true)
public long countByInvestigation(Investigation investigation,
 @Nullable
 AnnotationSetRole roleFilter)

Specified by:

countByInvestigation in interface AnnotationSetService

rebindInvestigation

@Transactional
public int rebindInvestigation(Investigation from,
 Investigation to)

Specified by:

rebindInvestigation in interface AnnotationSetService

listSummaries

@Transactional(readOnly=true)
public List<AnnotationSetSummaryValueObject> listSummaries(@Nullable
 AnnotationSetRole roleFilter,
 @Nullable
 AnnotationSetSource sourceFilter,
 @Nullable
 String createdByFilter,
 @Nullable
 AgentCurationKind kindFilter,
 @Nullable
 String statusFilter,
 @Nullable
 List<Long> investigationIds,
 int offset,
 int limit,
 @Nullable
 AnnotationSetDao.SummarySort sort,
 boolean descending)

Specified by:

listSummaries in interface AnnotationSetService

countSummaries

@Transactional(readOnly=true)
public long countSummaries(@Nullable
 AnnotationSetRole roleFilter,
 @Nullable
 AnnotationSetSource sourceFilter,
 @Nullable
 String createdByFilter,
 @Nullable
 AgentCurationKind kindFilter,
 @Nullable
 String statusFilter,
 @Nullable
 List<Long> investigationIds)

Specified by:

countSummaries in interface AnnotationSetService

finalizeSet

@Nullable
@Transactional
public AnnotationSet finalizeSet(Long id,
 @Nullable
 String finalizedBy,
 @Nullable
 String notes)

Description copied from interface: AnnotationSetService

Stamp finalizedAt + finalizedBy on the row, marking a DRAFT as "done editing" or a SNAPSHOT as the polished canonical view. Idempotent: a row already finalized returns unchanged (no re-stamp).

Specified by:

finalizeSet in interface AnnotationSetService

Parameters:

notes - the curator's closing note, or null. Trimmed, and truncated to fit rather than rejected — losing the tail of an explanation is a smaller harm than refusing a closure the curator has already decided on. A blank note is stored as null.

🛑 The one thing this is NOT idempotent about. A set that is already finalized is still re-stamped with a non-blank notes, because dropping the sentence and answering 200 is the exact failure the parameter exists to fix; a caller cannot tell that from a successful write. Everything else about the row stays as it was.

reopenSet

@Nullable
@Transactional
public AnnotationSet reopenSet(Long id)

Description copied from interface: AnnotationSetService

Clear finalizedAt + finalizedBy + finalizedNotes on the row, reopening a finalized DRAFT or unblessing a polished SNAPSHOT. Idempotent: a row already not finalized returns unchanged.

The note goes with the closure it explains. Carrying it across a reopen would attach one closure's words to the next one, and the UI pre-fills the re-close box from the value it read BEFORE reopening.

Specified by:

reopenSet in interface AnnotationSetService

updateProvenance

@Nullable
@Transactional
public AnnotationSet updateProvenance(Long id,
 AnnotationSetService.RunProvenance provenance)

Description copied from interface: AnnotationSetService

Correct the run-provenance envelope on an existing row in place, so a mis-stamped agentVersion / model / agentName / runSha / ranAt is fixed without the delete-and-recreate that mints a new id. Only the envelope moves; the set's content (payloadJson, parkedElements), its identity (role, source, runId, investigation, parent) and its finalized status are untouched.

Per field: null leaves the stored value alone, and a blank string clears it. ranAt has no blank form, so it can be corrected but not cleared.

Specified by:

updateProvenance in interface AnnotationSetService

Returns:

the updated row, or null if no row has that id

delete

@Transactional
public boolean delete(Long id)

Description copied from interface: AnnotationSetService

Delete the row with the given id. Returns true if a row was removed, false if no such row existed. Cascades on parent edges are governed by ON DELETE SET NULL: descendants survive, their parent link is cleared.

Specified by:

delete in interface AnnotationSetService

countSince

@Transactional(readOnly=true)
public long countSince(@Nullable
 Date since,
 @Nullable
 AnnotationSetRole roleFilter)

Specified by:

countSince in interface AnnotationSetService

countByRoleSince

@Transactional(readOnly=true)
public Map<AnnotationSetRole, Long> countByRoleSince(@Nullable
 Date since)

Specified by:

countByRoleSince in interface AnnotationSetService

countDistinctRunIdsSince

@Transactional(readOnly=true)
public long countDistinctRunIdsSince(@Nullable
 Date since,
 @Nullable
 AnnotationSetRole roleFilter)

Specified by:

countDistinctRunIdsSince in interface AnnotationSetService

findLatestCreatedAt

@Nullable
@Transactional(readOnly=true)
public Date findLatestCreatedAt(@Nullable
 AnnotationSetRole roleFilter)

Specified by:

findLatestCreatedAt in interface AnnotationSetService

updateStatus

@Transactional
public AnnotationSet updateStatus(AnnotationSet annotationSet,
 String status)

Description copied from interface: AnnotationSetService

Record where a proposal stands with its reviewer, and return the updated set.

🛑 The value is stored as given. There is deliberately no vocabulary check here — Paul, 2026-09-04: "don't lock us into any kind of enums. if we settle down on this we might formalize it." pending | needs_changes | accepted | rejected are the values in use, not the values permitted, and a caller sending a fifth gets it stored rather than rejected. The only gate is structural: non-blank, and short enough for the column.

Specified by:

updateStatus in interface AnnotationSetService

Parameters:

annotationSet - the set to rule on

status - the status, already trimmed and lowercased by the caller

Returns:

the updated set