Package com.apptus.esales.connector

Class Connector

java.lang.Object

com.apptus.esales.connector.Connector

Direct Known Subclasses:

CloudConnector, OnPremConnector

public abstract class Connector
extends Object

Abstract super type for CloudConnector and OnPremConnector. Shared operations are declared here to allow for code reuse for session-based and operations and some common operations.

Imports can be carried out using the import* methods such as importConfiguration(java.io.InputStream, String).
Exports can in a similar manner be done with the export* methods such as exportConfiguration().

The XML data formats are documented in the section Importing data on Apptus Zone (http://zone.apptus.com).
The format for configuration and panels isn't documented publicly. They are generated by eSales Manager and these exports and imports should be used for backup and migration only. Manually editing these files isn't supported and should not be done.

The procedure for imports can be found in the eSales tutorial on Apptus Zone (http://zone.apptus.com).

Use the session(String, String, String) method to get Session instances. These are used to notify eSales and query panels. View the Session documentation for details.

Author:

Thomas Raneland

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static class	Connector.ConnectorKey

Method Summary

Modifier and Type	Method	Description
List<String>	availableMarkets()	Returns a list of available markets from the eSales cluster.
EventDataJobResult	checkCustomerDataJobStatus(String jid)	Check the status of a GDPR customer data job.
EventDataJobResult	createExportCustomerDataJob(String customerKey)	Start a GDPR job on the cluster to export all data related to the given customer key.
EventDataJobResult	createRemoveCustomerDataJob(String customerKey)	Start a GDPR job on the cluster to remove all data related to the given customer key.
InputStream	downloadExportCustomerDataJobResult(String jid)	Download the result of a GDPR export customer data job.
long	downloadExportCustomerDataJobResult(String jid, File destination)	Download the result of a GDPR export customer data job.
InputStream	exportAds()	Exports ads from the eSales cluster as a full XML update document.
long	exportAds(File dest)	Exports ads from the eSales cluster as an update file.
InputStream	exportConfiguration()	Exports configuration from the eSales cluster as an XML update document.
long	exportConfiguration(File dest)	Exports configuration from the eSales cluster to an update file.
InputStream	exportPanels()	Exports panels from the eSales cluster as an XML document.
long	exportPanels(File dest)	Exports panels from the eSales cluster to a definition file.
InputStream	exportProducts()	Exports products and categories from the eSales cluster as a full XML update document.
long	exportProducts(File dest)	Exports products and categories from the eSales cluster as a full XML update file.
ProductStreamer	exportProducts(String filter, String presentationAttributes)	Returns an Iterable ProductStreamer that allows you to do filtered product exports, conveniently parsed into Result.Product items.
InputStream	exportSynonyms()	Exports synonyms from the eSales cluster as a full XML update document.
long	exportSynonyms(File dest)	Exports synonyms from the eSales cluster as an update file.
static String	getVersion()	Returns the connector version.
void	importAds(File importFile, String name)	Imports ads from the specified file to the eSales cluster.
void	importAds(InputStream importXml, String name)	Imports ads from the specified stream to the eSales cluster.
void	importConfiguration(File importFile, String name)	Imports configuration from the specified file to the eSales cluster.
void	importConfiguration(InputStream importXml, String name)	Imports configuration from the specified stream to the eSales cluster.
protected void	importFile(String type, File importFile, String name, Long timestampForTesting)
protected void	importFile(String type, File importFile, String name, Long timestampForTesting, Boolean force)
void	importPanels(File importFile, String name)	Imports panels from the specified file to the eSales cluster.
void	importPanels(InputStream importXml, String name)	Imports panels of the specified stream to the eSales cluster.
void	importProducts(File importFile, String name)	Imports products and categories from the specified file to the eSales cluster.
void	importProducts(File importFile, String name, Boolean force)	Imports products and categories from the specified file to the eSales cluster.
void	importProducts(InputStream importXml, String name)	Imports products and categories of the specified stream to the eSales cluster.
void	importProducts(InputStream importXml, String name, Boolean force)	Imports products and categories of the specified stream to the eSales cluster.
void	importSynonyms(File importFile, String name)	Imports synonyms from the specified file to the eSales cluster.
void	importSynonyms(InputStream importXml, String name)	Imports synonyms from the specified stream to the eSales cluster.
String	latestNotifications()	Returns the last 100 notifications received by eSales.
String	latestNotifications(Map<String,String> arguments)	Returns the last 100 notifications received by eSales.
protected void	putStrings(Map<? extends CharSequence,? extends CharSequence> arguments, ArgMap args)
Reporter	reporter(String market, TimeInterval interval)	Creates a reporter for a market during a specified time interval.
Reporter	reporterForUnknownMarket(TimeInterval interval)	Creates a reporter for the unknown market (sessions without a market property), during a specified time interval.
protected long	save(InputStream is, File dest)	Saves the content from an input stream to a file.
String	serverLog(int serverIndex, String name)	Gets a log from a server.
List<String>	serverLogNames()	Gets a list of available log names.
Session	session(String sessionKey)	Deprecated. use session(String sessionKey, String customerKey, String market) instead.
Session	session(String sessionKey, String customerKey, String market)	Creates a session for the specified session key with the specified customer key and market.
String	status()	Returns a status report from the eSales cluster as an XML document.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

session

@Deprecated
public final Session session(String sessionKey)

Deprecated.

use session(String sessionKey, String customerKey, String market) instead.

Creates a session for the specified session key.

Parameters:

sessionKey - The session key to identify the session

Returns:

A session for sessionKey with no market or customer key.

session

public Session session(String sessionKey,
                       String customerKey,
                       String market)

Creates a session for the specified session key with the specified customer key and market. Calling this method does not affect the session in the eSales server. A notification or panel query on the object created by this method, is necessary for the properties to stick to the session. When calling this method with null in place of customerKey and/or market, the server will keep the current values of these properties for this session.

Parameters:

sessionKey - The session key to identify the session

customerKey - the customer key for this session. Can be null

market - The market for this session. Can be null

Returns:

A new Session.

importFile

protected final void importFile(String type,
                                File importFile,
                                String name,
                                Long timestampForTesting)
                         throws IOException

Throws:

IOException

importFile

protected final void importFile(String type,
                                File importFile,
                                String name,
                                Long timestampForTesting,
                                Boolean force)
                         throws IOException

Throws:

IOException

importProducts

public final void importProducts(File importFile,
                                 String name)
                          throws IOException

Imports products and categories from the specified file to the eSales cluster.

Parameters:

importFile - A file with product data

name - An identifier for the request, may be null

Throws:

ClusterUnavailableException - if the cluster cannot be reached or all attempts fail

com.apptus.util.http.BadRequestException - if the import file contains errors or if the import is dangerous

com.apptus.util.http.SSLException - if the secure socket layer cannot be initialized (cloud connector only)

com.apptus.util.http.Response.BusyClusterIOException - if the cluster is busy with another task

IOException - if any other I/O error occurs

importProducts

public final void importProducts(File importFile,
                                 String name,
                                 Boolean force)
                          throws IOException

Imports products and categories from the specified file to the eSales cluster.

Parameters:

importFile - A file with product data

name - An identifier for the request, may be null

force - If the import should be forced through even if it is considered dangerous (e.g. drastically reduces the product count).

Throws:

ClusterUnavailableException - if the cluster cannot be reached or all attempts fail

com.apptus.util.http.BadRequestException - if the import file contains errors or if the import is dangerous

com.apptus.util.http.SSLException - if the secure socket layer cannot be initialized (cloud connector only)

com.apptus.util.http.Response.BusyClusterIOException - if the cluster is busy with another task

IOException - if any other I/O error occurs

importProducts

public final void importProducts(InputStream importXml,
                                 String name)
                          throws IOException

Imports products and categories of the specified stream to the eSales cluster.

Parameters:

importXml - Stream with product data

name - An identifier for the request, may be null

Throws:

ClusterUnavailableException - if the cluster cannot be reached or all attempts fail

com.apptus.util.http.BadRequestException - if the import file contains errors

com.apptus.util.http.ResendException - if the import failed and retries were impossible due to the input stream being consumed

com.apptus.util.http.SSLException - if the secure socket layer cannot be initialized (cloud connector only)

com.apptus.util.http.Response.BusyClusterIOException - if the cluster is busy with another task

IOException - if any other I/O error occurs

importProducts

public final void importProducts(InputStream importXml,
                                 String name,
                                 Boolean force)
                          throws IOException

Imports products and categories of the specified stream to the eSales cluster.

Parameters:

importXml - Stream with product data

name - An identifier for the request, may be null

force - If the import should be forced through even if it is considered dangerous (e.g. drastically reduces the product count).

Throws:

ClusterUnavailableException - if the cluster cannot be reached or all attempts fail

com.apptus.util.http.BadRequestException - if the import file contains errors

com.apptus.util.http.ResendException - if the import failed and retries were impossible due to the input stream being consumed

com.apptus.util.http.SSLException - if the secure socket layer cannot be initialized (cloud connector only)

com.apptus.util.http.Response.BusyClusterIOException - if the cluster is busy with another task

IOException - if any other I/O error occurs

importPanels

public final void importPanels(File importFile,
                               String name)
                        throws IOException

Imports panels from the specified file to the eSales cluster.

Parameters:

importFile - A file with a panel configuration

name - An identifier for the request, may be null

Throws:

ClusterUnavailableException - if the cluster cannot be reached or all attempts fail

com.apptus.util.http.BadRequestException - if the import file contains errors

com.apptus.util.http.SSLException - if the secure socket layer cannot be initialized (cloud connector only)

com.apptus.util.http.Response.BusyClusterIOException - if the cluster is busy with another task

IOException - if any other I/O error occurs

importPanels

public final void importPanels(InputStream importXml,
                               String name)
                        throws IOException

Imports panels of the specified stream to the eSales cluster.

Parameters:

importXml - Stream with a panel configuration

name - An identifier for the request, may be null

Throws:

ClusterUnavailableException - if the cluster cannot be reached or all attempts fail

com.apptus.util.http.BadRequestException - if the import file contains errors

com.apptus.util.http.ResendException - if the import failed and retries were impossible due to the input stream being consumed

com.apptus.util.http.SSLException - if the secure socket layer cannot be initialized (cloud connector only)

com.apptus.util.http.Response.BusyClusterIOException - if the cluster is busy with another task

IOException - if any other I/O error occurs

importConfiguration

public final void importConfiguration(File importFile,
                                      String name)
                               throws IOException

Imports configuration from the specified file to the eSales cluster.

Parameters:

importFile - A file with an eSales configuration

name - An identifier for the request, may be null

Throws:

ClusterUnavailableException - if the cluster cannot be reached or all attempts fail

com.apptus.util.http.BadRequestException - if the import file contains errors

com.apptus.util.http.SSLException - if the secure socket layer cannot be initialized (cloud connector only)

com.apptus.util.http.Response.BusyClusterIOException - if the cluster is busy with another task

IOException - if any other I/O error occurs

importConfiguration

public final void importConfiguration(InputStream importXml,
                                      String name)
                               throws IOException

Imports configuration from the specified stream to the eSales cluster.

Parameters:

importXml - Stream with an eSales configuration

name - An identifier for the request, may be null

Throws:

ClusterUnavailableException - if the cluster cannot be reached or all attempts fail

com.apptus.util.http.BadRequestException - if the import file contains errors

com.apptus.util.http.ResendException - if the import failed and retries were impossible due to the input stream being consumed

com.apptus.util.http.SSLException - if the secure socket layer cannot be initialized (cloud connector only)

com.apptus.util.http.Response.BusyClusterIOException - if the cluster is busy with another task

IOException - if any other I/O error occurs

importSynonyms

public final void importSynonyms(File importFile,
                                 String name)
                          throws IOException

Imports synonyms from the specified file to the eSales cluster.

Parameters:

importFile - A file with synonym data

name - An identifier for the request, may be null

Throws:

ClusterUnavailableException - if the cluster cannot be reached or all attempts fail

com.apptus.util.http.BadRequestException - if the import file contains errors

com.apptus.util.http.SSLException - if the secure socket layer cannot be initialized (cloud connector only)

com.apptus.util.http.Response.BusyClusterIOException - if the cluster is busy with another task

IOException - if any other I/O error occurs

importSynonyms

public final void importSynonyms(InputStream importXml,
                                 String name)
                          throws IOException

Imports synonyms from the specified stream to the eSales cluster.

Parameters:

importXml - Stream with synonym data

name - An identifier for the request, may be null

Throws:

ClusterUnavailableException - if the cluster cannot be reached or all attempts fail

com.apptus.util.http.BadRequestException - if the import file contains errors

com.apptus.util.http.ResendException - if the import failed and retries were impossible due to the input stream being consumed

com.apptus.util.http.SSLException - if the secure socket layer cannot be initialized (cloud connector only)

com.apptus.util.http.Response.BusyClusterIOException - if the cluster is busy with another task

IOException - if any other I/O error occurs

importAds

public final void importAds(File importFile,
                            String name)
                     throws IOException

Imports ads from the specified file to the eSales cluster.

Parameters:

importFile - A file with ad data

name - An identifier for the request, may be null

Throws:

ClusterUnavailableException - if the cluster cannot be reached or all attempts fail

com.apptus.util.http.BadRequestException - if the import file contains errors

com.apptus.util.http.SSLException - if the secure socket layer cannot be initialized (cloud connector only)

com.apptus.util.http.Response.BusyClusterIOException - if the cluster is busy with another task

IOException - if any other I/O error occurs

importAds

public final void importAds(InputStream importXml,
                            String name)
                     throws IOException

Imports ads from the specified stream to the eSales cluster.

Parameters:

importXml - Stream with ad data

name - An identifier for the request that can be referenced in logs, may be null

Throws:

ClusterUnavailableException - if the cluster cannot be reached or all attempts fail

com.apptus.util.http.BadRequestException - if the import file contains errors

com.apptus.util.http.ResendException - if the import failed and retries were impossible due to the input stream being consumed

com.apptus.util.http.SSLException - if the secure socket layer cannot be initialized (cloud connector only)

com.apptus.util.http.Response.BusyClusterIOException - if the cluster is busy with another task

IOException - if any other I/O error occurs

exportProducts

public final long exportProducts(File dest)
                          throws IOException

Exports products and categories from the eSales cluster as a full XML update file.

Parameters:

dest - Destination file

Returns:

The size of the saved file

Throws:

IOException - if there was any error exporting or writing to the file

exportProducts

public final InputStream exportProducts()
                                 throws IOException

Exports products and categories from the eSales cluster as a full XML update document.

Returns:

The export as an XML update document

Throws:

IOException - if there was any error exporting or writing to the file

exportProducts

public final ProductStreamer exportProducts(String filter,
                                            String presentationAttributes)

Returns an Iterable ProductStreamer that allows you to do filtered product exports, conveniently parsed into Result.Product items. Every new iteration on this class will result in a new request to eSales. Note that the ProductStreamer must be closed when done, which is most conveniently done by using a try-with-resources block as in the example below:

 try(ProductStreamer productStreamer = connector.exportProducts(null, null)){
     for (Product p : productStreamer){
         // Do something
     }
 }

While iterating, imports will be blocked from completing on a selected eSales server. Imports will not fail but will wait for the iteration to finish. This means that if you fail to close the ProductStreamer you might block imports indefinitely!

Parameters:

filter - the filter expression to use in the product selection, null or empty filter will select all products

presentationAttributes - the product attributes to include in the result, null or empty presentationAttributes will return the configured default presentation attributes in the cluster

Returns:

A ProductStreamer that can be used to iterate over the specified product selection

exportPanels

public final long exportPanels(File dest)
                        throws IOException

Exports panels from the eSales cluster to a definition file.

Parameters:

dest - Destination file

Returns:

The size of the saved file

Throws:

IOException - if there was any error exporting or writing to the file

exportPanels

public final InputStream exportPanels()
                               throws IOException

Exports panels from the eSales cluster as an XML document.

Returns:

The export as XML document

Throws:

IOException - if there was any error exporting

exportConfiguration

public final long exportConfiguration(File dest)
                               throws IOException

Exports configuration from the eSales cluster to an update file.

Parameters:

dest - Destination file

Returns:

The size of the saved file

Throws:

IOException - if there was any error exporting or writing to the file

exportConfiguration

public final InputStream exportConfiguration()
                                      throws IOException

Exports configuration from the eSales cluster as an XML update document.

Returns:

The export as an XML update document

Throws:

IOException - if there was any error exporting

exportSynonyms

public final long exportSynonyms(File dest)
                          throws IOException

Exports synonyms from the eSales cluster as an update file.

Parameters:

dest - Destination file

Returns:

The size of the saved file

Throws:

IOException - if there was any error exporting or writing to the file

exportSynonyms

public final InputStream exportSynonyms()
                                 throws IOException

Exports synonyms from the eSales cluster as a full XML update document.

Returns:

The export as an XML update document

Throws:

IOException - if there was any error exporting

exportAds

public final long exportAds(File dest)
                     throws IOException

Exports ads from the eSales cluster as an update file.

Parameters:

dest - Destination file

Returns:

The size of the saved file

Throws:

IOException - if there was any error exporting or writing to the file

exportAds

public final InputStream exportAds()
                            throws IOException

Exports ads from the eSales cluster as a full XML update document.

Returns:

The export as an XML update document

Throws:

IOException - if there was any error exporting

save

protected final long save(InputStream is,
                          File dest)
                   throws IOException

Saves the content from an input stream to a file.

Parameters:

is - Input stream

dest - Destination file

Returns:

The size of the file in bytes

Throws:

IOException - if there was any error saving to the dest file

availableMarkets

public List<String> availableMarkets()
                              throws IOException

Returns a list of available markets from the eSales cluster. Never returns null.

Returns:

An unmodifiable list of market names.

Throws:

IOException - if there was any problem getting markets.

reporter

public Reporter reporter(String market,
                         TimeInterval interval)

Creates a reporter for a market during a specified time interval.

The reporter can be used to fetch reports from the eSales cluster.

Parameters:

interval - The time interval for the reports

market - The market for the reports

Returns:

A Reporter object that can be used to fetch reports.

reporterForUnknownMarket

public Reporter reporterForUnknownMarket(TimeInterval interval)

Creates a reporter for the unknown market (sessions without a market property), during a specified time interval.

The reporter can be used to fetch reports from the eSales cluster.

Parameters:

interval - The time interval for the reports

Returns:

A Reporter object that can be used to fetch reports.

latestNotifications

public String latestNotifications()
                           throws IOException

Returns the last 100 notifications received by eSales.

Returns:

A string containing the last 100 notifications

Throws:

IOException - if there was any error getting latest notifications

latestNotifications

public String latestNotifications(Map<String,String> arguments)
                           throws IOException

Returns the last 100 notifications received by eSales.

Parameters:

arguments - The arguments of the notifications, for the moment only 'type' is supported

Returns:

A string containing the last 100 notifications

Throws:

IOException - if there was any error getting notifications

serverLog

public String serverLog(int serverIndex,
                        String name)
                 throws IOException

Gets a log from a server. Server index should be an index in the range [0, number_of_servers - 1]. The servers are indexed in the same order as they appear in the cluster string. The server indexes can also be retrieved from the status command. Name is the name of a log. Available log names can be retrieved from serverLogNames().

Parameters:

serverIndex - An index in the range [0, number of servers - 1]

name - The name of the log to be retrieved.

Returns:

The log as a string

Throws:

IOException - if there was any error getting a server log

serverLogNames

public List<String> serverLogNames()
                            throws IOException

Gets a list of available log names.

Returns:

a list of available log names.

Throws:

IOException - if there was any error getting server log names

status

public String status()
              throws IOException

Returns a status report from the eSales cluster as an XML document.

Returns:

The status report in XML.

Throws:

IOException - if there was any error getting cluster status

createRemoveCustomerDataJob

public EventDataJobResult createRemoveCustomerDataJob(String customerKey)
                                               throws IOException

Start a GDPR job on the cluster to remove all data related to the given customer key. Data will be removed both from memory and disk. "Linked" customer keys will also be removed (i.e. customer keys that have been notified in the same session).

Parameters:

customerKey - The customer key to remove.

Returns:

An object containing the job ID of the created job.

Throws:

IOException - if the response was unable to be parsed.

createExportCustomerDataJob

public EventDataJobResult createExportCustomerDataJob(String customerKey)
                                               throws IOException

Start a GDPR job on the cluster to export all data related to the given customer key. "Linked" customer keys will also be exported (i.e. customer keys that have been notified in the same session). Status of the job can be checked with checkCustomerDataJobStatus(String) and when the status is EventDataJobResult.Status.DONE, the resulting zip file can be downloaded using downloadExportCustomerDataJobResult(String).

Parameters:

customerKey - The customer key to export.

Returns:

An object containing the job ID of the created job.

Throws:

IOException - if the response was unable to be parsed.

checkCustomerDataJobStatus

public EventDataJobResult checkCustomerDataJobStatus(String jid)
                                              throws IOException

Check the status of a GDPR customer data job.

Parameters:

jid - The job ID.

Returns:

An object containing the status of the job.

Throws:

IOException - if the response was unable to be parsed.

downloadExportCustomerDataJobResult

public InputStream downloadExportCustomerDataJobResult(String jid)
                                                throws IOException

Download the result of a GDPR export customer data job.

Parameters:

jid - The job ID.

Returns:

An InputStream with the resulting zip file.

Throws:

IOException - if there was any error exporting customer data job result

downloadExportCustomerDataJobResult

public long downloadExportCustomerDataJobResult(String jid,
                                                File destination)
                                         throws IOException

Download the result of a GDPR export customer data job.

Parameters:

jid - The job ID.

destination - Where to save the resulting zip file.

Returns:

The number of bytes downloaded.

Throws:

IOException - if there was any error exporting or writing customer data job result to the file

getVersion

public static String getVersion()

Returns the connector version.

Returns:

Connector version.

putStrings

protected void putStrings(Map<? extends CharSequence,? extends CharSequence> arguments,
                          ArgMap args)