Java API Schnittstellenbeschreibung

Copyright ©

Mindbreeze GmbH, A-4020 Linz, 2018.

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.

IndizierungPermanenter Link zu dieser Überschrift

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 sendenPermanenter Link zu dieser Überschrift

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?Permanenter Link zu dieser Überschrift

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?Permanenter Link zu dieser Überschrift

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 InformationenPermanenter Link zu dieser Überschrift

Für weitere Informationen siehe https://www.mindbreeze.com/developer/basic-indexing.

Hinweise für Producer-Consumer SzenarienPermanenter Link zu dieser Überschrift

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 WiederholenPermanenter Link zu dieser Überschrift

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 WiederholenPermanenter Link zu dieser Überschrift

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 IDEPermanenter Link zu dieser Überschrift

Damit Sie mit der Eclipse IDE debuggen können, sind folgende Schritte notwendig:

  1. 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:

  1. endpoint: Die URL Ihrer Appliance (z.B. https://inspire.my.company.com:8443)
  2. filterid, indexid: Die TCP-Ports des Filter- und Indexservices (z.B. 23400, 23101)
  3. username, password: Informationen, die in den BASIC Authorization Header zur Appliance gesendet werden. (z.B. Anmeldeinformationen der inspireapi)
  4. nodeid: Zu finden im Management Center (z.B. inspire-abc123def567…)
  • Erzeugen Sie ein Projekt mit dem Kommando mesjavaplugin (oder mesjavaplugin.sh unter Linux):
  • Ein Ordner mit folgender Struktur wird erzeugt:
  • Fügen Sie das neue Projekt in Ihren Eclipse Workspace hinzu.
  • Klicken Sie mit der rechten Maustaste auf den Package-Explorer und klicken Sie auf „Import…“. Wählen Sie „General“ „Existing Projects into Workspace“:
  • Wählen Sie anschließend das neue Projekt aus:

  • Überprüfen Sie die Eigenschaften in der Datei „MySourceTest.java“ (korrekter Endpoint, Anmeldeinformationen, …) und passen Sie diese an, wenn notwendig.

    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 MetadatenPermanenter Link zu dieser Überschrift

    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 FragmentePermanenter Link zu dieser Überschrift

    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].

    Hinweise für Query Expression Transformation Service PluginsPermanenter Link zu dieser Überschrift

    Required PluginsPermanenter Link zu dieser Überschrift

    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>