Package net.gini.android

Class DocumentTaskManager

  • public class DocumentTaskManager
extends java.lang.Object
    The DocumentTaskManager is a high level API on top of the Gini API, which is used via the ApiCommunicator. It provides high level methods to handle document related tasks easily.

    • Field Detail

      • POLLING_INTERVAL

        public static long POLLING_INTERVAL
        The time in milliseconds between HTTP requests when a document is polled.

      • DEFAULT_COMPRESSION

        public static final int DEFAULT_COMPRESSION
        The default compression rate which is used for JPEG compression in per cent.
        See Also:
        Constant Field Values

    • Method Detail

      • deletePartialDocumentAndParents

        public bolts.Task<java.lang.String> deletePartialDocumentAndParents​(@NonNull
                                                                    java.lang.String documentId)
        Deletes a Gini partial document and all its parent composite documents.
        Partial documents can be deleted only, if they don't belong to any composite documents and this method deletes the parents before deleting the partial document.
        Parameters:
        documentId - The id of an existing partial document
        Returns:
        A Task which will resolve to an empty string.

      • deleteDocument

        public bolts.Task<java.lang.String> deleteDocument​(@NonNull
                                                   java.lang.String documentId)
        Deletes a Gini document. For deleting partial documents use deletePartialDocumentAndParents(String) instead.
        Parameters:
        documentId - The id of an existing document
        Returns:
        A Task which will resolve to an empty string.

      • createPartialDocument

        public bolts.Task<Document> createPartialDocument​(@NonNull
                                                  byte[] document,
                                                  @NonNull
                                                  java.lang.String contentType,
                                                  @Nullable
                                                  java.lang.String filename,
                                                  @Nullable
                                                  DocumentTaskManager.DocumentType documentType)
        Uploads raw data and creates a new Gini partial document.
        Parameters:
        document - A byte array representing an image, a pdf or UTF-8 encoded text
        contentType - The media type of the uploaded data
        filename - Optional the filename of the given document
        documentType - Optional a document type hint. See the documentation for the document type hints for possible values
        Returns:
        A Task which will resolve to the Document instance of the freshly created document.

      • createPartialDocument

        public bolts.Task<Document> createPartialDocument​(@NonNull
                                                  byte[] document,
                                                  @NonNull
                                                  java.lang.String contentType,
                                                  @Nullable
                                                  java.lang.String filename,
                                                  @Nullable
                                                  DocumentTaskManager.DocumentType documentType,
                                                  @NonNull
                                                  DocumentMetadata documentMetadata)
        Uploads raw data and creates a new Gini partial document.
        Parameters:
        document - A byte array representing an image, a pdf or UTF-8 encoded text
        contentType - The media type of the uploaded data
        filename - Optional the filename of the given document
        documentType - Optional a document type hint. See the documentation for the document type hints for possible values
        documentMetadata - Additional information related to the document (e.g. the branch id to which the client app belongs)
        Returns:
        A Task which will resolve to the Document instance of the freshly created document.

      • createCompositeDocument

        public bolts.Task<Document> createCompositeDocument​(@NonNull
                                                    java.util.List<Document> documents,
                                                    @Nullable
                                                    DocumentTaskManager.DocumentType documentType)
        Creates a new Gini composite document.
        Parameters:
        documents - A list of partial documents which should be part of a multi-page document
        documentType - Optional a document type hint. See the documentation for the document type hints for possible values
        Returns:
        A Task which will resolve to the Document instance of the freshly created document.

      • createCompositeDocument

        public bolts.Task<Document> createCompositeDocument​(@NonNull
                                                    java.util.LinkedHashMap<Document,​java.lang.Integer> documentRotationMap,
                                                    @Nullable
                                                    DocumentTaskManager.DocumentType documentType)
        Creates a new Gini composite document. The input Map must contain the partial documents as keys. These will be part of the multi-page document. The value for each partial document key is the amount in degrees the document has been rotated by the user.
        Parameters:
        documentRotationMap - A map of partial documents and their rotation in degrees
        documentType - Optional a document type hint. See the documentation for the document type hints for possible values
        Returns:
        A Task which will resolve to the Document instance of the freshly created document.

      • createDocument

        public bolts.Task<Document> createDocument​(@NonNull
                                           byte[] document,
                                           @Nullable
                                           java.lang.String filename,
                                           @Nullable
                                           DocumentTaskManager.DocumentType documentType)
        Uploads raw data and creates a new Gini document.
        Parameters:
        document - A byte array representing an image, a pdf or UTF-8 encoded text
        filename - Optional the filename of the given document.
        documentType - Optional a document type hint. See the documentation for the document type hints for possible values.
        Returns:
        A Task which will resolve to the Document instance of the freshly created document. Important: If using the default Gini API, then use createPartialDocument(byte[], String, String, DocumentType) to upload the document and then call createCompositeDocument(LinkedHashMap, DocumentType) (or createCompositeDocument(List, DocumentType)) to finish document creation. The returned composite document can be used to poll the processing state, to retrieve extractions and to send feedback.

      • createDocument

        public bolts.Task<Document> createDocument​(@NonNull
                                           byte[] document,
                                           @Nullable
                                           java.lang.String filename,
                                           @Nullable
                                           DocumentTaskManager.DocumentType documentType,
                                           @NonNull
                                           DocumentMetadata documentMetadata)
        Uploads raw data and creates a new Gini document.
        Parameters:
        document - A byte array representing an image, a pdf or UTF-8 encoded text
        filename - Optional the filename of the given document.
        documentType - Optional a document type hint. See the documentation for the document type hints for possible values.
        documentMetadata - Additional information related to the document (e.g. the branch id to which the client app belongs)
        Returns:
        A Task which will resolve to the Document instance of the freshly created document. Important: If using the default Gini API, then use createPartialDocument(byte[], String, String, DocumentType) to upload the document and then call createCompositeDocument(LinkedHashMap, DocumentType) (or createCompositeDocument(List, DocumentType)) to finish document creation. The returned composite document can be used to poll the processing state, to retrieve extractions and to send feedback.

      • createDocument

        @Deprecated
public bolts.Task<Document> createDocument​(@NonNull
                                           android.graphics.Bitmap document,
                                           @Nullable
                                           java.lang.String filename,
                                           @Nullable
                                           java.lang.String documentType,
                                           int compressionRate)
        Deprecated.
        If using the default Gini API, then use createPartialDocument(byte[], String, String, DocumentType) to upload the document and then call createCompositeDocument(LinkedHashMap, DocumentType) (or createCompositeDocument(List, DocumentType)) to finish document creation. The returned composite document can be used to poll the processing state, to retrieve extractions and to send feedback.

        If using the accounting Gini API, then use createDocument(byte[], String, DocumentType).

        Uploads the given photo of a document and creates a new Gini document.
        Parameters:
        document - A Bitmap representing the image
        filename - Optional the filename of the given document.
        documentType - Optional a document type hint. See the documentation for the document type hints for possible values.
        compressionRate - Optional the compression rate of the created JPEG representation of the document. Between 0 and 90.
        Returns:
        A Task which will resolve to the Document instance of the freshly created document.

      • createDocument

        @Deprecated
public bolts.Task<Document> createDocument​(@NonNull
                                           android.graphics.Bitmap document,
                                           @Nullable
                                           java.lang.String filename,
                                           @Nullable
                                           java.lang.String documentType,
                                           int compressionRate,
                                           @NonNull
                                           DocumentMetadata documentMetadata)
        Deprecated.
        If using the default Gini API, then use createPartialDocument(byte[], String, String, DocumentType, DocumentMetadata) to upload the document and then call createCompositeDocument(LinkedHashMap, DocumentType) (or createCompositeDocument(List, DocumentType)) to finish document creation. The returned composite document can be used to poll the processing state, to retrieve extractions and to send feedback.

        If using the accounting Gini API, then use createDocument(byte[], String, DocumentType, DocumentMetadata).

        Uploads the given photo of a document and creates a new Gini document.
        Parameters:
        document - A Bitmap representing the image
        filename - Optional the filename of the given document.
        documentType - Optional a document type hint. See the documentation for the document type hints for possible values.
        compressionRate - Optional the compression rate of the created JPEG representation of the document. Between 0 and 90.
        documentMetadata - Additional information related to the document (e.g. the branch id to which the client app belongs)
        Returns:
        A Task which will resolve to the Document instance of the freshly created document.

      • getExtractions

        public bolts.Task<java.util.Map<java.lang.String,​SpecificExtraction>> getExtractions​(@NonNull
                                                                                           Document document)
        Deprecated.
        Use getAllExtractions(Document) instead to be able to receive compound extractions, too.
        Get the extractions for the given document.
        Parameters:
        document - The Document instance for whose document the extractions are returned.
        Returns:
        A Task which will resolve to a mapping, where the key is a String with the name of the specific. See the Gini API documentation for a list of the names of the specific extractions.

      • getAllExtractions

        public bolts.Task<ExtractionsContainer> getAllExtractions​(@NonNull
                                                          Document document)
        Get the extractions for the given document.
        Parameters:
        document - The Document instance for whose document the extractions are returned.
        Returns:
        A Task which will resolve to an ExtractionsContainer object.

      • getDocument

        public bolts.Task<Document> getDocument​(@NonNull
                                        java.lang.String documentId)
        Get the document with the given unique identifier.
        Parameters:
        documentId - The unique identifier of the document.
        Returns:
        A document instance representing all the document's metadata.

      • getDocument

        public bolts.Task<Document> getDocument​(@NonNull
                                        android.net.Uri documentUri)
        Get the document with the given unique identifier. Please note that this method may use a slightly corrected URI from which it gets the document (e.g. if the URI's host does not conform to the base URL of the Gini API). Therefore it is not possibly to use this method to get a document from an arbitrary URI.
        Parameters:
        documentUri - The URI of the document.
        Returns:
        A document instance representing all the document's metadata.

      • pollDocument

        public bolts.Task<Document> pollDocument​(@NonNull
                                         Document document)
        Continually checks the document status (via the Gini API) until the document is fully processed. To avoid flooding the network, there is a pause of at least the number of seconds that is set in the POLLING_INTERVAL constant of this class. This method returns a Task which will resolve to a new document instance. It does not update the given document instance.
        Parameters:
        document - The document which will be polled.

      • cancelDocumentPolling

        public void cancelDocumentPolling​(@NonNull
                                  Document document)
        Cancels document polling.
        Parameters:
        document - The document which is being polled

      • sendFeedbackForExtractions

        public bolts.Task<Document> sendFeedbackForExtractions​(@NonNull
                                                       Document document,
                                                       @NonNull
                                                       java.util.Map<java.lang.String,​SpecificExtraction> extractions)
                                                throws org.json.JSONException
        Sends approved and conceivably corrected extractions for the given document. This is called "submitting feedback on extractions" in the Gini API documentation.
        Parameters:
        document - The document for which the extractions should be updated.
        extractions - A Map where the key is the name of the specific extraction and the value is the SpecificExtraction object. This is the same structure as returned by the getExtractions method of this manager.
        Returns:
        A Task which will resolve to the same document instance when storing the updated extractions was successful.
        Throws:
        org.json.JSONException - When a value of an extraction is not JSON serializable.

      • sendFeedbackForExtractions

        public bolts.Task<Document> sendFeedbackForExtractions​(@NonNull
                                                       Document document,
                                                       @NonNull
                                                       java.util.Map<java.lang.String,​SpecificExtraction> extractions,
                                                       @NonNull
                                                       java.util.Map<java.lang.String,​CompoundExtraction> compoundExtractions)
                                                throws org.json.JSONException
        Throws:
        org.json.JSONException

      • reportDocument

        public bolts.Task<java.lang.String> reportDocument​(@NonNull
                                                   Document document,
                                                   @Nullable
                                                   java.lang.String summary,
                                                   @Nullable
                                                   java.lang.String description)
        Sends an error report for the given document to Gini. If the processing result for a document was not satisfactory (e.g. extractions where empty or incorrect), you can create an error report for a document. This allows Gini to analyze and correct the problem that was found. The owner of this document must agree that Gini can use this document for debugging and error analysis.
        Parameters:
        document - The erroneous document.
        summary - Optional a short summary of the occurred error.
        description - Optional a more detailed description of the occurred error.
        Returns:
        A Task which will resolve to an error ID. This is a unique identifier for your error report and can be used to refer to the reported error towards the Gini support.

      • getLayout

        public bolts.Task<org.json.JSONObject> getLayout​(@NonNull
                                                 Document document)
        Gets the layout of a document. The layout of the document describes the textual content of a document with positional information, based on the processed document.
        Parameters:
        document - The document for which the layouts is requested.
        Returns:
        A task which will resolve to a string containing the layout xml.

      • extractionCandidatesFromApiResponse

        protected java.util.HashMap<java.lang.String,​java.util.List<Extraction>> extractionCandidatesFromApiResponse​(@NonNull
                                                                                                                   org.json.JSONObject responseData)
                                                                                                            throws org.json.JSONException
        Helper method which takes the JSON response of the Gini API as input and returns a mapping where the key is the name of the candidates list (e.g. "amounts" or "dates") and the value is a list of extraction instances.
        Parameters:
        responseData - The JSON data of the key candidates from the response of the Gini API.
        Returns:
        The created mapping as described above.
        Throws:
        org.json.JSONException - If the JSON data does not have the expected structure or if there is invalid data.

      • extractionFromApiResponse

        protected Extraction extractionFromApiResponse​(@NonNull
                                               org.json.JSONObject responseData)
                                        throws org.json.JSONException
        Helper method which creates an Extraction instance from the JSON data which is returned by the Gini API.
        Parameters:
        responseData - The JSON data.
        Returns:
        The created Extraction instance.
        Throws:
        org.json.JSONException - If the JSON data does not have the expected structure or if there is invalid data.