com.ibm.ctg.client

Class JavaGateway

  • java.lang.Object
    • com.ibm.ctg.client.JavaGateway


  • public class JavaGateway
    extends java.lang.Object
    The JavaGateway represents a logical connection between your program and the CICS Transaction Gateway when you specify a remote protocol. If you specify a local connection, you connect directly to the CICS server, bypassing any CICS Transaction Gateway servers.

    When you create a JavaGateway you determine the protocol to use, and if required, the connection details of the remote CICS Transaction Gateway server (network address and port number). With the JavaGateway class you can either specify this information using the setAddress(), setProtocol() and setPort() methods, or you can provide all the information in URL form of Protocol://Address:Port. You can use the setURL() method or pass the URL into one of the JavaGateway constructors.

    • Constructor Summary

      Constructors 
      Constructor and Description
      JavaGateway()
      Constructs a default JavaGateway object.
      JavaGateway(java.lang.String strSetURL, int iSetPort)
      Constructs a JavaGateway object and connects it via the defined protocol to a remote Gateway daemon or local client.
      JavaGateway(java.lang.String strSetURL, int iSetPort, int setSocketConnectTimeout, java.util.Properties protocolProps)
      Constructs a JavaGateway object and connects it via the defined protocol to a Gateway daemon or local client.
      JavaGateway(java.lang.String strSetURL, int iSetPort, int setSocketConnectTimeout, java.lang.String strSetClientSecurity, java.lang.String strSetServerSecurity, java.util.Properties protocolProps)
      Constructs a JavaGateway object and connects it via the defined protocol to a Gateway daemon or local client.
      JavaGateway(java.lang.String strSetURL, int iSetPort, java.util.Properties protocolProps)
      Constructs a JavaGateway object and connects it via the defined protocol to a remote Gateway daemon or local client.
      JavaGateway(java.lang.String strSetURL, int iSetPort, java.lang.String strSetClientSecurity, java.lang.String strSetServerSecurity)
      Constructs a JavaGateway object and connects it via the defined protocol to a remote Gateway daemon or local client.
      JavaGateway(java.lang.String strSetURL, int iSetPort, java.lang.String strSetClientSecurity, java.lang.String strSetServerSecurity, java.util.Properties protocolProps)
      Constructs a JavaGateway object and connects it via the defined protocol to a remote Gateway daemon or local client.
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void close()
      Closes the connection to the CICS Transaction Gateway.
      int flow(GatewayRequest gatRequest)
      Flows the specified GatewayRequest to the CICS Transaction Gateway and then waits for the reply.
      java.lang.String getAddress()
      Returns the address that this JavaGateway is currently or will be connected to.
      java.util.Locale getGatewayLocale()
      Returns the Locale of the machine running the remote Gateway daemon if it is known.
      java.lang.String getGatewayOs()
      Returns a string containing the operating system, architecture and version of the machine running the remote Gateway daemon.
      int getPort()
      Returns the port of the CICS Transaction Gateway that this JavaGateway instance is currently or will be connected to.
      java.lang.String getProtocol()
      Returns the protocol that this JavaGateway instance is currently using or will use to connect to the CICS Transaction Gateway.
      java.util.Properties getProtocolProperties()
      Returns a Properties object containing any settings specific to the protocol used to connect to the CICS Transaction Gateway, or null if there are none.
      java.lang.String getRequestExits()
      Get a string containing the comma-delimited package-qualified classnames of the RequestExit monitors that were or will be enabled when the open() method is called on this object.
      int getSocketConnectTimeout()
      Returns the socket connect timeout value for this JavaGateway instance.
      java.lang.String getURL()
      Returns the URL of the CICS Transaction Gateway that this JavaGateway is currently or will be connected to.
      boolean isInitialFlow()
      Checks whether an initial flow will be sent when this JavaGateway is opened.
      static boolean isLocal(java.lang.String protocol)
      Tests if a specified protocol string represents a local JavaGateway.
      boolean isOpen()
      Checks both our expected state and the real state of any wrappered object.
      void open()
      Opens this JavaGateway type object.
      void setAddress(java.lang.String strSetAddress)
      Set the address of the CICS Transaction Gateway that this JavaGateway instance connects to.
      void setInitialFlow(boolean bSetInitialFlow)
      When a JavaGateway instance connects to a remote Gateway, an initial flow takes place.
      void setPort(int iSetPort)
      Sets the port of the CICS Transaction Gateway that this JavaGateway instance connects to.
      void setProtocol(java.lang.String strSetProtocol)
      Set the protocol that this JavaGateway will use to connect to the CICS Transaction Gateway.
      void setProtocolProperties(java.util.Properties newProps)
      Sets the protocol specific properties for this JavaGateway.
      void setRequestExits(java.lang.String requestExits)
      Set the RequestExit monitors that will be enabled when the open() method is called on this object.
      void setSecurity(java.lang.String strSetClientSecurity, java.lang.String strSetServerSecurity)
      Sets the security classes to be used on the client and server sides of this connection.
      void setSocketConnectTimeout(int socketConnectTimeout)
      Sets the socket connection timeout value for this JavaGateway instance.
      void setURL(java.lang.String strSetURL)
      Sets the protocol, address and port of this JavaGateway by means of a single URL string.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • SSL_PROP_KEYRING_CLASS

        public static final java.lang.String SSL_PROP_KEYRING_CLASS
        SSL protocol key ring class or keystore property. Define this property in a properties object along with the SSL_PROP_KEYRING_PW to be able to specify the certificate store to be used by a single SSL JavaGateway.
        See Also:
        SSL_PROP_KEYRING_PW, Constant Field Values
      • SSL_PROP_CIPHER_SUITES

        public static final java.lang.String SSL_PROP_CIPHER_SUITES
        SSL protocol cipher suites property. Add this property to the properties object for a SSL JavaGateway to restrict the cipher suites that the connection can use. Multiple cipher suites can be specified, separated by ",".
        See Also:
        Constant Field Values
      • MCF_TOKEN

        public static final java.lang.String MCF_TOKEN
        ManagedConnectionFactory token protocol property. Used to ensure that only one IPIC connection to CICS is established for all ManagedConnections belonging to the same ManagedConnectionFactory.
        See Also:
        Constant Field Values
      • LOCAL_PROP_APPLID

        public static final java.lang.String LOCAL_PROP_APPLID
        APPLID. Add this property to the properties object for a JavaGateway to set the client APPLID. The client APPLID is included in the origin data sent over IPIC connections to CICS and is available to request monitoring exits. In local mode the client APPLID is also used to identify the client application when connecting to CICS using the IPIC protocol.
        See Also:
        Constant Field Values
      • LOCAL_PROP_APPLID_QUALIFIER

        public static final java.lang.String LOCAL_PROP_APPLID_QUALIFIER
        APPLID HIGH LEVEL QUALIFIER. Add this property to the properties object for a JavaGateway to set the client APPLID qualifier. The client APPLID qualifier is included in the origin data sent over IPIC connections to CICS and is available to request monitoring exits. In local mode the client APPLID qualifier is also used to identify the client application when connecting to CICS using the IPIC protocol.
        See Also:
        Constant Field Values
      • LOCAL_PROP_IPIC_SENDSESSIONS

        public static final java.lang.String LOCAL_PROP_IPIC_SENDSESSIONS
        Local mode IPIC send sessions. Add this property to the properties object for a JavaGateway to set the number of simultaneous transactions or CICS tasks that are allowed over IPIC connections to CICS in local mode.
        See Also:
        Constant Field Values
    • Constructor Detail

      • JavaGateway

        public JavaGateway()
        Constructs a default JavaGateway object. You should use the various set... methods to define the connection properties before calling the open() method to connect it to the target remote Gateway daemon or local client.
      • JavaGateway

        public JavaGateway(java.lang.String strSetURL,
                   int iSetPort)
                    throws java.io.IOException
        Constructs a JavaGateway object and connects it via the defined protocol to a remote Gateway daemon or local client. This constructor calls the relevant setURL(), setPort() and open() methods. This has the same result as constructing a default JavaGateway and then setting these properties prior to opening it.
        Parameters:
        strSetURL - URL specifying the remote/local Gateway to connect to
        iSetPort - TCP/IP port to connect to if connecting to a remote Gateway daemon. This parameter will be ignored if connecting via local mode.
        Throws:
        java.io.IOException - If an error occurs when opening the JavaGateway
        See Also:
        setURL(String), setPort(int iSetPort), open()
      • JavaGateway

        public JavaGateway(java.lang.String strSetURL,
                   int iSetPort,
                   java.util.Properties protocolProps)
                    throws java.io.IOException
        Constructs a JavaGateway object and connects it via the defined protocol to a remote Gateway daemon or local client. This constructor calls the relevant setURL(), setPort(), setProtocolProperties() and open() methods. This has the same result as constructing a default JavaGateway and then setting these properties prior to opening it.
        Parameters:
        strSetURL - URL specifying the remote/local Gateway to connect to
        iSetPort - TCP/IP port to connect to if connecting to a remote Gateway daemon. This parameter will be ignored if connecting via local mode.
        protocolProps - any protocol specific properties
        Throws:
        java.io.IOException - If an error occurs when opening the JavaGateway
        See Also:
        setURL(String), setPort(int iSetPort), setProtocolProperties(Properties), open()
      • JavaGateway

        public JavaGateway(java.lang.String strSetURL,
                   int iSetPort,
                   java.lang.String strSetClientSecurity,
                   java.lang.String strSetServerSecurity,
                   java.util.Properties protocolProps)
                    throws java.io.IOException
        Constructs a JavaGateway object and connects it via the defined protocol to a remote Gateway daemon or local client. This constructor calls the relevant setURL(), setPort(), setSecurity() and open() methods. This has the same result as constructing a default JavaGateway and then setting these properties prior to opening it.
        Parameters:
        strSetURL - URL specifying the remote/local Gateway to connect to
        iSetPort - TCP/IP port to connect to if connecting to a remote Gateway daemon. This parameter will be ignored if connecting via local mode.
        strSetClientSecurity - Name of class implementing ClientSecurity to use on this connection
        strSetServerSecurity - Name of class implementing ServerSecurity to use on this connection
        protocolProps - any protocol specific properties
        Throws:
        java.io.IOException - If an error occurs when opening the JavaGateway
        See Also:
        setURL(String), setPort(int iSetPort), setSecurity(String, String), setProtocolProperties(Properties), open()
      • JavaGateway

        public JavaGateway(java.lang.String strSetURL,
                   int iSetPort,
                   java.lang.String strSetClientSecurity,
                   java.lang.String strSetServerSecurity)
                    throws java.io.IOException
        Constructs a JavaGateway object and connects it via the defined protocol to a remote Gateway daemon or local client. This constructor calls the relevant setURL(), setPort(), setSecurity() and open() methods. This has the same result as constructing a default JavaGateway and then setting these properties prior to opening it.
        Parameters:
        strSetURL - URL specifying the remote/local Gateway to connect to
        iSetPort - TCP/IP port to connect to if connecting to a remote Gateway daemon. This parameter will be ignored if connecting via local mode.
        strSetClientSecurity - Name of class implementing ClientSecurity to use on this connection
        strSetServerSecurity - Name of class implementing ServerSecurity to use on this connection
        Throws:
        java.io.IOException - If an error occurs when opening the JavaGateway
        See Also:
        setURL(String), setPort(int iSetPort), setSecurity(String, String), open()
      • JavaGateway

        public JavaGateway(java.lang.String strSetURL,
                   int iSetPort,
                   int setSocketConnectTimeout,
                   java.util.Properties protocolProps)
                    throws java.io.IOException
        Constructs a JavaGateway object and connects it via the defined protocol to a Gateway daemon or local client. This constructor calls the relevant setURL(), setPort(), setSocketConnectTimeout(), setProtocolProperties() and open() methods. This has the same result as constructing a default JavaGateway and then setting these properties prior to opening it.
        Parameters:
        strSetURL - URL specifying the remote/local Gateway to connect to
        iSetPort - TCP/IP port to connect to if connecting to a remote Gateway daemon. This parameter will be ignored if connecting via local mode.
        setSocketConnectTimeout - The timeout value (in milliseconds) to allow a socket to connect to a remote Gateway daemon
        protocolProps - any protocol specific properties
        Throws:
        java.io.IOException - If an error occurs when opening the JavaGateway
        See Also:
        setURL(String), setPort(int iSetPort), setSocketConnectTimeout(int), setProtocolProperties(Properties), open()
      • JavaGateway

        public JavaGateway(java.lang.String strSetURL,
                   int iSetPort,
                   int setSocketConnectTimeout,
                   java.lang.String strSetClientSecurity,
                   java.lang.String strSetServerSecurity,
                   java.util.Properties protocolProps)
                    throws java.io.IOException
        Constructs a JavaGateway object and connects it via the defined protocol to a Gateway daemon or local client. This constructor calls the relevant setURL(), setPort(), setSocketConnectTimeout(), setSecurity(), setProtocolProperties() and open() methods. This has the same result as constructing a default JavaGateway and then setting these properties prior to opening it.
        Parameters:
        strSetURL - URL specifying the remote/local Gateway to connect to
        iSetPort - TCP/IP port to connect to if connecting to a remote Gateway daemon. This parameter will be ignored if connecting via local mode.
        setSocketConnectTimeout - The timeout value (in milliseconds) to allow a socket to connect to a remote Gateway daemon
        strSetClientSecurity - Name of class implementing ClientSecurity to use on this connection
        strSetServerSecurity - Name of class implementing ServerSecurity to use on this connection
        protocolProps - any protocol specific properties
        Throws:
        java.io.IOException - If an error occurs when opening the JavaGateway
        See Also:
        setURL(String), setPort(int iSetPort), setSocketConnectTimeout(int), setSecurity(String, String), setProtocolProperties(Properties), open()
    • Method Detail

      • getRequestExits

        public java.lang.String getRequestExits()
        Get a string containing the comma-delimited package-qualified classnames of the RequestExit monitors that were or will be enabled when the open() method is called on this object.
        Returns:
        the requestExits
      • setRequestExits

        public void setRequestExits(java.lang.String requestExits)
        Set the RequestExit monitors that will be enabled when the open() method is called on this object. The string contains comma-delimited package-qualified classnames of classes that implement the com.ibm.ctg.monitoring.RequestExit interface. These classes must be available on the class path.
        Parameters:
        requestExits - String containing the requestExits to set
      • isLocal

        public static boolean isLocal(java.lang.String protocol)
        Tests if a specified protocol string represents a local JavaGateway.
        Parameters:
        protocol - The protocol string to test
        Returns:
        true if the protocol is local; otherwise false
      • open

        public void open()
                  throws java.io.IOException
        Opens this JavaGateway type object. The connection parameters currently set are used to determine what type of underlying connection to create.
        Throws:
        java.io.IOException - If an error occurs when opening the JavaGateway
      • flow

        public int flow(GatewayRequest gatRequest)
                 throws java.io.IOException
        Flows the specified GatewayRequest to the CICS Transaction Gateway and then waits for the reply. The reply is returned in the original request object.

        If the thread is interrupted during the flow, an IOException is thrown but the request might continue to execute in the Gateway daemon. In this case the state of the request object is undefined.

        Parameters:
        gatRequest - GatewayRequest object containing the request
        Returns:
        Return code from this flow operation
        Throws:
        java.io.IOException - If a network I/O error occurs or the thread is interrupted during the operation
        java.lang.IllegalArgumentException - If a null object is passed to this method
      • close

        public void close()
                   throws java.io.IOException
        Closes the connection to the CICS Transaction Gateway.
        Throws:
        java.io.IOException - If a network I/O error occurs during the operation
      • setAddress

        public void setAddress(java.lang.String strSetAddress)
                        throws java.io.IOException
        Set the address of the CICS Transaction Gateway that this JavaGateway instance connects to.

        This method is only allowed when the JavaGateway is in a closed state.

        Parameters:
        strSetAddress - Address (normally TCP/IP) to connect to
        Throws:
        java.io.IOException - If the JavaGateway is in an open state
      • getAddress

        public java.lang.String getAddress()
        Returns the address that this JavaGateway is currently or will be connected to.
        Returns:
        String address (normally TCP/IP) to connect to
      • setPort

        public void setPort(int iSetPort)
                     throws java.io.IOException
        Sets the port of the CICS Transaction Gateway that this JavaGateway instance connects to. This parameter will be ignored if connecting via local mode.

        This method is only allowed when the JavaGateway is in a closed state.

        Parameters:
        iSetPort - Port to connect to
        Throws:
        java.io.IOException - If the JavaGateway is in an open state
      • getPort

        public int getPort()
        Returns the port of the CICS Transaction Gateway that this JavaGateway instance is currently or will be connected to. This value will be ignored if connecting via local mode.
        Returns:
        port value
      • setSocketConnectTimeout

        public void setSocketConnectTimeout(int socketConnectTimeout)
                                     throws java.io.IOException
        Sets the socket connection timeout value for this JavaGateway instance. This timeout represents the maximum amount of time (in milliseconds) a JavaGateway instance will attempt to open a socket connection successfully to a remote Gateway daemon. This parameter will be ignored if connecting via local mode.

        This method is only allowed when the JavaGateway is in a closed state.

        Parameters:
        socketConnectTimeout - The timeout value (in milliseconds). A value of 0 represents no timeout.
        Throws:
        java.io.IOException - If the JavaGateway is in an open state
        java.lang.IllegalArgumentException - If a negative value is passed
      • getSocketConnectTimeout

        public int getSocketConnectTimeout()
        Returns the socket connect timeout value for this JavaGateway instance. The timeout represents the maximum amount of time (in milliseconds) a JavaGateway instance will attempt to open a socket connection successfully to a remote Gateway daemon. This timeout will be ignored if connecting via local mode.
        Returns:
        int socketConnectTimeout The timeout value (in milliseconds). A value of 0 represents no timeout.
      • setProtocol

        public void setProtocol(java.lang.String strSetProtocol)
                         throws java.io.IOException
        Set the protocol that this JavaGateway will use to connect to the CICS Transaction Gateway. By default TCP/IP is selected protocol.

        This method is only allowed when the JavaGateway is in a closed state.

        Parameters:
        strSetProtocol - Protocol used to connect via
        Throws:
        java.io.IOException - If the JavaGateway is in an open state
      • getProtocol

        public java.lang.String getProtocol()
        Returns the protocol that this JavaGateway instance is currently using or will use to connect to the CICS Transaction Gateway.
        Returns:
        String protocol
      • setURL

        public void setURL(java.lang.String strSetURL)
                    throws java.io.IOException
        Sets the protocol, address and port of this JavaGateway by means of a single URL string. The URL takes the expected form of : protocol://address:port/

        This method is only allowed when the JavaGateway is in a closed state.

        Parameters:
        strSetURL - URL that the JavaGateway will connect to
        Throws:
        java.io.IOException - If the JavaGateway is in an open state
      • getURL

        public java.lang.String getURL()
        Returns the URL of the CICS Transaction Gateway that this JavaGateway is currently or will be connected to.
        Returns:
        String URL
      • setProtocolProperties

        public void setProtocolProperties(java.util.Properties newProps)
                                   throws java.io.IOException
        Sets the protocol specific properties for this JavaGateway.

        This method is only allowed when the JavaGateway is in a closed state.

        Parameters:
        newProps - The protocol specific properties
        Throws:
        java.io.IOException - If the JavaGateway is in an open state
      • getProtocolProperties

        public java.util.Properties getProtocolProperties()
        Returns a Properties object containing any settings specific to the protocol used to connect to the CICS Transaction Gateway, or null if there are none.
        Returns:
        a Properties object containing protocol specific properties
      • isOpen

        public boolean isOpen()
        Checks both our expected state and the real state of any wrappered object.
        Returns:
        true if this JavaGateway instance is connected to a Gateway as expected
      • setSecurity

        public void setSecurity(java.lang.String strSetClientSecurity,
                       java.lang.String strSetServerSecurity)
                         throws java.io.IOException
        Sets the security classes to be used on the client and server sides of this connection. The parameters specify the names of the classes to use. The client-side class must implement the ClientSecurity interface, and the server-side class the ServerSecurity interface.

        This method is only allowed when the JavaGateway is in a closed state.

        Parameters:
        strSetClientSecurity - Name of class implementing ClientSecurity to use on this connection
        strSetServerSecurity - Name of class implementing ServerSecurity to use on this connection
        Throws:
        java.io.IOException - If the JavaGateway is in an open state
      • setInitialFlow

        public void setInitialFlow(boolean bSetInitialFlow)
                            throws java.io.IOException
        When a JavaGateway instance connects to a remote Gateway, an initial flow takes place. This flow includes information about security objects being used, along with other information such as the Locale that the Gateway is using.

        If you are not using security objects and are not interested in any Locale information, you can choose to not incur the additional network traffic produced by the initial flow. Call this method with false to turn off the initial flow.

        This method is only allowed when the JavaGateway is in a closed state.

        Parameters:
        bSetInitialFlow - Whether to produce initial flows or not.
        Throws:
        java.io.IOException - If the JavaGateway is in an open state
      • isInitialFlow

        public boolean isInitialFlow()
        Checks whether an initial flow will be sent when this JavaGateway is opened.
        Returns:
        true if an initial flow will be sent when this JavaGateway is opened.
      • getGatewayLocale

        public java.util.Locale getGatewayLocale()
        Returns the Locale of the machine running the remote Gateway daemon if it is known.

        This method will return null if you have yet to open the connection to the remote Gateway, you disabled the initial flow which communicates this information, or you are connected to a local Gateway.

        Returns:
        Remote Gateway daemon Locale
      • getGatewayOs

        public java.lang.String getGatewayOs()
        Returns a string containing the operating system, architecture and version of the machine running the remote Gateway daemon.

        This method will return null if you have yet to open the connection to the remote Gateway, you disabled the initial flow which communicates this information, or you are connected to a local Gateway.

        Returns:
        String containing the operating system, architecture and version of the machine running the remote Gateway daemon.
©Copyright IBM Corp. 1994, 2012
Legal