com.pingidentity.pa.sdk.http.client

Class ClientRequest

java.lang.Object

com.pingidentity.pa.sdk.http.client.ClientRequest

public final class ClientRequest
extends Object

Represents a HTTP request that can be sent to a HTTP server by a HttpClient.

Constructor Summary

Constructors

Constructor and Description
ClientRequest(Method method, String requestTarget, Headers headers) Constructs a ClientRequest representing a HTTP request without a body.
ClientRequest(Method method, String requestTarget, Headers headers, byte[] body) Constructs a ClientRequest representing a HTTP request with a body.

Method Summary

Modifier and Type	Method and Description
static Headers	createHeaders() A helper method to create a Headers instance.
boolean	equals(Object o) Two ClientRequest instances are considered equal if their serialized representations are equal.
byte[]	getBody()
Headers	getHeaders()
Method	getMethod()
String	getRequestTarget()
int	hashCode() Similar to equals(Object), the hash code is computed based on the serialized representation
String	toString() Returns a String representation of this request.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ClientRequest

public ClientRequest(Method method,
                     String requestTarget,
                     Headers headers)

Constructs a ClientRequest representing a HTTP request without a body.

Parameters:

method - the HTTP method for the request

requestTarget - the request target to include in the request line. Typically, this of the form /path?query

headers - the Headers representing the header fields of the request. An instance of Headers can be created using createHeaders() or a HeadersFactory.

Throws:

IllegalArgumentException - when the specified data for the request is invalid:

• If the method is CONNECT. PingAccess will transparently send CONNECT requests based on administrator-defined configuration.
• If the method is TRACE. TRACE requests are not supported.
• If the request target contains characters not representable in the ISO-8859-1 charset. These characters should be percent-encoded. URLEncoder can be used to perform this encoding.
• If the request target contains a fragment (a # followed by zero or more characters)
• If the request target does not start with a forward slash (/). The exception to this is when the method is OPTIONS and the request target is equal to "*".
• If the Headers contain a Content-Length or Transfer-Encoding header field, these header fields will be set appropriately by PingAccess.
• If the Headers contain a Host header field. This header field will be set based on administrator-defined configuration.
• If the field values contained in the Headers instance contain characters that are not representable in the ISO-8859-1 charset.
• If a field name or value contained in the Headers instance contains a carriage return or line feed.

ClientRequest

public ClientRequest(Method method,
                     String requestTarget,
                     Headers headers,
                     byte[] body)

Constructs a ClientRequest representing a HTTP request with a body.

Parameters:

method - the HTTP method for the request

requestTarget - the request target (a.k.a. the request URI) to include in the request line. Typically, this is of the form /path?query.

headers - the Headers representing the header fields of the request. An instance of Headers can be created using createHeaders() or a HeadersFactory.

body - the bytes for the request body. For the sake of performance, the specified byte array is NOT copied. Users of this class must ensure the specified array is not changed after constructing an instance.

Throws:

IllegalArgumentException - when the specified data for the request is invalid:

• If the method is CONNECT. PingAccess will transparently send CONNECT requests based on administrator-defined configuration.
• If the method is TRACE. TRACE requests are not supported.
• If the method is GET, HEAD or DELETE and the body length is non-zero.
• If the request target contains characters not representable using the ISO-8859-1 charset. These characters should be percent-encoded. URLEncoder can be used to perform this encoding.
• If the request target contains a fragment (a # followed by zero or more characters)
• If the request target does not start with a forward slash (/). The exception to this is when the method is OPTIONS and the request target is equal to "*".
• If the Headers contain a Content-Length or Transfer-Encoding header field, these header fields will be set appropriately by PingAccess based on the length of body.
• If the Headers contain a Host header field. This header field will be set based on administrator-defined configuration.
• If the field values contained in the Headers instance contain characters that are not representable in the ISO-8859-1 charset.
• If a field name or value contained in the Headers instance contains a carriage return or line feed.

Method Detail

createHeaders

public static Headers createHeaders()

A helper method to create a Headers instance.

Returns:

the Headers instance

getMethod

public Method getMethod()

Returns:

the method for this request

getRequestTarget

public String getRequestTarget()

Returns:

the request target for this request

getHeaders

public Headers getHeaders()

Returns:

the Headers representing the header fields for this request

getBody

public byte[] getBody()

Returns:

the underlying byte array representing the request body. Callers should not modify this array.

toString

public String toString()

Returns a String representation of this request.

The representation only includes the length of the body to avoid inadvertently logging sensitive data that is often present in request body. Further, the Authorization and Cookie header fields are included with content redacted for the same reason.

Example output:

 ClientRequest[method=GET,requestTarget="/path?query",headers=[authorization: "<redacted>", x-custom:"value"],body=0]
 

Overrides:

toString in class Object

Returns:

a String representation of this request.

equals

public boolean equals(Object o)

Two ClientRequest instances are considered equal if their serialized representations are equal.

That is, the following requests are not considered equal, despite being semantically equivalent:

 GET / HTTP/1.1[\r][\n]
 Host: www.example.com[\r][\n]
 X-Custom: one
 Accept: application/json
 X-Custom: two
 [\r][\n]
 

 GET / HTTP/1.1[\r][\n]
 Host: www.example.com[\r][\n]
 X-Custom: one,two[\r][\n]
 Accept: application/json[\r][\n]
 [\r][\n]
 

PingAccess does not provide a semantic equivalence equals implementation because doing so requires the ability to canonicalize the payload body, which is not feasible. Further, while PingAccess might consider certain requests semantically equivalent, variations in HTTP server specification compliance might result in a server classifying those same requests as semantically different.

As a result, PingAccess uses a more conservative approach that ensures equal ClientRequest instances will result in the same server handling.

Overrides:

equals in class Object

Parameters:

o - the other ClientRequest

Returns:

true if the specified Object equals this ClientRequest

hashCode

public int hashCode()

Similar to equals(Object), the hash code is computed based on the serialized representation

Overrides:

hashCode in class Object

Returns:

the hash code for this ClientRequest