Assigning Usage Rights assigning-usage-rights
About the Acrobat Reader DC extensions Service about-the-acrobat-reader-dc-extensions-service
The Acrobat Reader DC extensions service enables your organization to easily share interactive PDF documents by extending the functionality of Adobe Reader. The Acrobat Reader DC extensions service fully supports any PDF document, up to and including PDF 1.7. It works with Adobe Reader 7.0 and later. The service adds usage rights to a PDF document, activating features that are not usually available when a PDF document is opened using Adobe Reader. Third party users do not require additional software or plug-ins to work with the rights-enabled documents.
You can accomplish these tasks using the Acrobat Reader DC extensions service:
- Apply usage rights to PDF documents. For information, see Applying Usage Rights to PDF Documents.
- Remove usage rights from PDF documents. For information, see Removing Usage Rights from PDF Documents.
- Retrieve credential details. For information, see Retrieving Credential Information.
Applying Usage Rights to PDF Documents applying-usage-rights-to-pdf-documents
You can apply usage rights to PDF documents using the Acrobat Reader DC extensions Java Client API and web service. Usage rights pertain to functionality that is available by default in Acrobat but not in Adobe Reader, such as the ability to add comments to a form or to fill in form fields and save the form. PDF documents that have usage rights applied to them are called rights-enabled documents. A user who opens a rights-enabled document in Adobe Reader can perform operations that are enabled for that specific document.
applyUsageRights
method, which is part of the Java API, you can set the isModeFinal
parameter of the ReaderExtensionsOptionSpec
object to false
. This results in the forms processed counter not being updated and an improvement in performance. If you are not concerned about updating the forms processed counter, it is recommended that you set the isModeFinal
parameter to false
.Summary of steps summary-of-steps
To apply usage rights to a PDF document, perform the following steps:
- Include project files.
- Create a Acrobat Reader DC extensions Client object.
- Retrieve a PDF document.
- Specify usage rights to apply.
- Apply usage rights to the PDF document.
- Save the rights-enabled PDF document.
Include project files
Include necessary files into your development project. If you are creating a client application using Java, then include the necessary JAR files. If you are using web services, then make sure that you include the proxy files.
Create a Acrobat Reader DC extensions Client object
To programmatically perform a Acrobat Reader DC extensionsservice operation, you must create a Acrobat Reader DC extensions service client object. If you are using the Acrobat Reader DC extensions Java API, create a ReaderExtensionsServiceClient
object. If you are using the Acrobat Reader DC extensions web service API, create a ReaderExtensionsServiceService
object.
Retrieve a PDF document
You must retrieve a PDF document in order to apply usage rights. Rights-enabled PDF documents contain a usage rights dictionary. When Adobe Reader opens a document containing such a dictionary, it enables the usage rights specified in the dictionary for that document only. If the document does not contain a usage rights dictionary, the Acrobat Reader DC extensions service creates one. If it already contains a dictionary, the Acrobat Reader DC extensions service overwrites existing usage rights with the ones you specify. The dictionary specifies which usage rights are enabled. When a user opens the document in Adobe Reader, only the usage rights specified in the dictionary are permitted.
Specify usage rights to apply
The usage rights that you can set are determined by a credential that you purchase from Adobe Systems Incorporated. Credentials typically provide permission to set a group of related usage rights, such as those pertaining to interactive forms. Each credential provides the right to create a certain number of rights-enabled PDF documents. An evaluation credential gives the right to create an unlimited number of draft documents.
Apply usage rights to the PDF document
To apply usage rights to a PDF document, you reference the alias of the credential that you are using to apply usage rights (a credential is typically installed during the installation of AEM Forms). Also you must specify the PDF document to which usage rights is applied. For information abut configuring a credential, see the installing and deploying guide for your application server.
Save the rights-enabled PDF document
After the Acrobat Reader DC extensions service applies usage rights to a PDF document, you can save the rights-enabled PDF document as a PDF file.
See also
Apply usage rights using the Java API
Apply usage rights using the web service API
Including AEM Forms Java library files
Acrobat Reader DC Extensions Service API Quick Starts
Apply usage rights using the Java API apply-usage-rights-using-the-java-api
Apply usage rights to a PDF document by using the Acrobat Reader DC Extensions API (Java):
-
Include project files
Include client JAR files, such as adobe-reader-extensions-client.jar, in your Java project’s class path.
-
Create a Acrobat Reader DC extensions Client object.
- Create a
ServiceClientFactory
object that contains connection properties. - Create a
ReaderExtensionsServiceClient
object by using its constructor and passing theServiceClientFactory
object.
- Create a
-
Retrieve a PDF document.
- Create a
java.io.FileInputStream
object that represents the PDF document by using its constructor and passing a string value that specifies the location of the PDF document. - Create a
com.adobe.idp.Document
object by using its constructor and passing thejava.io.FileInputStream
object.
- Create a
-
Specify usage rights to apply.
- Create a
UsageRights
object that represents usage rights by using its constructor. - For each usage right to apply, invoke a corresponding method that belongs to the
UsageRights
object. For example, to add theenableFormFillIn
usage right, invoke theUsageRights
object’senableFormFillIn
method and passtrue
. (Repeat this step for each usage right to apply).
- Create a
-
Apply usage rights to the PDF document.
-
Create a
ReaderExtensionsOptionSpec
object by using its constructor. This object contains run-time options that are required by the Acrobat Reader DC extensions service. When invoking this constructor, you must specify the following values:- The
UsageRights
object that contains the usage rights to apply to the document. - A string value that specifies a message that a user sees when the rights-enabled PDF document is opened in Adobe Reader 7.x. This message is not displayed in Adobe Reader 8.0.
- The
-
Apply usage rights to the PDF document by invoking the
ReaderExtensionsServiceClient
object’sapplyUsageRights
method and passing the following values:- The
com.adobe.idp.Document
object that contains the PDF document to which usage rights is applied. - A string value that specifies the alias of the credential that enables you to apply usage rights.
- A string value that specifies the corresponding password value. (Currently this parameter is ignored. You can pass
null
.)
- The
-
The
ReaderExtensionsOptionSpec
object that contains run-time options.
The
applyUsageRights
method returns acom.adobe.idp.Document
object that contains the rights-enabled PDF document. -
-
Save the rights-enabled PDF document.
- Create a
java.io.File
object and ensure that the file extension is .pdf. - Invoke the
com.adobe.idp.Document
object’scopyToFile
method to copy the contents of thecom.adobe.idp.Document
object to the file (ensure that you use thecom.adobe.idp.Document
object that was returned by theapplyUsageRights
method).
- Create a
See also
Applying Usage Rights to PDF Documents
Quick Start (SOAP mode):Applying usage rights using the Java API
Including AEM Forms Java library files
Apply usage rights using the web service API apply-usage-rights-using-the-web-service-api
Apply usage rights to a PDF document by using the Acrobat Reader DC Extensions API (web service):
-
Include project files.
Create a Microsoft .NET project that uses MTOM. Ensure that you use the following WSDL definition:
http://localhost:8080/soap/services/ReaderExtensionsService?WSDL&lc_version=9.0.1
.note note NOTE Replace localhost
with the IP address of the server hosting AEM Forms. -
Create a Acrobat Reader DC extensions Client object.
-
Create a
ReaderExtensionsServiceClient
object by using its default constructor. -
Create a
ReaderExtensionsServiceClient.Endpoint.Address
object by using theSystem.ServiceModel.EndpointAddress
constructor. Pass a string value that specifies the WSDL to the AEM Forms service (for example,http://localhost:8080/soap/services/ReaderExtensionsService?blob=mtom
. Ensure you specify?blob=mtom
.) -
Create a
System.ServiceModel.BasicHttpBinding
object by getting the value of theReaderExtensionsServiceClient.Endpoint.Binding
field. Cast the return value toBasicHttpBinding
. -
Set the
System.ServiceModel.BasicHttpBinding
object’sMessageEncoding
field toWSMessageEncoding.Mtom
. This value ensures that MTOM is used. -
Enable basic HTTP authentication by performing the following tasks:
- Assign the AEM forms user name to the field
ReaderExtensionsServiceClient.ClientCredentials.UserName.UserName
. - Assign the corresponding password value to the field
ReaderExtensionsServiceClient.ClientCredentials.UserName.Password
. - Assign the constant value
HttpClientCredentialType.Basic
to the fieldBasicHttpBindingSecurity.Transport.ClientCredentialType
. - Assign the constant value
BasicHttpSecurityMode.TransportCredentialOnly
to the fieldBasicHttpBindingSecurity.Security.Mode
.
- Assign the AEM forms user name to the field
-
-
Retrieve a PDF document.
- Create a
BLOB
object by using its constructor. TheBLOB
object is used to store a PDF document to which a usage rights is applied. - Create a
System.IO.FileStream
object by invoking its constructor and passing a string value that represents the file location of the PDF document and the mode in which to open the file. - Create a byte array that stores the content of the
System.IO.FileStream
object. You can determine the size of the byte array by getting theSystem.IO.FileStream
object’sLength
property. - Populate the byte array with stream data by invoking the
System.IO.FileStream
object’sRead
method. Pass the byte array, the starting position, and the stream length to read. - Populate the
BLOB
object by assigning itsMTOM
property with the contents of the byte array.
- Create a
-
Specify usage rights to apply.
- Create a
UsageRights
object that represents usage rights by using its constructor. - For each usage right to apply, assign the value
true
to the corresponding data member that belongs to theUsageRights
object. For example, to add theenableFormFillIn
usage right, assigntrue
to theUsageRights
object’senableFormFillIn
data member. (Repeat this step for each usage right to apply).
- Create a
-
Apply usage rights to the PDF document.
-
Create a
ReaderExtensionsOptionSpec
object by using its constructor. This object contains run-time options that are required by the Acrobat Reader DC extensions service. -
Assign the
UsageRights
object to theReaderExtensionsOptionSpec
object’susageRights
data member. -
Assign a string value that specifies the message that a user sees when the rights-enabled PDF document is opened in Adobe Reader to the
ReaderExtensionsOptionSpec
object’smessage
data member. -
Apply usage rights to the PDF document by invoking the
ReaderExtensionsServiceClient
object’sapplyUsageRights
method and passing the following values:- The
BLOB
object that contains the PDF document to which usage rights is applied. - A string value that specifies the alias of the credential that enables you to apply usage rights.
- A string value that specifies the corresponding password value. (Currently this parameter is ignored. You can pass
null
.)
- The
-
The
ReaderExtensionsOptionSpec
object that contains run-time options.
The
applyUsageRights
method returns aBLOB
object that contains the rights-enabled PDF document. -
-
Save the rights-enabled PDF document.
- Create a
System.IO.FileStream
object by invoking its constructor. Pass a string value that represents the file location of the rights-enabled PDF document. - Create a byte array that stores the data content of the
BLOB
object that was returned by theapplyUsageRights
method. Populate the byte array by getting the value of theBLOB
object’sMTOM
data member. - Create a
System.IO.BinaryWriter
object by invoking its constructor and passing theSystem.IO.FileStream
object. - Write the contents of the byte array to a PDF file by invoking the
System.IO.BinaryWriter
object’sWrite
method and passing the byte array.
- Create a
See also
Applying Usage Rights to PDF Documents
Invoking AEM Forms using SwaRef
Removing Usage Rights from PDF Documents removing-usage-rights-from-pdf-documents
You can remove usage rights from a rights-enabled document. Removing usage-rights from a rights-enabled PDF document is also necessary in order to perform other AEM Forms operations on it. For example, you must digitally sign (or certify) a PDF document before you set usage rights. Therefore if you want to perform operations on a rights-enabled document, you must remove usage rights from the PDF document, perform the other operations, such as digitally signing the document, and then re-apply usage rights to the document.
Summary of steps summary_of_steps-1
To remove usage rights from a rights-enabled PDF document, perform the following steps:
- Include project files.
- Create a Acrobat Reader DC extensions Client object.
- Retrieve a rights-enabled PDF document.
- Remove usage rights from the PDF document.
- Save the PDF document.
Include project files
Include necessary files into your development project. If you are creating a client application using Java, then include the necessary JAR files. If you are using web services, then make sure that you include the proxy files.
Create a Acrobat Reader DC extensions Client object
Before you can programmatically perform a Acrobat Reader DC extensions service operation, you must create a Acrobat Reader DC extensions service client object. If you are using the Java API, create a ReaderExtensionsServiceClient
object. If you are using the Acrobat Reader DC extensions web service API, create a ReaderExtensionsServiceService
object.
Retrieve a rights-enabled PDF document
Retrieve a rights-enabled PDF document in order to remove usage rights.
Remove usage rights from the PDF document
After you retrieve a rights-enabled PDF document, you can remove usage rights. After you remove usage rights, the PDF document will not have any additional functionality while viewed within Adobe Reader.
Save the PDF document
You can save the PDF document that no longer contains usage-rights as a PDF file. Once saved as a PDF file, the PDF document can be viewed in Adobe Reader or Acrobat.
See also
Remove usage rights using the Java API
Remove usage rights using the web service API
Including AEM Forms Java library files
Acrobat Reader DC Extensions Service API Quick Starts
Applying Usage Rights to PDF Documents
Remove usage rights using the Java API remove-usage-rights-using-the-java-api
Remove usage rights from a rights-enabled PDF document by using the Acrobat Reader DC extensions API (Java):
-
Include project files.
Include client JAR files, such as adobe-reader-extensions-client.jar, in your Java project’s class path.
-
Create a Acrobat Reader DC extensions Client object.
Create a
ReaderExtensionsServiceClient
object by using its constructor and passing aServiceClientFactory
object that contains connection properties. -
Retrieve a PDF document.
- Create a
java.io.FileInputStream
object that represent the rights-enabled PDF document by using its constructor and passing a string value that specifies the location of the PDF document. - Create a
com.adobe.idp.Document
object by using its constructor and passing thejava.io.FileInputStream
object.
- Create a
-
Remove usage rights from the PDF document.
Remove usage rights from the PDF document by invoking the
ReaderExtensionsServiceClient
object’sremoveUsageRights
method and passing thecom.adobe.idp.Document
object that contains the rights-enabled PDF document. This method returns acom.adobe.idp.Document
object that contains a PDF document that does not have usage rights. -
Apply usage rights to the PDF document.
- Create a
java.io.File
object and ensure that the file extension is .PDF. - Invoke the
Document
object’scopyToFile
method to copy the contents of theDocument
object to the file (ensure that you use theDocument
object that was returned by theremoveUsageRights
method).
- Create a
See also
Removing Usage Rights from PDF Documents
Quick Start (SOAP mode): Removing usage rights from a PDF document using the Java API
Including AEM Forms Java library files
Remove usage rights using the web service API remove-usage-rights-using-the-web-service-api
Remove usage rights from a rights-enabled PDF document by using the Acrobat Reader DC extensions API (web service):
-
Include project files.
Create a Microsoft .NET project that uses MTOM. Ensure that you use the following WSDL definition:
http://localhost:8080/soap/services/ReaderExtensionsService?WSDL&lc_version=9.0.1
.note note NOTE Replace localhost
with the IP address of the server hosting AEM Forms. -
Create a Acrobat Reader DC extensions Client object.
-
Create a
ReaderExtensionsServiceClient
object by using its default constructor. -
Create a
ReaderExtensionsServiceClient.Endpoint.Address
object by using theSystem.ServiceModel.EndpointAddress
constructor. Pass a string value that specifies the WSDL to the AEM Forms service (for example,http://localhost:8080/soap/services/ReaderExtensionsService?blob=mtom
. Ensure you specify?blob=mtom
.) -
Create a
System.ServiceModel.BasicHttpBinding
object by getting the value of theReaderExtensionsServiceClient.Endpoint.Binding
field. Cast the return value toBasicHttpBinding
. -
Set the
System.ServiceModel.BasicHttpBinding
object’sMessageEncoding
field toWSMessageEncoding.Mtom
. This value ensures that MTOM is used. -
Enable basic HTTP authentication by performing the following tasks:
- Assign the AEM forms user name to the field
ReaderExtensionsServiceClient.ClientCredentials.UserName.UserName
. - Assign the corresponding password value to the field
ReaderExtensionsServiceClient.ClientCredentials.UserName.Password
. - Assign the constant value
HttpClientCredentialType.Basic
to the fieldBasicHttpBindingSecurity.Transport.ClientCredentialType
. - Assign the constant value
BasicHttpSecurityMode.TransportCredentialOnly
to the fieldBasicHttpBindingSecurity.Security.Mode
.
- Assign the AEM forms user name to the field
-
-
Retrieve a PDF document.
- Create a
BLOB
object by using its constructor. TheBLOB
object is used to store the rights-enabled PDF document from which usage rights are removed. - Create a
System.IO.FileStream
object by invoking its constructor and passing a string value that represents the file location of the PDF document and the mode in which to open the file. - Create a byte array that stores the content of the
System.IO.FileStream
object. You can determine the size of the byte array by getting theSystem.IO.FileStream
object’sLength
property. - Populate the byte array with stream data by invoking the
System.IO.FileStream
object’sRead
method and passing the byte array, the starting position, and the stream length to read. - Populate the
BLOB
object by assigning itsMTOM
property with the contents of the byte array.
- Create a
-
Remove usage rights from the PDF document.
Remove usage rights from the PDF document by invoking the
ReaderExtensionsServiceClient
object’sremoveUsageRights
method and passing theBLOB
object that contains the rights-enabled PDF document. This method returns aBLOB
object that contains a PDF document that does not have usage rights. -
Apply usage rights to the PDF document.
- Create a
System.IO.FileStream
object by invoking its constructor and passing a string value that represents the PDF file location. - Create a byte array that stores the data content of the
BLOB
object that was returned by theremoveUsageRights
method. Populate the byte array by getting the value of theBLOB
object’sMTOM
data member. - Create a
System.IO.BinaryWriter
object by invoking its constructor and passing theSystem.IO.FileStream
object.
- Create a
See also
Removing Usage Rights from PDF Documents
Invoking AEM Forms using SwaRef
Retrieving Credential Information retrieving-credential-information
You can retrieve information about the credential that was used to apply usage rights to a rights-enabled PDF document. By retrieving information about a credential, you can obtain information such as the date after which the certificate is no longer valid.
Summary of steps summary_of_steps-2
To retrieve information about the credential that was used to apply usage rights to a PDF document, perform the following steps:
- Include project files.
- Create a Acrobat Reader DC extensions Client object.
- Retrieve a rights-enabled PDF document.
- Retrieve information about the credential.
Include project files
Include necessary files into your development project. If you are creating a client application using Java, then include the necessary JAR files. If you are using web services, then make sure that you include the proxy files.
Create a Acrobat Reader DC extensions Client object
Before you can programmatically perform a Acrobat Reader DC extensions service operation, you must create a Acrobat Reader DC extensions service client object. If you are using the Java API, create a ReaderExtensionsServiceClient
object. If you are using the Acrobat Reader DC extensions web service API, create a ReaderExtensionsServiceService
object.
Retrieve a rights-enabled PDF document
You must retrieve a rights-enabled PDF document in order to retrieve information about the credential. You can also retrieve information about a credential by specifying its alias; however, if you want to retrieve information about a credential that was used to apply usage rights to a specific rights-enabled PDF document, then you must retrieve the document.
Retrieve information about the credential
After you retrieve a rights-enabled PDF document, you can obtain information about the credential that was used to apply usage rights to it. You can obtain the following information about the credential:
- The message that is displayed within Adobe Reader when the rights-enabled PDF document is opened.
- The date after which the credential is no longer valid.
- The date before which the credential is not valid.
- The usage rights that were set for this rights-enabled PDF document.
- The number of times that the credential has been used.
See also
Remove usage rights using the Java API
Remove usage rights using the web service API
Including AEM Forms Java library files
Acrobat Reader DC Extensions Service API Quick Starts
Retrieve credential information using the Java API retrieve-credential-information-using-the-java-api
Retrieve credential information by using the Acrobat Reader DC extensions API (Java):
-
Include project files.
Include client JAR files, such as adobe-reader-extensions-client.jar, in your Java project’s class path.
-
Create a Acrobat Reader DC extensions Client object.
Create a
ReaderExtensionsServiceClient
object by using its constructor and passing aServiceClientFactory
object that contains connection properties. -
Retrieve a PDF document.
- Create a
java.io.FileInputStream
object that represent the rights-enabled PDF document by using its constructor and passing a string value that specifies the location of the rights-enabled PDF document. - Create a
com.adobe.idp.Document
object by using its constructor and passing thejava.io.FileInputStream
object.
- Create a
-
Remove usage rights from the PDF document.
- Retrieve information about the credential used to apply usage-rights to the PDF document by invoking the
ReaderExtensionsServiceClient
object’sgetDocumentUsageRights
method and passing thecom.adobe.idp.Document
object that contains the rights-enabled PDF document. This method return aGetUsageRightsResult
object that contains credential information. - Retrieve the date after which the credential is no longer valid by invoking the
GetUsageRightsResult
object’sgetNotAfter
method. This method returns ajava.util.Date
object that represents the date after which the credential is no longer valid. - Retrieve the message that is displayed in Adobe Reader when the rights-enabled PDF document is opened by invoking the
GetUsageRightsResult
object’sgetMessage
method. This method returns a string value that represents the message.
- Retrieve information about the credential used to apply usage-rights to the PDF document by invoking the
See also
Retrieving Credential Information
Quick Start (SOAP mode): Retrieving credential information using the Java API
Including AEM Forms Java library files
Retrieve credential information using the web service API retrieve-credential-information-using-the-web-service-api
Retrieve credential information using the Acrobat Reader DC extensions API (web service):
-
Include project files.
Create a Microsoft .NET project that uses MTOM. Ensure that you use the following WSDL definition:
http://localhost:8080/soap/services/ReaderExtensionsService?WSDL&lc_version=9.0.1
.note note NOTE Replace localhost
with the IP address of the server hosting AEM Forms. -
Create a Acrobat Reader DC extensions Client object.
-
Create an
ReaderExtensionsServiceClient
object by using its default constructor. -
Create a
ReaderExtensionsServiceClient.Endpoint.Address
object by using theSystem.ServiceModel.EndpointAddress
constructor. Pass a string value that specifies the WSDL to the AEM Forms service (for example,http://localhost:8080/soap/services/ReaderExtensionsService?blob=mtom
. Ensure you specify?blob=mtom
.) -
Create a
System.ServiceModel.BasicHttpBinding
object by getting the value of theReaderExtensionsServiceClient.Endpoint.Binding
field. Cast the return value toBasicHttpBinding
. -
Set the
System.ServiceModel.BasicHttpBinding
object’sMessageEncoding
field toWSMessageEncoding.Mtom
. This value ensures that MTOM is used. -
Enable basic HTTP authentication by performing the following tasks:
- Assign the AEM forms user name to the field
ReaderExtensionsServiceClient.ClientCredentials.UserName.UserName
. - Assign the corresponding password value to the field
ReaderExtensionsServiceClient.ClientCredentials.UserName.Password
. - Assign the constant value
HttpClientCredentialType.Basic
to the fieldBasicHttpBindingSecurity.Transport.ClientCredentialType
. - Assign the constant value
BasicHttpSecurityMode.TransportCredentialOnly
to the fieldBasicHttpBindingSecurity.Security.Mode
.
- Assign the AEM forms user name to the field
-
-
Retrieve a PDF document.
- Create a
BLOB
object by using its constructor. TheBLOB
object is used to store a rights-enabled PDF document. - Create a
System.IO.FileStream
object by invoking its constructor and passing a string value that represents the file location of the rights-enabled PDF document and the mode in which to open the file. - Create a byte array that stores the content of the
System.IO.FileStream
object. You can determine the size of the byte array by getting theSystem.IO.FileStream
object’sLength
property. - Populate the byte array with stream data by invoking the
System.IO.FileStream
object’sRead
method and passing the byte array, the starting position, and the stream length to read. - Populate the
BLOB
object by assigning itsMTOM
property with the contents of the byte array.
- Create a
-
Remove usage rights from the PDF document.
- Retrieve information about the credential used to apply usage-rights to the PDF document by invoking the
ReaderExtensionsServiceClient
object’sgetDocumentUsageRights
method and passing thecom.adobe.idp.Document
object that contains the rights-enabled PDF document. This method returns aGetUsageRightsResult
object that contains credential information. - Retrieve the date after which the credential is no longer valid by getting the value of the
GetUsageRightsResult
object’snotAfter
data member. The data type of this data member isSystem.DateTime
. - Retrieve the message that is displayed when the rights-enabled PDF document is opened in Adobe Reader by getting the value of the
GetUsageRightsResult
object’smessage
data member. The data type of this data member is a string. - Retrieve the number of times that the credential is used by getting the value of the
GetUsageRightsResult
object’suseCount
data member. The data type of this data member is an integer.
- Retrieve information about the credential used to apply usage-rights to the PDF document by invoking the
See also
Retrieving Credential Information
Invoking AEM Forms using SwaRef