Coding Example: Apply signature to PDF documents
Minimum technical requirements
- Java version: 7
- webPDF version: 7
- wsclient version: 1
If you want to use the operation of the webPDF webservice Signature, you have the possibility to use it via the webPDF wsclient library.
Important note:
The following coding example is based on the use of the webPDF wsclient library. In order to understand and apply the example, the following blog post should be considered first:
Preparations for Web Service Signature
First, you should already have created a REST or SOAP session and, by calling the WebserviceFactory, you should have created either a SignatureWebService object (for a SOAP session)
SignatureWebService signatureWebService = WebServiceFactory.createInstance(session, WebServiceType.SIGNATURE);
..or a SignatureRestWebService object (for a REST session):
SignatureRestWebService signatureWebService = WebServiceFactory.createInstance(session, WebServiceType.SIGNATURE);
You should also have passed either a RestDocument or a SoapDocument object to this WebService object by calling the setDocument() method.
What is the Signature Webservice?
The Signature Webservice is an endpoint of the webPDF server that allows adding signatures to PDF documents.
You can reinitialize the SignatureType operation and set it in the Webservice or use the automatically generated instance of the Webservice.
SignatureType signatureType = signatureWebService.getOperation();
The following parameters can be set for the ConverterType instance:
The object „add“
In this object, all settings are set to add a signature.
SignatureType.Add add = new SignatureType.Add(); signatureType.setAdd(add);
appendSignature (default value: true)
This parameter specifies whether an existing signature is to be replaced.
add.setAppendSignature(true);
certificationLevel (default value: „noChanges“)
The parameter specifies the signature level. The possible values are in the Enum CertificationLevelType and are:
- CertificationLevelType.NONE
Sign, but do not certify, the document – i.e. further signatures or changes are possible. - CertificationLevelType.NO_CHANGES
Certify the document and do not allow any further changes. - CertificationLevelType.FORM_FILLING_AND_SIGNATURES
Certify document, but allow fields to be filled in. - CertificationLevelType.FORM_FILLING_AND_SIGNATURES_AND_ANNOTATIONS
Certify document, but allow fields to be filled in and annotations to be added.
add.setCertificationLevel(CertificationLevelType.FORM_FILLING_AND_SIGNATURES);
contact (default value: “”)
The parameter specifies the name of the signer.
add.setContact("John Doe");
fieldName (default value: “Signature1”)
The parameter specifies the name of the field in which the signature will be contained.
add.setFieldName("SignatureField");
keyName (default value: “”)
Defines the name of the key (alias) to be used when signing the document. This setting overrides the server configuration setting. For more information, refer to the webPDF documentation in the chapter “Keystore“.
add.setKeyName("keyAlias");
keyPassword (default value: “”)
Defines the password required to access the private key of “keyName”. This setting overrides the server’s configuration setting. Further information can be found in the webPDF documentation in the chapter “Keystore“.
add.setKeyPassword("keyPassword");
reason (default value: “”)
This parameter can be used to specify the reason for adding the signature.
add.setReason("demonstration for wsclient blog article");
location (default value: “”)
This parameter specifies the location for adding the signature.
add.setLocation("Main Street 0, Anytown, USA");
The object „appearence“
Properties for the visual appearance of the signature can be defined in this object.
SignatureType.Add.Appearance appearance = new SignatureType.Add.Appearance(); add.setAppearance(appearance);
page (default value: 1)
This parameter defines the page on which the signature is displayed.
appearance.setPage(1);
identifier (default value: “”)
Text to be displayed in the right text field of the signature. If no value is specified, the name of the signer and the name components of the certificate are displayed there.
appearance.setIdentifier("right field of signature text");
name (default value: “”)
Sets the text to be displayed in the left part of the signature. If no value is specified, the name of the signer is displayed there.
appearance.setName("left area of signature");
The „identifierElements“ object
The components of the visual signature are defined in this object.
SignatureIdentifierType identifier = new SignatureIdentifierType(); appearance.setIdentifierElements(identifier);
With the options listed here for the object, the display can be activated or deactivated. The default value is true
identifier.setShowCommonName(true); identifier.setShowCountry(true); identifier.setShowDate(true); identifier.setShowLocal(true); identifier.setShowMail(true); identifier.setShowName(true); identifier.setShowOrganisationUnit(true); identifier.setShowSignedBy(true); identifier.setShowState(true);
The „image“ object
In this object a graphic for the visual signature is defined, which is drawn in the background of the signature.
SignatureImageType image = new SignatureImageType(); appearance.setImage(image);
position (default value: center)
Defines the position of the graphic within the signature field. This is done with an entry of the enum SignatureImagePositionType.
- SignatureImagePositionType.CENTER – centered
- SignatureImagePositionType.LEFT – left
- SignatureImagePositionType.RIGHT – right
image.setPosition(SignatureImagePositionType.CENTER);
opacity (default: 50)
Defines the opacity for the graphic as a percentage.
image.setOpacity(60);
The „data“ object
With this object the actual graphic for the image object is passed as Base64.
SignatureFileDataType imageData = new SignatureFileDataType();
image.setData(imageData);
imageData.setValue(Base64.encodeBase64(FileUtils.readFileToByteArray(new File("image.png"))));
The „position“ object
This object determines the position of the visual signature.
SignaturePositionType position = new SignaturePositionType(); appearance.setPosition(position);
x (Default value: 10 (millimeters from left margin))
X-position of the signature field.
position.setX(10F);
y (Default value: 10 (millimeters from the bottom))
Y position of the signature field.
position.setY(10F);
width (Default value: 80 (millimeter))
Width of the signature field.
position.setWidth(80F);
height (Default value: 40 (millimeter))
Height of the signature field.
position.setHeight(60F);
coordinates (default value: “user”)
Defines the coordinate system and thus the origin for the data with an entry of the Enums CoordinatesType.
- CoordinatesType.USER – User coordinate system (starting point top left)
- CoordinatesType.PDF – PDF coordinate system (starting point lower left)
position.setCoordinates(CoordinatesType.USER);
metrics (default value: “mm”)
Defines the measurement unit for the entries with an entry of the Enums MetricsType.
- MetricsType.MM – Millimeter
- MetricsType.PX – Pixel
position.setMetrics(MetricsType.MM);
Example
Finally, an example for a webservice call (for addressing the SOAP interface):
try (
// Setup of a session with the webPDF server (here SOAP):
SoapSession session = SessionFactory.createInstance(
WebServiceProtocol.SOAP,
new URL("https://localhost:8080/webPDF/"));
) {
SignatureWebService signatureWebService = WebServiceFactory.createInstance(session, WebServiceType.SIGNATURE);
SignatureType signatureType = signatureWebService.getOperation();
SignatureType.Add add = new SignatureType.Add();
signatureType.setAdd(add);
add.setReason("webPDF wsclient sample");
add.setLocation("Main Street, Anytown, USA");
add.setContact("Any Company");
add.setCertificationLevel(CertificationLevelType.NO_CHANGES);
add.setKeyName("Generic self-signed certificate");
SignatureType.Add.Appearance appearance = new SignatureType.Add.Appearance();
add.setAppearance(appearance);
SignaturePositionType position = new SignaturePositionType();
position.setX(5.0f);
position.setY(5.0f);
position.setWidth(80.0f);
position.setHeight(15.0f);
appearance.setPosition(position);
SignatureImageType image = new SignatureImageType();
SignatureFileDataType imageData = new SignatureFileDataType();
imageData.setValue(Files.readAllBytes(Paths.get("logo.png")));
image.setData(imageData);
image.setOpacity(40);
appearance.setImage(image);
appearance.setIdentifier("John Doe");
try (
// Make available the document to be processed.
// and the file in which the result is to be written:
SoapDocument document = new SoapDocument(new File("source.pdf").toURI(), new File("result.pdf"))) {
//Ausführung und schließen der Dokumente
signatureWebService.setDocument(document);
signatureWebService.process().close();
}
}
More info:
- Read more about using REST and SOAP in the blog.
- The parameters are also documented in our user manual: Signature Parameter Structure. Note: The parameters are preset with certain default values. If a default value is specified which does not deviate from your desired value, it is not necessary to set this parameter.
- Please also note our blog series on the subject of digital signatures, Part 1 (basics and legal aspects of digital signatures), Part 2 (how the encryption technique works) and Part 3 (how to apply the signature in the webPDF portal): Securing Documents with Digital Signatures):
More coding examples for webservices that you can use with the ws-client library can be found here.
Preparations for Web Service Signature
First, you should already have created a REST or SOAP session and, by calling the WebserviceFactory, you should have created either a SignatureWebService object (for a SOAP session)
SignatureWebService signatureWebService = WebServiceFactory.createInstance(session, WebServiceType.SIGNATURE);
..or a SignatureRestWebService object (for a REST session):
SignatureRestWebService signatureWebService = WebServiceFactory.createInstance(session, WebServiceType.SIGNATURE);
You should also have passed either a RestDocument or a SoapDocument object to this WebService object by calling the setDocument() method.
What is the Signature Webservice?
The Signature Webservice is an endpoint of the webPDF server that allows adding signatures to PDF documents.
You can reinitialize the SignatureType operation and set it in the Webservice or use the automatically generated instance of the Webservice.
SignatureType signatureType = signatureWebService.getOperation();
The following parameters can be set for the ConverterType instance:
The object „add“
In this object, all settings are set to add a signature.
SignatureType.Add add = new SignatureType.Add(); signatureType.setAdd(add);
appendSignature (default value: true)
This parameter specifies whether an existing signature is to be replaced.
add.setAppendSignature(true);
certificationLevel (default value: „noChanges“)
The parameter specifies the signature level. The possible values are in the Enum CertificationLevelType and are:
- CertificationLevelType.NONE
Sign, but do not certify, the document – i.e. further signatures or changes are possible. - CertificationLevelType.NO_CHANGES
Certify the document and do not allow any further changes. - CertificationLevelType.FORM_FILLING_AND_SIGNATURES
Certify document, but allow fields to be filled in. - CertificationLevelType.FORM_FILLING_AND_SIGNATURES_AND_ANNOTATIONS
Certify document, but allow fields to be filled in and annotations to be added.
add.setCertificationLevel(CertificationLevelType.FORM_FILLING_AND_SIGNATURES);
contact (default value: “”)
The parameter specifies the name of the signer.
add.setContact("John Doe");
fieldName (default value: “Signature1”)
The parameter specifies the name of the field in which the signature will be contained.
add.setFieldName("SignatureField");
keyName (default value: “”)
Defines the name of the key (alias) to be used when signing the document. This setting overrides the server configuration setting. For more information, refer to the webPDF documentation in the chapter “Keystore“.
add.setKeyName("keyAlias");
keyPassword (default value: “”)
Defines the password required to access the private key of “keyName”. This setting overrides the server’s configuration setting. Further information can be found in the webPDF documentation in the chapter “Keystore“.
add.setKeyPassword("keyPassword");
reason (default value: “”)
This parameter can be used to specify the reason for adding the signature.
add.setReason("demonstration for wsclient blog article");
location (default value: “”)
This parameter specifies the location for adding the signature.
add.setLocation("Main Street 0, Anytown, USA");
The object „appearence“
Properties for the visual appearance of the signature can be defined in this object.
SignatureType.Add.Appearance appearance = new SignatureType.Add.Appearance(); add.setAppearance(appearance);
page (default value: 1)
This parameter defines the page on which the signature is displayed.
appearance.setPage(1);
identifier (default value: “”)
Text to be displayed in the right text field of the signature. If no value is specified, the name of the signer and the name components of the certificate are displayed there.
appearance.setIdentifier("right field of signature text");
name (default value: “”)
Sets the text to be displayed in the left part of the signature. If no value is specified, the name of the signer is displayed there.
appearance.setName("left area of signature");
The „identifierElements“ object
The components of the visual signature are defined in this object.
SignatureIdentifierType identifier = new SignatureIdentifierType(); appearance.setIdentifierElements(identifier);
With the options listed here for the object, the display can be activated or deactivated. The default value is true
identifier.setShowCommonName(true); identifier.setShowCountry(true); identifier.setShowDate(true); identifier.setShowLocal(true); identifier.setShowMail(true); identifier.setShowName(true); identifier.setShowOrganisationUnit(true); identifier.setShowSignedBy(true); identifier.setShowState(true);
The „image“ object
In this object a graphic for the visual signature is defined, which is drawn in the background of the signature.
SignatureImageType image = new SignatureImageType(); appearance.setImage(image);
position (default value: center)
Defines the position of the graphic within the signature field. This is done with an entry of the enum SignatureImagePositionType.
- SignatureImagePositionType.CENTER – centered
- SignatureImagePositionType.LEFT – left
- SignatureImagePositionType.RIGHT – right
image.setPosition(SignatureImagePositionType.CENTER);
opacity (default: 50)
Defines the opacity for the graphic as a percentage.
image.setOpacity(60);
The „data“ object
With this object the actual graphic for the image object is passed as Base64.
SignatureFileDataType imageData = new SignatureFileDataType();
image.setData(imageData);
imageData.setValue(Base64.encodeBase64(FileUtils.readFileToByteArray(new File("image.png"))));
The „position“ object
This object determines the position of the visual signature.
SignaturePositionType position = new SignaturePositionType(); appearance.setPosition(position);
x (Default value: 10 (millimeters from left margin))
X-position of the signature field.
position.setX(10F);
y (Default value: 10 (millimeters from the bottom))
Y position of the signature field.
position.setY(10F);
width (Default value: 80 (millimeter))
Width of the signature field.
position.setWidth(80F);
height (Default value: 40 (millimeter))
Height of the signature field.
position.setHeight(60F);
coordinates (default value: “user”)
Defines the coordinate system and thus the origin for the data with an entry of the Enums CoordinatesType.
- CoordinatesType.USER – User coordinate system (starting point top left)
- CoordinatesType.PDF – PDF coordinate system (starting point lower left)
position.setCoordinates(CoordinatesType.USER);
metrics (default value: “mm”)
Defines the measurement unit for the entries with an entry of the Enums MetricsType.
- MetricsType.MM – Millimeter
- MetricsType.PX – Pixel
position.setMetrics(MetricsType.MM);
Example
Finally, an example for a webservice call (for addressing the SOAP interface):
try (
// Setup of a session with the webPDF server (here SOAP):
SoapSession session = SessionFactory.createInstance(
WebServiceProtocol.SOAP,
new URL("https://localhost:8080/webPDF/"));
) {
SignatureWebService signatureWebService = WebServiceFactory.createInstance(session, WebServiceType.SIGNATURE);
SignatureType signatureType = signatureWebService.getOperation();
SignatureType.Add add = new SignatureType.Add();
signatureType.setAdd(add);
add.setReason("webPDF wsclient sample");
add.setLocation("Main Street, Anytown, USA");
add.setContact("Any Company");
add.setCertificationLevel(CertificationLevelType.NO_CHANGES);
add.setKeyName("Generic self-signed certificate");
SignatureType.Add.Appearance appearance = new SignatureType.Add.Appearance();
add.setAppearance(appearance);
SignaturePositionType position = new SignaturePositionType();
position.setX(5.0f);
position.setY(5.0f);
position.setWidth(80.0f);
position.setHeight(15.0f);
appearance.setPosition(position);
SignatureImageType image = new SignatureImageType();
SignatureFileDataType imageData = new SignatureFileDataType();
imageData.setValue(Files.readAllBytes(Paths.get("logo.png")));
image.setData(imageData);
image.setOpacity(40);
appearance.setImage(image);
appearance.setIdentifier("John Doe");
try (
// Make available the document to be processed.
// and the file in which the result is to be written:
SoapDocument document = new SoapDocument(new File("source.pdf").toURI(), new File("result.pdf"))) {
//Ausführung und schließen der Dokumente
signatureWebService.setDocument(document);
signatureWebService.process().close();
}
}
More info:
- Read more about using REST and SOAP in the blog.
- The parameters are also documented in our user manual: Signature Parameter Structure. Note: The parameters are preset with certain default values. If a default value is specified which does not deviate from your desired value, it is not necessary to set this parameter.
- Please also note our blog series on the subject of digital signatures, Part 1 (basics and legal aspects of digital signatures), Part 2 (how the encryption technique works) and Part 3 (how to apply the signature in the webPDF portal): Securing Documents with Digital Signatures):
More coding examples for webservices that you can use with the ws-client library can be found here.