Schnittstellenbeschreibung
Java API
Copyright ©
Mindbreeze GmbH, A-4020 Linz, 2021.
Alle Rechte vorbehalten. Alle verwendeten Hard- und Softwarenamen sind Handelsnamen und/oder Marken der jeweiligen Hersteller.
Diese Unterlagen sind streng vertraulich. Durch die Übermittlung und Präsentation dieser Unterlagen alleine werden keine Rechte an unserer Software, an unseren Dienstleistungen und Dienstleistungsresultaten oder sonstigen geschützten Rechten begründet. Die Weitergabe, Veröffentlichung oder Vervielfältigung ist nicht gestattet.
Aus Gründen der einfacheren Lesbarkeit wird auf die geschlechtsspezifische Differenzierung, z.B. Benutzer/-innen, verzichtet. Entsprechende Begriffe gelten im Sinne der Gleichbehandlung grundsätzlich für beide Geschlechter.
Unterstütze Java Versionen
Das Mindbreeze Java SDK unterstützt Java Version 8.
Indizierung
Dieser Abschnitt behandelt das Senden von Objekten an Mindbreeze. Sie lernen die Bestandteile eines Crawler kennen und welche Daten für jedes gesendete Objekt bekannt sein müssen.
Objekte an Mindbreeze senden
Um Objekte suchen zu können, müssen zuerst Objekte im Index liegen. Dieses Kapitel erklärt, wie Sie Objekte Ihrer Datenquelle an Mindbreeze schicken können. Es ist sehr einfach ein Objekt suchbar zu machen, die folgenden Zeilen genügen, um ein Objekt mit dem Titel „title“ und dem key „1“ im Index abzulegen:
Indexable indexable = new Indexable();
indexable.setKey("1");
indexable.setTitle("title");
client.filterAndIndex(indexable);
Rund um diese Zeilen gibt es noch einige Dinge zu klären. Zuallererst müssen Sie sich Gedanken darüber machen, welche Dokumente aus Ihrer Datenquelle relevant für die Suche sind.
Welche Objekte gibt es in meiner Datenquelle?
Wenn man einen neue Datenquelle zur Suche hinzufügen möchte, sollte man sich immer Gedanken darüber machen, welche Inhalte für die Benutzer interessant sind.
Dieses Beispiel verwendet beliebige CMIS-Services als Datenquelle. CMIS bietet vier unterschiedliche Objekttypen: Folders, Documents, Relationsships und Policies. Hier werden ausschließlich Dokumente gesendet.
Wie werden Objekte gesendet? Welcher Prozess kümmert sich darum?
Mindbreeze verwendet Crawler, um Objekte an den Index zu senden. Ein Crawler kennt die Datenquelle und sendet die darin enthaltenen Objekte zur Indizierung. Für jeden Datenquellentyp gibt es einen Crawler. Für Mindbreeze InSpire gibt es unter anderem einen Microsoft Exchange Crawler und einen Microsoft SharePoint Crawler. Wir bieten die gleiche Pluginschnittstelle, die wir für unsere Crawler verwenden, auch in unserem SDK an.
Als ersten Schritt sollten Sie den Beispielcrawler als Plugin paketieren und in Ihrer Appliance einspielen. Klicken Sie mit der rechten Maustaste auf die Datei build.xml und wählen Sie Run As > Ant Build aus.
Dadurch wird im Verzeichnis build die das Plugin-Archiv cmis-datasource.zip angelegt.
Nun muss das Plugin noch in der Appliance hinterlegt werden. Öffnen Sie dazu die Konfigurationsoberfläche von Mindbreeze und wechseln zum Karteireiter Plugins. Wählen Sie die Zip-Datei aus und bestätigen Sie mit Upload.
Nun ist das Plugin installiert.
Legen Sie nun einen Index an und fügen Sie eine neue Datenquelle hinzu.
Weitere Informationen
Für weitere Informationen siehe https://www.mindbreeze.com/developer/basic-indexing.
Hinweise für Producer-Consumer Szenarien
Wenn ein Producer-Consumer Setup verwendet wird, synchronisieren sich die Indizes im regelmäßigen Abstand. Das Synchronisieren („SyncDelta“) benötigt je nach Datenmenge einige Sekunden bis Minuten. In dieser kurzen Zeit ist aus technischen Gründen der Index nur lesend („Read-Only“) verwendbar. (Der gleiche Effekt wird erreicht durch manuelles setzen des Index auf Read-Only).
Wenn in diesem Zeitfenster ein FilterAndIndexClient verwendet wird, z.B.
client.filterAndIndex(indexable)
so wird das indexable wird nicht indiziert. Durch die asynchrone Verarbeitung wird hier auch keine Exception geworfen.
Daher empfehlen wir folgende mögliche Strategien zur Fehlerbehandlung:
Automatisches Wiederholen
Hier wird im Fall, dass der Index gerade ein SyncDelta durchführt bzw Read-Only ist, das indexable automatisch wiederholt, solange bis es erfolgreich Indiziert wurde.
Dies muss mit dem Property repeat_on_503 in der Konfiguration aktiviert werden. Das Property muss auf true gesetzt werden.
In einem Crawler muss das Property als Option im plugins.xml gesetzt werden.
In einem eigenständigen Pusher muss das Property im Configuration-Objekt in beim Aufruf der Factory Methode von FilterAndIndexClientFactory gesetzt werden.
Manuelles Wiederholen
Um zu erkennen, ob die Verwendung von FilterAndIndexClient erfolgreich war, kann ein ProcessIndexableListener registriert werden:
client.addProcessIndexableListener(new ProcessIndexableListener() {
@Override
public void processed(ProcessIndexableEvent event) {
Indexable indexable = event.getSource();
boolean wasSuccessful = event.wasSuccessful();
Operation operation = event.getOperation(); // e.g. FILTER_AND_INDEX or DELETE
Throwable cause = event.getCause(); // if not successful, this is the exception
if (!wasSuccessful){
// Do error handling here
}
}
});
Dieser ProcessIndexableListener wird asynchron nach der Verwendung des FilterAndIndexClient aufgerufen.
Debugging mit der Eclipse IDE
Damit Sie mit der Eclipse IDE debuggen können, sind folgende Schritte notwendig:
- Damit die generierte Datei die richtigen Einstellungen enthält, müssen Sie einige Eigenschaften anpassen. Die entsprechende Konfigurationsdatei finden Sie in Ihrer Mindbreeze SDK Installation unter SDK/servicesapi/java/debug.properties.
Folgende Einstellungen sind gegebenenfalls anzupassen:
- endpoint: Die URL Ihrer Appliance (z.B. https://inspire.my.company.com:8443)
- filterid, indexid: Die TCP-Ports des Filter- und Indexservices (z.B. 23400, 23101)
- username, password: Informationen, die in den BASIC Authorization Header zur Appliance gesendet werden. (z.B. Anmeldeinformationen der inspireapi)
- nodeid: Zu finden im Management Center (z.B. inspire-abc123def567…)
Damit gewährleistet wird, dass der FilterAndIndexClient alle Dokumente zur weiteren Verarbeitung an den Filter und Index Service weiterleitet, muss der FilterAndIndexClient Ordnungsgemäß heruntergefahren werden.
Neben der generierten Klasse „MySourceTest.java“, in der Sie testen können, wird auch vom mesjavaplugin tool eine Run-Configuration im config Ordner erzeugt. (mysource-debug.launch) Wenn Sie die Test-Klasse ausführen (Rechtsklick > Run as > Java Application), startet Eclipse automatisch Ihre Tests mit der generierten Run-Configuration. Diese Run-Configuration beinhaltet alle notwendigen JAR-Dateien im Class-Path. Sie finden diese Dateien im Ordner „rt“. Standardmäßig werden alle Log-Informationen nach C:\\tmp\log-default-mysource.txt geschrieben. Zum Ändern dieses Pfads passen Sie den Pfad in der Methode configureLogger() an.
Zum Überprüfen, ob die Anfragen an den Index- und Filterservice erfolgreich sind, können Sie den „Reporting“-Bereich im Management Center öffnen. Unter „Performance“ > „Applications“ > „Filter Service“ (bzw. „Index Service“) können Sie die Anfragen anzeigen, die eingegangen sind.
Filter Service:
Index Service:
Komplexe Metadaten
Wie einfache Metadaten, wie String und Date indiziert werden können ist hier beschrieben:
https://www.mindbreeze.com/de/developer/basic-indexing#data-types
Es können jedoch auch komplexere Datenstrukturen indiziert werden, wie dieser Abschnitt zeigt.
XHTML Fragmente
Es können XHTML Fragmente als Metadatum indiziert werden. Diese Metadatum werden dann als HTML in den Suchresultaten angezeigt.
Folgendes Beispiel zeigt die Verwendung von ValueParser, mit dem ein HTML-Link als Metadatum gespeichert werden kann:
...
import com.mindbreeze.enterprisesearch.mesapi.filter.ValueParserFactory;
...
ValueParserFactory valueParser = ValueParserFactory.newInstance().newValueParser(null);
...
String xHtmlString = "<a href=\"http://example.com\">Click me</a>";
Item.Builder value = valueParser.parse(Format.XHTML, null, xHtmlString);
indexable.putProperty(NamedValue.newBuilder().setName("my_html_meta").addValue(value));
Hinweise: Der xHtmlString muss valides XHTML beinhalten. Das XHTML wird (in transformierter form) vollständig im Index gespeichert. Bei der Anzeige im Suchresultat als Metadatum werden jedoch viele XHTML-Elemente und Attribute entfernt, um das Layout gegen unerwünschte Änderungen zu schützen. Folgende XHTML Elemente werden im Suchresultat angezeigt: [a, span]. Folgende XHTML Attribute werden angezeigt, alle außer [id, class, JavaScript-functions].
Dynamisch aggregierbare Metadaten
Damit ein Metadatum filterbar ist, muss es „aggregierbar“ sein. Statisch aggregierbare Metadaten können im categoryDescriptor.xml definiert werden.
Um jedoch zur Laufzeit entscheiden zu können, welche Metadaten filterbar sein sollen, gibt es dynamisch aggregierbare Metadaten. Im Gegensatz zu statisch aggregierbaren Metadaten kann die Aggregierbarkeit zur Laufzeit und pro Dokument bestimmt werden. Folgendes Beispiel veranschaulicht, wie man bei einem Mindbreeze InSpire Dokument ein dynamisch aggregierbares Metadatum hinzufügt:
Indexable indexable = new Indexable();
indexable.putProperty(TypesProtos.NamedValue.newBuilder()
.setName("sample_meta")
.addValue(TypesProtos.Value.newBuilder()
.setStringValue("sample_value")
.setKind(TypesProtos.Value.Kind.STRING).build())
.setFlags(TypesProtos.NamedValue.Flags.INVERTED_VALUE |
TypesProtos.NamedValue.Flags.STORED_VALUE |
TypesProtos.NamedValue.Flags.AGGREGATED_VALUE)
);
Hinweise für Query Expression Transformation Service Plugins
Standard Reihenfolge
Da mehrere Query Expression Transformation Service Plugins konfiguriert werden können, ist die Reihenfolge wichtig in der diese Plugins nacheinander die Query Expression transformieren. Die Standard Reihenfolge kann mittels einer „priority“ im plugins.xml bestimmt werden. Diese „priority“ ist ein numerischer Wert und muss kleiner sein als 100.000. Die Plugins werden absteigend nacheinander ausgeführt (hohe Priortät zuerst).
Die Standard „priority“ kann pro Plugin im plugins.xml wie folgt gesetzt werden:
<!-- within the plugins.Plugin.code.Code section -->
<properties>
<KeyValuePair>
<key>priority</key>
<value>10000</value>
</KeyValuePair>
</properties>
Falls die standardmäßige Reihenfolge nicht den gewünschten Effekt zeigt, kann die Reihenfolge des Plugins mit den Pfeil-Knöpfen im Managementcenter verändert werden.
Required Plugins
Falls in einem Query Expression Transformation Service Plugin ein Fehler auftritt, (Exception oder Timeout), dann wird die Transformation übersprungen und die unveränderten Query Expression wird stattdessen verwendet.
Es gibt jedoch Plugins, die sensible Aufgaben übernehmen, wie z.B. sicherheitsrelevante Metadaten ein- und ausblenden oder beispielsweise Schlüsselwörter einer DSL auflösen. Wenn diese sensiblen Plugins defekt sind und es zu Fehlern kommen sollte, wäre ein Überspringen katastrophal, da eventuell sicherheitsrelevante Daten angezeigt werden, die bei einem korrekt funktionierenden Plugin nicht angezeigt werden würden.
Darum können Query Expression Transformation Service Plugins mit einem „required“-Flag markiert werden. Markierte Plugins werden bei einem Fehler nicht übersprungen, sondern stoppen die ganze Pipeline und es werden gar keine Ergebnisse bei der Suche angezeigt. („Fail-Fast“ Prinzip)
Das „required“ Flag kann pro Plugin im plugins.xml wie folgt gesetzt werden:
<!-- within the plugins.Plugin.code.Code section -->
<properties>
<KeyValuePair>
<key>required</key>
<value>true</value>
</KeyValuePair>
</properties>
Transform Non-Expandable Query Expressions
Query Expression Transformation Services transformieren nicht den gesamten Search Request, sondern die im Search Request enthaltenen Query Expressions. Üblicherweise können auch nicht alle Query Expressions transformiert werden, sondern nur Expandable Query Expressions. Dies kann dazu führen, dass in gewissen Situationen benötigten Daten nicht zur Transformation verwendet werden können.
Um dies zu umgehen, können Query Expression Transformation Services mit einem „transform_nonexpandable“-Flag markiert werden. Markierte Query Expression Transformation Services werden auch für das transformierten von nicht Expandable Query Expressions verwendet.
Das „transform_nonexpandable“-Flag kann pro Plugin im plugins.xml wie folgt gesetzt werden:
<!-- within the plugins.Plugin.code.Code section -->
<properties>
<KeyValuePair>
<key>transform_nonexpandable</key>
<value>true</value>
</KeyValuePair>
</properties>
Content Fetch Interface
Über das ContentFetch Interface können die Inhalte von verschiedenen Dokumenttypen bezogen werden.
public interface ContentFetch extends Closeable
Dabei müssen folgende Methoden implementiert werden:
public String getCategory();
Die Funktion getCategory() gibt die Kategorie der Datenquelle wie z.B. “Microsoft File” an, für die das content fetch verwendet werden kann.
public ContentData fetch(String category, String categoryInstance, String key,
String categoryClass, Principal identity,
Map<String, String> params);
Die Methode fetch() gibt das Datenobjekt des Suchergebnises beschrieben durch die Parameter zurück:
category – die Kategorie des Suchergebnises
categoryInstance – die Kategorieinstanz des Suchergebnises
key – der Schlüssel des Dokuments im Suchergebnis
categoryClass – Kategorieklasse des Suchergebnises
identity – Die Identität des Suchanwenders
params – Zusätzliche Parameter aus dem Kontext-Provider. Der Benutzer kann den mime Typ des Dokuments wie z.B. "mimetype" : “application/pdf“ in den params von fetch() angeben, um eine schnellere Verarbeitung zu erziehlen. Wenn der mime Typ nicht angegeben wird, dann muss er in der Implementierung der fetch() Methode aus dem Dokument ermittelt werden, was zusätzliche Laufzeit benötigt.
public void close();
Die Methode close() räumt das content fetch Objekt auf.