Package com.inductiveautomation.ignition.client.gateway_interface

Class GatewayInterface

java.lang.Object

com.inductiveautomation.ignition.client.gateway_interface.GatewayInterface

All Implemented Interfaces:

GatewayConstants

public class GatewayInterface
extends Object
implements GatewayConstants

The GatewayInterface provides an interface for all Client and Designer communication with the gateway. It uses an XML formatted message sent over HTTP to the "Gateway" servlet on the Ignition gateway (located at http://ip.address/[context]/system/gateway).

This class knows how to encode messages (via the various createMessage functions) and parses the response into a GatewayResponse object. It also handles cookie tracking for session management.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	GatewayInterface.AbstractMessagePrinter	A MessagePrinter that has some static string values pre-encoded into byte[]'s
static class	GatewayInterface.BasicMessage	Basic implementation of message printer for messages with variable number of arguments
static interface	GatewayInterface.GatewayExceptionMonitor	Used to allow the GatewayConnectionManager to monitor the kinds of exceptions that are being thrown from the gateway.
static interface	GatewayInterface.GatewayThroughputMonitor
static class	GatewayInterface.InvokeMessage	A MessagePrinter for invoke messages (MTYPE_INVOKE_FUNCTION)
static interface	GatewayInterface.MessagePrinter	A MessagePrinter simply prints its message to an outputstream.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	ENCODING

Fields inherited from interface com.inductiveautomation.ignition.common.gateway.GatewayConstants

_DATE_FORMATTER, ARG_MESSAGETYPE, ARG_MODULEID, ATR_INDEX, ATR_LENGTH, ATR_NAME, ATR_TYPE, booleanNull, byteNull, charNull, CONNECT_TIMEOUT, DATE_FORMAT_STRING, doubleNull, ELM_ARG, ELM_COLLIST, ELM_COLUMN, ELM_COMPRESSEDROWS, ELM_DATA, ELM_ERRORCODE, ELM_ERRORMESSAGE, ELM_EXCLS, ELM_EXMSG, ELM_EXOVERRIDES_TOSTRING, ELM_EXSTRING, ELM_MBODY, ELM_MESSAGE, ELM_MTYPE, ELM_NOTIFICATION, ELM_NOTIFICATIONS, ELM_RESPONSE, ELM_ROW, ELM_ROWS, ELM_SERIALIZED_RESPONSE, ELM_SETCOOKIE, ELM_STACKTRACE, ELM_STELM, ELM_STELM_DECL, ELM_STELM_FILE, ELM_STELM_LINE, ELM_STELM_METH, ERRNO_ASYNC_CALL, ERRNO_ASYNC_CALL_CANCELED, ERRNO_ASYNC_CALL_FAILED, ERRNO_BROWSE_ERROR, ERRNO_COMM_ERROR, ERRNO_CONNECTION_MODE, ERRNO_DBCONNECTION_NAMING, ERRNO_DBCONNECTION_SQL, ERRNO_HISTORY_QUERY_ERROR, ERRNO_INSECURE_REDIRECT, ERRNO_INTERNAL, ERRNO_INVALIDARGS, ERRNO_INVOCATION_EXCEPTION, ERRNO_LICENE_RESTRICTED, ERRNO_LOGIN_CANCELLED, ERRNO_LOGIN_FAILED, ERRNO_LOGIN_FAILED_LICENSING, ERRNO_NAMING, ERRNO_NO_SESSION, ERRNO_NON_ACTIVE_NODE, ERRNO_NON_MASTER_NODE, ERRNO_NOT_AUTHORIZED, ERRNO_NOTIMP, ERRNO_OK, ERRNO_PARSE, ERRNO_PASSWORD_EXPIRED, ERRNO_PONG, ERRNO_POST_ERROR, ERRNO_PROJECT_PULL, ERRNO_PROJECT_PUSH, ERRNO_RUNTIME_EXPIRED, ERRNO_SQL, ERRNO_SQLTAGS_PROVIDER_DISABLED, ERRNO_SQLTAGS_PROVIDER_FAULTED, ERRNO_SQLTAGS_PROVIDER_LOADING, ERRNO_SQLTAGS_PROVIDER_MISSING, ERRNO_SQLTAGS_SEND_TAGS, ERRNO_SSL_REQUIRED, ERRNO_TIMEOUT, ERRNO_TRIAL_EXPIRED, ERRNO_VERSION_INCOMPATABILITY, ERROR_MESSAGE_TYPE, floatNull, intNull, longNull, MODE_DISCONNECTED, MODE_FULL, MODE_READ_ONLY, MTYPE_COPY_IMAGE, MTYPE_CREATE_IMAGE_FOLDER, MTYPE_DBTEST, MTYPE_GET_NEW_RESOURCEID, MTYPE_INVALID, MTYPE_INVOKE_FUNCTION, MTYPE_LIST_AUTHS, MTYPE_LIST_COLS, MTYPE_LIST_DBS, MTYPE_LIST_IDPS, MTYPE_LIST_IMAGES, MTYPE_LIST_MODULES, MTYPE_LIST_ROLES, MTYPE_LIST_SECURITY_LEVELS, MTYPE_LIST_SQLTAG_PROVIDERS, MTYPE_LIST_TABLES, MTYPE_LIST_ZONES, MTYPE_PING, MTYPE_PLATFORM_EDITION, MTYPE_PUBLIC_PING, MTYPE_REMOVE_IMAGE, MTYPE_RENAME_IMAGE_FOLDER, MTYPE_REPORT_ERROR, MTYPE_SEND_EMAIL, MTYPE_SQLTAGS_ADD_SCANCLASS, MTYPE_SQLTAGS_ADD_TAGS, MTYPE_SQLTAGS_EDIT_SCANCLASS, MTYPE_SQLTAGS_EDIT_TAGS, MTYPE_SQLTAGS_ERROR_LIST, MTYPE_SQLTAGS_FSQL_BROWSE, MTYPE_SQLTAGS_FSQL_LIST, MTYPE_SQLTAGS_GET_SCANCLASS, MTYPE_SQLTAGS_LIST, MTYPE_SQLTAGS_META_LIST, MTYPE_SQLTAGS_POLL, MTYPE_SQLTAGS_REMOVE_SCANCLASS, MTYPE_SQLTAGS_REMOVE_TAGS, MTYPE_SQLTAGS_WRITE, MTYPE_STATUS_POLL, MTYPE_UPLOAD_IMAGE, MTYPE_VERSION_CHECK, OPC_BROWSE_TIMEOUT, PROTECT_DIALOG_TYPE, shortNull, SOCKET_TIMEOUT, WARNING_MESSAGE_TYPE

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	GatewayInterface()	For overridding
	GatewayInterface(ScopeVersionHash version, HttpURL gatewayUrl, boolean ssl, int connectTimeout, int socketTimeout, int concurrencyLevel, int opcBrowseTimeout)

Method Summary

Modifier and Type	Method	Description
void	connectionCheck(boolean publicPing)	Sends a ping message that (optionally) doesn't require a session.
static String	createDoubleArgMessage(int type, String argName1, String arg1, String argName2, String arg2)	Creates an message with two arguments.
static String	createMessage(int type)	Creates a message with no arguments
static String	createMessage(int type, String[] argNames, String[] args)	Creates a message that allows for any number of arguments where each argument has one value
static String	createMessage(int type, String[] argNames, String[][] args)	Creates a message that allows for any number of arguments including indexed argument values
boolean	dbTest(String datasource)
String	getCookie()
HttpURL	getGatewayAddress()
Version	getGatewayVersion()
static CookieManager	getHeaderCookieManager()
long	getLastMessage()
Exception	getLastPingException()
List<ModuleInfo>	getModules()
String	getPlatformEdition()
StatMetric	getSelectQueryMetric()
StatMetric	getSelectQueryRowMetric()
<T> T	invoke(String function, Serializable... args)	Invokes a function on the gateway.
<T> T	invokeWithTimeout(String function, int timeout, Serializable... args)
boolean	isSSL()
<T> T	moduleInvoke(String moduleId, String function, Serializable... args)	Invokes a function on the gateway side of a module by delegating the call to the module's RPC handler.
<T> T	moduleInvokeSafe(String moduleId, String function, Class[] signature, Serializable... args)	Special version of ModuleInvoke lets the caller specify the argument signature, in case any of the arguments may be null
static MessageBuilder	newMessage(int type)
int	ping()	Sends a message to the gateway and returns ERRNO_PONG if communication was successful, some other errno otherwise.
int	publicPing()	A special type of ping message that doesn't require a session.
List<ProjectDiff>	pullProject(Collection<ProjectSnapshot> snapshots)
void	pushProject(List<ChangeOperation> diffs)
void	reportError(String message, String details, String sysProps, String userDescription, String userName, String userContact)
Dataset	runLimitQuery(String query, String datasource, String txId, Integer limit, Serializable[] params, Class<?>[] paramTypes)	Sends a MTYPE_RUN_QUERY command to the gateway, returning the raw response
Dataset	runPrepStmt(String query, String datasource, boolean getIds, Object... args)	Deprecated.
Dataset	runPrepStmt(String query, String datasource, String txId, boolean getIds, Object... args)	Deprecated. Please use the following style instead:
Dataset	runQuery(String query, String datasource)	Sends a basic string-query MTYPE_RUN_QUERY command to the gateway, returning the raw response
Dataset	runQuery(String query, String datasource, String txId)
Dataset	runQuery(String query, String datasource, String txId, Serializable[] params, Class<?>[] paramTypes)
Dataset	runTagCalculationQuery(List<? extends Path> paths, List<? extends Aggregate> calculations, Date startDate, Date endDate, List<String> aliases, Flags queryFlags)
Dataset	runTagDensityQuery(Collection<? extends Path> paths, Date startDate, Date endDate)
Dataset	runTagHistoryQuery(Collection<? extends Path> paths, Date startDate, Date endDate, int returnSize, Aggregate aggregationMode, ReturnFormat format, List<String> aliases, List<? extends Aggregate> colAggModes, Flags queryFlags)
Dataset	runTagHistoryQuery(Collection<? extends Path> paths, Date startDate, Date endDate, int returnSize, Aggregate aggregationMode, ReturnFormat format, List<String> aliases, List<? extends Aggregate> colAggModes, Flags queryFlags, int timeoutMillis)
Dataset	runUpdateQuery(String query, String datasource)	Deprecated. use RunUpdateQueryMessage instead.
Dataset	runUpdateQuery(String query, String datasource, String txId, boolean getIds)	Deprecated. use RunUpdateQueryMessage instead, like this:
void	sendEmail(String smtpProfileName, String from, String subject, String body, String contentType, String[] recipients, String[] ccRecipients, String[] bccRecipients, String[] attachNames, String[] attachData, int timeout, int retries, String priority, String[] replyTo)
void	sendEmail(String smtp, String from, String subject, String body, String contentType, String[] recips, String username, String password, String priority, String[] attachNames, String[] attachData, int timeout, String[] replyTo)
Object	sendMessage(GatewayInterface.MessagePrinter printer)
Object	sendMessage(String message)
Object	sendMessage(String message, GatewayInterface.MessagePrinter printer, int socketTimeout)
void	setGatewayExceptionMonitor(GatewayInterface.GatewayExceptionMonitor listener)
void	setHttpConcurrency(int concurrencyLevel)
void	setPrivilegedRequestFlag()	Informs the GatewayInterface that the next request invoked on this thread should be privileged.
void	setPushNotificationListener(PushNotificationListener listener)
void	setSSL(boolean ssl)
void	setThroughputMonitor(GatewayInterface.GatewayThroughputMonitor monitor)
void	simulateDisconnect(int seconds)

Methods inherited from class java.lang.Object

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

Field Details

ENCODING

public static final String ENCODING

See Also:

• Constant Field Values

Constructor Details

GatewayInterface

protected GatewayInterface()

For overridding

GatewayInterface

public GatewayInterface(ScopeVersionHash version,
 HttpURL gatewayUrl,
 boolean ssl,
 int connectTimeout,
 int socketTimeout,
 int concurrencyLevel,
 int opcBrowseTimeout)

Method Details

getHeaderCookieManager

public static CookieManager getHeaderCookieManager()

setThroughputMonitor

public void setThroughputMonitor(GatewayInterface.GatewayThroughputMonitor monitor)

getGatewayAddress

public HttpURL getGatewayAddress()

isSSL

public boolean isSSL()

setSSL

public void setSSL(boolean ssl)

setGatewayExceptionMonitor

public void setGatewayExceptionMonitor(GatewayInterface.GatewayExceptionMonitor listener)

setPushNotificationListener

public void setPushNotificationListener(PushNotificationListener listener)

simulateDisconnect

public void simulateDisconnect(int seconds)

sendMessage

public Object sendMessage(String message)
                   throws GatewayException

Throws:

GatewayException

sendMessage

public Object sendMessage(GatewayInterface.MessagePrinter printer)
                   throws GatewayException

Throws:

GatewayException

sendMessage

public Object sendMessage(String message,
 GatewayInterface.MessagePrinter printer,
 int socketTimeout)
                   throws GatewayException

Throws:

GatewayException

getCookie

public String getCookie()

runUpdateQuery

@Deprecated
public Dataset runUpdateQuery(String query,
 String datasource)
                       throws GatewayException

Deprecated.

use RunUpdateQueryMessage instead.

Throws:

GatewayException

runUpdateQuery

@Deprecated
public Dataset runUpdateQuery(String query,
 String datasource,
 String txId,
 boolean getIds)
                       throws GatewayException

Deprecated.

use RunUpdateQueryMessage instead, like this:

 sendMessage(new RunUpdateQueryMessage(query)
   .database(datasource)
   .transactionId(txId)
   .getIds(getIds))
 

Throws:

GatewayException

runPrepStmt

@Deprecated
public Dataset runPrepStmt(String query,
 String datasource,
 boolean getIds,
 Object... args)
                    throws GatewayException

Deprecated.

Throws:

GatewayException

runPrepStmt

@Deprecated
public Dataset runPrepStmt(String query,
 String datasource,
 String txId,
 boolean getIds,
 Object... args)
                    throws GatewayException

Deprecated.

Please use the following style instead:

 sendMessage(new RunPrepStmtMessage(query)
   .database(dbName)
   .queryArgs(args)
   .transactionId(txId)
   .getIds(getIds)
   .build());
 

Throws:

GatewayException

getModules

public List<ModuleInfo> getModules()
                            throws GatewayException

Throws:

GatewayException

sendEmail

public void sendEmail(String smtp,
 String from,
 String subject,
 String body,
 String contentType,
 String[] recips,
 String username,
 String password,
 String priority,
 String[] attachNames,
 String[] attachData,
 int timeout,
 String[] replyTo)
               throws Exception

Throws:

Exception

sendEmail

public void sendEmail(String smtpProfileName,
 String from,
 String subject,
 String body,
 String contentType,
 String[] recipients,
 String[] ccRecipients,
 String[] bccRecipients,
 String[] attachNames,
 String[] attachData,
 int timeout,
 int retries,
 String priority,
 String[] replyTo)
               throws Exception

Throws:

Exception

Since:

7.8.0

runTagHistoryQuery

public Dataset runTagHistoryQuery(Collection<? extends Path> paths,
 Date startDate,
 Date endDate,
 int returnSize,
 Aggregate aggregationMode,
 ReturnFormat format,
 List<String> aliases,
 List<? extends Aggregate> colAggModes,
 Flags queryFlags)
                           throws GatewayException

Throws:

GatewayException

runTagHistoryQuery

public Dataset runTagHistoryQuery(Collection<? extends Path> paths,
 Date startDate,
 Date endDate,
 int returnSize,
 Aggregate aggregationMode,
 ReturnFormat format,
 List<String> aliases,
 List<? extends Aggregate> colAggModes,
 Flags queryFlags,
 int timeoutMillis)
                           throws GatewayException

Throws:

GatewayException

runTagCalculationQuery

public Dataset runTagCalculationQuery(List<? extends Path> paths,
 List<? extends Aggregate> calculations,
 Date startDate,
 Date endDate,
 List<String> aliases,
 Flags queryFlags)
                               throws GatewayException

Throws:

GatewayException

runTagDensityQuery

public Dataset runTagDensityQuery(Collection<? extends Path> paths,
 Date startDate,
 Date endDate)
                           throws GatewayException

Throws:

GatewayException

runQuery

public Dataset runQuery(String query,
 String datasource)
                 throws GatewayException

Sends a basic string-query MTYPE_RUN_QUERY command to the gateway, returning the raw response

Throws:

GatewayException

runQuery

public Dataset runQuery(String query,
 String datasource,
 String txId)
                 throws GatewayException

Throws:

GatewayException

runQuery

public Dataset runQuery(String query,
 String datasource,
 String txId,
 Serializable[] params,
 Class<?>[] paramTypes)
                 throws GatewayException

Throws:

GatewayException

runLimitQuery

public Dataset runLimitQuery(String query,
 String datasource,
 String txId,
 Integer limit,
 Serializable[] params,
 Class<?>[] paramTypes)
                      throws GatewayException

Sends a MTYPE_RUN_QUERY command to the gateway, returning the raw response

Parameters:

query - The query to execute.

datasource - The datasource to run against.

txId - The transaction ID to run against, if any.

limit - The maximum number of rows to return. If <=0, all rows will be returned.

params - An array of parameters. If this is non null and non empty, the query will be executed as a prepared statement.

paramTypes - An array of parameter types. Used to disambiguate the type of any null arguments. Must match the ordinality of params

Throws:

GatewayException

moduleInvokeSafe

public <T> T moduleInvokeSafe(String moduleId,
 String function,
 Class[] signature,
 Serializable... args)
                       throws GatewayException

Special version of ModuleInvoke lets the caller specify the argument signature, in case any of the arguments may be null

Throws:

GatewayException

moduleInvoke

public <T> T moduleInvoke(String moduleId,
 String function,
 Serializable... args)
                   throws GatewayException

Invokes a function on the gateway side of a module by delegating the call to the module's RPC handler.

Throws:

GatewayException

invoke

public <T> T invoke(String function,
 Serializable... args)
             throws GatewayException

Invokes a function on the gateway. It will return the return value of the function, or throw an exception if something went wrong.

Parameters:

function - The function name, optionally with a sub function. Examples: "GetGatewayTimezone" or "SQLTags.writeToTag"

args - Any number of args to send to the function

Throws:

GatewayException

invokeWithTimeout

public <T> T invokeWithTimeout(String function,
 int timeout,
 Serializable... args)
                        throws GatewayException

Throws:

GatewayException

reportError

public void reportError(String message,
 String details,
 String sysProps,
 String userDescription,
 String userName,
 String userContact)
                 throws Exception

Throws:

Exception

pullProject

public List<ProjectDiff> pullProject(Collection<ProjectSnapshot> snapshots)
                              throws Exception

Throws:

Exception

pushProject

public void pushProject(List<ChangeOperation> diffs)
                 throws Exception

Throws:

Exception

ping

public int ping()

Sends a message to the gateway and returns ERRNO_PONG if communication was successful, some other errno otherwise. (requires session)

publicPing

public int publicPing()

A special type of ping message that doesn't require a session. returns ERRNO_COMM_ERROR if the ping was not successful.

getLastPingException

public Exception getLastPingException()

connectionCheck

public void connectionCheck(boolean publicPing)
                     throws GatewayException

Sends a ping message that (optionally) doesn't require a session. Throws an exception if the ping was not successful.

Throws:

GatewayException

getGatewayVersion

public Version getGatewayVersion()
                          throws GatewayException

Throws:

GatewayException

getPlatformEdition

public String getPlatformEdition()
                          throws GatewayException

Returns:

the Gateway platform edition, where "" corresponds to the standard edition, and "edge" corresponds to the Edge edition.

Throws:

GatewayException

dbTest

public boolean dbTest(String datasource)

createDoubleArgMessage

public static String createDoubleArgMessage(int type,
 String argName1,
 String arg1,
 String argName2,
 String arg2)

Creates an message with two arguments. This overload is purely for efficiency so that we're not creating arrays unnecessarily

createMessage

public static String createMessage(int type,
 String[] argNames,
 String[] args)

Creates a message that allows for any number of arguments where each argument has one value

createMessage

public static String createMessage(int type)

Creates a message with no arguments

createMessage

public static String createMessage(int type,
 String[] argNames,
 String[][] args)

Creates a message that allows for any number of arguments including indexed argument values

newMessage

public static MessageBuilder newMessage(int type)

getSelectQueryMetric

public StatMetric getSelectQueryMetric()

getSelectQueryRowMetric

public StatMetric getSelectQueryRowMetric()

getLastMessage

public long getLastMessage()

setPrivilegedRequestFlag

public void setPrivilegedRequestFlag()

Informs the GatewayInterface that the next request invoked on this thread should be privileged. This means that it is not subject to concurrency throttling. This flag will be automatically reset to false after the request.

setHttpConcurrency

public void setHttpConcurrency(int concurrencyLevel)