Entwicklung eines Query Expression Transformer

Einführung

Der Query Expression Transformer bietet die Funktionalität, Mindbreeze Query Anfragen beliebig zu transformieren. Die Funktionalität wird durch das Erstellen eines Plugins mit dem Mindbreeze Software Development Toolkit bereitgestellt. Der SDK erzeugt ein Beispiel-Plugin, das angepasst werden kann.

Vorbereitung

Zum Bauen und Erstellen eines Plugins mit dem Mindbreeze Software Development Toolkit werden folgende Software Komponenten benötigt:

• Java SE Development Kit: Version 1.8 or later
• Eclipse IDE for Java Developers

Mindbreeze Software Development Toolkit

Um ein Plugin-Projekt für ein Query Expression Transformer Plugin zu erstellen, muss das Erstellungsskript mit folgenden Parametern aufgerufen werden:

mesjavaplugin.<sh|bat> <Plugin Type> <Name> <Base Package>

• Plugin Type: Der Plugin Typ muss queryexpressiontransformer sein.
• Name: Der Name des Plugins kann beliebig gewählt werden, wobei der Name keine Punkte oder Sonderzeichen beinhalten sollte. In der Index-Konfiguration kann das Plugin hochgeladen werden und mit dem angegebenen Namen konfiguriert werden.
• Base Package: Das Base Package der Java Klassen die erzeugt werden. Kann beliebig gewählt werden, wobei der Name keine Punkte oder Sonderzeichen beinhalten sollte.

Erzeugen eines Plugins

Das Mindbreeze Software Development Toolkit erzeugt ein Plugin-Projekt, welches unter dem angegebenen Namen im aktuellen Verzeichnis verfügbar ist.

1. Plugin Projekt in Eclipse importieren.
   
   
2. Eine Basisimplementierung des Plugins ist unter dem Namen <Name>QueryExpressionTransformer.java verfügbar.
   
3. Zum Erstellen des Plugins muss build.bat (Microsoft Windows) bzw. build.sh (Linux) aufgerufen werden. Ein Plugin mit dem Namen
   <name>-queryexpressiontransformer.zip wird erzeugt.
   
4. Das Plugin kann mit der Mindbreeze Konfigurationsoberfläche installiert werden.
   
5. Um das Plugin zu verwenden muss es in der Index-Konfiguration unter „Query Transformation Services“ konfiguriert werden. Dazu muss der Transformer zuerst aus dem Dropdown-Menü ausgewählt werden, um diesen dann mit „Add“ zu den Query Transformation Services hinzuzufügen.

1. Das automatisch generierte Plugin enthält Beispiel-Code zum Transformieren von Queries. Das Beispiel-Plugin transformiert Queries, welche die Wörter „DIN“ und „A4“/ „A5“/ etc. beinhalten. Solche Queries werden transformiert, sodass auch Objekte gefunden werden, dessen Dimensions-Metadaten dem DIN-Standard entsprechen.
   

Eine Query wie:

Poster Cat DIN A4

Wird transformiert zu:

(Poster Cat DIN A4) OR (width:297 AND height:210)

Unten sehen Sie eine Beispielsuche, wo ein zusätzliches Dokument durch diese Query Transformation gefunden wird.

Implementierung der Transformation

Implementierung der Request Transformation

Um den Request zu transformieren muss die Methode transform implementiert werden.

Dieses Beispiel ist im generierten Code des SDK enthalten und transformiert den einkommenden Query Expression Transformation Request. Es ist dabei zu beachten, dass die transformierte Query Expression schlussendlich als Query Expression Transformation Response weitergeleitet werden muss.

/*
* This inherited method is the entry point for transforming queries.
* */
@Override
public void transform(com.google.protobuf.RpcController rpcController,
                      QueryExprTransformationRequest request,
                          com.google.protobuf.RpcCallback<QueryExprTransformationResponse> done) {
        try {
            QueryExpr transformedQueryExpr = transformQueryExpr(request.getQueryExpr()); //transform the query

            //build response with transformed query
            QueryExprTransformationResponse.Builder responseBuilder = QueryExprTransformationResponse.newBuilder();
            responseBuilder.setQueryExpr(transformedQueryExpr);
            QueryExprTransformationResponse response = responseBuilder.build();
            done.run(response);
        } catch (Exception ex) {
            throw new RuntimeException(ex);
        }
    }

Die eigentliche Transformation führen wir in der Methode transformQueryExpr durch. Hier können Sie sehen, dass jede Art von Query Expression gesondert bearbeitet werden muss, damit das Endergebnis wieder richtig zusammengesetzt wird. Query Expressions können ineinander verschachtelt sein und können eine tiefe Baumstruktur bilden. Für das Transformieren von Queries mit einer solchen Baumstruktur, werden alle Kind-Queries rekursiv abgearbeitet. Der relevante Code dafür kann im generierten Beispiel in der Methode transformOnlyFieldsOfMessage gefunden werden und kann auch für individuelle Anwendungen mit wenig Anpassung weiterverwendet werden.

/*
     * This Query Expression Transformer can only handle expressions of type EXPR_TERMS.
     * These are the kind of query that is generated for queries without any formatting like "cat poster din a4"
     * Handling for other kinds of query expressions can be added here.
     * It is important to always return a valid Query Expression, not doing so can lead to follow-up-errors
     * */
    QueryExpr transformQueryExpr(QueryExpr expr) {
        if (expr.getKind() == Kind.EXPR_TERMS) {
            return transformQueryExprTerms(expr);
        }

        //recursively iterate through child elements, visit each child element and call transformQueryExpr method again for child query expressions
        return (QueryExpr) transformOnlyFieldsOfMessage(expr);
    }

In der Implementierung von transformQueryExprTerms aus dem generierten Beispiel kann man erkennen, wie die originale Query Expression zuerst durchsucht und dann manipuliert wird. Weitere Beispiele für das Erstellen von neuen Query Expressions können aus den Unit Tests entnommen werden.

    /*
    * Each kind of Query Expression will need to be handled slightly differently in order to transform the query appropriately.
    * This method contains logic to look for "din" and "a4" in the expression terms and perform the corresponding
    * transformation if the strings exist in the query.
    */
   QueryExpr transformQueryExprTerms(QueryExpr originalExpr) {
       if (originalExpr.getKind() != Kind.EXPR_TERMS) {
           throw new IllegalArgumentException("Expected kind to be \"EXPR_TERMS\" but was \"" + originalExpr.getKind() + "\"");
       }
       if (originalExpr.getTermsExpr() == null) {
           return originalExpr;
       }

       List<QueryExpr.Terms.Element> originalTerms = originalExpr.getTermsExpr().getElementList();
       String foundDinMarker = getDinMarkerIfInTerms(originalTerms);

       //don't transform if the text markers are not found
       if (foundDinMarker == null) {
           return originalExpr;
       }

       //build the new query
       QueryExpr heightMetadataSearchExpr = QueryExprHelper.labeled(HEIGHT_METADATA_NAME, QueryExprHelper.term(dinStandardToHeightMm.get(foundDinMarker)));
       QueryExpr widthMetadataSearchExpr = QueryExprHelper.labeled(WIDTH_METADATA_NAME, QueryExprHelper.term(dinStandardToWidthMm.get(foundDinMarker)));

       // In this example, we use 'OR' for the outside of the query to find additional results, which match the metadata
       // query while also including all results from the original query
       QueryExpr.Builder transformedQuery =
               QueryExprHelper.or(
                       QueryExprHelper.terms(originalTerms),
                       QueryExprHelper.and(
                               heightMetadataSearchExpr,
                               widthMetadataSearchExpr))
               .toBuilder();

       //always pass on the original unparsed expression
       copyOriginalUnparsedExpr(originalExpr, transformedQuery);

       return transformedQuery.build();
   }