Class GatewayInterface
- java.lang.Object
-
- com.inductiveautomation.ignition.client.gateway_interface.GatewayInterface
-
- All Implemented Interfaces:
GatewayConstants
public class GatewayInterface extends java.lang.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[]'sstatic class
GatewayInterface.BasicMessage
Basic implementation of message printer for messages with variable number of argumentsstatic 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 java.lang.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, 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, PROTECT_DIALOG_TYPE, shortNull, WARNING_MESSAGE_TYPE
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
GatewayInterface()
For overriddingGatewayInterface(ScopeVersionHash version, HttpURL gatewayUrl, boolean ssl, int connectTimeout, int socketTimeout, int concurrencyLevel, int opcBrowseTimeout)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
connectionCheck(boolean publicPing)
Sends a ping message that (optionally) doesn't require a session.static java.lang.String
createDoubleArgMessage(int type, java.lang.String argName1, java.lang.String arg1, java.lang.String argName2, java.lang.String arg2)
Creates an message with two arguments.static java.lang.String
createMessage(int type)
Creates a message with no argumentsstatic java.lang.String
createMessage(int type, java.lang.String[] argNames, java.lang.String[] args)
Creates a message that allows for any number of arguments where each argument has one valuestatic java.lang.String
createMessage(int type, java.lang.String[] argNames, java.lang.String[][] args)
Creates a message that allows for any number of arguments including indexed argument valuesboolean
dbTest(java.lang.String datasource)
java.lang.String
getCookie()
HttpURL
getGatewayAddress()
Version
getGatewayVersion()
static java.net.CookieManager
getHeaderCookieManager()
long
getLastMessage()
java.lang.Exception
getLastPingException()
java.util.List<ModuleInfo>
getModules()
java.lang.String
getPlatformEdition()
StatMetric
getSelectQueryMetric()
StatMetric
getSelectQueryRowMetric()
<T> T
invoke(java.lang.String function, java.io.Serializable... args)
Invokes a function on the gateway.<T> T
invokeWithTimeout(java.lang.String function, int timeout, java.io.Serializable... args)
boolean
isSSL()
<T> T
moduleInvoke(java.lang.String moduleId, java.lang.String function, java.io.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(java.lang.String moduleId, java.lang.String function, java.lang.Class[] signature, java.io.Serializable... args)
Special version of ModuleInvoke lets the caller specify the argument signature, in case any of the arguments may be nullstatic 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.java.util.List<ProjectDiff>
pullProject(java.util.Collection<ProjectSnapshot> snapshots)
void
pushProject(java.util.List<ChangeOperation> diffs)
void
reportError(java.lang.String message, java.lang.String details, java.lang.String sysProps, java.lang.String userDescription, java.lang.String userName, java.lang.String userContact)
Dataset
runLimitQuery(java.lang.String query, java.lang.String datasource, java.lang.String txId, java.lang.Integer limit, java.io.Serializable[] params, java.lang.Class<?>[] paramTypes)
Sends a MTYPE_RUN_QUERY command to the gateway, returning the raw responseDataset
runPrepStmt(java.lang.String query, java.lang.String datasource, boolean getIds, java.lang.Object... args)
Deprecated.Dataset
runPrepStmt(java.lang.String query, java.lang.String datasource, java.lang.String txId, boolean getIds, java.lang.Object... args)
Deprecated.Please use the following style instead:Dataset
runQuery(java.lang.String query, java.lang.String datasource)
Sends a basic string-query MTYPE_RUN_QUERY command to the gateway, returning the raw responseDataset
runQuery(java.lang.String query, java.lang.String datasource, java.lang.String txId)
Dataset
runQuery(java.lang.String query, java.lang.String datasource, java.lang.String txId, java.io.Serializable[] params, java.lang.Class<?>[] paramTypes)
Dataset
runTagCalculationQuery(java.util.List<? extends Path> paths, java.util.List<? extends Aggregate> calculations, java.util.Date startDate, java.util.Date endDate, java.util.List<java.lang.String> aliases, Flags queryFlags)
Dataset
runTagDensityQuery(java.util.Collection<? extends Path> paths, java.util.Date startDate, java.util.Date endDate)
Dataset
runTagHistoryQuery(java.util.Collection<? extends Path> paths, java.util.Date startDate, java.util.Date endDate, int returnSize, Aggregate aggregationMode, ReturnFormat format, java.util.List<java.lang.String> aliases, java.util.List<? extends Aggregate> colAggModes, Flags queryFlags)
Dataset
runTagHistoryQuery(java.util.Collection<? extends Path> paths, java.util.Date startDate, java.util.Date endDate, int returnSize, Aggregate aggregationMode, ReturnFormat format, java.util.List<java.lang.String> aliases, java.util.List<? extends Aggregate> colAggModes, Flags queryFlags, int timeoutMillis)
Dataset
runUpdateQuery(java.lang.String query, java.lang.String datasource)
Deprecated.use RunUpdateQueryMessage instead.Dataset
runUpdateQuery(java.lang.String query, java.lang.String datasource, java.lang.String txId, boolean getIds)
Deprecated.use RunUpdateQueryMessage instead, like this:void
sendEmail(java.lang.String smtpProfileName, java.lang.String from, java.lang.String subject, java.lang.String body, java.lang.String contentType, java.lang.String[] recipients, java.lang.String[] ccRecipients, java.lang.String[] bccRecipients, java.lang.String[] attachNames, java.lang.String[] attachData, int timeout, int retries, java.lang.String priority, java.lang.String[] replyTo)
void
sendEmail(java.lang.String smtp, java.lang.String from, java.lang.String subject, java.lang.String body, java.lang.String contentType, java.lang.String[] recips, java.lang.String username, java.lang.String password, java.lang.String priority, java.lang.String[] attachNames, java.lang.String[] attachData, int timeout, java.lang.String[] replyTo)
java.lang.Object
sendMessage(GatewayInterface.MessagePrinter printer)
java.lang.Object
sendMessage(java.lang.String message)
java.lang.Object
sendMessage(java.lang.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)
-
-
-
Field Detail
-
ENCODING
public static final java.lang.String ENCODING
- See Also:
- Constant Field Values
-
-
Constructor Detail
-
GatewayInterface
protected GatewayInterface()
For overridding
-
GatewayInterface
public GatewayInterface(ScopeVersionHash version, HttpURL gatewayUrl, boolean ssl, int connectTimeout, int socketTimeout, int concurrencyLevel, int opcBrowseTimeout)
-
-
Method Detail
-
getHeaderCookieManager
public static java.net.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)
-
sendMessage
public java.lang.Object sendMessage(java.lang.String message) throws GatewayException
- Throws:
GatewayException
-
sendMessage
public java.lang.Object sendMessage(GatewayInterface.MessagePrinter printer) throws GatewayException
- Throws:
GatewayException
-
sendMessage
public java.lang.Object sendMessage(java.lang.String message, GatewayInterface.MessagePrinter printer, int socketTimeout) throws GatewayException
- Throws:
GatewayException
-
getCookie
public java.lang.String getCookie()
-
runUpdateQuery
@Deprecated public Dataset runUpdateQuery(java.lang.String query, java.lang.String datasource) throws GatewayException
Deprecated.use RunUpdateQueryMessage instead.- Throws:
GatewayException
-
runUpdateQuery
@Deprecated public Dataset runUpdateQuery(java.lang.String query, java.lang.String datasource, java.lang.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(java.lang.String query, java.lang.String datasource, boolean getIds, java.lang.Object... args) throws GatewayException
Deprecated.- Throws:
GatewayException
-
runPrepStmt
@Deprecated public Dataset runPrepStmt(java.lang.String query, java.lang.String datasource, java.lang.String txId, boolean getIds, java.lang.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 java.util.List<ModuleInfo> getModules() throws GatewayException
- Throws:
GatewayException
-
sendEmail
public void sendEmail(java.lang.String smtp, java.lang.String from, java.lang.String subject, java.lang.String body, java.lang.String contentType, java.lang.String[] recips, java.lang.String username, java.lang.String password, java.lang.String priority, java.lang.String[] attachNames, java.lang.String[] attachData, int timeout, java.lang.String[] replyTo) throws java.lang.Exception
- Throws:
java.lang.Exception
-
sendEmail
public void sendEmail(java.lang.String smtpProfileName, java.lang.String from, java.lang.String subject, java.lang.String body, java.lang.String contentType, java.lang.String[] recipients, java.lang.String[] ccRecipients, java.lang.String[] bccRecipients, java.lang.String[] attachNames, java.lang.String[] attachData, int timeout, int retries, java.lang.String priority, java.lang.String[] replyTo) throws java.lang.Exception
- Throws:
java.lang.Exception
- Since:
- 7.8.0
-
runTagHistoryQuery
public Dataset runTagHistoryQuery(java.util.Collection<? extends Path> paths, java.util.Date startDate, java.util.Date endDate, int returnSize, Aggregate aggregationMode, ReturnFormat format, java.util.List<java.lang.String> aliases, java.util.List<? extends Aggregate> colAggModes, Flags queryFlags) throws GatewayException
- Throws:
GatewayException
-
runTagHistoryQuery
public Dataset runTagHistoryQuery(java.util.Collection<? extends Path> paths, java.util.Date startDate, java.util.Date endDate, int returnSize, Aggregate aggregationMode, ReturnFormat format, java.util.List<java.lang.String> aliases, java.util.List<? extends Aggregate> colAggModes, Flags queryFlags, int timeoutMillis) throws GatewayException
- Throws:
GatewayException
-
runTagCalculationQuery
public Dataset runTagCalculationQuery(java.util.List<? extends Path> paths, java.util.List<? extends Aggregate> calculations, java.util.Date startDate, java.util.Date endDate, java.util.List<java.lang.String> aliases, Flags queryFlags) throws GatewayException
- Throws:
GatewayException
-
runTagDensityQuery
public Dataset runTagDensityQuery(java.util.Collection<? extends Path> paths, java.util.Date startDate, java.util.Date endDate) throws GatewayException
- Throws:
GatewayException
-
runQuery
public Dataset runQuery(java.lang.String query, java.lang.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(java.lang.String query, java.lang.String datasource, java.lang.String txId) throws GatewayException
- Throws:
GatewayException
-
runQuery
public Dataset runQuery(java.lang.String query, java.lang.String datasource, java.lang.String txId, java.io.Serializable[] params, java.lang.Class<?>[] paramTypes) throws GatewayException
- Throws:
GatewayException
-
runLimitQuery
public Dataset runLimitQuery(java.lang.String query, java.lang.String datasource, java.lang.String txId, java.lang.Integer limit, java.io.Serializable[] params, java.lang.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(java.lang.String moduleId, java.lang.String function, java.lang.Class[] signature, java.io.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(java.lang.String moduleId, java.lang.String function, java.io.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(java.lang.String function, java.io.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(java.lang.String function, int timeout, java.io.Serializable... args) throws GatewayException
- Throws:
GatewayException
-
reportError
public void reportError(java.lang.String message, java.lang.String details, java.lang.String sysProps, java.lang.String userDescription, java.lang.String userName, java.lang.String userContact) throws java.lang.Exception
- Throws:
java.lang.Exception
-
pullProject
public java.util.List<ProjectDiff> pullProject(java.util.Collection<ProjectSnapshot> snapshots) throws java.lang.Exception
- Throws:
java.lang.Exception
-
pushProject
public void pushProject(java.util.List<ChangeOperation> diffs) throws java.lang.Exception
- Throws:
java.lang.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 java.lang.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 java.lang.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(java.lang.String datasource)
-
createDoubleArgMessage
public static java.lang.String createDoubleArgMessage(int type, java.lang.String argName1, java.lang.String arg1, java.lang.String argName2, java.lang.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 java.lang.String createMessage(int type, java.lang.String[] argNames, java.lang.String[] args)
Creates a message that allows for any number of arguments where each argument has one value
-
createMessage
public static java.lang.String createMessage(int type)
Creates a message with no arguments
-
createMessage
public static java.lang.String createMessage(int type, java.lang.String[] argNames, java.lang.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)
-
-