Package com.attivio.sdk.client.audit

Interface AuditReaderApi

  • 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 Description
      static java.lang.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 Description
      java.lang.Iterable<java.util.UUID> getActiveClients()
      Returns the clientIds for all active clients.
      CloseableIterable<AuditDetail> getAll​(java.util.UUID clientId, long startSeq, long count)  
      java.lang.Iterable<java.util.UUID> getAllClients()
      Returns the clientIds for all clients sorted by clientId for ease of comparison.
      java.lang.Iterable<AuditDetail> getAuditDetails​(java.lang.String docId, java.util.Date start, java.util.Date end)
      Returns an Iterable of AuditDetails associated with the document.
      java.lang.Iterable<AuditDetail> getAuditDetails​(java.lang.String docId, java.util.UUID clientId)
      Returns an Iterable of AuditDetails associated with the document.
      java.lang.Iterable<AuditDetail> getByCorrelationId​(java.util.UUID clientId, java.util.UUID correlationId)
      Get all audit details for a document via its correlationId.
      java.lang.Iterable<java.lang.String> getCreatedDocuments​(java.util.Date start, java.util.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.
      java.lang.Iterable<java.lang.String> getCreatedDocuments​(java.util.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.
      java.lang.Iterable<java.lang.String> getDocuments​(java.util.EnumSet<ProcessingResultCode> codeSet, java.util.Date start, java.util.Date end)
      Returns a list of IDs for all documents for which a resultCode in codeSet was received at some point during content processing.
      java.lang.Iterable<java.lang.String> getDocuments​(java.util.EnumSet<ProcessingResultCode> codeSet, java.util.UUID clientId)
      Returns a list of IDs for all documents for which a resultCode in codeSet was received at some point during content processing.
      java.lang.Iterable<java.util.UUID> getInactiveClients()
      Returns the clientIds for all inactive clients.
      java.lang.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.
      java.lang.Iterable<java.lang.String> getProcessedDocuments​(java.util.Date start, java.util.Date end)
      Returns a list of IDs for all documents which have completed processing during the specified date range.
      java.lang.Iterable<java.lang.String> getProcessedDocuments​(java.util.UUID clientId)
      Returns a list of IDs for all documents which have completed processing which were sent by the specified client.
      java.lang.Iterable<java.lang.String> getSearchableDocuments​(java.lang.String indexName, java.util.Date start, java.util.Date end)
      Returns an Iterable of IDs for all documents which became searchable during the specified date range.
      java.lang.Iterable<java.lang.String> getSearchableDocuments​(java.lang.String indexName, java.util.UUID clientId)
      Returns an Iterable of IDs for all documents that are searchable and were fed by the specified client.
      AuditClientSummary getSummary​(java.util.UUID clientId)  
      AuditClientSummary waitForCompletion​(java.util.UUID clientId)
      Waits until all documents and messages created by this client have completed processing.
      AuditClientSummary waitForCompletion​(java.util.UUID clientId, long timeout)
      Waits until all documents and messages created by this client have completed processing.
      java.util.Date whenSearchable​(java.lang.String indexName, java.util.UUID clientId)
      Returns the earliest date an index commit was received after all documents for the client were indexed.
      java.util.Date whenSearchable​(java.lang.String indexName, java.util.UUID clientId, java.lang.String docId)
      Returns the earliest date an index commit was received after the document was indexed.

    • Field Detail

      • UNAVAILABLE

        static final java.lang.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

        java.lang.Iterable<java.lang.String> getCreatedDocuments​(java.util.Date start,
                                                         java.util.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

        java.lang.Iterable<java.lang.String> getCreatedDocuments​(java.util.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

        java.lang.Iterable<java.lang.String> getSearchableDocuments​(java.lang.String indexName,
                                                            java.util.Date start,
                                                            java.util.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

        java.lang.Iterable<java.lang.String> getSearchableDocuments​(java.lang.String indexName,
                                                            java.util.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

        java.lang.Iterable<java.lang.String> getProcessedDocuments​(java.util.Date start,
                                                           java.util.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

        java.lang.Iterable<java.lang.String> getProcessedDocuments​(java.util.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

        java.lang.Iterable<java.lang.String> getDocuments​(java.util.EnumSet<ProcessingResultCode> codeSet,
                                                  java.util.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

        java.lang.Iterable<java.lang.String> getDocuments​(java.util.EnumSet<ProcessingResultCode> codeSet,
                                                  java.util.Date start,
                                                  java.util.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

        java.util.Date whenSearchable​(java.lang.String indexName,
                              java.util.UUID clientId,
                              java.lang.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

        java.util.Date whenSearchable​(java.lang.String indexName,
                              java.util.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

        java.lang.Iterable<AuditDetail> getAuditDetails​(java.lang.String docId,
                                                java.util.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

        java.lang.Iterable<AuditDetail> getAuditDetails​(java.lang.String docId,
                                                java.util.Date start,
                                                java.util.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​(java.util.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​(java.util.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​(java.util.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​(java.util.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

        java.lang.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

        java.lang.Iterable<AuditDetail> getByCorrelationId​(java.util.UUID clientId,
                                                   java.util.UUID correlationId)
                                            throws AttivioException
        Get all audit details for a document via its correlationId.
        Throws:
        AttivioException

      • getActiveClients

        java.lang.Iterable<java.util.UUID> getActiveClients()
                                             throws AttivioException
        Returns the clientIds for all active clients.
        Returns:
        an Iterable of clientIds
        Throws:
        AttivioException

      • getInactiveClients

        java.lang.Iterable<java.util.UUID> getInactiveClients()
                                               throws AttivioException
        Returns the clientIds for all inactive clients.
        Returns:
        an Iterable of clientIds
        Throws:
        AttivioException

      • getAllClients

        java.lang.Iterable<java.util.UUID> getAllClients()
                                          throws AttivioException
        Returns the clientIds for all clients sorted by clientId for ease of comparison.
        Returns:
        an Iterable of clientIds
        Throws:
        AttivioException