com.sas.hls.resource.repository
Interface SignatureService


public interface SignatureService

A service for creating and retrieving electronic signature information for file resources in the repository.

Electronic signatures, in this sense, represent a "stamp" for a particular user for a particular version of a file. For example, this "stamp" can represent an approval (or disapproval) of a particular version of a file by a specific user which can enable administrative users to track the viability of a version of a file through a loosely-defined approval process. This "stamp" can be used to track an overall sign-off process which enables users to promote (or demote) specific files in a production environment. This is only one example of how this functionality can be used by end-users.

Repository files can be either versioned or unversioned when undergoing a signature process, but containers can never be signed.

When an unversioned file is updated or deleted, all of it's electronic signatures will be removed automatically. Since signatures are tied to a particular version of a file, the signatures are linked to that content's lifecycle. When a new version of a versioned file is created, the electronic signatures associated with the prior version are kept and are accessible since the prior version is maintained within the repository. If the versioned file is deleted, all of the electronic signatures are removed form the system as well.


Method Summary
 Signature createSignature(String path, CreateSignatureInfo createSignatureInfo)
          Create an electronic signature for the current version of a file (only the current version of a file can be electronically signed).
 Set<String> getSignatureReasons()
          Retrieve all of the valid signature reasons that can be used when populating a CreateSignatureInfo object to create an electronic signature on a repository file.
 Set<String> getSignatureRoles()
          Retrieve all of the valid signature roles that can be used when populating a CreateSignatureInfo object to create an electronic signature on a repository file.
 Set<Signature> getSignatures(String path)
          Retrieve all the electronic signatures associated to a file in the repository.
 Set<Signature> getSignaturesByVersion(String path, String version)
          Retrieve the electronic signatures for a specific version of a file in the repository.
 Set<Signature> getSignaturesForLatestVersion(String path)
          Retrieve the electronic signatures for the latest version of a file in the repository.
 boolean isLatestVersionSigned(String path)
          Determine if any electronic signatures exist for the latest version of a file in the repository.
 boolean isSigned(String path)
          Determine if any electronic signatures exist for any version of a file in the repository.
 boolean isVersionSigned(String path, String version)
          Determine if any electronic signatures exist for a specific version of a file in the repository.
 

Method Detail

getSignatureReasons

Set<String> getSignatureReasons()
Retrieve all of the valid signature reasons that can be used when populating a CreateSignatureInfo object to create an electronic signature on a repository file. This Set of reasons are pre-configured on the server and will be used to validate any signature being created.

Returns:
The Set of valid signature reasons.
Since:
1.7
See Also:
createSignature(String, CreateSignatureInfo)

getSignatureRoles

Set<String> getSignatureRoles()
Retrieve all of the valid signature roles that can be used when populating a CreateSignatureInfo object to create an electronic signature on a repository file. This Set of roles are pre-configured on the server and will be used to validate any signature being created.

Returns:
The Set of valid signature roles.
Since:
1.7
See Also:
createSignature(String, CreateSignatureInfo)

createSignature

Signature createSignature(String path,
                          CreateSignatureInfo createSignatureInfo)
                          throws AuthenticationException,
                                 RepositoryResourceNotFoundException,
                                 SigningException
Create an electronic signature for the current version of a file (only the current version of a file can be electronically signed). The CreateSignatureInfo object must contain the valid credentials of the user signing the file. The credentials will be used to verify the authenticity of the signer so any issues authenticating the signer will generate an AuthenticationException.

The signing parameters supplied in the CreateSignatureInfo object will be stored with the electronic signature and be used in generating the signature value itself. This signature metadata not only describes the signature itself, but is used in the cryptography of generating the signature value. Thereby, the signature is self-describing and self-validating.

The signature role specified on the CreateSignatureInfo object is required and must be a valid signing role matching a value from getSignatureRoles(). The signature reason specified on the CreateSignatureInfo object is required and must be a valid signing reason matching a value from getSignatureReasons(). The signature comment is optional.

Parameters:
path - The path to the file to be signed.
createSignatureInfo - The parameters to be used in creating the signature, including the credentials of the signer.
Returns:
The Signature object created.
Throws:
AuthenticationException - Thrown if the credentials presented are incorrect, or the account being used is locked, expired or inactive.
RepositoryResourceNotFoundException - Thrown if the file does not exist.
SigningException - Thrown if the signature generation process fails.
IllegalPathException - Thrown if the path is to a non-file object.
Since:
1.7
See Also:
getSignatureRoles(), getSignatureReasons()

isSigned

boolean isSigned(String path)
Determine if any electronic signatures exist for any version of a file in the repository. For unversioned files, the current file version will be used. If the file is versioned, all of the existing versions will be used. If the path does not exist, or is for a non-file object then false will be returned.

Parameters:
path - The path to the file.
Returns:
true if signatures exist for any version of the file, false otherwise.
Since:
1.7

isLatestVersionSigned

boolean isLatestVersionSigned(String path)
Determine if any electronic signatures exist for the latest version of a file in the repository. The file can be versioned or unversioned for this method, the current version will be used in both cases. If the path does not exist, or is for a non-file object then false will be returned.

Parameters:
path - The path to the file.
Returns:
true if signatures exist for the current version of the file, false otherwise.
Since:
1.7

isVersionSigned

boolean isVersionSigned(String path,
                        String version)
Determine if any electronic signatures exist for a specific version of a file in the repository. If the path does not exist, or is for a non-file object, or is for an unversioned file then false will be returned. The version passed must a valid repository file version label such as RepositoryFile.getVersionLabel() .

Parameters:
path - The path to the file.
version - The version of the file to check.
Returns:
true if signatures exist for this version of the file, false otherwise.
Since:
1.7
See Also:
RepositoryFile.getVersionLabel()

getSignatures

Set<Signature> getSignatures(String path)
                             throws RepositoryResourceNotFoundException
Retrieve all the electronic signatures associated to a file in the repository. For unversioned files, all of the current signatures will be retrieved. If the file is versioned, all of the signatures for all of the versions will be retrieved. If the path presented is to a container then an IllegalPathException will be thrown since container objects cannot be electronically signed.

If the path does not exist a RepositoryResourceNotFoundException will be thrown.

Parameters:
path - The path to the file.
Returns:
The Set of signatures that correspond to all versions of the specified file.
Throws:
RepositoryResourceNotFoundException - Thrown if the file does not exist.
IllegalPathException - Thrown if the path is to a non-file object.
Since:
1.7

getSignaturesForLatestVersion

Set<Signature> getSignaturesForLatestVersion(String path)
                                             throws RepositoryResourceNotFoundException
Retrieve the electronic signatures for the latest version of a file in the repository. The file can be versioned or unversioned for this method, the current version will be used in both cases. If the path presented is to a container then an IllegalPathException will be thrown since container objects cannot be electronically signed.

If the path does not exist a RepositoryResourceNotFoundException will be thrown.

Parameters:
path - The path to the file.
Returns:
The Set of signatures that were created for the current version of the file.
Throws:
RepositoryResourceNotFoundException - Thrown if the file does not exist.
IllegalPathException - Thrown if the path is to a non-file object.
Since:
1.7

getSignaturesByVersion

Set<Signature> getSignaturesByVersion(String path,
                                      String version)
                                      throws RepositoryResourceNotFoundException
Retrieve the electronic signatures for a specific version of a file in the repository. If the path presented is to a container then an IllegalPathException will be thrown since container objects cannot be electronically signed. If the path presented is to an unversioned file then an IllegalPathException will be thrown. The version passed must a valid repository file version label such as RepositoryFile.getVersionLabel() .

If the path does not exist, or the version does not exist then a RepositoryResourceNotFoundException will be thrown.

Parameters:
path - The path to the file.
version - The version of the file to use.
Returns:
The Set of signatures that were created for this particular version of the file.
Throws:
RepositoryResourceNotFoundException - Thrown if the file or version does not exist.
IllegalPathException - Thrown if the path is to a non-file object or a file which is not versioned.
Since:
1.7
See Also:
RepositoryFile.getVersionLabel()


Copyright (c) 2014, SAS Institute Inc., Cary, NC, USA