Class JavaGateway
- java.lang.Object
-
- com.ibm.ctg.client.JavaGateway
-
public class JavaGateway extends java.lang.ObjectThe 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()andsetPort()methods, or you can provide all the information in URL form ofProtocol://Address:Port. You can use thesetURL()method or pass the URL into one of the JavaGateway constructors.
-
-
Field Summary
Fields Modifier and Type Field and Description static java.lang.StringLOCAL_PROP_APPLIDAPPLID.static java.lang.StringLOCAL_PROP_APPLID_QUALIFIERAPPLID HIGH LEVEL QUALIFIER.static java.lang.StringLOCAL_PROP_IPIC_HEARTBEATLocal mode IPIC heartbeat interval.static java.lang.StringLOCAL_PROP_IPIC_SENDSESSIONSLocal mode IPIC send sessions.static java.lang.StringMCF_TOKENManagedConnectionFactory token protocol property.static java.lang.StringPROP_CLIENT_PORTLocal port for remote mode applications.static java.lang.StringSSL_PROP_CIPHER_SUITESSSL protocol cipher suites property.static java.lang.StringSSL_PROP_KEYRING_CLASSSSL protocol key ring class or keystore property.static java.lang.StringSSL_PROP_KEYRING_PWSSL protocol key ring or keystore password property.
-
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 voidclose()Closes the connection to the CICS Transaction Gateway.intflow(GatewayRequest gatRequest)Flows the specified GatewayRequest to the CICS Transaction Gateway and then waits for the reply.java.lang.StringgetAddress()Returns the address that this JavaGateway is currently or will be connected to.java.util.LocalegetGatewayLocale()Returns the Locale of the machine running the remote Gateway daemon if it is known.java.lang.StringgetGatewayOs()Returns a string containing the operating system, architecture and version of the machine running the remote Gateway daemon.intgetPort()Returns the port of the CICS Transaction Gateway that this JavaGateway instance is currently or will be connected to.java.lang.StringgetProtocol()Returns the protocol that this JavaGateway instance is currently using or will use to connect to the CICS Transaction Gateway.java.util.PropertiesgetProtocolProperties()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.StringgetRequestExits()Get a string containing the comma-delimited package-qualified classnames of theRequestExitmonitors that were or will be enabled when the open() method is called on this object.intgetSocketConnectTimeout()Returns the socket connect timeout value for this JavaGateway instance.java.lang.StringgetURL()Returns the URL of the CICS Transaction Gateway that this JavaGateway is currently or will be connected to.booleanisInitialFlow()Checks whether an initial flow will be sent when this JavaGateway is opened.static booleanisLocal(java.lang.String protocol)Tests if a specified protocol string represents a local JavaGateway.booleanisOpen()Checks both our expected state and the real state of any wrappered object.voidopen()Opens this JavaGateway type object.voidsetAddress(java.lang.String strSetAddress)Set the address of the CICS Transaction Gateway that this JavaGateway instance connects to.voidsetInitialFlow(boolean bSetInitialFlow)When a JavaGateway instance connects to a remote Gateway, an initial flow takes place.voidsetPort(int iSetPort)Sets the port of the CICS Transaction Gateway that this JavaGateway instance connects to.voidsetProtocol(java.lang.String strSetProtocol)Set the protocol that this JavaGateway will use to connect to the CICS Transaction Gateway.voidsetProtocolProperties(java.util.Properties newProps)Sets the protocol specific properties for this JavaGateway.voidsetRequestExits(java.lang.String requestExits)Set theRequestExitmonitors that will be enabled when the open() method is called on this object.voidsetSecurity(java.lang.String strSetClientSecurity, java.lang.String strSetServerSecurity)Sets the security classes to be used on the client and server sides of this connection.voidsetSocketConnectTimeout(int socketConnectTimeout)Sets the socket connection timeout value for this JavaGateway instance.voidsetURL(java.lang.String strSetURL)Sets the protocol, address and port of this JavaGateway by means of a single URL string.
-
-
-
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 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
-
LOCAL_PROP_IPIC_HEARTBEAT
public static final java.lang.String LOCAL_PROP_IPIC_HEARTBEAT
Local mode IPIC heartbeat interval. Add this property to the properties object for a JavaGateway to set the time, in seconds, that an IPIC connection must be inactive before heartbeats are sent to the CICS server in local mode.- See Also:
- Constant Field Values
-
PROP_CLIENT_PORT
public static final java.lang.String PROP_CLIENT_PORT
Local port for remote mode applications. Add this property to the properties object for a JavaGateway to set the local port number for a client application running in a remote mode topology.- 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.IOExceptionConstructs 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 toiSetPort- 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.IOExceptionConstructs 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 toiSetPort- 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.IOExceptionConstructs 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 toiSetPort- 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 implementingClientSecurityto use on this connectionstrSetServerSecurity- Name of class implementingServerSecurityto use on this connectionprotocolProps- 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.IOExceptionConstructs 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 toiSetPort- 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 implementingClientSecurityto use on this connectionstrSetServerSecurity- Name of class implementingServerSecurityto 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.IOExceptionConstructs 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 toiSetPort- 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 daemonprotocolProps- 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.IOExceptionConstructs 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 toiSetPort- 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 daemonstrSetClientSecurity- Name of class implementingClientSecurityto use on this connectionstrSetServerSecurity- Name of class implementingServerSecurityto use on this connectionprotocolProps- 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 theRequestExitmonitors 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 theRequestExitmonitors 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 thecom.ibm.ctg.monitoring.RequestExitinterface. 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.IOExceptionOpens 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 operationjava.lang.IllegalArgumentException- If a null object is passed to this method
-
close
public void close() throws java.io.IOExceptionCloses 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.IOExceptionSet 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.IOExceptionSets 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.IOExceptionSets 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 statejava.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.IOExceptionSet 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.IOExceptionSets 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.IOExceptionSets 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.IOExceptionSets 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 theClientSecurityinterface, and the server-side class theServerSecurityinterface.This method is only allowed when the JavaGateway is in a closed state.
- Parameters:
strSetClientSecurity- Name of class implementingClientSecurityto use on this connectionstrSetServerSecurity- Name of class implementingServerSecurityto 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.IOExceptionWhen 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.
-
-