com.ibm.cics.server
Class TcpipRequest

java.lang.Object
  extended by com.ibm.cics.server.TcpipRequest
All Implemented Interfaces:
TidyUpOnTermination
Direct Known Subclasses:
HttpRequest

public class TcpipRequest
extends java.lang.Object
implements TidyUpOnTermination

Usage:
This class provides the Java implementation of TCPIP requests related to the following CICS API commands:

This class acts like a singleton. The constructor is protected and class method getTcpipRequestInstance() has to be used to obtain the TcpipRequest object.

The getCertificateInfo() method returns the full certificate. This is equivalent to CICS API command EXTRACT CERTIFICATE

The setter methods allow instance variables to be set in the TcpipRequest object. These variables relate to the following options on the CICS API command WEB RECEIVE:

By default MAXLENGTH is set to 32K and NOTRUNCATE is not set. These values can be overridden by the setters.

Method getContent() will receive the clients request body. This is equivalent to CICS API command WEB RECEIVE INTO.

Depending on the size of the body sent by the client and the MAXLENGTH value the complete body may not be received. Method isBodyComplete() returns boolean true if the whole body was returned by the getContent() method. If the whole body was not returned by getContent() then isBodyTruncated() returns boolean true unless setNoTruncate() was used to specify NOTRUNCATE. If NOTRUNCATE was specified and the complete body was not returned by getContent() then isBodyPartial() returns boolean true and getContent() can be used to obtain the next portion of the body.

The HTTP body can also be received into a named container by getContentAsCountainer(). If the HTTP body is received into a named container any instance variables set by the setter methods are ignored with the exception of CHARACTERSET.

The get*() methods return the various CICS API command EXTRACT TCPIP values and the madiaType and character-set of the HTTP body sent be the client.

The isSSL() and isClientAuth() methods return boolean values that can be used to determine the SSLTYPE returned from CICS API command WEB EXTRACT SSLTYPE.

Version:
07/02/19
Author:
Ian Shore, Adrian Bull

Field Summary
static int AUTOAUTH
          Constant - Auto auth Authentication
static int AUTOREGISTER
          Constant - Auto register Authentication
static int BASICAUTH
          Constant - Basic Authentication
static int CERTIFICAUTH
          Constant - Certificate Authentication
static int CLIENTAUTH
          Constant - Client Authenticated SSL
static int IPV4
          Constant - IPV4
static int IPV6
          Constant - IPV6
static int NOAUTHENTIC
          Constant - No Authentication
static int NOSSL
          Constant - No SSL
static int NOTAPPLIC
          Constant - NOTAPPLIC
static java.lang.Integer NOTSET
          Constant - NOT SET
static int NOTSUPPORTED
          Constant - Privacy supported
static int REQUIRED
          Constant - Privacy required
static int SSL
          Constant - SSL
static int SUPPORTED
          Constant - Privacy not supported
 
Fields inherited from interface com.ibm.cics.server.TidyUpOnTermination
COPYRIGHT, SCCSID
 
Method Summary
 void drive_ibmJVMTidyUp()
          Method to drive the static ibmJVMTidyUp method in a non-resettable JVM
 int getAuthenticate()
          Usage:
Returns an integer which indicates the authentication requested for the client using the transaction.
 java.lang.String getBodyCharset()
          Usage:
Returns the HTTP body character-set in which the HTTP body was encoded in by the client.
 CertificateInfo getCertificateInfo()
          Usage:
Returns the owner certificate.
 CertificateInfo getCertificateInfo(int ownerIssuer)
          Usage:
Returns the requested certificate, either the owner or the issuer certificate.
 java.lang.String getClientAddress()
          Usage:
Returns the client's TCPIP address.
 byte[] getClientHostAddress()
          Usage:
Returns the client's TCPIP address in a Java byte array.
 byte[] getClientHostAddress6()
          Usage:
Returns the client's IPv6 TCPIP address in a Java byte array.
 java.lang.String getClientHostName()
          Usage:
Returns the client's name as known by the Domain Name Server.
 int getClientIpFamily()
          Usage:
Returns an integer which indicates the format of the IP address of the client.
 byte[] getContent()
          Usage:
Returns the body of the HTTP request.
 byte[] getContent(java.lang.String hostCodePage, java.lang.String characterset)
          Usage:
Returns the body of the HTTP request.
 Container getContentAsContainer(java.lang.String toContainer)
          Usage:
Stores the body of the HTTP request in a named container.
 Container getContentAsContainer(java.lang.String toContainer, java.lang.String toChannel)
          Usage:
Stores the body of the HTTP request in a named container.
 int getMaxDataLen()
          Usage:
Returns an maximum data length value for the socket.
 java.lang.String getMediaType()
          Usage:
Returns the media type of the HTTP body sent by the client.
 int getPortNumber()
          Usage:
Returns the TCPIP port number associated with the transaction.
 int getPrivacy()
          Usage:
Returns an integer which indicates the privacy requested for the client using the transaction.
 java.lang.String getServerAddress()
          Usage:
Returns the server's TCPIP address.
 byte[] getServerHostAddress()
          Usage:
Returns the server's TCPIP address in a Java byte array.
 byte[] getServerHostAddress6()
          Usage:
Returns the server's IPv6 TCPIP address in a Java byte array.
 java.lang.String getServerHostName()
          Usage:
Returns the server's name as known by the Domain Name Server.
 int getServerIpFamily()
          Usage:
Returns an integer which indicates the format of the IP address of the server.
static TcpipRequest getTcpipRequestInstance()
          Usage:
Class method that returns the TcpipRequest object.
 java.lang.String getTcpipService()
          Usage:
Returns the name of the TCPIP service associated with the transaction.
 boolean isBodyComplete()
          Usage:
Returns a boolean which indicates whether the body returned by getContent() method was complete or not.
 boolean isBodyPartial()
          Usage:
Returns a boolean which indicates whether the body returned by getContent() method was a partial body or not.
 boolean isBodyTruncated()
          Usage:
Returns a boolean which indicates whether the body returned by getContent() method was truncated or not.
 boolean isClientAuth()
          Usage:
Returns a boolean which indicates whether the Secure Sockets Layer (SSL) is client authorised or not.
 boolean isSSL()
          Usage:
Returns a boolean which indicates whether the Secure Sockets Layer (SSL) is being used.
 void setCharacterset(java.lang.String characterset)
          Usage:
Sets WEB RECEIVE command option CHARACTERSET.
 void setClientCodePage(java.lang.String characterset)
          Usage:
Sets WEB RECEIVE command option CHARACTERSET.
 void setHostCodePage(java.lang.String hostCodePage)
          Usage:
Sets WEB RECEIVE command option HOSTCODEPAGE.
 void setMaxLength(int maxLength)
          Usage:
Sets WEB RECEIVE command option MAXLENGTH.
 void setNoServerConvert()
          Usage:
Sets WEB RECEIVE command option SERVERCONV to NOSRVCONVERT.
 void setNoTruncate()
          Usage:
Sets WEB RECEIVE command option NOTRUNCATE.
 void setServerConvert()
          Usage:
Sets WEB RECEIVE command option SERVERCONV to SRVCONVERT.
 void setTruncate()
          Usage:
Resets WEB RECEIVE command option NOTRUNCATE.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NOTSET

public static final java.lang.Integer NOTSET
Constant - NOT SET


NOTAPPLIC

public static final int NOTAPPLIC
Constant - NOTAPPLIC

See Also:
Constant Field Values

IPV4

public static final int IPV4
Constant - IPV4

See Also:
Constant Field Values

IPV6

public static final int IPV6
Constant - IPV6

See Also:
Constant Field Values

SSL

public static final int SSL
Constant - SSL

See Also:
Constant Field Values

NOSSL

public static final int NOSSL
Constant - No SSL

See Also:
Constant Field Values

CLIENTAUTH

public static final int CLIENTAUTH
Constant - Client Authenticated SSL

See Also:
Constant Field Values

NOAUTHENTIC

public static final int NOAUTHENTIC
Constant - No Authentication

See Also:
Constant Field Values

BASICAUTH

public static final int BASICAUTH
Constant - Basic Authentication

See Also:
Constant Field Values

CERTIFICAUTH

public static final int CERTIFICAUTH
Constant - Certificate Authentication

See Also:
Constant Field Values

AUTOREGISTER

public static final int AUTOREGISTER
Constant - Auto register Authentication

See Also:
Constant Field Values

AUTOAUTH

public static final int AUTOAUTH
Constant - Auto auth Authentication

See Also:
Constant Field Values

SUPPORTED

public static final int SUPPORTED
Constant - Privacy not supported

See Also:
Constant Field Values

REQUIRED

public static final int REQUIRED
Constant - Privacy required

See Also:
Constant Field Values

NOTSUPPORTED

public static final int NOTSUPPORTED
Constant - Privacy supported

See Also:
Constant Field Values
Method Detail

getTcpipRequestInstance

public static TcpipRequest getTcpipRequestInstance()
Usage:
Class method that returns the TcpipRequest object.

Returns:
TcpipRequest object

getCertificateInfo

public CertificateInfo getCertificateInfo()
                                   throws InvalidRequestException
Usage:
Returns the owner certificate. This is equivalent to CICS API command EXTRACT CERTIFICATE OWNER

Returns:
The owner certificate
Throws:
InvalidRequestException - a INVREQ condition occurred

getCertificateInfo

public CertificateInfo getCertificateInfo(int ownerIssuer)
                                   throws InvalidRequestException
Usage:
Returns the requested certificate, either the owner or the issuer certificate. This is equivalent to CICS API command EXTRACT CERTIFICATE OWNER or EXTRACT CERTIFICATE ISSUER.

Parameters:
ownerIssuer - indicates whether the owner or issuer certificate is required
Returns:
Owner or issuer certificate
Throws:
InvalidRequestException - a INVREQ condition occurred

getClientHostName

public java.lang.String getClientHostName()
                                   throws InvalidRequestException
Usage:
Returns the client's name as known by the Domain Name Server. This is equivalent to CICS API command TCPIP EXTRACT CLIENTNAME.

Returns:
The clients name
Throws:
InvalidRequestException - a INVREQ condition occurred

getServerHostName

public java.lang.String getServerHostName()
                                   throws InvalidRequestException
Usage:
Returns the server's name as known by the Domain Name Server. This is equivalent to CICS API command TCPIP EXTRACT SERVERNAME.

Returns:
The server name
Throws:
InvalidRequestException - a INVREQ condition occurred

getClientAddress

public java.lang.String getClientAddress()
                                  throws InvalidRequestException
Usage:
Returns the client's TCPIP address. This is equivalent to CICS API command TCPIP EXTRACT CLIENTADDR.

Returns:
The client's TCPIP address
Throws:
InvalidRequestException - a INVREQ condition occurred

getServerAddress

public java.lang.String getServerAddress()
                                  throws InvalidRequestException
Usage:
Returns the server's TCPIP address. This is equivalent to CICS API command TCPIP EXTRACT SERVERADDR.

Returns:
The server's TCPIP address
Throws:
InvalidRequestException - a INVREQ condition occurred

getClientHostAddress

public byte[] getClientHostAddress()
                            throws InvalidRequestException
Usage:
Returns the client's TCPIP address in a Java byte array. This is equivalent to CICS API command TCPIP EXTRACT CLIENTADDRNU.

Returns:
The client's TCPIP address
Throws:
InvalidRequestException - a INVREQ condition occurred

getServerHostAddress

public byte[] getServerHostAddress()
                            throws InvalidRequestException
Usage:
Returns the server's TCPIP address in a Java byte array. This is equivalent to CICS API command TCPIP EXTRACT SERVERADDRNU.

Returns:
The server's TCPIP address
Throws:
InvalidRequestException - a INVREQ condition occurred

getClientHostAddress6

public byte[] getClientHostAddress6()
                             throws InvalidRequestException
Usage:
Returns the client's IPv6 TCPIP address in a Java byte array. This is equivalent to CICS API command TCPIP EXTRACT CLNTADDR6NU.

Returns:
The client's IPv6 TCPIP address
Throws:
InvalidRequestException - a INVREQ condition occurred

getServerHostAddress6

public byte[] getServerHostAddress6()
                             throws InvalidRequestException
Usage:
Returns the server's IPv6 TCPIP address in a Java byte array. This is equivalent to CICS API command TCPIP EXTRACT SRVRADDR6NU.

Returns:
The server's TCPIP address
Throws:
InvalidRequestException - a INVREQ condition occurred

getClientIpFamily

public int getClientIpFamily()
                      throws InvalidRequestException
Usage:
Returns an integer which indicates the format of the IP address of the client. The possible values are IPV4, IPV6 or NOTAPPLIC. This is equivalent to CICS API command TCPIP EXTRACT CLNTIPFAMILY.

Returns:
The authentication value
Throws:
InvalidRequestException - a INVREQ condition occurred

getServerIpFamily

public int getServerIpFamily()
                      throws InvalidRequestException
Usage:
Returns an integer which indicates the format of the IP address of the server. The possible values are IPV4, IPV6 or NOTAPPLIC. This is equivalent to CICS API command TCPIP EXTRACT SRVRIPFAMILY.

Returns:
The authentication value
Throws:
InvalidRequestException - a INVREQ condition occurred

isSSL

public boolean isSSL()
              throws InvalidRequestException
Usage:
Returns a boolean which indicates whether the Secure Sockets Layer (SSL) is being used. If the SSLTYPE is not equal to NOSSL then true is returned, otherwise false is returned. This method and method isClientAuth() can be used to determine the SSLTYPE value which can be either NOSSL, SSL or CLIENTAUTH. These methods are equivalent to CICS API command EXTRACT TCPIP SSLTYPE.

Returns:
True if SSLTYPE != NOSSL
Throws:
InvalidRequestException - a INVREQ condition occurred

isClientAuth

public boolean isClientAuth()
                     throws InvalidRequestException
Usage:
Returns a boolean which indicates whether the Secure Sockets Layer (SSL) is client authorised or not. If the SSLTYPE is equal to CLIENTAUTH then true is returned, otherwise false is returned. This method and method isSSL() can be used to determine the SSLTYPE value which can be either NOSSL, SSL or CLIENTAUTH. These methods are equivalent to CICS API command EXTRACT TCPIP SSLTYPE.

Returns:
True if SSLTYPE == CLIENTAUTH
Throws:
InvalidRequestException - a INVREQ condition occurred

getTcpipService

public java.lang.String getTcpipService()
                                 throws InvalidRequestException
Usage:
Returns the name of the TCPIP service associated with the transaction. This is equivalent to CICS API command TCPIP EXTRACT TCPIPSERVICE.

Returns:
The TCPIP service name
Throws:
InvalidRequestException - a INVREQ condition occurred

getPortNumber

public int getPortNumber()
                  throws InvalidRequestException
Usage:
Returns the TCPIP port number associated with the transaction. This is equivalent to CICS API command TCPIP EXTRACT PORTNUMBER.

Returns:
The port number
Throws:
InvalidRequestException - a INVREQ condition occurred

getAuthenticate

public int getAuthenticate()
                    throws InvalidRequestException
Usage:
Returns an integer which indicates the authentication requested for the client using the transaction. The possible values are AUTOAUTH, AUTOREGISTER, BASICAUTH, CERTIFICAUTH or NOAUTHENTIC. This is equivalent to CICS API command TCPIP EXTRACT AUTHENTICATE.

Returns:
The authentication value
Throws:
InvalidRequestException - a INVREQ condition occurred

getPrivacy

public int getPrivacy()
               throws InvalidRequestException
Usage:
Returns an integer which indicates the privacy requested for the client using the transaction. The possible values are NOTSUPPORTED, REQUIRED or SUPPORTED. This is equivalent to CICS API command TCPIP EXTRACT PRIVACY

Returns:
The privacy value
Throws:
InvalidRequestException - a INVREQ condition occurred

getMaxDataLen

public int getMaxDataLen()
                  throws InvalidRequestException
Usage:
Returns an maximum data length value for the socket. This is equivalent to CICS API command TCPIP EXTRACT MAXDATALEN.

Returns:
The maximum data length value for the socket
Throws:
InvalidRequestException - a INVREQ condition occurred

setServerConvert

public void setServerConvert()
Usage:
Sets WEB RECEIVE command option SERVERCONV to SRVCONVERT.


setNoServerConvert

public void setNoServerConvert()
Usage:
Sets WEB RECEIVE command option SERVERCONV to NOSRVCONVERT. This method also clears CHARACTERSET and HOSTCODEPAGE information set by methods setCharacterset() and setHostCodePage().


setClientCodePage

public void setClientCodePage(java.lang.String characterset)
Usage:
Sets WEB RECEIVE command option CHARACTERSET. This method also sets SERVERCONV to SRVCONVERT.

Parameters:
characterset - contains the code-page of the HTTP requests body.

setCharacterset

public void setCharacterset(java.lang.String characterset)
Usage:
Sets WEB RECEIVE command option CHARACTERSET. This method also sets SERVERCONV to SRVCONVERT.

Parameters:
characterset - contains the code-page of the HTTP requests body.

setHostCodePage

public void setHostCodePage(java.lang.String hostCodePage)
Usage:
Sets WEB RECEIVE command option HOSTCODEPAGE. This method also sets SERVERCONV to SRVCONVERT.

Parameters:
hostCodePage - contains the code-page that the HTTP requests body will be converted into.

setNoTruncate

public void setNoTruncate()
Usage:
Sets WEB RECEIVE command option NOTRUNCATE.


setTruncate

public void setTruncate()
Usage:
Resets WEB RECEIVE command option NOTRUNCATE.


setMaxLength

public void setMaxLength(int maxLength)
                  throws LengthErrorException
Usage:
Sets WEB RECEIVE command option MAXLENGTH.

Parameters:
maxLength - contains the maximum length value
Throws:
LengthErrorException - maxLength not greater than 0

getContent

public byte[] getContent(java.lang.String hostCodePage,
                         java.lang.String characterset)
                  throws InvalidRequestException,
                         RecordNotFoundException,
                         NonHttpDataException
Usage:
Returns the body of the HTTP request. This is equivalent to CICS API command WEB RECEIVE.

Parameters:
hostCodePage - is the code-page to be used to convert from the ASCII code-page in which it was received in, into the EBCDIC code-page in which CICS will process it
characterset - is the code-page in which the HTTP body is encoded
Returns:
byte[]
Throws:
InvalidRequestException - a INVREQ condition occurred
RecordNotFoundException - a NOTFND condition occurred
NonHttpDataException - is present in this class because HttpRequest subclass extends TcpipRequest however TcpipRequest will not throw it!

getContent

public byte[] getContent()
                  throws InvalidRequestException,
                         RecordNotFoundException,
                         NonHttpDataException
Usage:
Returns the body of the HTTP request. This is equivalent to CICS API command WEB RECEIVE.

Returns:
The body of the HTTP request
Throws:
InvalidRequestException - a INVREQ condition occurred
RecordNotFoundException - a NOTFND condition occurred
NonHttpDataException - is present in this class because HttpRequest subclass extends TcpipRequest however TcpipRequest will not throw it!

getContentAsContainer

public Container getContentAsContainer(java.lang.String toContainer,
                                       java.lang.String toChannel)
                                throws InvalidRequestException,
                                       RecordNotFoundException,
                                       ChannelErrorException,
                                       ContainerErrorException
Usage:
Stores the body of the HTTP request in a named container. This is equivalent to CICS API command WEB RECEIVE CONTAINER CHANNEL. This method creates the container to hold the HTTP request, so determines the attributes of that container. If the container of the same name already exists it is deleted and created by this method.

Parameters:
toContainer - is the name if the container into which the HTTP body is to be stored
toChannel - is the name of the channel that owns the container
Returns:
Container object
Throws:
InvalidRequestException - a INVREQ condition occurred
RecordNotFoundException - a NOTFND condition occurred
ChannelErrorException - a CHANNELERR condition occurred
ContainerErrorException - a CONTAINERERR condition occurred

getContentAsContainer

public Container getContentAsContainer(java.lang.String toContainer)
                                throws InvalidRequestException,
                                       RecordNotFoundException,
                                       ChannelErrorException,
                                       ContainerErrorException
Usage:
Stores the body of the HTTP request in a named container. The Container will be owned by the current channel. This is equivalent to CICS API command WEB RECEIVE CONTAINER. This method creates the container to hold the HTTP request, so determines the attributes of that container. If the container of the same name already exists it is deleted and created by this method.

Parameters:
toContainer - is the name if the container into which the HTTP body is to be stored
Returns:
Container object
Throws:
InvalidRequestException - a INVREQ condition occurred
RecordNotFoundException - a NOTFND condition occurred
ChannelErrorException - a CHANNELERR condition occurred
ContainerErrorException - a CONTAINERERR condition occurred

isBodyComplete

public boolean isBodyComplete()
Usage:
Returns a boolean which indicates whether the body returned by getContent() method was complete or not.

Returns:
True if complete body returned by getContent()

isBodyTruncated

public boolean isBodyTruncated()
Usage:
Returns a boolean which indicates whether the body returned by getContent() method was truncated or not.

Returns:
True if truncated body returned by getContent()

isBodyPartial

public boolean isBodyPartial()
Usage:
Returns a boolean which indicates whether the body returned by getContent() method was a partial body or not. If so further getContent() methods can be used to obtain the remainder of the body.

Returns:
True if partial body returned by getContent()

getBodyCharset

public java.lang.String getBodyCharset()
                                throws InvalidRequestException
Usage:
Returns the HTTP body character-set in which the HTTP body was encoded in by the client. Method getContent() or Container method put() must have been used to receive the body or part of the body before this method is used, otherwise an InvalidRequestException will be throw.

Returns:
The HTTP body char-set
Throws:
InvalidRequestException - a INVREQ condition occurred

getMediaType

public java.lang.String getMediaType()
                              throws InvalidRequestException
Usage:
Returns the media type of the HTTP body sent by the client. Method getContent() or Container method put() must have been used to receive the body or part of the body before this method is used, otherwise an InvalidRequestException will be throw.

Returns:
The HTTP media type
Throws:
InvalidRequestException - a INVREQ condition occurred

drive_ibmJVMTidyUp

public void drive_ibmJVMTidyUp()
Method to drive the static ibmJVMTidyUp method in a non-resettable JVM

Specified by:
drive_ibmJVMTidyUp in interface TidyUpOnTermination