CIB jView sign technischer Leitfaden
3. Schneller Einstieg: Einbindung des CIB jview&sign in Java
3.2. Dynamische Anbindung an die Signaturkomponente Jview&sign
In CIB Jview sind auch Funktionen zur Anbindung an die Formularkomponente Jview&sign integriert.
Dazu sind Datenstrukturen und Callback-Methoden definiert, die in den folgenden Abschnitten beschrieben werden.
Interface SignFieldInfo zum Austausch von Informationen über ein SignaturfeldInterface SignFieldCallback mit Callback-Methoden zur Information über die Anzahl und den Status der Signaturfelder sowie ihre Aktualisierung
Interface CustomCloseDialogInfo zum Austausch von Informationen für den CustomCloseDialogCallback
Interface SignFieldInfo zum Austausch von Informationen über ein Signaturfeld
Die Datenstruktur SignFieldInfo dient zum Austausch von Informationen über ein Signaturfeld, sie ist im CIB jview (package de.cib.view.modules.sign) definiert.
Interface SignFieldInfo (extends FieldInfo):
package de.cib.view.modules.sign;
import de.cib.view.modules.FieldInfo;
/**
* Interface representing the sign field info for information exchange.
*
* It allows information exchange about a list of sign fields e.g. via
* interface SignFieldCallback.
* @see FieldInfo
* @see SignFieldCallback
*/
public interface SignFieldInfo extends FieldInfo {
public String getReason();
public void setReason(String reason);
public String getSignerName();
public void setSignerName(String signerName);
public String getLocation();
public void
setLocation(String location);
public boolean isSigned();
public String getTimeStamp();
}
Interface FieldInfo:
package de.cib.view.modules;
/**
* Interface representing the field info.
*
* It allows information exchange about a field.
*/
public interface FieldInfo {
// Setter for setMandatory - for later use
// public void setMandatory(boolean isMandatory);
public String getType();
public String getName();
public String getTooltip();
public void setTooltip(String tooltip);
public int getCount();
public boolean isLocked();
// Setter for setLocked - for later use
// public void setLocked(boolean isLocked);
}
Interface SignFieldCallback mit Callback-Methoden zur Information über die Anzahl und den Status der Signaturfelder sowie ihre Aktualisierung
package de.cib.view.modules;
/**
* Interface FieldCallback
*
* This interface is used to exchange information about current fields.
*
*/
public interface FieldCallback {
public static final int ON_LOAD = 1;
public static final int ON_SAVE = 2;
public static final int ON_EXIT = 8;
}
Der Aufrufer muss sich dazu bei der Jview-Instanz als Listener anmelden.
Es gibt verschiedene Zeitpunkte, zu denen die Aufrufe des SignFieldCallback an den Listener geschickt werden, was durch den Parameter „eventType“ signalisiert wird:
- ON_LOAD – beim Laden eines Dokuments
- ON_SAVE – beim Speichern eines Dokuments
- ON_EXIT – beim Beenden des Viewers
Welches Dokument geladen oder gespeichert wird, wird im Parameter „fileName“ mitgeteilt.
Das Interface SignFieldCallback ist im CIB jview (package de.cib.view.modules.sign) definiert und umfasst folgende Methoden.
Interface SignFieldCallback:
package de.cib.view.modules.sign;
import java.util.List;
/**
* Interface SignFieldCallback
*
* This interface is used to exchange
information about current
* sign fields.
*/
public interface SignFieldCallback {
/**
* Notifies about the current number of sign fields
*
* @param countSignFields Number of sign fields
* @param fileName Name of loaded file
* @param
eventType SignFieldCallback.ON_LOAD |
SignFieldCallback.ON_SAVE
| SignFieldCallback.ON_EXIT
*/
public void
numberOfSignFields(int countSignFields,
String fileName, int
eventType);
/**
* Provides the list of SignFieldInfo for all sign fields.
* It allows to read and update current values for each sign field.
*
* @param signFieldInfoList List of SignFieldInfo elements
* @param fileName Name of loaded file
* @param
eventType
SignFieldCallback.ON_LOAD |
SignFieldCallback.ON_SAVE
| SignFieldCallback.ON_EXIT
* @return true if successful otherwise false
*/
public boolean
updateSignFieldInformation(List<SignFieldInfo>
signFieldInfoList, String
fileName, int eventType);
/**
* Gets ordered sign field list from input sign field list
*
* @param inputSignFields List of input sign field names
* @param orderedSignFields List of ordered sign field names
* @param int eventType SignFieldCallback.ON_LOAD (only)
* @return true if successful otherwise false
*/
public boolean
getOrderedSignFields(List<String> inputSignFields,
List<String>
orderedSignFields, int eventType);
}
Hinweise:
Die Callback-Methode getOrderedSignFields wird nur
beim Laden eines Dokuments aufgerufen (Event type SignFieldCallback.ON_LOAD), und zwar nach dem Aufruf der bisherigen
Callback-Methoden numberOfSignFields und updateSignFieldInformation.
Falls die Property ICibApplication.PROPERTY_SIGN_REQUIRED_FIRST
= "signRequiredFirst.Enabled"
gesetzt ist, wird die Callback-Methode getOrderedSignFields nicht
aufgerufen, in diesem Fall werden zuerst die erforderlichen und danach die
optionalen Signaturfelder durchlaufen.
Beim Speichern eines Dokuments (Event type SignFieldCallback.ON_SAVE)
und beim Beenden des Jview (Event type SignFieldCallback.ON_EXIT)
werden nur die Callback-Methoden numberOfSignFields und updateSignFieldInformation
aufgerufen.
Beim Aufruf der Callback-Methode getOrderedSignFields werden diese Parameter übergeben:
- List<String> inputSignFields: Liste der Namen der Signaturfelder
- List<String> orderedSignFields: Leere Liste, die in der Callback-Methode mit der sortierten Liste der Signaturfeld-Namen gefüllt werden kann, falls eine andere Sortierung gewünscht ist.
- int eventType: Event type SignFieldCallback.ON_LOAD
Behandlung nach Aufruf der
Callback-Methode getOrderedSignFields:
- Falls die Liste orderedSignFields unverändert leer zurückgeliefert wird, bleibt die Reihenfolge der Signaturfelder unverändert.
- Falls eine nichtleere Liste orderedSignFields zurückgeliefert wird, werden die Signaturfelder in der in orderedSignFields angegebenen Reihenfolge durchlaufen.
- Falls die Liste der geordneten Signaturfelder weniger Elemente als die Liste der übergebenen Signaturfelder enthält, werden nur die Signaturfelder aus der Liste orderedSignFields in der angegebenen Reihenfolge durchlaufen. Signaturfelder, die nicht in der Liste der geordneten Signaturfelder enthalten, werden in der Ausfüllreihenfolge nicht berücksichtigt. Es erfolgt eine Trace-Ausgabe, dass die Liste orderedSignFields weniger Elemente als die Liste inputSignFields enthält.
- Falls die Liste der geordneten Signaturfelder mehr Elemente als die Liste der übergebenen Signaturfelder enthält, werden nur die Signaturfelder aus der Liste orderedSignFields in der angegebenen Reihenfolge durchlaufen, die auch in der Liste inputSignFields enthalten sind. Es erfolgt eine Trace-Ausgabe, dass die Liste orderedSignFields mehr Elemente als die Liste inputSignFields enthält.
- Die Prüfung der Signaturfeldnamen wird case-sensitiv durchgeführt, d.h. gleiche Feldnamen mit vom Original abweichender Groß-/Kleinschreibung werden als ungültige Feldnamen betrachtet.
- Falls die Liste orderedSignFields ungültige Einträge enthält, also Einträge die nicht in der Liste der übergebenen Signaturfelder enthalten sind, werden die falschen Einträge nicht in die Liste der auszufüllenden Signaturfelder übernommen und eine entsprechende Trace-Ausgabe erfolgt.
- Falls die Liste orderedSignFields doppelte Einträge enthält, werden die doppelten Einträge nicht in die Liste der auszufüllenden Signaturfelder übernommen und eine entsprechende Trace-Ausgabe erfolgt.
- Tritt beim Aufruf des SignField-Callbacks getOrderedSignFields oder bei der Nachbearbeitung eine Exception auf, wird diese abgefangen, eine Trace-Ausgabe gemacht und eine entsprechende Fehlermeldung angezeigt.
Code-Beispiel zum Setzen eines SignFieldCallback Listeners bei der Jview-Instanz:
// Definition eines SignFieldCallback Listeners
static class SignFieldCallbackTester implements SignFieldCallback {
public void
numberOfSignFields(int countSignFields,
String fileName, int
eventType) {
JCibTrace.info("SignFieldCallback
- numberOfSignFields = "
+ countSignFields
+ ", fileName
= " + fileName
+ ",
eventType = " + eventType);
}
public boolean
updateSignFieldInformation(List<SignFieldInfo>
signFieldInfoList,
String fileName, int eventType) {
JCibTrace.info("SignFieldCallback
-
updateSignFieldInformation:
fileName = " + fileName
+ ",
eventType = " + eventType);
// Example how to read and update sign field information
if (signFieldInfoList == null)
return false;
if (eventType == SignFieldCallback.ON_LOAD) {
int i = 0;
for (SignFieldInfo info : signFieldInfoList) {
i++;
info.setSignerName("Signer_" + i);
info.setReason("SignReason_" + i);
// Set each sign
field with even index to
// mandatory,
with odd index to optional.
// Method setMandatory not yet available!
// info.setMandatory(i % 2 == 0);
info.setTooltip("Tooltip-" + info.getName());
JCibTrace.info(
"Update
sign field " + info.getName()
+ ",
SignerName = " + info.getSignerName()
+
", Reason = " + info.getReason()
+
", Location = " + info.get Location()
+ ", isSigned = " +
info.isSigned()
+
", TimeStamp = " + info.getTimeStamp()
+
", isMandatory = " + info.isMandatory()
+
", Tooltip = " + info.getTooltip());
}
}
else if (eventType == SignFieldCallback.ON_SAVE) {
for (SignFieldInfo info : signFieldInfoList) {
JCibTrace.info(
"Read
sign field " + info.getName()
+
", SignerName = " + info.getSignerName()
+
", Reason = " + info.getReason()
+
", Location = " + info.getLocation()
+
", isSigned = " + info.isSigned()
+
", TimeStamp = " + info.getTimeStamp()
+
", isMandatory = " + info.isMandatory()
+
", Tooltip = " + info.getTooltip());
}
}
else if (eventType == SignFieldCallback.ON_EXIT) {
for (SignFieldInfo info : signFieldInfoList) {
JCibTrace.info(
"Read
sign field " + info.getName()
+
", SignerName = " + info.getSignerName()
+
", Reason = " + info.getReason()
+ ", Location = " + info.getLocation()
+
", isSigned = " + info.isSigned()
+
", TimeStamp = " + info.getTimeStamp()
+
", isMandatory = " + info.isMandatory()
+
", Tooltip = " + info.getTooltip());
}
}
return true;
}
public boolean
getOrderedSignFields(
List<String>inputSignFields,
List<String>
orderedSignFields,
int
eventType) {
if (eventType != SignFieldCallback.ON_LOAD) {
JCibTrace.debug("SignFieldCallback
.getOrderedSignFields
- Only eventType SignFieldCallback.ON_LOAD
allowed.");
return false;
}
if (inputSignFields == null) {
JCibTrace.debug("SignFieldCallback
.getOrderedSignFields
- No input sign field
list
given");
return false;
}
if (orderedSignFields == null) {
JCibTrace.debug("SignFieldCallback
.getOrderedSignFields
- No ordered sign field
list
given");
return false;
}
// Clear ordered sign field list
orderedSignFields.clear();
// Fill ordered sign field list with all input sign fields
orderedSignFields.addAll(inputSignFields);
// Order output sign list e.g. by alphabetical string order Collections.sort(orderedSignFields);
JCibTrace.debug("SignFieldCallback.getOrderedSignFields
-
Event type =
" + eventType
+ "\nInput sign fields:" + inputSignFields
+ "\nOrdered sign fields:" + orderedSignFields);
return true;
}
}
// Beim Start von Jview
// Register SignFieldCallback Listener
viewer.setSignFieldCallback(new SignFieldCallbackTester());
...
// Beim Beenden von Jview
// do post processing here
viewer.stop();
// Unregister SignFieldCallback Listener
viewer.setSignFieldCallback(null);
...
Interface CustomCloseDialogInfo zum Austausch von Informationen für den CustomCloseDialogCallback
Die Datenstruktur CustomCloseDialogInfo dient zum Austausch von Informationen für den CustomCloseDialogCallback, sie ist im CIB jview (package de.cib.view.modules) definiert.
Interface CustomCloseDialogInfo:
package de.cib.view.modules;
/**
* Interface describing the data structure for custom close dialog
* with information to form and sign fields.
*
*/
public interface CustomCloseDialogInfo {
/**
* Returns whether the form is changed or not
* @return boolean flag
*/
boolean isFormChanged();
/**
* Gets the unsigned mandatory field count
* @return number of unsigned mandatory fields
*/
int getUnsignedMandatorySignatureCount();
/**
* Gets the unsigned optional field count
* @return number of unsigned optional fields
*/
int getUnsignedOptionalSignatureCount();
}
Das Interface CustomCloseDialogCallback ist im CIB jview (package de.cib.view.modules) definiert und umfasst folgende Methoden.
Interface CustomCloseDialogCallback:
package de.cib.view.modules;
/**
* Interface defining the callback for custom close dialog
*
*/
public interface CustomCloseDialogCallback {
/**
* Method showCustomCloseDialog
* @param customCloseDialogInfo interface to read form&sign data
* @return returnCode of CustomCloseDialog
* 0 - Yes
* 1 - No
* 2 - Cancel
*/
public int showCustomCloseDialog(
CustomCloseDialogInfo customCloseDialogInfo);
}
Der Aufrufer muss sich dazu bei der Jview-Instanz als Listener anmelden, dazu ein Code-Beispiel:
// register CustomCloseDialogCallback
viewer.setCustomCloseDialogCallback(new CustomCloseDialogCallback() {
@Override
public int showCustomCloseDialog(
CustomCloseDialogInfo customCloseDialog) {
int unsignedMandatoryCount = customCloseDialog
.getUnsignedMandatorySignatureCount();
int unsignedOptionalCount = customCloseDialog
.getUnsignedOptionalSignatureCount();
int unsignedSignatureCount = unsignedMandatoryCount
+ unsignedOptionalCount;
String message = "";
if (customCloseDialog.isFormChanged())
message = "Das Dokument enthält Änderungen an Formularfeldern, die noch nicht gespeichert wurden.";
if (unsignedSignatureCount > 0) {
if (!message.isEmpty())
message += "\n";
message += "Das Dokument enthält noch %1 zu signierende(s) Feld(er), %2 Pflicht- und %3 optionale Feld(er).";
message
= message.replaceFirst("%1",
String.valueOf(unsignedSignatureCount));
message =
message.replaceFirst("%2",
String.valueOf(unsignedMandatoryCount));
message =
message.replaceFirst("%3",
String.valueOf(unsignedOptionalCount));
}
if (message.isEmpty())
return JCibOptionPane.YES_OPTION;
message += "\nMöchten Sie die Bearbeitung trotzdem beenden?";
return
JCibOptionPane.showYesNoDialog(
viewer, message, "Rückfrage"));
}
});
Methode zur Abfrage des Rückgabewerts beim Beenden-Dialog:
In der Viewer-Instanz (Klasse JCibView) ist die Methode getCloseAction() verfügbar, die den Rückgabewert des Beenden-Dialogs liefert.
int closeDialogButton = viewer.getCloseAction();
Mögliche Werte (siehe auch CustomCloseDialogCallback):
0 – Ja
1 – Nein
2 – Abbrechen
-1 – Vorbelegung (Dialog wurde nicht geöffnet)
Code-Beispiel für die Abfrage des gedrückten Buttons nach dem Beenden im Exit-Hook:
viewer.setExitHook(new Runnable() {
public void run() {
// do post processing here
viewer.stop();
// unregister FormFieldCallback Listener
viewer.setFormFieldCallback(null);
// Unregister SignFieldCallback Listener
viewer.setSignFieldCallback(null);
int closeDialogButton = viewer.getCloseAction();
System.out.println("The following button was pressed in the close dialog: " + closeDialogButton);
}
});