Package com.ibm.cics.server

Class TcpipRequest

java.lang.Object
com.ibm.cics.server.API
com.ibm.cics.server.TcpipRequest
All Implemented Interfaces:
com.ibm.cics.server.internal.TidyUpOnTermination
Direct Known Subclasses:
HttpRequest
public class TcpipRequest extends API implements com.ibm.cics.server.internal.TidyUpOnTermination
This class provides the Java implementation of TCPIP requests related to the following CICS API commands:
  • EXTRACT CERTIFICATE
  • EXTRACT TCPIP
  • WEB RECEIVE.

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:

  • SERVERCONV SRVCONVERT
  • SERVERCONV NOSRVCONVERT
  • CHARACTERSET
  • HOSTCODEPAGE
  • NOTRUNCATE
  • MAXLENGTH

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 getContentAsContainer(String) or getContentAsContainer(String, String). 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.

See Also:
Since CICS TS version:
2.3

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    ATTLSAWARE
    Constant - AT-TLS aware
    static final int
    AUTOAUTH
    Constant - Auto auth Authentication
    static final int
    AUTOREGISTER
    Constant - Auto register Authentication
    static final int
    BASICAUTH
    Constant - Basic Authentication
    static final int
    CERTIFICAUTH
    Constant - Certificate Authentication
    static final int
    CLIENTAUTH
    Constant - Client Authenticated SSL
    static final int
    IPV4
    Constant - IPV4
    static final int
    IPV6
    Constant - IPV6
    static final int
    NOAUTHENTIC
    Constant - No Authentication
    static final int
    NOSSL
    Constant - No SSL
    static final int
    NOTAPPLIC
    Constant - NOTAPPLIC
    static final Integer
    NOTSET
    Constant - NOT SET
    static final int
    NOTSUPPORTED
    Constant - Privacy not supported
    static final int
    REQUIRED
    Constant - Privacy required
    static final int
    SSL
    Constant - SSL
    static final int
    SUPPORTED
    Constant - Privacy supported

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    drive_ibmJVMTidyUp()
    Method to drive the static ibmJVMTidyUp method in a non-resettable JVM
    int
    getAuthenticate()
    Returns an integer which indicates the authentication requested for the client using the transaction.
    String
    getBodyCharset()
    Returns the HTTP body character-set in which the HTTP body was encoded in by the client.
    CertificateInfo
    getCertificateInfo()
    Returns the owner certificate.
    CertificateInfo
    getCertificateInfo(int ownerIssuer)
    Returns the requested certificate, either the owner or the issuer certificate.
    String
    getClientAddress()
    Returns the client's TCPIP address.
    byte[]
    getClientHostAddress()
    Returns the client's TCPIP address in a Java byte array.
    byte[]
    getClientHostAddress6()
    Returns the client's IPv6 TCPIP address in a Java byte array.
    String
    getClientHostName()
    Returns the client's name as known by the Domain Name Server.
    int
    getClientIpFamily()
    Returns an integer which indicates the format of the IP address of the client.
    byte[]
    getContent()
    Returns the body of the HTTP request.
    byte[]
    getContent(String theHostCodePage, String theCharacterset)
    Returns the body of the HTTP request.
    Container
    getContentAsContainer(String targetContainer)
    Stores the body of the HTTP request in a named container.
    Container
    getContentAsContainer(String targetContainer, String targetChannel)
    Stores the body of the HTTP request in a named container.
    int
    getMaxDataLen()
    Returns an maximum data length value for the socket.
    String
    getMediaType()
    Returns the media type of the HTTP body sent by the client.
    int
    getPortNumber()
    Returns the TCPIP port number associated with the transaction.
    int
    getPrivacy()
    Returns an integer which indicates the privacy requested for the client using the transaction.
    String
    getServerAddress()
    Returns the server's TCPIP address.
    byte[]
    getServerHostAddress()
    Returns the server's TCPIP address in a Java byte array.
    byte[]
    getServerHostAddress6()
    Returns the server's IPv6 TCPIP address in a Java byte array.
    String
    getServerHostName()
    Returns the server's name as known by the Domain Name Server.
    int
    getServerIpFamily()
    Returns an integer which indicates the format of the IP address of the server.
    static TcpipRequest
    getTcpipRequestInstance()
    Class method that returns the TcpipRequest object.
    String
    getTcpipService()
    Returns the name of the TCPIP service associated with the transaction.
    boolean
    isATTLSAware()
    Returns a boolean which indicates whether the Secure Sockets Layer (SSL) is AT-TLS aware or not.
    boolean
    isBodyComplete()
    Returns a boolean which indicates whether the body returned by getContent() method was complete or not.
    boolean
    isBodyPartial()
    Returns a boolean which indicates whether the body returned by getContent() method was a partial body or not.
    boolean
    isBodyTruncated()
    Returns a boolean which indicates whether the body returned by getContent() method was truncated or not.
    boolean
    isClientAuth()
    Returns a boolean which indicates whether the Secure Sockets Layer (SSL) is client authorised or not.
    boolean
    isSSL()
    Returns a boolean which indicates whether the Secure Sockets Layer (SSL) is being used.
    void
    setCharacterset(String theCharacterset)
    Sets WEB RECEIVE command option CHARACTERSET.
    void
    setClientCodePage(String theCharacterset)
    Sets WEB RECEIVE command option CHARACTERSET.
    void
    setHostCodePage(String theHostCodePage)
    Sets WEB RECEIVE command option HOSTCODEPAGE.
    void
    setMaxLength(int maxLength)
    Sets WEB RECEIVE command option MAXLENGTH.
    void
    setNoServerConvert()
    Sets WEB RECEIVE command option SERVERCONV to NOSRVCONVERT.
    void
    setNoTruncate()
    Sets WEB RECEIVE command option NOTRUNCATE.
    void
    setServerConvert()
    Sets WEB RECEIVE command option SERVERCONV to SRVCONVERT.
    void
    setTruncate()
    Resets WEB RECEIVE command option NOTRUNCATE.

    Methods inherited from class com.ibm.cics.server.API

    getCICSServerApiVersion

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • NOTSET

      public static final Integer NOTSET
      Constant - NOT SET
      Since CICS TS version:
      2.3

    • NOTAPPLIC

      public static final int NOTAPPLIC
      Constant - NOTAPPLIC
      Since CICS TS version:
      4.1

    • IPV4

      public static final int IPV4
      Constant - IPV4
      Since CICS TS version:
      4.1

    • IPV6

      public static final int IPV6
      Constant - IPV6
      Since CICS TS version:
      4.1

    • SSL

      public static final int SSL
      Constant - SSL
      Since CICS TS version:
      2.3

    • NOSSL

      public static final int NOSSL
      Constant - No SSL
      Since CICS TS version:
      2.3

    • CLIENTAUTH

      public static final int CLIENTAUTH
      Constant - Client Authenticated SSL
      Since CICS TS version:
      2.3

    • NOAUTHENTIC

      public static final int NOAUTHENTIC
      Constant - No Authentication
      Since CICS TS version:
      2.3

    • BASICAUTH

      public static final int BASICAUTH
      Constant - Basic Authentication
      Since CICS TS version:
      2.3

    • CERTIFICAUTH

      public static final int CERTIFICAUTH
      Constant - Certificate Authentication
      Since CICS TS version:
      2.3

    • AUTOREGISTER

      public static final int AUTOREGISTER
      Constant - Auto register Authentication
      Since CICS TS version:
      2.3

    • AUTOAUTH

      public static final int AUTOAUTH
      Constant - Auto auth Authentication
      Since CICS TS version:
      2.3

    • SUPPORTED

      public static final int SUPPORTED
      Constant - Privacy supported
      Since CICS TS version:
      2.3

    • REQUIRED

      public static final int REQUIRED
      Constant - Privacy required
      Since CICS TS version:
      2.3

    • NOTSUPPORTED

      public static final int NOTSUPPORTED
      Constant - Privacy not supported
      Since CICS TS version:
      2.3

    • ATTLSAWARE

      public static final int ATTLSAWARE
      Constant - AT-TLS aware
      Since CICS TS version:
      6.2

  • Method Details

    • getTcpipRequestInstance

      public static TcpipRequest getTcpipRequestInstance()
      Class method that returns the TcpipRequest object.
      Returns:
      TcpipRequest object
      Since CICS TS version:
      2.3

    • getCertificateInfo

      public CertificateInfo getCertificateInfo() throws InvalidRequestException
      Returns the owner certificate. This is equivalent to CICS API command EXTRACT CERTIFICATE OWNER
      Returns:
      The owner certificate
      Throws:
      InvalidRequestException - a INVREQ condition occurred
      Since CICS TS version:
      2.3

    • getCertificateInfo

      public CertificateInfo getCertificateInfo(int ownerIssuer) throws InvalidRequestException
      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
      Since CICS TS version:
      2.3

    • getClientHostName

      public String getClientHostName() throws InvalidRequestException
      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
      Since CICS TS version:
      2.3

    • getServerHostName

      public String getServerHostName() throws InvalidRequestException
      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
      Since CICS TS version:
      2.3

    • getClientAddress

      public String getClientAddress() throws InvalidRequestException
      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
      Since CICS TS version:
      2.3

    • getServerAddress

      public String getServerAddress() throws InvalidRequestException
      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
      Since CICS TS version:
      2.3

    • getClientHostAddress

      public byte[] getClientHostAddress() throws InvalidRequestException
      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
      Since CICS TS version:
      2.3

    • getServerHostAddress

      public byte[] getServerHostAddress() throws InvalidRequestException
      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
      Since CICS TS version:
      2.3

    • getClientHostAddress6

      public byte[] getClientHostAddress6() throws InvalidRequestException
      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
      Since CICS TS version:
      4.1

    • getServerHostAddress6

      public byte[] getServerHostAddress6() throws InvalidRequestException
      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
      Since CICS TS version:
      4.1

    • getClientIpFamily

      public int getClientIpFamily() throws InvalidRequestException
      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
      Since CICS TS version:
      4.1

    • getServerIpFamily

      public int getServerIpFamily() throws InvalidRequestException
      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
      Since CICS TS version:
      4.1

    • isSSL

      public boolean isSSL() throws InvalidRequestException
      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.

      These methods are equivalent to CICS API command EXTRACT TCPIP SSLTYPE.

      Returns:
      true if SSLTYPE is not NOSSL
      Throws:
      InvalidRequestException - An INVREQ condition occurred
      Since CICS TS version:
      2.3

    • isClientAuth

      public boolean isClientAuth() throws InvalidRequestException
      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.

      These methods are equivalent to CICS API command EXTRACT TCPIP SSLTYPE.

      Returns:
      true if SSLTYPE is CLIENTAUTH.
      Throws:
      InvalidRequestException - An INVREQ condition occurred.
      Since CICS TS version:
      2.3

    • isATTLSAware

      public boolean isATTLSAware() throws InvalidRequestException
      Returns a boolean which indicates whether the Secure Sockets Layer (SSL) is AT-TLS aware or not. If the SSLTYPE is equal to ATTLSAWARE then true is returned, otherwise false is returned.

      These methods are equivalent to CICS API command EXTRACT TCPIP SSLTYPE.

      Returns:
      true if SSLTYPE is ATTLSAWARE.
      Throws:
      InvalidRequestException - An INVREQ condition occurred.
      Since CICS TS version:
      6.2

    • getTcpipService

      public String getTcpipService() throws InvalidRequestException
      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
      Since CICS TS version:
      2.3

    • getPortNumber

      public int getPortNumber() throws InvalidRequestException
      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
      Since CICS TS version:
      2.3

    • getAuthenticate

      public int getAuthenticate() throws InvalidRequestException
      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
      Since CICS TS version:
      2.3

    • getPrivacy

      public int getPrivacy() throws InvalidRequestException
      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
      Since CICS TS version:
      2.3

    • getMaxDataLen

      public int getMaxDataLen() throws InvalidRequestException
      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
      Since CICS TS version:
      3.1

    • setServerConvert

      public void setServerConvert()
      Sets WEB RECEIVE command option SERVERCONV to SRVCONVERT.
      Since CICS TS version:
      3.1

    • setNoServerConvert

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

    • setClientCodePage

      public void setClientCodePage(String theCharacterset)
      Sets WEB RECEIVE command option CHARACTERSET. This method also sets SERVERCONV to SRVCONVERT.
      Parameters:
      theCharacterset - contains the code-page of the HTTP requests body.
      Since CICS TS version:
      3.1

    • setCharacterset

      public void setCharacterset(String theCharacterset)
      Sets WEB RECEIVE command option CHARACTERSET. This method also sets SERVERCONV to SRVCONVERT.
      Parameters:
      theCharacterset - contains the code-page of the HTTP requests body.
      Since CICS TS version:
      3.2

    • setHostCodePage

      public void setHostCodePage(String theHostCodePage)
      Sets WEB RECEIVE command option HOSTCODEPAGE. This method also sets SERVERCONV to SRVCONVERT.
      Parameters:
      theHostCodePage - contains the code-page that the HTTP requests body will be converted into.
      Since CICS TS version:
      3.1

    • setNoTruncate

      public void setNoTruncate()
      Sets WEB RECEIVE command option NOTRUNCATE.
      Since CICS TS version:
      3.1

    • setTruncate

      public void setTruncate()
      Resets WEB RECEIVE command option NOTRUNCATE.
      Since CICS TS version:
      3.1

    • setMaxLength

      public void setMaxLength(int maxLength) throws LengthErrorException
      Sets WEB RECEIVE command option MAXLENGTH.
      Parameters:
      maxLength - contains the maximum length value
      Throws:
      LengthErrorException - maxLength not greater than 0
      Since CICS TS version:
      3.1

    • getContent

      public byte[] getContent(String theHostCodePage, String theCharacterset) throws InvalidRequestException, RecordNotFoundException, NonHttpDataException
      Returns the body of the HTTP request. This is equivalent to CICS API command WEB RECEIVE.
      Parameters:
      theHostCodePage - 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
      theCharacterset - 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!
      Since CICS TS version:
      2.3

    • getContent

      public byte[] getContent() throws InvalidRequestException, RecordNotFoundException, NonHttpDataException
      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!
      Since CICS TS version:
      3.1

    • getContentAsContainer

      public Container getContentAsContainer(String targetContainer, String targetChannel) throws InvalidRequestException, RecordNotFoundException, ChannelErrorException, ContainerErrorException
      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:
      targetContainer - is the name if the container into which the HTTP body is to be stored
      targetChannel - 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
      Since CICS TS version:
      3.2

    • getContentAsContainer

      public Container getContentAsContainer(String targetContainer) throws InvalidRequestException, RecordNotFoundException, ChannelErrorException, ContainerErrorException
      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:
      targetContainer - 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
      Since CICS TS version:
      3.2

    • isBodyComplete

      public boolean isBodyComplete()
      Returns a boolean which indicates whether the body returned by getContent() method was complete or not.
      Returns:
      True if complete body returned by getContent()
      Since CICS TS version:
      3.1

    • isBodyTruncated

      public boolean isBodyTruncated()
      Returns a boolean which indicates whether the body returned by getContent() method was truncated or not.
      Returns:
      True if truncated body returned by getContent()
      Since CICS TS version:
      3.1

    • isBodyPartial

      public boolean isBodyPartial()
      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()
      Since CICS TS version:
      3.1

    • getBodyCharset

      public String getBodyCharset() throws InvalidRequestException
      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
      Since CICS TS version:
      3.2

    • getMediaType

      public String getMediaType() throws InvalidRequestException
      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
      Since CICS TS version:
      3.2

    • drive_ibmJVMTidyUp

      public void drive_ibmJVMTidyUp()
      Method to drive the static ibmJVMTidyUp method in a non-resettable JVM
      Specified by:
      drive_ibmJVMTidyUp in interface com.ibm.cics.server.internal.TidyUpOnTermination
      Since CICS TS version:
      2.3