com.ibm.cics.server
Class HttpClientResponse

java.lang.Object
  extended by com.ibm.cics.server.HttpClientResponse

public class HttpClientResponse
extends java.lang.Object

Usage:
This class provides the Java implementation of HTTP client response related to the following CICS API commands:

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:

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.

Version:
05/05/19
Author:
Adrian Bull

Field Summary
static int NOTSET
          Constant for an unset status code
 
Constructor Summary
HttpClientResponse()
          Usage:
Public default constructor.
 
Method Summary
 void endBrowseHeader(HttpSession session)
          Usage:
Signal the end of the HTTP header browse.
 java.lang.String getBodyCharset()
          Usage:
Returns the HTTP body character-set of the servers response.
 java.lang.String getCharacterset()
          Usage:
Returns the HTTP body character-set of the servers response.
 java.lang.String getCharactersetTrim()
          Usage:
Returns the HTTP body character-set of the servers response.
 byte[] getContent(HttpSession session)
          Usage:
Returns the body of the servers response.
 Container getContentAsContainer(HttpSession session, java.lang.String toContainer)
          Usage:
Stores the body of the HTTP response in a named container.
 Container getContentAsContainer(HttpSession session, java.lang.String toContainer, java.lang.String toChannel)
          Usage:
Stores the body of the HTTP response in a named container.
 java.lang.String getHeader(HttpSession session, java.lang.String header)
          Usage:
Returns the contents of a HTTP header.
 java.lang.String getMediaType()
          Usage:
Returns the mediaType of the servers response.
 java.lang.String getMediaTypeTrim()
          Usage:
Returns the mediaType of the servers response.
 HttpHeader getNextHeader(HttpSession session)
          Usage:
Returns the next HTTP header name-value pair to be browsed.
 int getStatusCode()
          Usage:
Returns the status code of the servers response.
 java.lang.String getStatusText()
          Usage:
Returns the status text of the servers response.
 boolean isBodyComplete()
          Usage:
Returns a boolean which indicates whether the body returned by getContent() was completely returned.
 boolean isBodyPartial()
          Usage:
Returns a boolean which indicates whether body returned by getContent() was a partial body or not.
 boolean isBodyTruncated()
          Usage:
Returns a boolean which indicates whether the body returned by getContent() was truncated or not.
 void setClientConvert()
          Usage:
Sets WEB RECEIVE SESSTOKEN command option CLIENTCONV to CLICONVERT.
 void setMaxLength(int maxLength)
          Usage:
Sets WEB RECEIVE SESSTOKEN command option MAXLENGTH.
 void setNoClientConvert()
          Usage:
Sets WEB RECEIVE SESSTOKEN command option CLIENTCONV to NOCLICONVERT.
 void setNoTruncate()
          Usage:
Sets WEB RECEIVE SESSTOKEN command option NOTRUNCATE.
 void setTruncate()
          Usage:
Resets WEB RECEIVE SESSTOKEN command option NOTRUNCATE.
 void startBrowseHeader(HttpSession session)
          Usage:
Signal the start of a browse of the HTTP headers from the first name-value pair.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NOTSET

public static final int NOTSET
Constant for an unset status code

See Also:
Constant Field Values
Constructor Detail

HttpClientResponse

public HttpClientResponse()
Usage:
Public default constructor.

Method Detail

setClientConvert

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


setNoClientConvert

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


setNoTruncate

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


setTruncate

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


setMaxLength

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

Parameters:
maxLength - contains the maximum length value
Throws:
LengthErrorException - if maxLength is less than 1

getContent

public byte[] getContent(HttpSession session)
                  throws InvalidRequestException,
                         IOErrorException,
                         NotOpenException,
                         TimedOutException
Usage:
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

getContentAsContainer

public Container getContentAsContainer(HttpSession session,
                                       java.lang.String toContainer,
                                       java.lang.String toChannel)
                                throws InvalidRequestException,
                                       IOErrorException,
                                       NotOpenException,
                                       TimedOutException,
                                       ChannelErrorException,
                                       ContainerErrorException
Usage:
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.
toContainer - is the name if the container into which the HTTP body is to be stored
toChannel - 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

getContentAsContainer

public Container getContentAsContainer(HttpSession session,
                                       java.lang.String toContainer)
                                throws InvalidRequestException,
                                       IOErrorException,
                                       NotOpenException,
                                       TimedOutException,
                                       ChannelErrorException,
                                       ContainerErrorException
Usage:
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.
toContainer - is the name if the container into which the HTTP body is to be stored
Returns:
Container object
Throws:
InvalidRequestException - a INVREQ condition occurred
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

getStatusCode

public int getStatusCode()
                  throws InvalidRequestException
Usage:
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

getStatusText

public java.lang.String getStatusText()
                               throws InvalidRequestException
Usage:
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

getMediaType

public java.lang.String getMediaType()
                              throws InvalidRequestException
Usage:
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

getMediaTypeTrim

public java.lang.String getMediaTypeTrim()
                                  throws InvalidRequestException
Usage:
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

getCharacterset

public java.lang.String getCharacterset()
                                 throws InvalidRequestException
Usage:
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

getCharactersetTrim

public java.lang.String getCharactersetTrim()
                                     throws InvalidRequestException
Usage:
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

getBodyCharset

public java.lang.String getBodyCharset()
                                throws InvalidRequestException
Usage:
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

isBodyComplete

public boolean isBodyComplete()
Usage:
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()

isBodyTruncated

public boolean isBodyTruncated()
Usage:
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()

isBodyPartial

public boolean isBodyPartial()
Usage:
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()

getHeader

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

startBrowseHeader

public void startBrowseHeader(HttpSession session)
                       throws InvalidRequestException,
                              NotOpenException,
                              LogicException
Usage:
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

getNextHeader

public HttpHeader getNextHeader(HttpSession session)
                         throws LogicException,
                                NotOpenException,
                                EndOfFileException
Usage:
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

endBrowseHeader

public void endBrowseHeader(HttpSession session)
                     throws LogicException,
                            NotOpenException
Usage:
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