Connectors¶

The Voyado Elevate Connector is a Java/.NET API that provides an interface to the Elevate Servers that together constitute an Elevate installation. The API provides a model where queries are conceptually sent to the Elevate cluster as a whole. Should one or more Elevate Servers happen to be offline or not respond in time, the Connector will transparently perform any necessary retries and redirections. This means that if requests are made through the Connector both load balancing and failover will be handled automatically.

Connector object¶

The Connector object allows for communication with an Elevate cluster. It can be either a CloudConnector object or an OnPremConnector object. The configuration of the cluster, and the information of the Elevate servers, will be fetched based on the information sent in the cluster definition string.

CloudConnector¶

Use a static method on the CloudConnector class to get a CloudConnector object. Credentials to a cluster, e.g. user name and password, will be provided by Voyado. The Connector will automatically acquire the current cluster configuration from the Voyado Elevate Cloud environment as well as automatically refresh it if the configuration changes.

CloudConnector conn = CloudConnector.getOrCreate("esales://username:password");

OnPremConnector¶

Use a static method on the OnPremConnector class to get an OnPremConnector object. Note that the server addresses, the URI, must be manually configured. The URI is a semicolon separated list of host names and ports for the server in the cluster. If the cluster changes, the Connector will try to keep up by refreshing its configuration from the configured servers. However, its still best to update the configuration string if the cluster needs to change.

OnPremConnector conn = OnPremConnector.getOrCreate("esales://server-1:35810;server-2:35810");

Session object¶

Some requests made to Elevate requires that the request is connected to a session. To identify sessions, Session objects are used upon which requests can be made. A session can be created from the Connector object. The returned Session object can be kept, or a new one can be created when needed.

The customer_key and/or market can be specified when the object is created. If they are unknown when the object is created they can be replaced by null. Note that if the Session objects are kept, as opposed to creating a new one when needed, the customer_key and/or market will automatically be changed in the object if a property notification with the appropriate name (customer_key or market respectively) is made on it.

Also note that creating the Session object does not modify the server. It will apply the market and the customer key to the session first when a notification is made or a panel is retrieved within the session.

Session session = conn.session("MySessionKey", "MyCustomerKey", "Sweden");
...
Session session2 = conn.session("MyOtherSessionKey", null, "Sweden");

Retrieving content¶

To retrieve the contents of a panel with a Connector, the panel to query must first be specified. The retreiveContent() method can then be called with appropriate arguments. The content from the panel can be retrieved as an object called PanelContent. This object corresponds to the content at some level in the panel hierarchy and can thus either be a container or contain a result. The method isZone() will return true if it is a zone, i.e. a panel which may contain sub-panels, while the method hasResult() will return true if it contains a result. Sub-panels can be retrieved in the following way:

ArgMap arguments = new ArgMap();
arguments.put("attribute", "value");
...
Panel panel = session.panel("/example_page");
PanelContent panelContent = panel.retrieveContent(arguments);
if (panelContent.isZone()) {
    List<PanelContent> subPanels = panelContent.subPanels();
}

If the PanelContent contains any result, the type of the result may vary. It can be one of seven different result types upon which different methods can be invoked. At the point where the result is used, it is most likely known which type of result that is expected from a certain panel. Below several examples of how to retrieve different types of results are shown.

try {
    PanelContent subpanelContent = panelContent.subpanel("search_hits");
    if (subpanelContent.hasResult()) {
        Products products = subpanelContent.resultAsProducts();
        // Treat the products
    }
    subpanelContent = panelContent.subpanel("autocomplete");
    if (subpanelContent.hasResult()) {
        Completions completions = subpanelContent.resultAsCompletions();
        // Treat the completions
    }
    subpanelContent = panelContent.subpanel("corrections");
    if (subpanelContent.hasResult()) {
        Corrections corrections = subpanelContent.resultAsCorrections();
        // Treat the corrections
    }
    subpanelContent = panelContent.subpanel("facets");
    if (subpanelContent.hasResult()) {
        Values values = subpanelContent.resultAsValues();
        // Treat the values
    }
    subpanelContent = panelContent.subpanel("search_hit_count");
    if (subpanelContent.hasResult()) {
        Count count = subpanelContent.resultAsCount();
        // Treat the count
    }
    subpanelContent = panelContent.subpanel("ad_information");
    if (subpanelContent.hasResult()) {
        Ads ads = subpanelContent.resultAsAds();
        // Treat the ads
    }
    subpanelContent = panelContent.subpanel("recent_searches");
    if (subpanelContent.hasResult()) {
        Phrases phrases = subpanelContent.resultAsPhrases();
        // Treat the phrases
    }
} catch (ResultTypeException e) {
  // One of the results did not match the specified result type.
}

Full export¶

A full export to XML of products, configuration, ads, panels, and synonyms can be done using the Connector. Below is an example of a product export:

try(InputStream stream = conn.exportProducts()) {
    // read stream
} catch (IOException e) {
    System.out.println("Failed to export products");
}

// Or export directly to a file
try {
    conn.exportProducts(new File("/path/to/products.xml"));
} catch (IOException e) {
    System.out.println("Failed to export products to file");
}

// The same procedure can be done for Configuration, Ads, Panels, Synonyms.

Filtered product export¶

In addition to doing a full export to XML with the Connector, products can also be fetched as the same kind of objects used in panel results. A filter can be specified to only get a subset of all products. Below is an example using the Java Connector:

public static void printPaperbackPrices(Connector conn) {
    String filter = "category:'books' AND format:'paperback'";
    String presentationAttributes = "title, author, price";
    try (ProductStreamer productStreamer = conn.exportProducts(filter, presentationAttributes)) {
        for (Product product : productStreamer) {
            String title = product.getValue("title", product.key());
            String author = product.getValue("author", "Unknown author");
            String price = product.getValue("price", "Unknown price");
            System.out.println(title + " by " + author + " costs " + price);
        }
    } catch (InterruptedIterationException e) {
        System.out.println();
        System.out.println("... and maybe more.");
    }
}

For more details, see the documentation for the ProductStreamer class in the documentation for Java or .NET.

Downloads¶

For Connector downloads, see Downloads.

Connector specific documentation¶

• Java: Apptus Connector Docs for Java
• .NET: Apptus Connector Docs for .NET