com.ibm.cics.server
Class TcpipRequest

java.lang.Object
  extended bycom.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 overriden 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 varibales 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 characterset 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
           
static int AUTOREGISTER
           
static int BASICAUTH
           
static int CERTIFICAUTH
           
static int CLIENTAUTH
           
static int NOAUTHENTIC
           
static int NOSSL
           
static int NOTSET
           
static int NOTSUPPORTED
           
static int REQUIRED
           
static int SSL
           
static int 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 characterset 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 Jave byte array.
 java.lang.String getClientHostName()
          Usage:
Returns the client's name as known by the Domain Name Server.
 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.
 java.lang.String getServerHostName()
          Usage:
Returns the server's name as known by the Domain Name 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 int NOTSET
See Also:
Constant Field Values

SSL

public static final int SSL
See Also:
Constant Field Values

NOSSL

public static final int NOSSL
See Also:
Constant Field Values

CLIENTAUTH

public static final int CLIENTAUTH
See Also:
Constant Field Values

NOAUTHENTIC

public static final int NOAUTHENTIC
See Also:
Constant Field Values

BASICAUTH

public static final int BASICAUTH
See Also:
Constant Field Values

CERTIFICAUTH

public static final int CERTIFICAUTH
See Also:
Constant Field Values

AUTOREGISTER

public static final int AUTOREGISTER
See Also:
Constant Field Values

AUTOAUTH

public static final int AUTOAUTH
See Also:
Constant Field Values

SUPPORTED

public static final int SUPPORTED
See Also:
Constant Field Values

REQUIRED

public static final int REQUIRED
See Also:
Constant Field Values

NOTSUPPORTED

public static final int NOTSUPPORTED
See Also:
Constant Field Values
Method Detail

getTcpipRequestInstance

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

Returns:
TcpipRequest object
Throws:
None

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 Jave 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

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

Returns:
None
Throws:
None

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

Returns:
None
Throws:
None

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 codepage of the HTTP requests body.
Returns:
None
Throws:
None

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 codepage of the HTTP requests body.
Returns:
None
Throws:
None

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 codepage that the HTTP requests body will be converted into.
Returns:
None
Throws:
None

setNoTruncate

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

Returns:
None
Throws:
None

setTruncate

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

Returns:
None
Throws:
None

setMaxLength

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

Parameters:
maxLength - contains the maximum length value
Returns:
None
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 codepage to be used to convert from the ASCII codepage in which it was received in, into the EBCDIC codepage in which CICS will process it
characterset - is the codepage 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 channnel. 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:
Conatiner 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()
Throws:
None

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()
Throws:
None

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()
Throws:
None

getBodyCharset

public java.lang.String getBodyCharset()
                                throws InvalidRequestException
Usage:
Returns the HTTP body characterset 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 charset
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