Package io.constructor.client

Class ConstructorIO

java.lang.Object
io.constructor.client.ConstructorIO
public class ConstructorIO extends Object
Constructor.io Client

  • Field Details

    • apiToken

      public String apiToken

    • apiKey

      public String apiKey

    • protocol

      public String protocol

    • host

      public String host

    • basePath

      public String basePath

    • port

      public Integer port

    • version

      public String version

    • constructorToken

      public String constructorToken

  • Constructor Details

    • ConstructorIO

      public ConstructorIO(String apiToken, String apiKey, boolean isHTTPS, String host, String constructorToken)
      Creates a constructor.io Client.
      Parameters:
      apiToken - API Token, gotten from your Constructor.io Dashboard, and kept secret.
      apiKey - API Key, used publicly in your in-site javascript client.
      isHTTPS - true to use HTTPS, false to use HTTP. It is highly recommended that you use HTTPS.
      host - The host of the autocomplete service that you are using. It is recommended that you let this value be null, in which case the host defaults to the Constructor.io autocomplete service at ac.cnstrc.com.
      constructorToken - The token provided by Constructor to identify your company's traffic if proxying requests for results

    • ConstructorIO

      public ConstructorIO(String apiToken, String apiKey, String constructorToken, boolean isHTTPS, String host, String basePath)
      Creates a constructor.io Client.
      Parameters:
      apiToken - API Token, gotten from your Constructor.io Dashboard, and kept secret.
      apiKey - API Key, used publicly in your in-site javascript client.
      constructorToken - The token provided by Constructor to identify your company's traffic if proxying requests for results
      isHTTPS - true to use HTTPS, false to use HTTP. It is highly recommended that you use HTTPS.
      host - The host of the autocomplete service that you are using. It is recommended that you let this value be null, in which case the host defaults to the Constructor.io autocomplete service at ac.cnstrc.com.
      basePath - The basePath to use with the host. It is recommended that you let this value be null, in which there will not be any base path.

    • ConstructorIO

      public ConstructorIO(String apiToken, String apiKey, boolean isHTTPS, String host)
      Creates a constructor.io Client.
      Parameters:
      apiToken - API Token, gotten from your Constructor.io Dashboard, and kept secret.
      apiKey - API Key, used publicly in your in-site javascript client.
      isHTTPS - true to use HTTPS, false to use HTTP. It is highly recommended that you use HTTPS.
      host - The host of the autocomplete service that you are using. It is recommended that you let this value be null, in which case the host defaults to the Constructor.io autocomplete service at ac.cnstrc.com.

    • ConstructorIO

      public ConstructorIO(String apiToken, String apiKey, boolean isHTTPS, String host, int port)

  • Method Details

    • setHttpClient

      public static void setHttpClient(okhttp3.OkHttpClient newClient)
      Parameters:
      newClient - the OkHttpClient to use by all instances

    • setHttpClientConfig

      public static void setHttpClientConfig(HttpClientConfig config)
      Parameters:
      config - the Http client config

    • getHttpClient

      public static okhttp3.OkHttpClient getHttpClient()
      Returns:
      the HTTP client used by all instances

    • setApiKey

      public void setApiKey(String apiKey)
      Sets apiKey

    • verify

      public boolean verify() throws ConstructorException
      Verifies that an autocomplete service is working.
      Returns:
      true if working.
      Throws:
      ConstructorException - if the service is not working

    • createOrReplaceItems

      public boolean createOrReplaceItems(ConstructorItem[] items, String section, Boolean force, String notificationEmail) throws ConstructorException
      Adds multiple items to your index whilst replacing existing ones (limit of 1,000 items)
      Parameters:
      items - the items you want to add or replace.
      section - the section of the index that you're adding the items to.
      force - whether or not the system should process the request even if it will invalidate a large number of existing variations.
      notificationEmail - An email address where you'd like to receive an email notification in case the task fails.
      Returns:
      true if working
      Throws:
      ConstructorException - if the request is invalid.

    • createOrReplaceItems

      public boolean createOrReplaceItems(ConstructorItem[] items) throws ConstructorException
      Throws:
      ConstructorException

    • createOrReplaceItems

      public boolean createOrReplaceItems(ConstructorItem[] items, String section) throws ConstructorException
      Throws:
      ConstructorException

    • createOrReplaceItems

      public boolean createOrReplaceItems(ConstructorItem[] items, String section, Boolean force) throws ConstructorException
      Throws:
      ConstructorException

    • deleteItems

      public boolean deleteItems(ConstructorItem[] items, String section, Boolean force, String notificationEmail) throws ConstructorException
      Deleted multiple items from your index (limit of 1,000 items)
      Parameters:
      items - the items that you are deleting
      section - the section of the index that you're removing the items from.
      force - whether or not the system should process the request even if it will invalidate a large number of existing variations.
      notificationEmail - An email address where you'd like to receive an email notification in case the task fails.
      Returns:
      true if successfully removed
      Throws:
      ConstructorException - if the request is invalid

    • deleteItems

      public boolean deleteItems(ConstructorItem[] items) throws ConstructorException
      Throws:
      ConstructorException

    • deleteItems

      public boolean deleteItems(ConstructorItem[] items, String section) throws ConstructorException
      Throws:
      ConstructorException

    • deleteItems

      public boolean deleteItems(ConstructorItem[] items, String section, Boolean force) throws ConstructorException
      Throws:
      ConstructorException

    • retrieveItems

      public ItemsResponse retrieveItems(ItemsRequest req) throws ConstructorException
      Retrieves the items service for items
      Parameters:
      req - the items request
      Returns:
      an ItemsResponse response
      Throws:
      ConstructorException - if the request is invalid.

    • retrieveItemsAsJson

      public String retrieveItemsAsJson(ItemsRequest req) throws ConstructorException
      Queries the items service for items
      Parameters:
      req - the items request
      Returns:
      a string of JSON
      Throws:
      ConstructorException - if the request is invalid.

    • deleteVariations

      public boolean deleteVariations(ConstructorVariation[] variations, String section, Boolean force, String notificationEmail) throws ConstructorException
      Deletes multiple variations from your index (limit of 1,000 variations)
      Parameters:
      variations - the variations that you are deleting
      section - the section of the autocomplete that you're removing the items from.
      force - whether or not the system should process the request even if it will invalidate a large number of existing variations.
      notificationEmail - An email address where you'd like to receive an email notification in case the task fails.
      Returns:
      true if successfully removed
      Throws:
      ConstructorException - if the request is invalid

    • deleteVariations

      public boolean deleteVariations(ConstructorVariation[] variations) throws ConstructorException
      Throws:
      ConstructorException

    • deleteVariations

      public boolean deleteVariations(ConstructorVariation[] variations, String section) throws ConstructorException
      Throws:
      ConstructorException

    • deleteVariations

      public boolean deleteVariations(ConstructorVariation[] variations, String section, Boolean force) throws ConstructorException
      Throws:
      ConstructorException

    • updateItems

      public boolean updateItems(ConstructorItem[] items, String section, Boolean force, String notificationEmail, CatalogRequest.OnMissing onMissing) throws ConstructorException
      Updates items from your index.
      Parameters:
      items - the items that you're updating
      section - the section of the autocomplete that you're modifying the item for.
      force - whether or not the system should process the request even if it will invalidate a large number of existing variations.
      onMissing - Either "FAIL", "IGNORE", "CREATE", indicating how the system will handle updating items that don't exist. "FAIL" fails the ingestion if there are items that don't exist. "IGNORE" ignores items that don't exist. "CREATE" creates items that don't exist. Defaults to "FAIL".
      notificationEmail - An email address where you'd like to receive an email notification in case the task fails.
      Returns:
      true if successfully modified
      Throws:
      ConstructorException - if the request is invalid.

    • updateItems

      public boolean updateItems(ConstructorItem[] items, String section, Boolean force, String notificationEmail) throws ConstructorException
      Updates items from your index.
      Parameters:
      items - the items that you're updating
      section - the section of the autocomplete that you're modifying the item for.
      force - whether or not the system should process the request even if it will invalidate a large number of existing variations.
      notificationEmail - An email address where you'd like to receive an email notification in case the task fails.
      Returns:
      true if successfully modified
      Throws:
      ConstructorException - if the request is invalid.

    • updateItems

      public boolean updateItems(ConstructorItem[] items) throws ConstructorException
      Throws:
      ConstructorException

    • updateItems

      public boolean updateItems(ConstructorItem[] items, String section) throws ConstructorException
      Throws:
      ConstructorException

    • updateItems

      public boolean updateItems(ConstructorItem[] items, String section, Boolean force) throws ConstructorException
      Throws:
      ConstructorException

    • updateVariations

      public boolean updateVariations(ConstructorVariation[] variations, String section, Boolean force, String notificationEmail, CatalogRequest.OnMissing onMissing) throws ConstructorException
      Update variations from your index.
      Parameters:
      variations - the variations that you're updating.
      section - the section of the autocomplete that you're modifying the item for.
      force - whether or not the system should process the request even if it will invalidate a large number of existing variations.
      notificationEmail - An email address where you'd like to receive an email notification in case the task fails.
      onMissing - Either "FAIL", "IGNORE", "CREATE", indicating how the system will handle updating variations that don't exist. "FAIL" fails the ingestion if there are items that don't exist. "IGNORE" ignores variations that don't exist. "CREATE" creates items that don't exist. Defaults to "FAIL".
      Returns:
      true if successfully modified
      Throws:
      ConstructorException - if the request is invalid.

    • updateVariations

      public boolean updateVariations(ConstructorVariation[] variations, String section, Boolean force, String notificationEmail) throws ConstructorException
      Update variations from your index.
      Parameters:
      variations - the variations that you're updating.
      section - the section of the autocomplete that you're modifying the item for.
      force - whether or not the system should process the request even if it will invalidate a large number of existing variations.
      notificationEmail - An email address where you'd like to receive an email notification in case the task fails.
      Returns:
      true if successfully modified
      Throws:
      ConstructorException - if the request is invalid.

    • updateVariations

      public boolean updateVariations(ConstructorVariation[] variations) throws ConstructorException
      Throws:
      ConstructorException

    • updateVariations

      public boolean updateVariations(ConstructorVariation[] variations, String section) throws ConstructorException
      Throws:
      ConstructorException

    • updateVariations

      public boolean updateVariations(ConstructorVariation[] variations, String section, Boolean force) throws ConstructorException
      Throws:
      ConstructorException

    • createOrReplaceVariations

      public boolean createOrReplaceVariations(ConstructorVariation[] variations, String section, Boolean force, String notificationEmail) throws ConstructorException
      Adds multiple variations to your index whilst replacing existing ones (limit of 1,000 items)
      Parameters:
      variations - the items you want to add or replace.
      section - the section of the autocomplete that you're adding the items to.
      force - whether or not the system should process the request even if it will invalidate a large number of existing variations.
      notificationEmail - An email address where you'd like to receive an email notification in case the task fails.
      Returns:
      true if working
      Throws:
      ConstructorException - if the request is invalid.

    • createOrReplaceVariations

      public boolean createOrReplaceVariations(ConstructorVariation[] variations) throws ConstructorException
      Throws:
      ConstructorException

    • createOrReplaceVariations

      public boolean createOrReplaceVariations(ConstructorVariation[] variations, String section) throws ConstructorException
      Throws:
      ConstructorException

    • createOrReplaceVariations

      public boolean createOrReplaceVariations(ConstructorVariation[] variations, String section, Boolean force) throws ConstructorException
      Throws:
      ConstructorException

    • retrieveVariations

      public VariationsResponse retrieveVariations(VariationsRequest req) throws ConstructorException
      Queries the variations service for variations
      Parameters:
      req - the variations request
      Returns:
      an VariationsResponse response
      Throws:
      ConstructorException - if the request is invalid.

    • retrieveVariationsAsJson

      public String retrieveVariationsAsJson(VariationsRequest req) throws ConstructorException
      Queries the variations service for variations
      Parameters:
      req - the variations request
      Returns:
      a string of JSON
      Throws:
      ConstructorException - if the request is invalid.

    • autocomplete

      public AutocompleteResponse autocomplete(AutocompleteRequest req, UserInfo userInfo) throws ConstructorException
      Queries the autocomplete service.

      Note that if you're making an autocomplete request for a website, you should definitely use our javascript client instead of doing it server-side! That's important. That will be a solid latency difference.

      Parameters:
      req - the autocomplete request
      userInfo - optional information about the user
      Returns:
      an autocomplete response
      Throws:
      ConstructorException - if the request is invalid.

    • autocompleteAsJSON

      public String autocompleteAsJSON(AutocompleteRequest req, UserInfo userInfo) throws ConstructorException
      Queries the autocomplete service.

      Note that if you're making an autocomplete request for a website, you should definitely use our javascript client instead of doing it server-side! That's important. That will be a solid latency difference.

      Parameters:
      req - the autocomplete request
      userInfo - optional information about the user
      Returns:
      a string of JSON
      Throws:
      ConstructorException - if the request is invalid.

    • search

      public SearchResponse search(SearchRequest req, UserInfo userInfo) throws ConstructorException
      Queries the search service.

      Note that if you're making a search request for a website, you should definitely use our javascript client instead of doing it server-side! That's important. That will be a solid latency difference.

      Parameters:
      req - the search request
      userInfo - optional information about the user
      Returns:
      a search response
      Throws:
      ConstructorException - if the request is invalid.

    • search

      public void search(SearchRequest req, UserInfo userInfo, SearchCallback c) throws ConstructorException
      Queries the search service.

      Note that if you're making a search request for a website, you should definitely use our javascript client instead of doing it server-side! That's important. That will be a solid latency difference.

      Parameters:
      req - the search request
      userInfo - optional information about the user
      c - a callback with success and failure conditions
      Throws:
      ConstructorException - if the request is invalid.

    • searchAsJSON

      public String searchAsJSON(SearchRequest req, UserInfo userInfo) throws ConstructorException
      Queries the search service.

      Note that if you're making a search request for a website, you should definitely use our javascript client instead of doing it server-side! That's important. That will be a solid latency difference.

      Parameters:
      req - the search request
      userInfo - optional information about the user
      Returns:
      a string of JSON
      Throws:
      ConstructorException - if the request is invalid.

    • browse

      public BrowseResponse browse(BrowseRequest req, UserInfo userInfo) throws ConstructorException
      Queries the browse service.

      Note that if you're making a browse request for a website, you should definitely use our javascript client instead of doing it server-side! That's important. That will be a solid latency difference.

      Parameters:
      req - the browse request
      userInfo - optional information about the user
      Returns:
      a browse response
      Throws:
      ConstructorException - if the request is invalid.

    • browse

      public void browse(BrowseRequest req, UserInfo userInfo, BrowseCallback c) throws ConstructorException
      Queries the browse service.

      Note that if you're making a browse request for a website, you should definitely use our javascript client instead of doing it server-side! That's important. That will be a solid latency difference.

      Parameters:
      req - the browse request
      userInfo - optional information about the user
      c - a callback with success and failure conditions
      Throws:
      ConstructorException - if the request is invalid.

    • browseAsJSON

      public String browseAsJSON(BrowseRequest req, UserInfo userInfo) throws ConstructorException
      Queries the browse service.

      Note that if you're making a browse request for a website, you should definitely use our javascript client instead of doing it server-side! That's important. That will be a solid latency difference.

      Parameters:
      req - the browse request
      userInfo - optional information about the user
      Returns:
      a string of JSON
      Throws:
      ConstructorException - if the request is invalid.

    • browseItems

      public BrowseResponse browseItems(BrowseItemsRequest req, UserInfo userInfo) throws ConstructorException
      Queries the browse service with item id's.

      Note that if you're making a browse request for a website, you should definitely use our javascript client instead of doing it server-side! That's important. That will be a solid latency difference.

      Parameters:
      req - the browse items request
      userInfo - optional information about the user
      Returns:
      a browse response
      Throws:
      ConstructorException - if the request is invalid.

    • browseItems

      public void browseItems(BrowseItemsRequest req, UserInfo userInfo, BrowseCallback c) throws ConstructorException
      Queries the browse service with item id's.

      Note that if you're making a browse request for a website, you should definitely use our javascript client instead of doing it server-side! That's important. That will be a solid latency difference.

      Parameters:
      req - the browse items request
      userInfo - optional information about the user
      c - a callback with success and failure conditions
      Throws:
      ConstructorException - if the request is invalid.

    • browseItemsAsJSON

      public String browseItemsAsJSON(BrowseItemsRequest req, UserInfo userInfo) throws ConstructorException
      Queries the browse service with item id's.

      Note that if you're making a browse request for a website, you should definitely use our javascript client instead of doing it server-side! That's important. That will be a solid latency difference.

      Parameters:
      req - the browse items request
      userInfo - optional information about the user
      Returns:
      a string of JSON
      Throws:
      ConstructorException - if the request is invalid.

    • browseFacets

      public BrowseFacetsResponse browseFacets(BrowseFacetsRequest req) throws ConstructorException
      Queries the browse facets service
      Parameters:
      req - the browse facets request
      Returns:
      a browse facets response
      Throws:
      ConstructorException - if the request is invalid.

    • browseFacetsAsJSON

      public String browseFacetsAsJSON(BrowseFacetsRequest req) throws ConstructorException
      Queries the browse facets service
      Parameters:
      req - the browse facets request
      Returns:
      a string of JSON
      Throws:
      ConstructorException - if the request is invalid.

    • browseFacetOptions

      public BrowseFacetOptionsResponse browseFacetOptions(BrowseFacetOptionsRequest req) throws ConstructorException
      Queries the browse facet options service
      Parameters:
      req - the browse facet options request
      Returns:
      a browse facet options response
      Throws:
      ConstructorException - if the request is invalid.

    • browseFacetOptionsAsJSON

      public String browseFacetOptionsAsJSON(BrowseFacetOptionsRequest req) throws ConstructorException
      Queries the browse facet options service
      Parameters:
      req - the browse facet options request
      Returns:
      a string of JSON
      Throws:
      ConstructorException - if the request is invalid.

    • naturalLanguageSearch

      public SearchResponse naturalLanguageSearch(NaturalLanguageSearchRequest req, UserInfo userInfo) throws ConstructorException
      Queries the search service with natural language processing.

      Note that if you're making a search request for a website, you should definitely use our javascript client instead of doing it server-side! That's important. That will be a solid latency difference.

      Parameters:
      req - the natural language search request
      userInfo - optional information about the user
      Returns:
      a search response
      Throws:
      ConstructorException - if the request is invalid.

    • naturalLanguageSearchAsJSON

      public String naturalLanguageSearchAsJSON(NaturalLanguageSearchRequest req, UserInfo userInfo) throws ConstructorException
      Queries the search service with natural language processing.

      Note that if you're making a search request for a website, you should definitely use our javascript client instead of doing it server-side! That's important. That will be a solid latency difference.

      Parameters:
      req - the natural language search request
      userInfo - optional information about the user
      Returns:
      a string of JSON
      Throws:
      ConstructorException - if the request is invalid.

    • recommendations

      public RecommendationsResponse recommendations(RecommendationsRequest req, UserInfo userInfo) throws ConstructorException
      Queries the recommendations service to retrieve results.

      Note that if you're making a recommendations request for a website, you should definitely use our javascript client instead of doing it server-side! That's important. That will be a solid latency difference.

      Parameters:
      req - the recommendations request
      userInfo - optional information about the user
      Returns:
      a recommendations response
      Throws:
      ConstructorException - if the request is invalid.

    • recommendationsAsJSON

      public String recommendationsAsJSON(RecommendationsRequest req, UserInfo userInfo) throws ConstructorException
      Queries the recommendations service to retrieve results.

      Note that if you're making an recommendations request for a website, you should definitely use our javascript client instead of doing it server-side! That's important. That will be a solid latency difference.

      Parameters:
      req - the recommendations request
      userInfo - optional information about the user
      Returns:
      a string of JSON
      Throws:
      ConstructorException - if the request is invalid.

    • replaceCatalog

      public String replaceCatalog(CatalogRequest req) throws ConstructorException
      Send a full catalog to replace the current one (sync)
      Parameters:
      req - the catalog request
      Returns:
      a string of JSON
      Throws:
      ConstructorException - if the request is invalid.

    • updateCatalog

      public String updateCatalog(CatalogRequest req) throws ConstructorException
      Send a partial catalog to update specific items (delta)
      Parameters:
      req - the catalog request
      Returns:
      a string of JSON
      Throws:
      ConstructorException - if the request is invalid.

    • patchCatalog

      public String patchCatalog(CatalogRequest req) throws ConstructorException
      Send a patch delta catalog to update specific items (delta)
      Parameters:
      req - the catalog request
      Returns:
      a string of JSON
      Throws:
      ConstructorException - if the request is invalid.

    • allTasks

      public AllTasksResponse allTasks(AllTasksRequest req) throws ConstructorException
      Queries the tasks service for all tasks
      Parameters:
      req - the all tasks request
      Returns:
      a all tasks response
      Throws:
      ConstructorException - if the request is invalid.

    • allTasksAsJson

      public String allTasksAsJson(AllTasksRequest req) throws ConstructorException
      Queries the tasks service for all tasks
      Parameters:
      req - the all tasks request
      Returns:
      a string of JSON
      Throws:
      ConstructorException - if the request is invalid.

    • task

      public Task task(TaskRequest req) throws ConstructorException
      Queries the task service for a task id
      Parameters:
      req - the task request
      Returns:
      a Task response
      Throws:
      ConstructorException - if the request is invalid.

    • taskAsJson

      public String taskAsJson(TaskRequest req) throws ConstructorException
      Queries the task service for a task id
      Parameters:
      req - the task request
      Returns:
      a string of JSON
      Throws:
      ConstructorException - if the request is invalid.

    • allRedirects

      public AllRedirectsResponse allRedirects(AllRedirectsRequest req) throws ConstructorException
      Queries the redirects service for all redirects
      Parameters:
      req - the all redirects request
      Returns:
      a all redirects response
      Throws:
      ConstructorException - if the request is invalid.

    • allRedirectsAsJson

      public String allRedirectsAsJson(AllRedirectsRequest req) throws ConstructorException
      Queries the redirects service for all redirects
      Parameters:
      req - the all redirects request
      Returns:
      a string of JSON
      Throws:
      ConstructorException - if the request is invalid.

    • quizNextQuestion

      public QuizQuestionResponse quizNextQuestion(QuizRequest req, UserInfo userInfo) throws ConstructorException
      Queries the quiz service for a quiz question
      Parameters:
      req - the Quiz request
      Returns:
      a Quiz Question Response
      Throws:
      ConstructorException - if the request is invalid.

    • quizNextQuestionAsJson

      public String quizNextQuestionAsJson(QuizRequest req, UserInfo userInfo) throws ConstructorException
      Queries the quiz service for the a quiz question
      Parameters:
      req - the Quiz request
      Returns:
      a string of JSON
      Throws:
      ConstructorException - if the request is invalid.

    • quizResults

      public QuizResultsResponse quizResults(QuizRequest req, UserInfo userInfo) throws ConstructorException
      Queries the quiz service for the quiz results
      Parameters:
      req - the Quiz request
      Returns:
      a Quiz Results Response
      Throws:
      ConstructorException - if the request is invalid.

    • quizResultsAsJson

      public String quizResultsAsJson(QuizRequest req, UserInfo userInfo) throws ConstructorException
      Queries the quiz service for the quiz results
      Parameters:
      req - the Quiz request
      Returns:
      a string of JSON
      Throws:
      ConstructorException - if the request is invalid.