CICS® Transaction Gateway Programming Reference v1.1.0.0

com.ibm.ctg.client
Class JavaGateway

java.lang.Object
  extended by com.ibm.ctg.client.JavaGateway
Direct Known Subclasses:
EPIGateway

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.


Field Summary
static java.lang.String LOCAL_PROP_APPLID
          APPLID.
static java.lang.String LOCAL_PROP_APPLID_QUALIFIER
          APPLID HIGH LEVEL QUALIFIER.
static java.lang.String MCF_TOKEN
          ManagedConnectionFactory token protocol property.
static java.lang.String SSL_PROP_CIPHER_SUITES
          SSL protocol cipher suites property.
static java.lang.String SSL_PROP_KEYRING_CLASS
          SSL protocol key ring class or keystore property.
static java.lang.String SSL_PROP_KEYRING_PW
          SSL protocol key ring or keystore password property.
 
Constructor Summary
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
 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_KEYRING_PW

public static final java.lang.String SSL_PROP_KEYRING_PW
SSL protocol key ring or keystore password property.

See Also:
SSL_PROP_KEYRING_CLASS, 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 Local JavaGateway to set the APPLID for the connection to CICS. This is only relevant for IPIC connections. In remote mode, this property is unused.

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 Local JavaGateway to set the APPLID for the connection to CICS. This is only relevant for IPIC connections. In remote mode, this property is unused.

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 intial 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 intial 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, 2014
Legal