lv.pasts.eme.edoc

## Interface EDOC

-     public interface EDOC

  An `EDOC` class represents the EDOC 1.0 document format.

  An instance of `EDOC` class can be obtained using the `EDOCBuilder` class.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `EDOCDataFile` | `addFile(File file)` Adds a new file to the existing `EDOC` data file list.
    `EDOCDataFile` | `addFile(String pathname)` Adds a new file to the existing `EDOC` data file list.
    `EDOCDataFile` | `addFile(String name, byte[] data, String contentType)` Adds a new file to the existing `EDOC` data file list.
    `EDOCDataFile` | `addFile(URL url)` Adds a new file to the existing `EDOC` data file list.
    `EDOCSignature` | `addSignature(EDOCSignatureContext edocSignatureContext)` Adds a new signature to the existing `EDOC` signature list.
    `EDOCSignature` | `addSignature(KeyAccessor keyAccessor, EDOCSignatureCallback edocSignatureCallback)` Adds a new signature to the existing `EDOC` signature list.
    `void` | `close()` Closes this `EDOC` file and releases associated system resources.
    `boolean` | `containsFile(String name)` Returns true if a file with the specified name is contained by this EDOC.
    `EDOCProperties` | `getBaseProperties()` Returns `EDOC` base properties.
    `EDOCProperties` | `getCoreProperties()` Returns `EDOC` core properties.
    `EDOCProperties` | `getExtendedProperties()` Returns `EDOC` extended properties.
    `EDOCDataFile` | `getFile(String name)` Returns the data file by the specified name.
    `int` | `getFileCount()` Returns the number of files in this EDOC.
    `EDOCDataFile[]` | `getFiles()` Returns an array of data files in this EDOC.
    `String` | `getName()` Returns the name of this EDOC file.
    `EDOCSignature` | `getSignature(String id)` Returns the signature by the specified id.
    `int` | `getSignatureCount()` Returns the number of signatures in this EDOC.
    `EDOCSignature[]` | `getSignatures()` Returns an array of signatures in this EDOC.
    `EDOCTemplate` | `getTemplate()` Returns the template used to create this `EDOC` file.
    `EDOCPreparedSignature` | `prepareSignature(SignatureType signatureType, X509Certificate certificate)` Prepares a new signature for this `EDOC` instance.
    `void` | `removeFile(String name)` Removes `EDOCDataFile` object from the existing `EDOC` data file list.
    `void` | `removeSignature(String id)` Removes `EDOCSignature` object from the existing `EDOC` signature list.
    `void` | `saveTo(File file)` Saves this EDOC file to the given file.
    `void` | `saveTo(File file, int zipCompressionLevel)` Saves this EDOC file to the given file using the given ZIP compression level.
    `void` | `saveTo(OutputStream outputStream)` Saves this EDOC file to the given output stream.
    `void` | `saveTo(OutputStream outputStream, int zipCompressionLevel)` Saves this EDOC file to the given output stream using the given ZIP compression level.
    `EDOCValidatorResult` | `validate(EDOCValidatorListener listener)` Validates this `EDOC` document.

- - ### Method Detail

    - #### getFileCount

          int getFileCount()

      Returns the number of files in this EDOC.
      Returns:
        the number of files in this EDOC.

    - #### getFiles

          EDOCDataFile[] getFiles()

      Returns an array of data files in this EDOC.
      Returns:
        an array of `EDOCDataFile` objects in this EDOC (may be empty, but not null).

    - #### getFile

          EDOCDataFile getFile(String name)
                        throws EDOCException

      Returns the data file by the specified name.
      Parameters:
        `name` - the name of `EDOCDataFile` to be returned.
      Returns:
        the `EDOCDataFile` object by the specified name.
      Throws:
        `EDOCException` - if file with the specified name does not exist.

    - #### containsFile

          boolean containsFile(String name)

      Returns true if a file with the specified name is contained by this EDOC.
      Parameters:
        `name` - the name of `EDOCDataFile` to be checked.
      Returns:
        true if a file with the specified name is contained by this EDOC.

    - #### addFile

          EDOCDataFile addFile(String pathname)
                        throws EDOCException

      Adds a new file to the existing `EDOC` data file list.
      Parameters:
        `pathname` - an abstract pathname denoting the file to add.
      Returns:
        the newly-created `EDOCDataFile` object.
      Throws:
        `EDOCException` - if file with the same name is already added, `EDOC` alrady contains `EDOCSignature`, or file by the specified pathname cannot be read.

    - #### addFile

          EDOCDataFile addFile(File file)
                        throws EDOCException

      Adds a new file to the existing `EDOC` data file list.
      Parameters:
        `file` - a `File` object denoting the file to add.
      Returns:
        the newly-created `EDOCDataFile` object.
      Throws:
        `EDOCException` - if file with the same name is already added, `EDOC` alrady contains `EDOCSignature`, or the specified `File` cannot be read.

    - #### addFile

          EDOCDataFile addFile(URL url)
                        throws EDOCException

      Adds a new file to the existing `EDOC` data file list.
      Parameters:
        `url` - an `URL` object representing the file to add.
      Returns:
        the newly-created `EDOCDataFile` object.
      Throws:
        `EDOCException` - if file with the same name is already added, `EDOC` alrady contains `EDOCSignature`, or file from the specified `URL` cannot be read.

    - #### addFile

          EDOCDataFile addFile(String name,
                               byte[] data,
                               String contentType)
                        throws EDOCException

      Adds a new file to the existing `EDOC` data file list.
      Parameters:
        `name` - name of the file to add.
        `data` - byte array representing the file to add.
        `contentType` - the content type of the file to add.
      Returns:
        the newly-created `EDOCDataFile` object.
      Throws:
        `EDOCException` - if file with the same name is already added, or `EDOC` alrady contains `EDOCSignature`.

    - #### removeFile

          void removeFile(String name)
                   throws EDOCException

      Removes `EDOCDataFile` object from the existing `EDOC` data file list.
      Parameters:
        `name` - the name of `EDOCDataFile` to be removed.
      Throws:
        `EDOCException` - if data file cannot be deleted, or `EDOC` alrady contains `EDOCSignature`.

    - #### getSignatureCount

          int getSignatureCount()

      Returns the number of signatures in this EDOC.
      Returns:
        the number of signatures in this EDOC.

    - #### getSignatures

          EDOCSignature[] getSignatures()

      Returns an array of signatures in this EDOC.
      Returns:
        an array of `EDOCSignature` objects in this EDOC (may be empty, but not null).

    - #### getSignature

          EDOCSignature getSignature(String id)
                              throws EDOCException

      Returns the signature by the specified id.
      Parameters:
        `id` - the id of `EDOCSignature` to be returned.
      Returns:
        the `EDOCSignature` object by the specified id.
      Throws:
        `EDOCException` - if signature with the specified id does not exist.

    - #### addSignature

          EDOCSignature addSignature(KeyAccessor keyAccessor,
                                     EDOCSignatureCallback edocSignatureCallback)
                              throws EDOCException

      Adds a new signature to the existing `EDOC` signature list.

      A `KeyAccessor` is used to access the document signing certificate. Optionally a client authentication certificate can be required when requesting a timestamp from the timestamping authority (TSA).

      While creating the signature a communication with the user is required, therefore you must specify an instance of `EDOCSignatureCallback` object which implements the required callback methods.

      Parameters:
        `keyAccessor` - a `KeyAccessor` instance used to access cryptographic keys and certificates.
        `edocSignatureCallback` - callback object used to get user input.
      Returns:
        the newly-created `EDOCSignature` object.
      Throws:
        `EDOCException` - if signature cannot be created.
      Since:
        1.3.3

    - #### addSignature

          EDOCSignature addSignature(EDOCSignatureContext edocSignatureContext)
                              throws EDOCException

      Adds a new signature to the existing `EDOC` signature list.
      Parameters:
        `edocSignatureContext` - EDOC signature context.
      Returns:
        the newly-created `EDOCSignature` object.
      Throws:
        `EDOCException` - if signature cannot be created.
      Since:
        1.4.2

    - #### prepareSignature

          EDOCPreparedSignature prepareSignature(SignatureType signatureType,
                                                 X509Certificate certificate)
                                          throws EDOCException

      Prepares a new signature for this `EDOC` instance.

      The signature value for `EDOCPreparedSignature` is not calculated automatically and must be provided using the `EDOCPreparedSignature.setSignatureValue(byte[])` method.

      In order to add another signature or save the `EDOC` document, the current `EDOCPreparedSignature` must be completed using the `EDOCPreparedSignature.complete()` method.

      Parameters:
        `signatureType` - the desired signature type.

        The signature level must be specified using the `SignatureType.setSignatureLevel(int)` method.

        `certificate` - the document signing certificate.
      Returns:
        the newly-created `EDOCPreparedSignature` object.
      Throws:
        `EDOCException` - if signature cannot be prepared.
      Since:
        2.1.0

    - #### removeSignature

          void removeSignature(String id)
                        throws EDOCException

      Removes `EDOCSignature` object from the existing `EDOC` signature list. If there are more signatures, only the last one can be removed.
      Parameters:
        `id` - the id of `EDOCSignature` to be removed.
      Throws:
        `EDOCException` - if signature cannot be removed.

    - #### getCoreProperties

          EDOCProperties getCoreProperties()

      Returns `EDOC` core properties.
      Returns:
        the `EDOCProperties` object containing core properties.

    - #### getBaseProperties

          EDOCProperties getBaseProperties()

      Returns `EDOC` base properties.
      Returns:
        the `EDOCProperties` object containing base properties.

    - #### getExtendedProperties

          EDOCProperties getExtendedProperties()

      Returns `EDOC` extended properties.
      Returns:
        the `EDOCProperties` object containing extended properties.

    - #### getTemplate

          EDOCTemplate getTemplate()

      Returns the template used to create this `EDOC` file.
      Returns:
        the `EDOCTemplate` object containing template information.

    - #### getName

          String getName()

      Returns the name of this EDOC file.
      Returns:
        the name of this `EDOC` file (never null).

    - #### saveTo

          void saveTo(File file)
               throws EDOCException

      Saves this EDOC file to the given file.
      Parameters:
        `file` - a file where this `EDOC` file should be saved.
      Throws:
        `EDOCException` - if this EDOC file cannot be saved.

    - #### saveTo

          void saveTo(File file,
                      int zipCompressionLevel)
               throws EDOCException

      Saves this EDOC file to the given file using the given ZIP compression level.
      Parameters:
        `file` - a file where this `EDOC` file should be saved.
        `zipCompressionLevel` - the ZIP compression level (0-9).
      Throws:
        `EDOCException` - if this EDOC file cannot be saved.
      Since:
        1.4.0

    - #### saveTo

          void saveTo(OutputStream outputStream)
               throws EDOCException

      Saves this EDOC file to the given output stream.
      Parameters:
        `outputStream` - an output stream where this `EDOC` file should be saved.
      Throws:
        `EDOCException` - if this EDOC file cannot be saved.

    - #### saveTo

          void saveTo(OutputStream outputStream,
                      int zipCompressionLevel)
               throws EDOCException

      Saves this EDOC file to the given output stream using the given ZIP compression level.
      Parameters:
        `outputStream` - an output stream where this `EDOC` file should be saved.
        `zipCompressionLevel` - the ZIP compression level (0-9).
      Throws:
        `EDOCException` - if this EDOC file cannot be saved.
      Since:
        1.4.0

    - #### validate

          EDOCValidatorResult validate(EDOCValidatorListener listener)
                                throws EDOCException

      Validates this `EDOC` document.

      To notify the user about the validation process, validation status events are generated. To get these notifications, an application must specify an instance of `EDOCValidatorListener` object which implements the required listener methods.

      Parameters:
        `listener` - the EDOCValidatorListener to be notified.
      Returns:
        the result of the validation process.
      Throws:
        `EDOCException` - if EDOC validation cannot be performed.

    - #### close

          void close()
              throws EDOCException

      Closes this `EDOC` file and releases associated system resources.
      Throws:
        `EDOCException` - if associated system resources cannot be released.

Copyright VAS Latvijas Valsts radio un televizijas centrs / Developed by SIA EUSO