com.adobe.livecycle.rightsmanagement.client
Interface DocumentManager


public interface DocumentManager

The DocumentManager interface provides methods for manipulating the policy security of documents. You can use DocumentManager to secure documents with policies, remove security from documents secured with policies, and to obtain the licenses for policy-secured documents.

To see an instance of this type used in a code example, see the Applying a policy to a PDF document using the Java API quick start in Programming with LiveCycle ES4.


Method Summary
 Document applyPolicy(Document inPDFDoc, java.lang.String documentName, java.lang.String policySetName, java.lang.String policyName, java.lang.String pubDomain, java.lang.String pubUsername)
          Deprecated. use protectDocument
 void associateUserWithLicenseAndPolicy(java.lang.String domain, java.lang.String userId, java.lang.String licenseId, java.lang.String policyId)
          Associates the user specified with the domain and userid with the supplied licenseId and policyId
 PublishLicenseDTO createLicense(java.lang.String policyId, java.lang.String publishUserId, java.lang.String publishUserDomain)
          Creates a publish license for the specified user and policy combination
 Document extractProtectedDocument(Document inPDFDoc)
          Extracts the protected document which is an attachment in the document with cover page.
 java.lang.String getLicenseId(Document inPDFDoc)
          Retrieves the license identifier value for the specified secure document.
 PublishLicenseDTO getPublishLicenseForUser(java.lang.String domain, java.lang.String userId)
          Fetches the com.adobe.edc.common.dto.PublishLicenseDTO that contains the information required for protecting a document
 RMInspectResult inspectDocument(Document inDoc)
          Retrieves the license information and other details for the specified protected document.
 RMSecureDocumentResult protectDocument(Document inDoc, PublishLicenseDTO publishLicense)
          Secures a given PDF or Office document with the specified license.
 RMSecureDocumentResult protectDocument(Document inPDFDoc, java.lang.String documentName, java.lang.String policySetName, java.lang.String policyName, java.lang.String pubDomain, java.lang.String pubUsername, RMLocale locale)
          Secures a given PDF or Office document with the specified policy.
 RMSecureDocumentResult protectDocument(Document inPDFDoc, java.lang.String documentName, java.lang.String policySetName, java.lang.String policyName, java.lang.String pubDomain, java.lang.String pubUsername, RMLocale locale, boolean bExactMatchForNames)
          Secures a given PDF or Office document with the specified policy.
 RMSecureDocumentResult protectDocumentWithCoverPage(Document inPDFDoc, java.lang.String documentName, java.lang.String policySetName, java.lang.String policyName, java.lang.String pubDomain, java.lang.String pubUsername, Document coverPDFDoc, boolean bExactMatchForNames)
          Secures a given PDF with the specified policy, and returns a document with a cover page and the protected document as an attachment.
 Document removeSecurity(Document inPDFDoc)
          Removes the security from a policy-protected document provided that a super administrator is used in connection settings.
 Document unlockPDF(Document inPDFDoc)
          Unlocks a policy-protected document.
 

Method Detail

getLicenseId

java.lang.String getLicenseId(Document inPDFDoc)
                              throws SDKException
Retrieves the license identifier value for the specified secure document. You retrieve a license identifier value when you want to perform a task, such as revoking a policy-protected document. To see this method used in a code example, see the Revoking a document using the Java API quick start in Programming with LiveCycle ES4.

Parameters:
inPDFDoc - A com.adobe.idp.Document object that represents the policy-protected document from which to extract the license. This value must represent a document that was secured using the Rights Management service.
Returns:
A unique java.lang.String identifier for the com.adobe.livecycle.rightsmanagement.client.infomodel.License object associated with the specified document. Note: Document publishers can dynamically change policies for documents that they have published. Use the LicenseManager.getLicense(String) method to retrieve the License object from the server.
Throws:
SDKException - if any of the following conditions occur:
  • The file specified is not a policy-protected file.
  • The packager component is not installed.
  • An error occurred while communicating with the Rights Management service.
  • In LC 8.0.x releases this API will throw SDKException.E_INVALID_FILE error code instead of SDKException.E_INVALID_ARG in case PDF is not encrypted

inspectDocument

RMInspectResult inspectDocument(Document inDoc)
                                throws SDKException
Retrieves the license information and other details for the specified protected document.

Parameters:
inDoc - A com.adobe.idp.Document object that represents the policy-protected document from which to extract the license. This value must represent a PDF or MS-Office file that was secured using the Rights Management service.
Returns:
A com.adobe.livecycle.rightsmanagement.RMInspectResult object associated with the specified document.
Throws:
SDKException - if any of the following conditions occur:
  • The file specified is not a policy-protected file.
  • The packager component is not installed.
  • An error occurred while communicating with the Rights Management service.

applyPolicy

Document applyPolicy(Document inPDFDoc,
                     java.lang.String documentName,
                     java.lang.String policySetName,
                     java.lang.String policyName,
                     java.lang.String pubDomain,
                     java.lang.String pubUsername)
                     throws SDKException
Deprecated. use protectDocument

Secures a given PDF document with the specified policy. The pubDomain and pubUsername parameters must either be a valid domain name and valid username, or both must be null. If you invoke this method with only one of the two being null, you will cause an exception. Also, an invalid or blank domain name, or an invalid or blank username will also cause an exception.

To see this method used in a code example, see the Applying a policy to a PDF document using the Java API quick start in Programming with LiveCycle ES4.

Parameters:
inPDFDoc - A Document object that represents the PDF document to secure with the policy.
documentName - A java.lang.String that contains the name of the document. This value can have a maximum length of 255 single-byte characters.
policySetName - A java.lang.String that specifies the policy set to use to secure the document. If this parameter value is null, then the My Policies policy set is used.
policyName - A java.lang.String that specifies the name of the policy to use to secure the document.
pubDomain - A java.lang.String that represents the name of the User Manager domain of the user who is the publisher of the document. This parameter value is optional.
pubUsername - A java.lang.String that represents the canonical name of the User Manager user who is the publisher of the document. This parameter value is optional.
Returns:
A Document object that represents the policy-protected PDF document.
Throws:
SDKException - if any of the following conditions occur:
  • A parameter is invalid.
  • An error occurred while communicating with the Rights Management service.
  • An error occurred while securing the document.
See Also:
DocumentManager

protectDocument

RMSecureDocumentResult protectDocument(Document inPDFDoc,
                                       java.lang.String documentName,
                                       java.lang.String policySetName,
                                       java.lang.String policyName,
                                       java.lang.String pubDomain,
                                       java.lang.String pubUsername,
                                       RMLocale locale)
                                       throws SDKException
Secures a given PDF or Office document with the specified policy. The pubDomain and pubUsername parameters must either be a valid domain name and valid username, or both must be null. If you invoke this method with only one of the two being null, you will cause an exception. Also, an invalid or blank domain name, or an invalid or blank username will also cause an exception.

To see this method used in a code example that secures a PDF document, see the Applying a policy to a PDF document using the Java API quick start in Programming with LiveCycle ES4.

To see this method used in a code example that secures a Word document, see the Applying a policy to a Word document using the Java API quick start in Programming with LiveCycle ES4.

Parameters:
inPDFDoc - A Document object that represents the PDF or MS Office document to secure with the policy.
documentName - A java.lang.String that contains the name of the document. This value can have a maximum length of 255 single-byte characters.
policySetName - A java.lang.String that specifies the policy set to use to secure the document. If this parameter value is null, then the My Policies policy set is used.
policyName - A java.lang.String that specifies the name of the policy to use to secure the document.
pubDomain - A java.lang.String that represents the name of the User Manager domain of the user who is the publisher of the document. This parameter value is optional. If this parameter is set, then the pubUsername parameter must be set. Otherwise, both of these parameters can be null.
pubUsername - A java.lang.String that represents the canonical name of the User Manager user who is the publisher of the document. This parameter value is optional. If this parameter is set, then the pubDomain parameter must be set. Otherwise, both of these parameters can be null.
locale - A com.adobe.livecycle.rightsmanagement.Locale that represents the locale to be used for selecting the MS Office template. This parameter value is optional and not used for PDF documents.
Returns:
A com.adobe.livecycle.rightsmanagement.RMSecureDocumentResult object that represents the policy-protected document and other meta data.
Throws:
SDKException - if any of the following conditions occur:
  • A parameter is invalid.
  • An error occurred while communicating with the Rights Management service.
  • An error occurred while securing the document.
See Also:
DocumentManager

protectDocument

RMSecureDocumentResult protectDocument(Document inPDFDoc,
                                       java.lang.String documentName,
                                       java.lang.String policySetName,
                                       java.lang.String policyName,
                                       java.lang.String pubDomain,
                                       java.lang.String pubUsername,
                                       RMLocale locale,
                                       boolean bExactMatchForNames)
                                       throws SDKException
Secures a given PDF or Office document with the specified policy. The pubDomain and pubUsername parameters must either be a valid domain name and valid username, or both must be null. If you invoke this method with only one of the two being null, you will cause an exception. Also, an invalid or blank domain name, or an invalid or blank username will also cause an exception.

To see this method used in a code example that secures a PDF document, see the Applying a policy to a PDF document using the Java API quick start in Programming with LiveCycle ES4.

To see this method used in a code example that secures a Word document, see the Applying a policy to a Word document using the Java API quick start in Programming with LiveCycle ES4.

Parameters:
inPDFDoc - A Document object that represents the PDF or MS Office document to secure with the policy.
documentName - A java.lang.String that contains the name of the document. This value can have a maximum length of 255 single-byte characters.
policySetName - A java.lang.String that specifies the policy set to use to secure the document. If this parameter value is null, then the My Policies policy set is used.
policyName - A java.lang.String that specifies the name of the policy to use to secure the document.
pubDomain - A java.lang.String that represents the name of the User Manager domain of the user who is the publisher of the document. This parameter value is optional. If this parameter is set, then the pubUsername parameter must be set. Otherwise, both of these parameters can be null.
pubUsername - A java.lang.String that represents the canonical name of the User Manager user who is the publisher of the document. This parameter value is optional. If this parameter is set, then the pubDomain parameter must be set. Otherwise, both of these parameters can be null.
locale - A com.adobe.livecycle.rightsmanagement.Locale that represents the locale to be used for selecting the MS Office template. This parameter value is optional and not used for PDF documents.
bExactMatchForNames - A java.lang.Boolean that tells if exact name should be used while searching the policy. The default is false. It is recommended to use true for better performance.
Returns:
A com.adobe.livecycle.rightsmanagement.RMSecureDocumentResult object that represents the policy-protected document and other meta data.
Throws:
SDKException - if any of the following conditions occur:
  • A parameter is invalid.
  • An error occurred while communicating with the Rights Management service.
  • An error occurred while securing the document.
See Also:
DocumentManager

protectDocumentWithCoverPage

RMSecureDocumentResult protectDocumentWithCoverPage(Document inPDFDoc,
                                                    java.lang.String documentName,
                                                    java.lang.String policySetName,
                                                    java.lang.String policyName,
                                                    java.lang.String pubDomain,
                                                    java.lang.String pubUsername,
                                                    Document coverPDFDoc,
                                                    boolean bExactMatchForNames)
                                                    throws SDKException
Secures a given PDF with the specified policy, and returns a document with a cover page and the protected document as an attachment. The pubDomain and pubUsername parameters must either be a valid domain name and valid username, or both must be null. If you invoke this method with only one of the two being null, you will cause an exception. Also, an invalid or blank domain name, or an invalid or blank username will also cause an exception.

Parameters:
inPDFDoc - A Document object that represents the PDF document to secure with the policy.
documentName - A java.lang.String that contains the name of the document. This value can have a maximum length of 255 single-byte characters.
policySetName - A java.lang.String that specifies the policy set to use to secure the document. If this parameter value is null, then the My Policies policy set is used.
policyName - A java.lang.String that specifies the name of the policy to use to secure the document.
pubDomain - A java.lang.String that represents the name of the User Manager domain of the user who is the publisher of the document. This parameter value is optional. If this parameter is set, then the pubUsername parameter must be set. Otherwise, both of these parameters can be null.
pubUsername - A java.lang.String that represents the canonical name of the User Manager user who is the publisher of the document. This parameter value is optional. If this parameter is set, then the pubDomain parameter must be set. Otherwise, both of these parameters can be null.
coverPDFDoc - A Document object that represents the cover PDF document which will hold the protected document as an attachment.
bExactMatchForNames - A java.lang.Boolean that tells if exact name should be used while searching the policy. The default is false. It is recommended to use true for better performance.
Returns:
A com.adobe.livecycle.rightsmanagement.RMSecureDocumentResult object that represents the policy-protected document with the cover page and other meta data.
Throws:
SDKException - if any of the following conditions occur:
  • A parameter is invalid.
  • An error occurred while communicating with the Rights Management service.
  • An error occurred while securing the document.
See Also:
DocumentManager

removeSecurity

Document removeSecurity(Document inPDFDoc)
                        throws SDKException
Removes the security from a policy-protected document provided that a super administrator is used in connection settings. If not, then the policy used to secure a document must contain the SWITCH_POLICY permission in order for this method to remove the security from a PDF document. Also, the user specified in the LiveCycle ES2 connection settings must also have that permission. Otherwise, an exception is thrown. A user cannot open an unsecured PDF document until the returned document is written to a PDF or DOC file.

To see this method used in a code example that removes a policy from a PDF document, see the Removing a policy from a PDF document using the Java API quick start in Programming with LiveCycle ES4.

To see this method used in a code example that removes a policy from a Word document, see the Removing a policy from a Word document using the Java API quick start in Programming with LiveCycle ES4.

Parameters:
inPDFDoc - A Document object that represents the policy-protected document.
Returns:
A Document object that represents an unsecured document.
Throws:
SDKException - if any of the following conditions occur:
  • A parameter is invalid.
  • An error occurred while communicating with the Rights Management service.
  • An error occurred when removing the policy.

unlockPDF

Document unlockPDF(Document inPDFDoc)
                   throws SDKException
Unlocks a policy-protected document. You must unlock a policy-protected document in order to pass the document to another LiveCycle ES2 service. For example, before the Signatures service can sign a policy-protected document, it must be unlocked. This method only temporarily unlocks the document while a subsequent operation is performed. After the operation is performed, the Rights Management service secures the document.

Parameters:
inPDFDoc - A Document object that represents the policy-protected PDF document.
Returns:
A Document object that represents the resulting unlocked document.
Throws:
SDKException - if any of the following conditions occur:
  • A parameter is invalid.
  • An error occurred while communicating with the Rights Management service.
  • An error occurred while unlocking the document.

extractProtectedDocument

Document extractProtectedDocument(Document inPDFDoc)
                                  throws SDKException
Extracts the protected document which is an attachment in the document with cover page. The document with cover page can be created using protectDocumentWithCoverPage method.

Parameters:
inPDFDoc - A Document object that represents the cover PDF document holding the protected document as an attachment.
Returns:
A Document object that represents the protected document.
Throws:
SDKException - if any of the following conditions occur:
  • A parameter is invalid.
  • An error occurred while communicating with the Rights Management service.

protectDocument

RMSecureDocumentResult protectDocument(Document inDoc,
                                       PublishLicenseDTO publishLicense)
                                       throws SDKException
Secures a given PDF or Office document with the specified license.

Parameters:
inDoc - A Document object that represents the PDF or MS Office document to secure with the policy.
publishLicense - a com.adobe.edc.common.dto.PublishLicenseDTO that contains the information required for protecting the document.
Returns:
A com.adobe.livecycle.rightsmanagement.RMSecureDocumentResult object that represents the policy-protected document and other meta data.
Throws:
SDKException - if any of the following conditions occur:
  • A parameter is invalid.
  • An error occurred while communicating with the Rights Management service.
  • An error occurred while securing the document.

createLicense

PublishLicenseDTO createLicense(java.lang.String policyId,
                                java.lang.String publishUserId,
                                java.lang.String publishUserDomain)
                                throws SDKException
Creates a publish license for the specified user and policy combination

Parameters:
policyId - The policy id for which the license needs to be created
publishUserId - user id of the publisher
publishUserDomain - domain name for the publisher
Returns:
publishLicense a com.adobe.edc.common.dto.PublishLicenseDTO that contains the information required for protecting a document
Throws:
SDKException - if any of the following conditions occur:
  • A parameter is invalid.
  • An error occurred while communicating with the Rights Management service.
  • The user invoking the service doesnt have the publishing permission for the specified policy in the policy id.
See Also:
#protectDocument(com.adobe.idp.Document, com.adobe.edc.common.dto.PublishLicenseDTO)

associateUserWithLicenseAndPolicy

void associateUserWithLicenseAndPolicy(java.lang.String domain,
                                       java.lang.String userId,
                                       java.lang.String licenseId,
                                       java.lang.String policyId)
                                       throws SDKException
Associates the user specified with the domain and userid with the supplied licenseId and policyId

Parameters:
domain - name of the domain for the user for whom the license needs to be created
userId - user id of the user for whom the license needs to be created
licenseId - license id for the license which needs to be associated with the user
policyId - policy id for the policy which needs to be associated with the user
Throws:
SDKException - if any of the following conditions occur:
  • A parameter is invalid.
  • An error occurred while communicating with the Rights Management service.

getPublishLicenseForUser

PublishLicenseDTO getPublishLicenseForUser(java.lang.String domain,
                                           java.lang.String userId)
                                           throws SDKException
Fetches the com.adobe.edc.common.dto.PublishLicenseDTO that contains the information required for protecting a document

Parameters:
domain - domain name for the user for whom we want to fetch the license and policy information
userId - user id for the user for whom we want to fetch the license and policy information
Returns:
Throws:
SDKException - if any of the following conditions occur:
  • A parameter is invalid.
  • An error occurred while communicating with the Rights Management service.


[an error occurred while processing this directive] [an error occurred while processing this directive]