org.faceless.pdf2.viewer2

## Class SignatureProvider

- java.lang.Object
- - org.faceless.pdf2.viewer2.ViewerFeature
  - - org.faceless.pdf2.viewer2.SignatureProvider

- Direct Known Subclasses:
    KeyStoreSignatureProvider, RemoteSignatureProvider

      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 and Description
    --- | ---
    `class` | `SignatureProvider.SignatureState` A SignatureState contains information about a `FormSignature` once it's been verified.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `SignatureProvider(String name)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and 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
    `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()`.
    `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
      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
        `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
        `listener` - the ActionListener that should be called when the SignatureProvider is chosen

    - #### 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.
      Parameters:
        `docpanel` - the DocumentPanel containing the signature
        `field` - the FormSignature that was verified
        `state` - the state of the signature

Copyright © 2001-2015 Big Faceless Organization