Package com.sas.lsaf.content.repository.signature

## Interface SignatureService

-     public interface SignatureService

  The service to create and retrieve signature information for files in the repository.

  Signatures represent a "stamp" for a specific user for a specific version of a file. For example, the signature can represent an approval (or disapproval) of a specific version of a file by a specific user. The signature can enable administrative users to track the viability of a version of a file through a loosely-defined approval process. The signature can be used to track an overall sign-off process that enables users to promote (or demote) specific files in a production environment. This is one example of the way that signatures can be used.

  Repository files can be either versioned or not versioned when they are signed. Containers cannot be signed.

  When an unversioned file is updated or deleted, all of the signatures are removed. Because signatures are tied to a specific version of a file, the signatures are linked to that content's lifecycle. When a new version of a versioned file is created, the signatures that are associated with the prior version are kept and are accessible because the prior version is maintained within the repository. If a versioned file is deleted, all of the signatures are removed.

  Since:
    1.7

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Signature` | `createSignature​(java.lang.String path, CreateSignatureInfo createSignatureInfo)` | Creates a signature for the current version of a file (only the current version of a file can be signed).
    `java.util.Set<java.lang.String>` | `getSignatureReasons()` | Gets all of the valid signature reasons that can be used to populate a `CreateSignatureInfo` object to create a signature.
    `java.util.Set<java.lang.String>` | `getSignatureRoles()` | Gets all of the valid signature roles that can be used to populate a `CreateSignatureInfo` object to create a signature.
    `java.util.Set<Signature>` | `getSignatures​(java.lang.String path)` | Gets all of the signatures that are associated with a file.
    `java.util.Set<Signature>` | `getSignaturesByVersion​(java.lang.String path, java.lang.String version)` | Gets all of the the signatures for a specific version of a file.
    `java.util.Set<Signature>` | `getSignaturesForLatestVersion​(java.lang.String path)` | Gets all of the signatures for the latest version of a file.
    `RepositoryFile.SigningStatus` | `getSigningStatus​(java.lang.String path)` | Describes the overall signature status of the file.
    `boolean` | `isVersionSigned​(java.lang.String path, java.lang.String version)` | Indicates whether a signatures exists for the specific version of a file.

- - ### Method Detail

    - #### getSignatureReasons

          java.util.Set<java.lang.String> getSignatureReasons()

      Gets all of the valid signature reasons that can be used to populate a `CreateSignatureInfo` object to create a signature. The set of reasons is configured on the server and is used to validate a signature.
      Returns:
        The set of valid signature reasons.
      Since:
        1.7
      See Also:
        `createSignature(String, CreateSignatureInfo)`

    - #### getSignatureRoles

          java.util.Set<java.lang.String> getSignatureRoles()

      Gets all of the valid signature roles that can be used to populate a `CreateSignatureInfo` object to create a signature. The set of roles is configured on the server and is used to validate a signature.
      Returns:
        The set of valid signature roles.
      Since:
        1.7
      See Also:
        `createSignature(String, CreateSignatureInfo)`

    - #### createSignature

          Signature createSignature​(java.lang.String path,
                                    CreateSignatureInfo createSignatureInfo)
                             throws AuthenticationException,
                                    SigningException

      Creates a signature for the current version of a file (only the current version of a file can be signed). The `CreateSignatureInfo` object must contain the valid credentials of the user who signs the file. The credentials are used to verify the authenticity of the signer, so issues that arise when authenticating the signer generate an `AuthenticationException`.

      The signing parameters supplied in the `CreateSignatureInfo` object are stored with the signature and are used to generate the signature value itself. The signature metadata not only describes the signature itself, it is used in the cryptography to generate the signature value. Therefore, the signature is self-describing and self-validating.

      The signature role that is specified on the `CreateSignatureInfo` object is required and must be a valid signing role that matches a value from `getSignatureRoles()`. The signature reason that is specified in the `CreateSignatureInfo` object is required and must be a valid signing reason that matches a value from `getSignatureReasons()`.

      Parameters:
        `path` - The path to the file to sign.
        `createSignatureInfo` - The parameters to use to create the signature, which includes the credentials of the signer.
      Returns:
        The `Signature` object to create.
      Throws:
        `AuthenticationException` - Thrown when the credentials presented are incorrect or the account to use is locked, expired, or inactive.
        `SigningException` - Thrown when the signature generation process fails.
      Since:
        1.7
      See Also:
        `getSignatureRoles()`, `getSignatureReasons()`

    - #### getSigningStatus

          RepositoryFile.SigningStatus getSigningStatus​(java.lang.String path)
                                                 throws RepositoryItemNotFoundException

      Describes the overall signature status of the file. If the file is versioned, the possible values are `NONE`, `CURRENT`, `PREVIOUS`, and `CURRENT_AND_PREVIOUS`. `CURRENT` means that the current version is signed and no previous version is signed. `PREVIOUS` means that at least one previous version of the file is signed and the current version is not signed. `CURRENT_AND_PREVIOUS` means that the current version is signed and at least one previous version is signed.

      If the file is not versioned, the possible values are `NONE` and `CURRENT`.

      Parameters:
        `path` - The path to the file.
      Throws:
        `RepositoryItemNotFoundException` - Thrown when the file does not exist.
      Since:
        2.1

    - #### isVersionSigned

          boolean isVersionSigned​(java.lang.String path,
                                  java.lang.String version)

      Indicates whether a signatures exists for the specific version of a file. If the path does not exist, references an object that is not a file, or is for an unversioned file, then `False` is returned. The version must be a valid repository file version label, such as one returned by calling `RepositoryFile.getVersion()`.
      Parameters:
        `path` - The path to the file.
        `version` - The version of the file.
      Returns:
        `True`, if signatures exist for the version of the file, `False` otherwise.
      Since:
        1.7
      See Also:
        `RepositoryFile.getVersion()`

    - #### getSignatures

          java.util.Set<Signature> getSignatures​(java.lang.String path)
                                          throws RepositoryItemNotFoundException

      Gets all of the signatures that are associated with a file. For an unversioned file, all of the current signatures are retrieved. For a versioned file, all of the signatures for all of the versions are retrieved. If the path is to a container, then an `IllegalArgumentException` is thrown because container objects cannot be signed.

      If the path does not exist, a `RepositoryItemNotFoundException` is thrown.

      Parameters:
        `path` - The path to the file.
      Returns:
        The `set` of signatures that correspond to all versions of the file.
      Throws:
        `RepositoryItemNotFoundException` - Thrown when the file does not exist.
      Since:
        1.7

    - #### getSignaturesForLatestVersion

          java.util.Set<Signature> getSignaturesForLatestVersion​(java.lang.String path)
                                                          throws RepositoryItemNotFoundException

      Gets all of the signatures for the latest version of a file. The file can be versioned or unversioned, the current version is used in both cases. If the path is to a container, then an `IllegalArgumentException` is thrown because container objects cannot be signed.

      If the path does not exist, a `RepositoryItemNotFoundException` is thrown.

      Parameters:
        `path` - The path to the file.
      Returns:
        The `set` of signatures that were created for the current version of the file.
      Throws:
        `RepositoryItemNotFoundException` - Thrown when the file does not exist.
      Since:
        1.7

    - #### getSignaturesByVersion

          java.util.Set<Signature> getSignaturesByVersion​(java.lang.String path,
                                                          java.lang.String version)
                                                   throws RepositoryItemNotFoundException

      Gets all of the the signatures for a specific version of a file. If the path is to a container, then an `IllegalArgumentException` is thrown because container objects cannot be signed. The version must be a valid repository file version label, such as `RepositoryFile.getVersion()` .

      If the path does not exist, or the version does not exist, then a `RepositoryItemNotFoundException` is thrown.

      Parameters:
        `path` - The path to the file.
        `version` - The version of the file.
      Returns:
        The `set` of signatures that were created for the version of the file.
      Throws:
        `RepositoryItemNotFoundException` - Thrown when the file or version does not exist.
      Since:
        1.7
      See Also:
        `RepositoryFile.getVersion()`