Package com.ibm.cics.server

Class HttpClientResponse

java.lang.Object
com.ibm.cics.server.API
com.ibm.cics.server.HttpClientResponse
public class HttpClientResponse extends API
This class provides the Java implementation of HTTP client response related to the following CICS API commands:
  • WEB RECEIVE SESSTOKEN
  • WEB READ SESSTOKEN
  • WEB STARTBROWSE SESSTOKEN
  • WEB READNEXT SESSTOKEN
  • WEB ENDBROWSE SESSTOKEN.

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

  • NOTRUNCATE
  • CLIENTCONV
  • 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 servers response body. This is equivalent to CICS API command WEB RECEIVE SESSTOKEN INTO.

Depending on the size of the body sent by the server 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 method getContentAsContainer(). If the HTTP body is received into a named container any instance variables set by the setter methods are ignored.

Getters getStatusCode(), getStatusText(), getBodyCharset() and getMediaType() will return the STATUSCODE, STATUSTEXT, the HTTP BODYCHARSET and MEDIATYPE of the servers response. These getters will only return information if the getContent() method or getContentAsContainer() method has already been issued to obtain the body or part of the body.

Method getHeader() will return the contents of the required HTTP header, this is equivalent to CICS API command WEB READ SESSTOKEN.

Method startBrowseHeader() will start the browse of the HTTP headers, this is equivalent to CICS API command WEB STARTBROWSE SESSTOKEN.

Method getNextHeader() will return the next HTTP header name-value pair, this is equivalent to CICS API command WEB READNEXT SESSTOKEN.

Method endBrowseHeader() will terminate the browse of the HTTP headers, this is equivalent to CICS API command WEB ENDBROWSE SESSTOKEN.

See Also:
Since CICS TS version:
3.1

  • Field Details

    • NOTSET

      public static final int NOTSET
      Constant for an unset status code
      Since CICS TS version:
      3.1

  • Constructor Details

    • HttpClientResponse

      public HttpClientResponse()
      Public default constructor.
      Since CICS TS version:
      3.1

  • Method Details

    • setClientConvert

      public void setClientConvert()
      Sets WEB RECEIVE SESSTOKEN command option CLIENTCONV to CLICONVERT.

      Since CICS TS version:
      3.1

    • setNoClientConvert

      public void setNoClientConvert()
      Sets WEB RECEIVE SESSTOKEN command option CLIENTCONV to NOCLICONVERT.

      Since CICS TS version:
      3.1

    • setNoTruncate

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

      Since CICS TS version:
      3.1

    • setTruncate

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

      Since CICS TS version:
      3.1

    • setMaxLength

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

      Parameters:
      maxLength - contains the maximum length value
      Throws:
      LengthErrorException - if maxLength is less than 1
      Since CICS TS version:
      3.1

    • getContent

      public byte[] getContent(HttpSession session) throws InvalidRequestException, IOErrorException, NotOpenException, TimedOutException
      Returns the body of the servers response. This is equivalent to CICS API command WEB RECEIVE SESSTOKEN INTO.

      Parameters:
      session - is the HttpSession object associated with the RECEIVE.
      Returns:
      The body of the server response
      Throws:
      InvalidRequestException - a INVREQ condition occurred
      IOErrorException - a IOERR condition occurred
      NotOpenException - a NOTOPEN condition occurred
      TimedOutException - a TIMEDOUT condition occurred
      Since CICS TS version:
      3.1

    • getContentAsString

      public String getContentAsString(HttpSession session) throws InvalidRequestException, IOErrorException, NotOpenException, TimedOutException
      Returns the body of the servers response in String format. This function assumes content is returned in LOCALCCSID. This is equivalent to CICS API command WEB RECEIVE SESSTOKEN INTO.

      Parameters:
      session - is the HttpSession object associated with the RECEIVE.
      Returns:
      The body of the server response as a String
      Throws:
      InvalidRequestException - a INVREQ condition occurred
      IOErrorException - a IOERR condition occurred
      NotOpenException - a NOTOPEN condition occurred
      TimedOutException - a TIMEDOUT condition occurred
      Since CICS TS version:
      5.2

    • getContentAsContainer

      public Container getContentAsContainer(HttpSession session, String targetContainer, String targetChannel) throws InvalidRequestException, IOErrorException, NotOpenException, TimedOutException, ChannelErrorException, ContainerErrorException
      Stores the body of the HTTP response in a named container. This is equivalent to CICS API command WEB RECEIVE SESSTOKEN CONTAINER CHANNEL. This method creates the container to hold the HTTP response, 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:
      session - is the HttpSesion object.
      targetContainer - is the name if the container into which the HTTP body is to be stored
      targetChannel - is the channel that owns the container
      Returns:
      Container object
      Throws:
      InvalidRequestException - a INVREQ condition occurred
      IOErrorException - a IOERR condition occurred
      NotOpenException - a NOTOPEN condition occurred
      TimedOutException - a TIMEDOUT condition occurred
      ChannelErrorException - a CHANNELERR condition occurred
      ContainerErrorException - a CONTAINERERR condition occurred
      Since CICS TS version:
      3.2

    • getContentAsContainer

      public Container getContentAsContainer(HttpSession session, String targetContainer) throws InvalidRequestException, IOErrorException, NotOpenException, TimedOutException, ChannelErrorException, ContainerErrorException
      Stores the body of the HTTP response in a named container. The Container will be owned by the current channel. This is equivalent to CICS API command WEB RECEIVE SESSTOKEN CONTAINER. This method creates the container to hold the HTTP response, 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:
      session - is the HttpSesion object.
      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
      IOErrorException - a IOERR condition occurred
      NotOpenException - a NOTOPEN condition occurred
      TimedOutException - a TIMEDOUT condition occurred
      ChannelErrorException - a CHANNELERR condition occurred
      ContainerErrorException - a CONTAINERERR condition occurred
      Since CICS TS version:
      3.2

    • getStatusCode

      public int getStatusCode() throws InvalidRequestException
      Returns the status code of the servers response. This is equivalent to CICS API command WEB RECEIVE SESSTOKEN STATUSCODE. Method getContent() or getContentAsContainer() 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 servers response status code
      Throws:
      InvalidRequestException - if getContent() or getContentAsContainer() not issued before this method
      Since CICS TS version:
      3.1

    • getStatusText

      public String getStatusText() throws InvalidRequestException
      Returns the status text of the servers response. This is equivalent to CICS API command WEB RECEIVE SESSTOKEN STATUSTEXT. Method getContent() or getContentAsContainer() 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 servers response status text
      Throws:
      InvalidRequestException - if getContent() or getContentAsContainer() not issued before this method
      Since CICS TS version:
      3.1

    • getMediaType

      public String getMediaType() throws InvalidRequestException
      Returns the mediaType of the servers response. This is equivalent to CICS API command WEB RECEIVE SESSTOKEN MEDIATYPE. The mediaType string will not be trimmed Method getContent() or getContentAsContainer() 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 servers response mediaType
      Throws:
      InvalidRequestException - if getContent() or getCotentAsContainer() not issued before this method
      Since CICS TS version:
      3.1

    • getMediaTypeTrim

      public String getMediaTypeTrim() throws InvalidRequestException
      Returns the mediaType of the servers response. The mediaType string will be trimmed. This is equivalent to CICS API command WEB RECEIVE SESSTOKEN MEDIATYPE. Method getContent() or getContentAsContainer() 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 servers response mediaType
      Throws:
      InvalidRequestException - if getContent() or getCotentAsContainer() not issued before this method
      Since CICS TS version:
      3.2

    • getCharacterset

      public String getCharacterset() throws InvalidRequestException
      Returns the HTTP body character-set of the servers response. The character-set string will not be trimmed. This is equivalent to CICS API command WEB RECEIVE SESSTOKEN CHARACTERSET. Method getContent() or getContentAsContainer() 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 servers response character-set
      Throws:
      InvalidRequestException - if getContent() or getContentAsContainer() not issued before this method
      Since CICS TS version:
      3.1

    • getCharactersetTrim

      public String getCharactersetTrim() throws InvalidRequestException
      Returns the HTTP body character-set of the servers response. This is equivalent to CICS API command WEB RECEIVE SESSTOKEN CHARACTERSET. The character string will be trimmed. Method getContent() or getContentAsContainer() 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 servers response character-set
      Throws:
      InvalidRequestException - if getContent() or getContentAsContainer() not issued before this method
      Since CICS TS version:
      3.2

    • getBodyCharset

      public String getBodyCharset() throws InvalidRequestException
      Returns the HTTP body character-set of the servers response. This is equivalent to CICS API command WEB RECEIVE SESSTOKEN CHARACTERSET. Method getContent() or getContentAsContainer() 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 servers response character-set
      Throws:
      InvalidRequestException - if getContent() or getContentAsContainer() not issued before this method
      Since CICS TS version:
      3.2

    • isBodyComplete

      public boolean isBodyComplete()
      Returns a boolean which indicates whether the body returned by getContent() was completely returned. If more than one getContent() used to return the body then the isBodyComplete() will indicate when the last portion of the body has been returned. When getContentAsContainer() used of obtain the HTTP body the complete body is stored in the named container so true will be returned.

      Returns:
      True if complete body returned or this is last portion of the 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() was truncated or not. When getContentAsContainer() used of obtain the HTTP body the complete body is stored in the named container so false will be returned.

      Returns:
      True if truncated body returned by getContent()
      Since CICS TS version:
      3.1

    • isBodyPartial

      public boolean isBodyPartial()
      Returns a boolean which indicates whether 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 getContentAsContainer() used of obtain the HTTP body the complete body is stored in the named container so false will be returned.

      Returns:
      True if partial body returned by getContent()
      Since CICS TS version:
      3.1

    • getHeader

      public String getHeader(HttpSession session, String header) throws InvalidRequestException, NotOpenException
      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 SESSTOKEN.

      Parameters:
      session - is the HttpSession object associated with the READ
      header - contains the name of the HTTP header
      Returns:
      The named HTTP header value
      Throws:
      InvalidRequestException - a INVREQ condition occurred
      NotOpenException - a NOTOPEN condition occurred
      Since CICS TS version:
      3.1

    • startBrowseHeader

      public void startBrowseHeader(HttpSession session) throws InvalidRequestException, NotOpenException, LogicException
      Signal the start of a browse of the HTTP headers from the first name-value pair. This is equivalent to CICS API command WEB STARTBROWSE HTTPHEADER SESSTOKEN.

      Parameters:
      session - is the HttpSession object associated with the BROWSE
      Throws:
      InvalidRequestException - a INVREQ condition occurred
      NotOpenException - a NOTOPEN condition occurred
      LogicException - a ILLOGIC condition occurred
      Since CICS TS version:
      3.1

    • getNextHeader

      public HttpHeader getNextHeader(HttpSession session) throws LogicException, NotOpenException, EndOfFileException
      Returns the next HTTP header name-value pair to be browsed. This is equivalent to CICS API command WEB READNEXT HTTPHEADER SESSTOKEN.

      Parameters:
      session - is the HttpSession object associated with the BROWSE
      Returns:
      The next HTTP header name-value pair
      Throws:
      LogicException - a ILLOGIC condition occurred
      NotOpenException - a NOTOPEN condition occurred
      EndOfFileException - a ENDFILE condition occurred
      Since CICS TS version:
      3.1

    • endBrowseHeader

      public void endBrowseHeader(HttpSession session) throws LogicException, NotOpenException
      Signal the end of the HTTP header browse. This is equivalent to CICS API command WEB ENDBROWSE HTTPHEADER SESSTOKEN.

      Parameters:
      session - is the HttpSession object associated with the BROWSE
      Throws:
      LogicException - a ILLOGIC condition occurred
      NotOpenException - a NOTOPEN condition occurred
      Since CICS TS version:
      3.1