AuditReaderApi (platform/sdk 5.5.1.0-SNAPSHOT API)

All Known Implementing Classes:: MockIngestAuditApi

public interface AuditReaderApi

The AuditReaderApi allows for the consumption of audit information about the processing of messages documents. This information is generated by implementations of the AuditWriterApi. These interfaces work with the same data but are separated to allow for differing security and implementation.

Terms:

Term	Definition
idle	A client is idle between any audit records the client generates and after its "last" event.
inactive	A client is considered inactive if it has been idle longer than maxIdleClientMs. It is otherwise considered active.
incomplete	A client is incomplete if its summary information is imbalanced. A client is complete or balanced at a point in time if CREATED = COMPLETED + DROPPED + LOST

Timestamps:

The AuditReaderApi uses timestamps and date ranges in numerous places. In all cases, the timestamp corresponds to the server time. Since many server-side hosts may be involved in the processing of documents and messages, clusters without synchronized clocks may result in some variation in the timestamps of audit results. Audit timestamps may not be reliably used to determine an exact sequence of events.

Caveats

For performance reasons some implementations may delay writes of document ids when collecting audit information. In these cases, the document ID will appear as UNAVAILABLE. A subsequent call of the API should result in a valid id.

$Revision$

Field Summary

Fields
Modifier and Type Field and Description

static String UNAVAILABLE
For performance reasons some implementations may delay writes of document ids when collecting audit information.

Fields
Modifier and Type	Field and Description
`static String`	`UNAVAILABLE` For performance reasons some implementations may delay writes of document ids when collecting audit information.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`Iterable<UUID>`	`getActiveClients()` Returns the clientIds for all active clients.
`CloseableIterable<AuditDetail>`	`getAll(UUID clientId, long startSeq, long count)`
`Iterable<AuditDetail>`	`getAuditDetails(String docId, Date start, Date end)` Returns an `Iterable` of `AuditDetail`s associated with the document.
`Iterable<AuditDetail>`	`getAuditDetails(String docId, UUID clientId)` Returns an `Iterable` of `AuditDetail`s associated with the document.
`Iterable<AuditDetail>`	`getByCorrelationId(UUID clientId, UUID correlationId)` Get all audit details for a document via its `correlationId`.
`Iterable<String>`	`getCreatedDocuments(Date start, Date end)` Returns a list of IDs for all documents which were received by the system or created within the system during the specified date range.
`Iterable<String>`	`getCreatedDocuments(UUID clientId)` Returns a list of IDs for all documents which were received by the system or created within the system by the specified clientId.
`Iterable<String>`	`getDocuments(EnumSet<ProcessingResultCode> codeSet, Date start, Date end)` Returns a list of IDs for all documents for which a `resultCode` in `codeSet` was received at some point during content processing.
`Iterable<String>`	`getDocuments(EnumSet<ProcessingResultCode> codeSet, UUID clientId)` Returns a list of IDs for all documents for which a `resultCode` in `codeSet` was received at some point during content processing.
`Iterable<UUID>`	`getInactiveClients()` Returns the clientIds for all inactive clients.
`Iterable<AuditDetail>`	`getLostDetails(long startSeq, long endSeq)` Returns all audit detail events that have been flagged as LOST and have a sequence id >= `startSeq` and < `endSeq`.
`Iterable<String>`	`getProcessedDocuments(Date start, Date end)` Returns a list of IDs for all documents which have completed processing during the specified date range.
`Iterable<String>`	`getProcessedDocuments(UUID clientId)` Returns a list of IDs for all documents which have completed processing which were sent by the specified client.
`Iterable<String>`	`getSearchableDocuments(String indexName, Date start, Date end)` Returns an `Iterable` of IDs for all documents which became searchable during the specified date range.
`Iterable<String>`	`getSearchableDocuments(String indexName, UUID clientId)` Returns an `Iterable` of IDs for all documents that are searchable and were fed by the specified client.
`AuditClientSummary`	`getSummary(UUID clientId)`
`AuditClientSummary`	`waitForCompletion(UUID clientId)` Waits until all documents and messages created by this client have completed processing.
`AuditClientSummary`	`waitForCompletion(UUID clientId, long timeout)` Waits until all documents and messages created by this client have completed processing.
`Date`	`whenSearchable(String indexName, UUID clientId)` Returns the earliest date an index commit was received after all documents for the client were indexed.
`Date`	`whenSearchable(String indexName, UUID clientId, String docId)` Returns the earliest date an index commit was received after the document was indexed.

- Field Detail
  - UNAVAILABLE
```
static final String UNAVAILABLE
```
    For performance reasons some implementations may delay writes of document ids when collecting audit information. In these cases, the document ID will appear as <unavailable>. A subsequent call of the API should result in a valid id.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getCreatedDocuments
```
Iterable<String> getCreatedDocuments(Date start,
                                     Date end)
                              throws AttivioException
```
    Returns a list of IDs for all documents which were received by the system or created within the system during the specified date range.
    
    Parameters:
    
    start - the inclusive start date.
    
    end - the exclusive end date.
    
    Throws:
    
    AttivioException - if query cannot be executed
  - getCreatedDocuments
```
Iterable<String> getCreatedDocuments(UUID clientId)
                              throws AttivioException
```
    Returns a list of IDs for all documents which were received by the system or created within the system by the specified clientId.
    
    Parameters:
    
    clientId - restricts results to clientId, null not allowed.
    
    Throws:
    
    AttivioException - if query cannot be executed
  - getSearchableDocuments
```
Iterable<String> getSearchableDocuments(String indexName,
                                        Date start,
                                        Date end)
                                 throws AttivioException
```
    Returns an Iterable of IDs for all documents which became searchable during the specified date range. Indexed documents become searchable when an associated commit is received. The component with name <indexName>-content-dispatcher generates ProcessingResultCode.OK result codes for each document it sees document it processes. Once it generates an associated OK result for a Commit message, those documents are searchable.
    A reference algorithm is to find the latest commit (T1) that occurred before the start of the time range and the latest commit (T2) before the end of the time range. Then any documents that reached the indexer in the time range T1-T2 are the ones that became searchable.
    
    Parameters:
    
    indexName - the name of the index. To look up index related information, the actual Attivio component that interfaces to the index must be determined. The indexName is used to compute this component name. This is done by adding the suffix -content-dispatcher to the indexName. Additionally if indexName does not supply the workflow where the component is located (specified by a name followed by a .), the default name indexer. will be prepended.
    
    start - the inclusive start date.
    
    end - the exclusive end date.
    
    Throws:
    
    AttivioException - if query cannot be executed
  - getSearchableDocuments
```
Iterable<String> getSearchableDocuments(String indexName,
                                        UUID clientId)
                                 throws AttivioException
```
    Returns an Iterable of IDs for all documents that are searchable and were fed by the specified client. Indexed documents become searchable when an associated commit is received. The component with name <indexName>-content-dispatcher generates ProcessingResultCode.OK result codes for each document it sees document it processes. Once it generates an associated OK result for a Commit message, those documents are searchable.
    
    Parameters:
    
    indexName - the name of the index. To look up index related information, the actual Attivio component that interfaces to the index must be determined. The indexName is used to compute this component name. This is done by adding the suffix -content-dispatcher to the indexName. Additionally if indexName does not supply the workflow where the component is located (specified by a name followed by a .), the default name indexer. will be prepended.
    
    clientId - restricts results to clientId, null not allowed.
    
    Throws:
    
    AttivioException - if query cannot be executed
  - getProcessedDocuments
```
Iterable<String> getProcessedDocuments(Date start,
                                       Date end)
                                throws AttivioException
```
    Returns a list of IDs for all documents which have completed processing during the specified date range. A document is considered complete when all possible side-effects of processing the document have occurred. This state is associated with the receipt of an AuditDetail for the document with a resultCode of ProcessingResultCode.COMPLETED.
    
    Parameters:
    
    start - the inclusive start date.
    
    end - the exclusive end date.
    
    Throws:
    
    AttivioException - if query cannot be executed
  - getProcessedDocuments
```
Iterable<String> getProcessedDocuments(UUID clientId)
                                throws AttivioException
```
    Returns a list of IDs for all documents which have completed processing which were sent by the specified client. A document is considered complete when all possible side-effects of processing the document have occurred. This state is associated with the receipt of an AuditDetail for the document with a resultCode of ProcessingResultCode.COMPLETED.
    
    Parameters:
    
    clientId - restricts results to clientId, null not allowed.
    
    Throws:
    
    AttivioException - if query cannot be executed
  - getDocuments
```
Iterable<String> getDocuments(EnumSet<ProcessingResultCode> codeSet,
                              UUID clientId)
                       throws AttivioException
```
    Returns a list of IDs for all documents for which a resultCode in codeSet was received at some point during content processing. Since there are multiple content processing stages codes may appear multiple times and multiple codes may match. The returned list will be restricted to documents fed by clientId.
    
    Parameters:
    
    codeSet - set of result codes to match
    
    clientId - restricts results to clientId, null not allowed.
    
    Returns:
    
    an Iterable of document IDs. Document IDs appear at most once.
    
    Throws:
    
    AttivioException - if query cannot be executed
  - getDocuments
```
Iterable<String> getDocuments(EnumSet<ProcessingResultCode> codeSet,
                              Date start,
                              Date end)
                       throws AttivioException
```
    Returns a list of IDs for all documents for which a resultCode in codeSet was received at some point during content processing. Since there are multiple content processing stages codes may appear multiple times and multiple codes may match. The returned list will be restricted to documents fed within the specified time range.
    
    Parameters:
    
    codeSet - set of result codes to match
    
    start - the inclusive start date.
    
    end - the exclusive end date.
    
    Returns:
    
    an Iterable of document IDs. Document IDs appear at most once.
    
    Throws:
    
    AttivioException - if query cannot be executed
  - whenSearchable
```
Date whenSearchable(String indexName,
                    UUID clientId,
                    String docId)
             throws AttivioException
```
    Returns the earliest date an index commit was received after the document was indexed. A document is considered indexed after the receipt of a ProcessingResultCode.OK audit result for the index content dispatcher component ( <indexName>-content-dispatcher). Documents which are not marked OK by the indexer are not considered by this method as they will never become searchable.
    
    Parameters:
    
    indexName - the name of the index. To look up index related information, the actual Attivio component that interfaces to the index must be determined. The indexName is used to compute this component name. This is done by adding the suffix -content-dispatcher to the indexName. Additionally if indexName does not supply the workflow where the component is located (specified by a name followed by a .), the default name indexer. will be prepended.
    
    clientId - restricts results to clientId, null not allowed.
    
    docId -
    
    Returns:
    
    the date when document docId became searchable or null if not yet searchable
    
    Throws:
    
    AttivioException - if query cannot be executed
  - whenSearchable
```
Date whenSearchable(String indexName,
                    UUID clientId)
             throws AttivioException
```
    Returns the earliest date an index commit was received after all documents for the client were indexed. A document is considered indexed after the receipt of a ProcessingResultCode.OK audit result for the index content dispatcher component (<indexName>-content-dispatcher). Documents which are not marked OK by the indexer are not considered by this method as they will never become searchable.
    
    Parameters:
    
    indexName - the name of the index. To look up index related information, the actual Attivio component that interfaces to the index must be determined. The indexName is used to compute this component name. This is done by adding the suffix -content-dispatcher to the indexName. Additionally if indexName does not supply the workflow where the component is located (specified by a name followed by a .), the default name indexer. will be prepended.
    
    clientId - restricts results to clientId, null not allowed.
    
    Returns:
    
    the date when all documents submitted (so far) by client clientId became searchable or null if all documents are not yet searchable or no documents have been submitted by the client.
    
    Throws:
    
    AttivioException - if query cannot be executed
  - getAuditDetails
```
Iterable<AuditDetail> getAuditDetails(String docId,
                                      UUID clientId)
                               throws AttivioException
```
    Returns an Iterable of AuditDetails associated with the document. This list may include the audit information for a number of components and will include the creation and completion audit records if available. This method may be called while the document is still being processed.
    
    Parameters:
    
    docId - the document ID to match
    
    clientId - restricts results to clientId, null not allowed.
    
    Throws:
    
    AttivioException - if query cannot be executed
  - getAuditDetails
```
Iterable<AuditDetail> getAuditDetails(String docId,
                                      Date start,
                                      Date end)
                               throws AttivioException
```
    Returns an Iterable of AuditDetails associated with the document. This list may include the audit information for a number of components and will include the creation and completion audit records if available. This method may be called while the document is still being processed. null values for start and end will return all available audit records for the document.
    
    Parameters:
    
    docId - the document ID to match
    
    start - the inclusive start date.
    
    end - the exclusive end date.
    
    Throws:
    
    AttivioException - if query cannot be executed
  - waitForCompletion
```
AuditClientSummary waitForCompletion(UUID clientId)
                              throws AttivioException
```
    Waits until all documents and messages created by this client have completed processing. If this method is called while feeding of new documents or messages occur in a separate thread or process, it may hang indefinitely or return prematurely. The only way to ensure that no processing associated with the client is occurring is to feed and waitForCompletion from the same thread of control.
    
    Parameters:
    
    clientId - restricts results to clientId, null not allowed.
    
    Returns:
    
    summary information about the client ingestion state or null if the client does not exist.
    
    Throws:
    
    AttivioException - if query cannot be executed
  - waitForCompletion
```
AuditClientSummary waitForCompletion(UUID clientId,
                                     long timeout)
                              throws AttivioException
```
    Waits until all documents and messages created by this client have completed processing. If this method is called while feeding of new documents or messages occur in a separate thread or process, it may hang indefinitely or return prematurely. The only way to ensure that no processing associated with the client is occurring is to feed and waitForCompletion from the same thread of control.
    
    Parameters:
    
    clientId -
    
    timeout -
    
    Returns:
    
    the associated AuditClientSummary if waited successfully, null if timeout occurred or client does not exist.
    
    Throws:
    
    AttivioException - if query cannot be executed
  - getSummary
```
AuditClientSummary getSummary(UUID clientId)
                       throws AttivioException
```
    Parameters:
    
    clientId - restricts results to clientId, null not allowed.
    
    Returns:
    
    summary information about the client ingestion state or null if the client does not exist.
    
    Throws:
    
    AttivioException - if query cannot be executed
  - getAll
```
CloseableIterable<AuditDetail> getAll(UUID clientId,
                                      long startSeq,
                                      long count)
                               throws AttivioException
```
    Parameters:
    
    clientId -
    
    startSeq - starting sequence ID for response
    
    count - the maximum number of audit details to return, use Long.MAX_VALUE for all
    
    Returns:
    
    all audit information for the client
    
    Throws:
    
    AttivioException
  - getLostDetails
```
Iterable<AuditDetail> getLostDetails(long startSeq,
                                     long endSeq)
                              throws AttivioException
```
    Returns all audit detail events that have been flagged as LOST and have a sequence id >= startSeq and < endSeq.
    NOTE: this method is used internally to replay LOST messages for fault tolerance.
    
    Throws:
    
    AttivioException
  - getByCorrelationId
```
Iterable<AuditDetail> getByCorrelationId(UUID clientId,
                                         UUID correlationId)
                                  throws AttivioException
```
    Get all audit details for a document via its correlationId.
    
    Throws:
    
    AttivioException
  - getActiveClients
```
Iterable<UUID> getActiveClients()
                         throws AttivioException
```
    Returns the clientIds for all active clients.
    
    Returns:
    
    an Iterable of clientIds
    
    Throws:
    
    AttivioException
  - getInactiveClients
```
Iterable<UUID> getInactiveClients()
                           throws AttivioException
```
    Returns the clientIds for all inactive clients.
    
    Returns:
    
    an Iterable of clientIds
    
    Throws:
    
    AttivioException

Interface AuditReaderApi

Terms:

Timestamps:

Caveats

Field Summary

Method Summary

Field Detail

UNAVAILABLE

Method Detail

getCreatedDocuments

getCreatedDocuments

getSearchableDocuments

getSearchableDocuments

getProcessedDocuments

getProcessedDocuments

getDocuments

getDocuments

whenSearchable

whenSearchable

getAuditDetails

getAuditDetails

waitForCompletion

waitForCompletion

getSummary

getAll

getLostDetails

getByCorrelationId

getActiveClients

getInactiveClients