Interface AuditContext

All Known Subinterfaces:
BalpAuditContext
All Known Implementing Classes:
DefaultAuditContext, DefaultBalpAuditContext
public interface AuditContext
AuditContext is the central location where all aspects of serializing and sending out Audit messages are defined. This includes
  • whether auditing is enabled at all
  • the transmission protocol (UDP, TLS, ...)
  • the queue implementation (synchronous, asynchronous, ...
  • the serialization strategy (e.g. which DICOM audit version shall be used)
  • global parameters like source ID, enterprise ID
Since:
3.5
Author:
Christian Ohr

  • Method Details

    • isAuditEnabled

      boolean isAuditEnabled()
      Returns:
      true if auditing is enabled, false otherwise

    • getAuditRepositoryHostName

      String getAuditRepositoryHostName()
      Returns:
      hostname of the audit repository

    • getAuditRepositoryAddress

      InetAddress getAuditRepositoryAddress()
      Returns:
      address of the audit repository

    • getAuditRepositoryPort

      int getAuditRepositoryPort()
      Returns:
      port of the audit repository

    • getAuditRepositoryContextPath

      default String getAuditRepositoryContextPath()
      Returns:
      context path of the audit repository, for transports that address it over HTTP. Empty unless the audit repository is reached through one.

    • getJwtExtractorProperties

      default JwtExtractorProperties getJwtExtractorProperties()
      Returns:
      where to find the claims in an access token the audited request carried. Not tied to any audit format; the defaults point at the standard JWT claims and the IHE IUA/BPPC extensions.

    • getRequestIdHeaderNames

      default List<String> getRequestIdHeaderNames()
      Names of the HTTP headers that may carry the id correlating the audit records the two ends of a transaction write about it, most preferred first. The first header the request actually carries wins; a request carrying none is audited without such an id.

      IHE BALP asks for RequestIdHeaders.X_REQUEST_ID and reports it as the transaction entity of an AuditEvent, which is why that is the default. A deployment that already propagates a trace can name its headers here instead -- RequestIdHeaders.TRACEPARENT for W3C Trace Context, RequestIdHeaders.B3 and RequestIdHeaders.X_B3_TRACE_ID for the single-header and multi-header flavours of B3 -- and the id is reported in the same place. Naming both B3 headers is the way to accept whichever flavour a caller happens to use; they yield the same id.

      Any other name works too and is then taken at face value; see RequestIdHeaders for the headers whose value needs more than that.

      Returns:
      the header names to look for, most preferred first. Empty disables the lookup.

    • getRequestIdType

      default ParticipantObjectIdType getRequestIdType()
      Participant object ID type to record the correlation id under, whichever of getRequestIdHeaderNames() it was found in. Set this only to flatten the distinction: by default the type follows the header, so that the audit record says which propagation format the id came from -- see RequestIdHeaders.participantObjectIdType(String).

      A deployment whose audit repository only understands ParticipantObjectIdTypeCode.XRequestId would name that one here.

      Returns:
      the participant object ID type to force, or null to let it follow the header

    • getSendingApplication

      String getSendingApplication()
      Returns:
      sending application

    • getAuditTransmissionProtocol

      AuditTransmissionProtocol getAuditTransmissionProtocol()
      Returns:
      the wire protocol to be used

    • getAuditMessageQueue

      AuditMessageQueue getAuditMessageQueue()
      Returns:
      the queue implementation to be used

    • getTlsParameters

      TlsParameters getTlsParameters()
      Returns:
      the SSL socket factory to be used for TLS-based connections

    • getWsAuditDatasetEnricher

      <T extends WsAuditDatasetEnricher> T getWsAuditDatasetEnricher()
      Returns:
      Audit dataset enricher for Web Service based transactions.

    • getFhirAuditDatasetEnricher

      <T extends FhirAuditDatasetEnricher> T getFhirAuditDatasetEnricher()
      Returns:
      Audit dataset enricher for FHIR based transactions.

    • getAuditMessagePostProcessor

      default AuditMessagePostProcessor getAuditMessagePostProcessor()
      Returns:
      a post-processor for audit messages (defaults to a NO-OP implementation

    • getSerializationStrategy

      default SerializationStrategy getSerializationStrategy()
      Returns:
      the serialization strategy (defaults to the latest relevant DICOM version)

    • audit

      default void audit(AuditMessage... messages)
      Sends out the (potentially post-processed) audit messages as configured in this audit context
      Parameters:
      messages - audit messages to be sent

    • getAuditMetadataProvider

      default AuditMetadataProvider getAuditMetadataProvider()
      Returns audit metadata e.g. for populating the RFC 5424 header
      Returns:
      audit metadata

    • getAuditValueIfMissing

      default String getAuditValueIfMissing()
      Returns a value that is used when an otherwise mandatory attribute for an audit record in missing (e.g. a participant object ID). In this case, we can still write an audit record (e.g. documenting a failed request due to the missing attribute).

      This can also be set to null at the risk that building the audit record might throw an exception.

      Returns:
      a value that is used when an otherwise mandatory attribute for an audit record in missing

    • getAuditSourceId

      String getAuditSourceId()
      Returns:
      Source ID attribute of the audit event

    • getAuditEnterpriseSiteId

      String getAuditEnterpriseSiteId()
      Returns:
      Enterprise site ID attribute of the audit event

    • getAuditSource

      AuditSource getAuditSource()
      Returns:
      type of audit source

    • getAuditExceptionHandler

      AuditExceptionHandler getAuditExceptionHandler()
      Returns:
      exception handler

    • isIncludeParticipantsFromResponse

      boolean isIncludeParticipantsFromResponse()
      Determines whether participant object records shall be added to the audit message that are derived from the response of a request. This specifically applies to query results. The DICOM audit specification states that this should not be the case, however, project and legal requirements sometimes mandate that e.g. patient identifiers being retrieved shall be audited.
      Returns:
      true if participant object records shall be added, otherwise false

    • getContextRegistry

      io.micrometer.context.ContextRegistry getContextRegistry()
      Returns a registry of ThreadLocalAccessor instances that are used to propagate context when asynchronously queuing audit records.
      Returns:
      context registry

    • noAudit

      static AuditContext noAudit()