com.ibm.cics.server

Class HttpRequest

  • All Implemented Interfaces:
    com.ibm.cics.server.internal.TidyUpOnTermination


    public class HttpRequest
    extends TcpipRequest
    This class provides the Java implementation of HTTP requests related to the following CICS API WEB server commands:
    • WEB EXTRACT
    • WEB READ HTTPHEADER
    • WEB READ FORMFIELD
    • WEB READ QUERYPARM
    • WEB STARTBROWSE HTTPHEADER
    • WEB READNEXT HTTPHEADER
    • WEB ENDBROWSE HTTPHEADER
    • WEB STARTBROWSE FORMFIELD
    • WEB READNEXT FORMFIELD
    • WEB ENDBROWSE FORMFIELD
    • WEB STARTBROWSE QUERYPARM
    • WEB READNEXT QUERYPARM
    • WEB ENDBROWSE QUERYPARM
    • WEB RECEIVE.

    This class extends class TcpipRequest so the TcpipRequest class related CICS API commands, listed below, are also available.

    • EXTRACT CERTIFICATE
    • EXTRACT TCPIP

    This class is a singleton class. The constructor is private and class method getHttpRequestInstance() has to be used to obtain the HttpRequest object.

    The getHttpHeader() method returns the named HTTP header value. This is equivalent to CICS API command WEB READ HTTPHEADER.

    The getFormField() method returns the named HTML form field value. This is equivalent to CICS API command WEB READ FORMFIELD.

    The getQueryParm() method returns the named keyword value of a name/value pair. This is equivalent to CICS API command WEB READ QUERYPARM.

    The startBrowseHeader() method signals the start of a browse of the HTTP headers, getNextHeader() method is used to browse the HTTP headers and endBrowseHeader() signals the termination of the browse. These are equivalent to CICS API commands WEB STARTBROWSE HTTPHEADER, WEB READNEXT HTTPHEADER and WEB ENDBROWSE HTTPHEADER.

    The startBrowseFormField() method signals the start of a browse of the HTTP form fields, getNextFormField() method is used to browse the form fields and endBrowseFormField() method signals the termination of the browse. These are equivalent to CICS API commands WEB STARTBROWSE FORMFIELD, WEB READNEXT FORMFIELD and WEB ENDBROWSE FORMFIELD.

    The startBrowseQueryParm() method signals the start of a browse of the keyword parameters, getNextQueryParm() method is used to browse the keyword parameters and endBrowseQueryParm() method signals the termination of the browse. These are equivalent to CICS API commands WEB STARTBROWSE QUERYPARM, WEB READNEXT QUERYPARM and WEB ENDBROWSE QUERYPARM.

    The setter methods allow instance variables to be set in the HttpRequest 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 using method getContentAsContainer(). 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 getter methods return the various CICS API command WEB EXTRACT values and the mediaType and character-set of the HTTP body sent by the client.

    The isDataHttp() method returns a boolean which indicates the request type from the CICS API command WEB EXTRACT.

    See Also:
    API for general restrictions on using the JCICS API.
    Since CICS TS version:
    2.3
    Since package version:
    1.0.0
    • Field Detail

      • NOTSET

        public static final int NOTSET
        Constant - NOT SET
        Since CICS TS version:
        2.3
        Since package version:
        1.0.0
    • Method Detail

      • getHttpRequestInstance

        public static HttpRequest getHttpRequestInstance()
        Class method that returns the HttpRequest object.
        Returns:
        The HttpRequest object
        Since CICS TS version:
        2.3
        Since package version:
        1.0.0
      • getHttpMethod

        public java.lang.String getHttpMethod()
                                       throws InvalidRequestException
        Returns the HTTP method string on the request line of the in-bound message. This is equivalent to CICS API command WEB EXTRACT HTTPMETHOD.
        Returns:
        The HTTP method string
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        2.3
        Since package version:
        1.0.0
      • getHttpVersion

        public java.lang.String getHttpVersion()
                                        throws InvalidRequestException
        Returns the HTTP version string on the request line of the in-bound message. This is equivalent to CICS API command WEB EXTRACT HTTPVERSION.
        Returns:
        The HTTP version string
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        2.3
        Since package version:
        1.0.0
      • getRequestType

        public java.lang.String getRequestType()
                                        throws InvalidRequestException
        Returns the type of request received, either HTTPYES or HTTPNO. This is equivalent to CICS API command WEB EXTRACT REQUESTTYPE.
        Returns:
        The request type string, either HTTPYES or HTTPNO
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        2.3
        Since package version:
        1.0.0
      • isDataHttp

        public boolean isDataHttp()
                           throws InvalidRequestException
        Returns a boolean which indicates the request type. If the request type is HTTPYES then true is returned, otherwise false is returned. This is equivalent to CICS API command WEB EXTRACT REQUESTTYPE.
        Returns:
        True if REQUESTTYPE is HTTPYES
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        2.3
        Since package version:
        1.0.0
      • getPath

        public java.lang.String getPath()
                                 throws InvalidRequestException
        Returns the PATH specified in the request line on the in-bound message. This is equivalent to CICS API command WEB EXTRACT PATH.
        Returns:
        The path
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        2.3
        Since package version:
        1.0.0
      • getQueryString

        public java.lang.String getQueryString()
                                        throws InvalidRequestException
        Returns the query string on the request line of the HTTP request. This is equivalent to CICS API command WEB EXTRACT QUERYSTRING.
        Returns:
        The query string
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        2.3
        Since package version:
        1.0.0
      • getHost

        public java.lang.String getHost()
                                 throws InvalidRequestException
        Returns the host string from the HTTP request. This is equivalent to CICS API command WEB EXTRACT HOST.
        Returns:
        The host string
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        3.1
        Since package version:
        1.0.0
      • getHostType

        public int getHostType()
                        throws InvalidRequestException
        Returns the host type from the HTTP request. This is equivalent to CICS API command WEB EXTRACT HOSTTYPE.
        Returns:
        The CVDA describing the host type
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        4.1
        Since package version:
        1.200.0
      • isSchemeHttp

        public boolean isSchemeHttp()
                             throws InvalidRequestException
        Returns a boolean which indicates if the scheme is HTTP or not. This is equivalent to CICS API command WEB EXTRACT SCHEME.
        Returns:
        True if scheme is HTTP, otherwise false
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        3.1
        Since package version:
        1.0.0
      • isSchemeHttps

        public boolean isSchemeHttps()
                              throws InvalidRequestException
        Returns a boolean which indicates if the scheme is HTTPS or not. This is equivalent to CICS API command WEB EXTRACT SCHEME.
        Returns:
        True if scheme is HTTPS, otherwise false
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        3.1
        Since package version:
        1.0.0
      • getScheme

        public java.lang.String getScheme()
                                   throws InvalidRequestException
        Returns the scheme from the HTTP request. This is equivalent to CICS API command WEB EXTRACT SCHEME.
        Returns:
        The scheme string, either HTTP or HTTPS
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        3.1
        Since package version:
        1.0.0
      • getUrimap

        public java.lang.String getUrimap()
                                   throws InvalidRequestException
        Returns the URIMAP associated with the HTTP request. This is equivalent to CICS API command WEB EXTRACT URIMAP.
        Returns:
        The URIMAP string
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        3.1
        Since package version:
        1.0.0
      • getPortNumber

        public int getPortNumber()
                          throws InvalidRequestException
        Returns the port number associated with the HTTP request. This is equivalent to CICS API command WEB EXTRACT PORTNUMBER.
        Overrides:
        getPortNumber in class TcpipRequest
        Returns:
        The port number
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        3.1
        Since package version:
        1.0.0
      • getHeader

        public java.lang.String getHeader(java.lang.String header)
                                   throws InvalidRequestException
        Returns the contents of a HTTP header. If the requested header is not found a null string is returned. This is equivalent to CICS API command WEB READ HTTPHEADER.
        Parameters:
        header - contains the name of the HTTP header
        Returns:
        The named HTTP header value (null if not found)
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        2.3
        Since package version:
        1.0.0
      • getFormField

        public java.lang.String getFormField(java.lang.String formField)
                                      throws InvalidRequestException
        Returns the value of a field from the HTML form. If the requested form field is not found a null string is returned. This is equivalent to CICS API command WEB READ FORMFIELD.
        Parameters:
        formField - contains the name of the form field
        Returns:
        The named form field value (null if not found)
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        2.3
        Since package version:
        1.0.0
      • getFormField

        public java.lang.String getFormField(java.lang.String formField,
                                             java.lang.String hostCodePage,
                                             java.lang.String characterset)
                                      throws InvalidRequestException
        Returns the value of a field from the HTML form. If the requested form field is not found a null string is returned. This is equivalent to CICS API command WEB READ FORMFIELD CHARACTERSET HOSTCODEPAGE.
        Parameters:
        formField - contains the name of the form field
        hostCodePage - contains the host code-page to be used when the forms data is converted from the ASCII code-page it was received in, into the EBCDIC code-page in which CICS will process it
        characterset - contains the code-page in which the form is encoded
        Returns:
        The named form field value (null if not found)
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        2.3
        Since package version:
        1.0.0
      • getFormFieldData

        public byte[] getFormFieldData(java.lang.String formField)
                                throws InvalidRequestException
        Returns the value of a field from the HTML form. If the requested form field is not found a null is returned. This is equivalent to CICS API command WEB READ FORMFIELD.
        Parameters:
        formField - contains the name of the form field
        Returns:
        The named form field value (null if not found)
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        2.3
        Since package version:
        1.0.0
      • getFormFieldData

        public byte[] getFormFieldData(java.lang.String formField,
                                       java.lang.String hostCodePage,
                                       java.lang.String characterset)
                                throws InvalidRequestException
        Returns the value of a field from the HTML form. If the requested form field is not found a null is returned. This is equivalent to CICS API command WEB READ FORMFIELD CHARACTERSET HOSTCODEPAGE.
        Parameters:
        formField - contains the name of the form field
        hostCodePage - contains the host code-page to be used when the forms data is converted from the ASCII code-page it was received in, into the EBCDIC code-page in which CICS will process it
        characterset - contains the code-page in which the form is encoded
        Returns:
        The named form field value (null if not found)
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        2.3
        Since package version:
        1.0.0
      • getQueryParm

        public java.lang.String getQueryParm(java.lang.String queryParm)
                                      throws InvalidRequestException
        Reads a keyword parameter, consisting of a name and value pair, from a query string in a URL, and returns it. If the requested name is not found a null string is returned. This is equivalent to CICS API command WEB READ QUERYPARM.
        Parameters:
        queryParm - contains the name of the query parameter to read
        Returns:
        The value of the name/value pair, or null if not found
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        4.1
        Since package version:
        1.200.0
      • setServerConvert

        public void setServerConvert()
        Sets WEB RECEIVE command option SERVERCONV to SRVCONVERT.
        Overrides:
        setServerConvert in class TcpipRequest
        Since CICS TS version:
        3.1
        Since package version:
        1.0.0
      • 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().
        Overrides:
        setNoServerConvert in class TcpipRequest
        Since CICS TS version:
        3.1
        Since package version:
        1.0.0
      • setClientCodePage

        public void setClientCodePage(java.lang.String theCharacterset)
        Sets WEB RECEIVE command option CHARACTERSET. This method also sets SERVERCONV to SRVCONVERT.
        Overrides:
        setClientCodePage in class TcpipRequest
        Parameters:
        theCharacterset - contains the code-page of the HTTP requests body.
        Since CICS TS version:
        3.1
        Since package version:
        1.0.0
      • setCharacterset

        public void setCharacterset(java.lang.String theCharacterset)
        Sets WEB RECEIVE command option CHARACTERSET. This method also sets SERVERCONV to SRVCONVERT.
        Overrides:
        setCharacterset in class TcpipRequest
        Parameters:
        theCharacterset - contains the code-page of the HTTP requests body.
        Since CICS TS version:
        3.2
        Since package version:
        1.100.0
      • setHostCodePage

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

        public void setNoTruncate()
        Sets WEB RECEIVE command option NOTRUNCATE.
        Overrides:
        setNoTruncate in class TcpipRequest
        Since CICS TS version:
        3.1
        Since package version:
        1.0.0
      • setTruncate

        public void setTruncate()
        Resets WEB RECEIVE command option NOTRUNCATE.
        Overrides:
        setTruncate in class TcpipRequest
        Since CICS TS version:
        3.1
        Since package version:
        1.0.0
      • setMaxLength

        public void setMaxLength(int maxLength)
                          throws LengthErrorException
        Sets WEB RECEIVE command option MAXLENGTH.
        Overrides:
        setMaxLength in class TcpipRequest
        Parameters:
        maxLength - contains the maximum length value
        Throws:
        LengthErrorException - if maxLength is less than 1
        Since CICS TS version:
        3.1
        Since package version:
        1.0.0
      • getContent

        public byte[] getContent(java.lang.String theHostCodePage,
                                 java.lang.String theCharacterset)
                          throws InvalidRequestException,
                                 RecordNotFoundException,
                                 NonHttpDataException
        Returns the body of the HTTP request. This is equivalent to CICS API command WEB RECEIVE.
        Overrides:
        getContent in class TcpipRequest
        Parameters:
        theHostCodePage - contains the host code-page to be used when the body is converted from the ASCII code-page it was received in, into the EBCDIC code-page in which CICS will process it
        theCharacterset - contains the code-page in which the HTTP body is encoded
        Returns:
        The body of the HTTP request
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        RecordNotFoundException - a NOTFND condition occurred
        NonHttpDataException - WEB RECEIVE data is of type HTTPNO
        Since CICS TS version:
        2.3
        Since package version:
        1.0.0
      • isBodyComplete

        public boolean isBodyComplete()
        Returns a boolean which indicates whether the body returned by getContent() was completely returned or the last portion of the body was returned by the last getContent() call. When Container method get(HttpRequest request) is used to store the HTTP body in a named container this method will return true.
        Overrides:
        isBodyComplete in class TcpipRequest
        Returns:
        True if complete body returned or this is last portion of body returned by getContent()
        Since CICS TS version:
        3.1
        Since package version:
        1.0.0
      • isBodyTruncated

        public boolean isBodyTruncated()
        Returns a boolean which indicates whether the body returned by getContent() was truncated or not. When Container method get(HttpRequest request) is used to store the HTTP body in a named container this method will return false.

        Overrides:
        isBodyTruncated in class TcpipRequest
        Returns:
        True if truncated body returned by getContent()
        Since CICS TS version:
        3.1
        Since package version:
        1.0.0
      • isBodyPartial

        public boolean isBodyPartial()
        Returns a boolean which indicates whether the body returned by getContent() was a partial body or not. If true getContent() can be used to receive the next portion of the body. When Container method get(HttpRequest request) is used to store the HTTP body in a named container this method will return false.
        Overrides:
        isBodyPartial in class TcpipRequest
        Returns:
        True if partial body returned by getContent()
        Since CICS TS version:
        3.1
        Since package version:
        1.0.0
      • getBodyCharset

        public java.lang.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.
        Overrides:
        getBodyCharset in class TcpipRequest
        Returns:
        The HTTP body char-set
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        3.2
        Since package version:
        1.100.0
      • getMediaType

        public java.lang.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.
        Overrides:
        getMediaType in class TcpipRequest
        Returns:
        The HTTP media type
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        3.2
        Since package version:
        1.100.0
      • endBrowseHeader

        public void endBrowseHeader()
                             throws InvalidRequestException
        Signal the end of the HTTP header browse. This is equivalent to CICS API command WEB ENDBROWSE HTTPHEADER.
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        2.3
        Since package version:
        1.0.0
      • startBrowseFormField

        public void startBrowseFormField(java.lang.String name)
                                  throws InvalidRequestException,
                                         RecordNotFoundException,
                                         LogicException
        Signal the start of HTML form field browse from a specific name-value pair. This is equivalent to CICS API command WEB STARTBROWSE FORMFIELD.
        Parameters:
        name - contains the name of the form field from which the browse will start
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        RecordNotFoundException - a NOTFND condition occurred
        LogicException - a ILLOGIC condition occurred
        Since CICS TS version:
        2.3
        Since package version:
        1.0.0
      • startBrowseFormField

        public void startBrowseFormField(java.lang.String name,
                                         java.lang.String hostCodePage,
                                         java.lang.String characterset)
                                  throws InvalidRequestException,
                                         RecordNotFoundException,
                                         LogicException
        Signal the start of HTML form field browse from a specific name-value pair. This is equivalent to CICS API command WEB STARTBROWSE FORMFIELD CHARACTERSET HOSTCODEPAGE.
        • startBrowseFormField(null, null, null); is the same as startBrowseFormField() and signals the start of an HTML form field browse from the first name-value pair.
        • startBrowseFormField(name, null, null); is the same as startBrowseFormField(name) and signals the start of an HTML form field browse from a specific name-value pair.
        Parameters:
        name - contains the name of the form field from which the browse will start. Can be null, in which case the browse will start from the first name-value pair
        hostCodePage - contains the host code-page to be used when the forms data is converted from the ASCII code-page it was received in, into the EBCDIC code-page in which CICS will process it. Can be null, in which case the hostCodePage will be set to the value of SIT parameter LOCALCCSID (which will default to 037 if not set). The value of hostCodePage will be ignored if characterset is null
        characterset - contains the code-page in which the form is encoded. If characterset is null, but the HTTP client provides a charset value in a Content-Type header (not standard practice for HTML forms submission), the charset value is used; otherwise, CICS assumes ISO-8859-1.
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        RecordNotFoundException - a NOTFND condition occurred
        LogicException - a ILLOGIC condition occurred
        Since CICS TS version:
        2.3
        Since package version:
        1.0.0
      • endBrowseFormField

        public void endBrowseFormField()
                                throws InvalidRequestException
        Signal the end of the form field browse. This is equivalent to CICS API command WEB ENDBROWSE FORMFIELD.
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        2.3
        Since package version:
        1.0.0
      • startBrowseQueryParm

        public void startBrowseQueryParm(java.lang.String name)
                                  throws InvalidRequestException,
                                         RecordNotFoundException,
                                         LogicException
        Signal the start of HTML queryparm browse from a specific name-value pair. This is equivalent to CICS API command WEB STARTBROWSE QUERYPARM(name).

        Parameters:
        name - contains the name of the keyword parameter from which the browse will start
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        RecordNotFoundException - a NOTFND condition occurred
        LogicException - a ILLOGIC condition occurred
        Since CICS TS version:
        4.1
        Since package version:
        1.200.0
      • endBrowseQueryParm

        public void endBrowseQueryParm()
                                throws InvalidRequestException
        Signal the end of the queryparm browse. This is equivalent to CICS API command WEB ENDBROWSE QUERYPARM.
        Throws:
        InvalidRequestException - a INVREQ condition occurred
        Since CICS TS version:
        4.1
        Since package version:
        1.200.0
      • drive_ibmJVMTidyUp

        public final void drive_ibmJVMTidyUp()
        Call the ibmJVMTidyUp method from a non-resettable JVM
        Specified by:
        drive_ibmJVMTidyUp in interface com.ibm.cics.server.internal.TidyUpOnTermination
        Overrides:
        drive_ibmJVMTidyUp in class TcpipRequest
        Since CICS TS version:
        2.3
        Since package version:
        1.0.0