RequestHttpObjectBuilder (OpenSAML 3.x utility extensions

Type Parameters:

T - the concrete request type

All Superinterfaces:

SAMLObjectBuilder<T>
```
public interface RequestHttpObjectBuilder<T extends RequestAbstractType>
extends SAMLObjectBuilder<T>
```
A generic request builder that is used to create Request messages.
A request builder instance may only be used to create one request and should not be re-used. Instead a new builder should be created using a builder factory.

By default the request builder creates a Request object based on the SP and IdP settings in metadata and the configuration of the builder factory, but it is also possible to control the request by using chaining calls as illustrated below:
```
 RequestHttpObject request = builder.relayState("hello").binding("urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST").build();
 
```
Author:

Martin Lindström (martin.lindstrom@litsec.se)

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`String`	`binding()` Returns the SAML binding that should be used when sending the request.
`RequestHttpObjectBuilder<T>`	`binding(String binding)` The builder is created with the SAML binding to use when sending the request message (redirect or post).
`RequestHttpObject<T>`	`buildHttpObject()` Compiles the request by invoking `SAMLObjectBuilder.build()`, optionally signs it and encodes it according to the configured binding and returns a RequestHttpObject that can be used by the SP application to send the request to the Identity Provider.
`RequestHttpObjectBuilder<T>`	`endpoint(String url)` For testing purposes
`String`	`entityID()` Returns the entityID of the Service Provider that this builder is serving.
`String`	`idpEntityID()` Returns the entityID for the IdP to which we are constructing the request.
`boolean`	`performSignature()` Predicate that tells whether the request being created will be signed or not.
`RequestHttpObjectBuilder<T>`	`performSignature(boolean signatureFlag)` The RequestBuilder reads the federation metadata and determines that a request should be signed if based on requirements from the IdP and SP.
`String`	`relayState()` Returns the SAML RelayState that has been configured for this builder.
`RequestHttpObjectBuilder<T>`	`relayState(String relayState)` Installs the SAML RelayState to use when sending the request.
`T`	`request()` Returns a reference to the request object that this builder object is handling.
`RequestHttpObjectBuilder<T>`	`request(T request)` Replaces the request object that this builder currently is processing with a new and updated object.
`X509Credential`	`signatureCredentials()` Returns the signature credentials this builder object has been configured to use during request signing.
`RequestHttpObjectBuilder<T>`	`signatureCredentials(X509Credential signatureCredentials)` Using this method the signature credentials for the builder object may be changed.

Methods inherited from interface se.litsec.opensaml.core.SAMLObjectBuilder
build

- Method Detail
  - buildHttpObject
```
RequestHttpObject<T> buildHttpObject()
                              throws SignatureException,
                                     ResolverException,
                                     MessageEncodingException
```
    Compiles the request by invoking SAMLObjectBuilder.build(), optionally signs it and encodes it according to the configured binding and returns a RequestHttpObject that can be used by the SP application to send the request to the Identity Provider.
    
    Returns:
    
    a RequestHttpObject object
    
    Throws:
    
    SignatureException - for signature creation errors
    
    ResolverException - for metadata errors
    
    MessageEncodingException - for encoding errors
  - entityID
```
String entityID()
```
    Returns the entityID of the Service Provider that this builder is serving.
    
    Returns:
    
    entityID of the Service Provider
  - idpEntityID
```
String idpEntityID()
```
    Returns the entityID for the IdP to which we are constructing the request.
    
    Returns:
    
    entityID of the Identity Provider
  - relayState
```
RequestHttpObjectBuilder<T> relayState(String relayState)
```
    Installs the SAML RelayState to use when sending the request.
    
    Parameters:
    
    relayState - the RelayState
    
    Returns:
    
    an updated builder object
  - relayState
```
String relayState()
```
    Returns the SAML RelayState that has been configured for this builder.
    
    Returns:
    
    the SAML RelayState or null if none has been configured
  - request
```
RequestHttpObjectBuilder<T> request(T request)
```
    Replaces the request object that this builder currently is processing with a new and updated object.
    Note: Care should be taken when using this method, and if only a particular attribute or element of the request should be modified it is generally better to use the request() method that returns a reference to the contained request message, or the special purpose methods for this purpose.
    
    Parameters:
    
    request - the request object to install to the builder
    
    Returns:
    
    an updated builder object
    
    See Also:
    
    request()
  - request
```
T request()
```
    Returns a reference to the request object that this builder object is handling. In order to modify parts of the request this method should be used.
    Also see the methods that directly modifies attributes and elements.
    
    Returns:
    
    a reference to the request object
  - binding
```
RequestHttpObjectBuilder<T> binding(String binding)
                             throws ResolverException
```
    The builder is created with the SAML binding to use when sending the request message (redirect or post). This method may be used to override this setting.
    
    Parameters:
    
    binding - the URI of the SAML binding to use (e.g., "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect")
    
    Returns:
    
    an updated builder object
    
    Throws:
    
    ResolverException - if the binding supplied does not match a binding found in the IdP:s entity descriptor
  - binding
```
String binding()
```
    Returns the SAML binding that should be used when sending the request.
    
    Returns:
    
    the URI of the SAML binding to use
  - performSignature
```
RequestHttpObjectBuilder<T> performSignature(boolean signatureFlag)
```
    The RequestBuilder reads the federation metadata and determines that a request should be signed if based on requirements from the IdP and SP.
    Using this method it is possible to override the default behaviour by explicitly state the request should be signed, or not signed.
    
    Parameters:
    
    signatureFlag - flag telling whether the request being created should be signed or not
    
    Returns:
    
    an updated builder object
  - performSignature
```
boolean performSignature()
```
    Predicate that tells whether the request being created will be signed or not.
    
    Returns:
    
    if the request being created will be signed true is returned, and false otherwise
  - signatureCredentials
```
RequestHttpObjectBuilder<T> signatureCredentials(X509Credential signatureCredentials)
```
    Using this method the signature credentials for the builder object may be changed. This is typically useful when the SP has more than one signature key, or for testing purposes.
    
    Parameters:
    
    signatureCredentials - the "new" signature credentials
    
    Returns:
    
    an updated builder object
  - signatureCredentials
```
X509Credential signatureCredentials()
```
    Returns the signature credentials this builder object has been configured to use during request signing.
    
    Returns:
    
    the signature credentials
  - endpoint
```
RequestHttpObjectBuilder<T> endpoint(String url)
```
    For testing purposes
    The method will change the endpoint to where the request will be sent, but will not modify the Destination attribute of the request element.
    
    Parameters:
    
    url - the endpoint to assign
    
    Returns:
    
    an updated builder object

Interface RequestHttpObjectBuilder<T extends RequestAbstractType>

Method Summary

Methods inherited from interface se.litsec.opensaml.core.SAMLObjectBuilder

Method Detail

buildHttpObject

entityID

idpEntityID

relayState

relayState

request

request

binding

binding

performSignature

performSignature

signatureCredentials

signatureCredentials

endpoint