Developing an API V2 search request response transformer

Copyright ©

Mindbreeze GmbH, A-4020 Linz, 2018.

All rights reserved. All hardware and software names used are brand names and/or trademarks of their respective manufacturers.

These documents are strictly confidential. The submission and presentation of these documents does not confer any rights to our software, our services and service outcomes, or any other protected rights. The dissemination, publication, or reproduction hereof is prohibited.

For ease of readability, gender differentiation has been waived. Corresponding terms and definitions apply within the meaning and intent of the equal treatment principle for both sexes.

IntroductionPermanent link for this heading

The API V2 search request response transformer provides a functionality that allows you to transform API V2 search requests and responses into a format that you can define yourself. This functionality is made available by the creation of a plugin with the Mindbreeze Software Development Toolkit. The SDK creates a sample plugin that can be customized.

PreparationPermanent link for this heading

The following software components are needed to build and create a plugin with the Mindbreeze Software Development Toolkit:

  • Java SE Development Kit: Version 1.8 or newer
  • Eclipse IDE for Java developers

Creating a Mindbreeze plugin projectPermanent link for this heading

The Mindbreeze Software Development Toolkit contains a tool for generating a plugin project. The tool is provided as mesjavaplugin.bat for Microsoft Windows and as for Linux.

Mindbreeze Software Development ToolkitPermanent link for this heading

To create a plugin project for an API V2 search request transformer plugin, the tool has to be opened using the following parameters:

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

  • Plugin type: The plugin type has to be searchtransformer.
  • Name: You can choose any name you’d like for the plugin. In the configuration of the client service, the plugin can be selected using the name provided.
  • Base package: The base package of the Java classes that are created. Can be freely chosen.

Creating a pluginPermanent link for this heading

The Mindbreeze Software Development Toolkit creates a plugin project that is available in the current directory under the name provided.

  1. Import a plugin project in Eclipse

  1. A basic implementation of the plugin is available under the name <Name>
  2. To create the plugin, build.bat (Microsoft Windows) or (Linux) has to be called up. A plugin with the name
    <name> is generated.
  3. The plugin can be installed with the Mindbreeze configuration interface.
  4. In order to use the plugin, it has to be configured in the client service configuration. In this example an API V2 search request response transformer with the name APIV2SearchRequestResponseTransformer.MyCustomTransformer is configured. In order to get the metadata extension, mes:key, category, categoryinstance and icon in the result, they were configured as additional metadata. The parameter source specifies whether the value or the HTML representation is used.

  5. The plugin can be called up using the URL https://clientservice:clientserviceport/plugin/ID/search?params. In this example, the ID would be APIV2SearchRequestResponseTransformer.MyCustomTransformer. The sample plugin that was created is called up using the URL https://clientservice:clientserviceport/plugin/ID/search?q=ALL&num=20. This URL performs a search for ALL and returns 20 results in XML format.

Implementing the transformationPermanent link for this heading

Implementing the request transformationPermanent link for this heading

In order to transform the request, the method transformRequest has to be implemented.

This example is included in the generated code of the SDK and transforms the search request, defined by the HTTP parameters q and num into a Mindbreeze search request. The metadata from the plugin configuration is requested in the Mindbreeze search request in order to be present in the result.

Implementing the response transformationPermanent link for this heading

The response transformation is performed in the method transformResponse.

transformResponse(RpcController controller, ResponseTransformationRequest request, RpcCallback<HTTPResponse> done)

The request parameter contains the request to be transformed.  The response can be set using the parameter done. The following example writes all titles of the query response as text to the response.

The HTTP content type is determined by defining the media type in the response.