Package org.faceless.pdf2.viewer2

Class SignatureProvider

java.lang.Object

org.faceless.pdf2.viewer2.ViewerFeature

org.faceless.pdf2.viewer2.SignatureProvider

Direct Known Subclasses:

KeyStoreSignatureProvider

public abstract class SignatureProvider
extends ViewerFeature

A ViewerFeature that acts as a service provider for applying Digital Signatures. When a digital signature field is encounted by the PDF viewer, it will search its list of features for an instance of this class that can sign or can verify the field as appropriate. A dialog will then be presented.

Although each type of subclass will be different, there are several properties that apply to any digital signature and so they can be specified here. Subclasses implementing the showSignDialog() method are expected to use these values if specified, or prompt the user otherwise.

The following initialization parameters can be specified to configure subclasses of this feature.

name	The name of the entity signing the document - the default value of getDefaultName()
reason	The reason for the signature - the default value of getDefaultReason().
location	The location the signature is being applied - the default value of getDefaultLocation().
certification	The type of certification to use for the first signature applied to a PDF (the default value of getDefaultCertificationType()). Valid values are none, nochanges, forms or comments. If the signature being applied is not the initial signature this is ignored

Since:

2.11

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
class	SignatureProvider.SignatureState	A SignatureState contains information about a FormSignature once it's been verified.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	SignatureProvider(String name)

Method Summary

Modifier and Type	Method	Description
abstract boolean	canSign(FormSignature field)	Return true if this SignatureProvider can sign the specified field
abstract boolean	canVerify(FormSignature field)	Return true if this SignatureProvider can verify the specified field
SignatureProvider.SignatureState	createSignatureState(FormSignature signature)	Create a new SignatureProvider.SignatureState that is appropriate for use with this SignatureProvider.
int	getDefaultCertificationType()	Return the default type of certification for any new signatures using the showSignDialog() method, or -1 to not specify a default.
String	getDefaultLocation()	Return the location of the new signature being applied using the showSignDialog() method, or null to not specify a default.
String	getDefaultName()	Return the name of the entity signing the document using the showSignDialog() method, or null to not specify a default.
String	getDefaultReason()	Return the reason that the new signature is being applied using the showSignDialog() method, or null to not specify a default.
abstract String	getDisplayName()	Return the "user friendly" name of this SignatureProvider, to use in dialogs and menus.
static ImageIcon	getIcon(DocumentPanel docpanel, FormSignature field)	Get an Icon that can be used to describe the specified signature.
static SignatureProvider.SignatureState	getSignatureState(DocumentPanel docpanel, FormSignature field)	Get a previously determined SignatureProvider.SignatureState for the specified signature field, as set by setSignatureState().
List<Map.Entry<String,String>>	getSummaryText(FormSignature field, DocumentPanel docpanel)
PDFViewer	getViewer()	Return the PDFViewer set in initialize(org.faceless.pdf2.viewer2.PDFViewer)
void	initialize(PDFViewer viewer)	Called when the feature is first added to a viewer
static void	selectSignProvider(DocumentPanel docpanel, FormSignature field, JComponent comp, Point point, ActionListener listener)	Select a SignatureProvider that can be used to sign the specified signature field.
static void	selectVerifyProvider(DocumentPanel docpanel, FormSignature field, JComponent comp, Point point, ActionListener listener)	Select a SignatureProvider that can be used to verify the specified signature field.
static void	setSignatureState(DocumentPanel docpanel, FormSignature field, SignatureProvider.SignatureState state)	Set the SignatureProvider.SignatureState of this field - should be called by the showVerifyDialog() method after the field has been verified, to save the details of the verification.
abstract void	showSignDialog(JComponent root, FormSignature field)	Display the signing dialog for the specified field, and assuming all goes well sign the field at the end.
abstract void	showVerifyDialog(JComponent root, FormSignature field)	Show a dialog displaying information about the specified (signed) digital signature field.
SignatureProvider.SignatureState	verify(JComponent root, FormSignature field)	Verify the field.

Methods inherited from class org.faceless.pdf2.viewer2.ViewerFeature

getAllEnabledFeatures, getAllFeatures, getCustomJavaScript, getFeatureProperty, getFeatureURLProperty, getName, isEnabledByDefault, setFeatureName, teardown, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SignatureProvider

protected SignatureProvider(String name)

Method Detail

initialize

public void initialize(PDFViewer viewer)

Description copied from class: ViewerFeature

Called when the feature is first added to a viewer

Overrides:

initialize in class ViewerFeature

getViewer

public final PDFViewer getViewer()

Return the PDFViewer set in initialize(org.faceless.pdf2.viewer2.PDFViewer)

getDisplayName

public abstract String getDisplayName()

Return the "user friendly" name of this SignatureProvider, to use in dialogs and menus.

getDefaultName

public String getDefaultName()

Return the name of the entity signing the document using the showSignDialog() method, or null to not specify a default.

getDefaultReason

public String getDefaultReason()

Return the reason that the new signature is being applied using the showSignDialog() method, or null to not specify a default.

getDefaultLocation

public String getDefaultLocation()

Return the location of the new signature being applied using the showSignDialog() method, or null to not specify a default.

getDefaultCertificationType

public int getDefaultCertificationType()

Return the default type of certification for any new signatures using the showSignDialog() method, or -1 to not specify a default.

Returns:

one of FormSignature.CERTIFICATION_UNCERTIFIED, FormSignature.CERTIFICATION_NOCHANGES, FormSignature.CERTIFICATION_ALLOWFORMS, FormSignature.CERTIFICATION_ALLOWCOMMENTS, or the value -1 to prompt the user (the default).

canSign

public abstract boolean canSign(FormSignature field)

Return true if this SignatureProvider can sign the specified field

canVerify

public abstract boolean canVerify(FormSignature field)

Return true if this SignatureProvider can verify the specified field

showSignDialog

public abstract void showSignDialog(JComponent root,
                                    FormSignature field)
                             throws IOException,
                                    GeneralSecurityException

Display the signing dialog for the specified field, and assuming all goes well sign the field at the end.

Parameters:

root - the JCompoment the dialog should be relative to - typically this is the DocumentPanel

field - the field to be signed

Throws:

IOException

GeneralSecurityException

showVerifyDialog

public abstract void showVerifyDialog(JComponent root,
                                      FormSignature field)

Show a dialog displaying information about the specified (signed) digital signature field. The dialog should display the signatures verification state, which may be determined by this method or retrieved from a previous verification

Parameters:

root - the JCompoment the dialog should be relative to - typically this is the DocumentPanel

field - the field to be verified

verify

public SignatureProvider.SignatureState verify(JComponent root,
                                               FormSignature field)

Verify the field. Must be overridden by any SignatureProvider that returns true from canVerify(). This method may provide visual feedback to the user, but it's primary purpose is to verify the field and return its state so it should not block user progress unless it's unavoidable.

Parameters:

root - the component that should be used as a root for

field - the signed field

Returns:

the SignatureState, or null if verification was cancelled and the state is unknown

Since:

2.11.7

getIcon

public static final ImageIcon getIcon(DocumentPanel docpanel,
                                      FormSignature field)

Get an Icon that can be used to describe the specified signature.

selectSignProvider

public static final void selectSignProvider(DocumentPanel docpanel,
                                            FormSignature field,
                                            JComponent comp,
                                            Point point,
                                            ActionListener listener)

Select a SignatureProvider that can be used to sign the specified signature field. The listener parameter specifies an ActionListener which will be called with the chosen provider - the ActionEvent it will be given will have the source set to the chosen provider and the action type set to "sign".

If more than one SignatureProvider is available this method will show a dialog allowing the user to choose, otherwise the the listener will be called without a dialog being displayed.

Parameters:

docpanel - the DocumentPanel containing the PDF

field - the field the user is requesting to sign

comp - the Component the user has clicked on or selected to request the signing

point - the position relative to comp that any dialog should be based around. If null, no dialog will be displayed, and hte first match will be used

listener - the ActionListener that should be called when the SignatureProvider is chosen

selectVerifyProvider

public static final void selectVerifyProvider(DocumentPanel docpanel,
                                              FormSignature field,
                                              JComponent comp,
                                              Point point,
                                              ActionListener listener)

Select a SignatureProvider that can be used to verify the specified signature field. The listener parameter specifies an ActionListener which will be called with the chosen provider - the ActionEvent it will be given will have the source set to the chosen provider and the action type set to "verify".

If more than one SignatureProvider is available this method will show a dialog allowing the user to choose, otherwise the the listener will be called without a dialog being displayed.

Parameters:

docpanel - the DocumentPanel containing the PDF

field - the field the user is requesting to verify

comp - the Component the user has clicked on or selected to request the verification

point - the position relative to comp that any dialog should be based around. If null, no dialog will be displayed, and hte first match will be used

listener - the ActionListener that should be called when the SignatureProvider is chosen

getSummaryText

public List<Map.Entry<String,String>> getSummaryText(FormSignature field,
                                                           DocumentPanel docpanel)

createSignatureState

public SignatureProvider.SignatureState createSignatureState(FormSignature signature)

Create a new SignatureProvider.SignatureState that is appropriate for use with this SignatureProvider. This method is expected to be overridden by subclasses

Parameters:

signature - the signature (required)

Returns:

a new SignatureProvider.SignatureState to be initialized

Since:

2.28.7

getSignatureState

public static final SignatureProvider.SignatureState getSignatureState(DocumentPanel docpanel,
                                                                       FormSignature field)

Get a previously determined SignatureProvider.SignatureState for the specified signature field, as set by setSignatureState(). If this method returns null then the signature has not been verified yet.

Parameters:

docpanel - the DocumentPanel containing the signature

field - the FormSignature whose state is being checked

Since:

2.11.7

setSignatureState

public static final void setSignatureState(DocumentPanel docpanel,
                                           FormSignature field,
                                           SignatureProvider.SignatureState state)

Set the SignatureProvider.SignatureState of this field - should be called by the showVerifyDialog() method after the field has been verified, to save the details of the verification. This method may be called in any thread, but it will fire the "stateChanged" DocumentPanelEvent on the Swing Event Dispatch Thread.

If "field" and "state" are both null, this is a special action that removes the state for any existing fields. This can be used to reset the state of all signatures in the document to unknown

Parameters:

docpanel - the DocumentPanel containing the signature

field - the FormSignature that was verified, or if state==null, this can be null to indicate "all fields"

state - the state of the signature, or null