Package com.inductiveautomation.ignition.client.gateway_interface

Class 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.

    • 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()

      • getGatewayAddress

        public HttpURL getGatewayAddress()

      • isSSL

        public boolean isSSL()

      • setSSL

        public void setSSL​(boolean ssl)

      • 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

      • 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,
                                  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

      • 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,
                        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

      • 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

      • 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)