Module org.refcodes.rest
Package org.refcodes.rest

Class RestResponseHandler

java.lang.Object
org.refcodes.web.AbstractHttpRequest
org.refcodes.web.HttpClientRequest
org.refcodes.rest.RestResponseHandler
All Implemented Interfaces:
org.refcodes.component.Closable, org.refcodes.component.Closable.CloseBuilder<org.refcodes.component.LinkComponent.LinkComponentBuilder<RestResponseHandler>>, org.refcodes.component.ConnectionStatusAccessor, org.refcodes.component.LinkComponent, org.refcodes.component.LinkComponent.LinkComponentBuilder<RestResponseHandler>, org.refcodes.component.Openable, org.refcodes.component.Openable.OpenBuilder<org.refcodes.component.LinkComponent.LinkComponentBuilder<RestResponseHandler>>, org.refcodes.component.OpenedAccessor, RestResponseConsumer, org.refcodes.web.HeaderFieldsAccessor<org.refcodes.web.RequestHeaderFields>, org.refcodes.web.HeaderFieldsAccessor.HeaderFieldsBuilder<org.refcodes.web.RequestHeaderFields,RestResponseHandler>, org.refcodes.web.HeaderFieldsAccessor.HeaderFieldsMutator<org.refcodes.web.RequestHeaderFields>, org.refcodes.web.HeaderFieldsAccessor.HeaderFieldsProperty<org.refcodes.web.RequestHeaderFields>, org.refcodes.web.HttpBodyAccessor.HttpBodyProvider<org.refcodes.web.BadRequestException>, org.refcodes.web.HttpMethodAccessor, org.refcodes.web.HttpMethodAccessor.HttpMethodBuilder<RestResponseHandler>, org.refcodes.web.HttpMethodAccessor.HttpMethodMutator, org.refcodes.web.HttpMethodAccessor.HttpMethodProperty, org.refcodes.web.HttpRequest, org.refcodes.web.HttpRequestBuilder<RestResponseHandler>, org.refcodes.web.QueryFieldsAccessor, org.refcodes.web.QueryFieldsAccessor.QueryFieldsMutator, org.refcodes.web.QueryFieldsAccessor.QueryFieldsProperty, org.refcodes.web.RedirectDepthAccessor, org.refcodes.web.RedirectDepthAccessor.RedirectDepthBuilder<RestResponseHandler>, org.refcodes.web.RedirectDepthAccessor.RedirectDepthMutator, org.refcodes.web.RedirectDepthAccessor.RedirectDepthProperty, org.refcodes.web.UrlAccessor, org.refcodes.web.UrlAccessor.UrlBuilder, org.refcodes.web.UrlAccessor.UrlMutator
public class RestResponseHandler extends org.refcodes.web.HttpClientRequest implements RestResponseConsumer, org.refcodes.web.QueryFieldsAccessor.QueryFieldsProperty, org.refcodes.web.HeaderFieldsAccessor.HeaderFieldsProperty<org.refcodes.web.RequestHeaderFields>, org.refcodes.web.RedirectDepthAccessor.RedirectDepthBuilder<RestResponseHandler>, org.refcodes.web.HttpRequestBuilder<RestResponseHandler>, org.refcodes.web.HttpMethodAccessor.HttpMethodProperty, org.refcodes.web.HttpMethodAccessor.HttpMethodBuilder<RestResponseHandler>, org.refcodes.component.LinkComponent.LinkComponentBuilder<RestResponseHandler>, org.refcodes.component.ConnectionStatusAccessor, org.refcodes.web.HeaderFieldsAccessor.HeaderFieldsBuilder<org.refcodes.web.RequestHeaderFields,RestResponseHandler>
A RestResponseHandler describes a REST request and the RestResponseConsumer in charge for handling a REST response. The RestResponseHandler describes the HttpMethod to be used, the targeted URL, the HeaderFields as well as the Query-Fields and the request Object or InputStream. It provides builder functionality and lambda support for handling the responses addressed to this RestResponseHandler. The lambda defined as RestResponseConsumer acts as the single listener to this RestResponseHandler responsible for handling the responses for which this RestResponseHandler is responsible. The locator to which a RestResponseHandler targets for is defined by the getUrl() property.

  • Nested Class Summary

    Nested classes/interfaces inherited from interface org.refcodes.component.Closable

    org.refcodes.component.Closable.CloseAutomaton, org.refcodes.component.Closable.CloseBuilder<B extends org.refcodes.component.Closable.CloseBuilder<B>>

    Nested classes/interfaces inherited from interface org.refcodes.component.ConnectionStatusAccessor

    org.refcodes.component.ConnectionStatusAccessor.ConnectionStatusMutator, org.refcodes.component.ConnectionStatusAccessor.ConnectionStatusProperty

    Nested classes/interfaces inherited from interface org.refcodes.web.HeaderFieldsAccessor

    org.refcodes.web.HeaderFieldsAccessor.HeaderFieldsBuilder<T extends org.refcodes.web.HeaderFields<?,?>,B extends org.refcodes.web.HeaderFieldsAccessor.HeaderFieldsBuilder<T,B>>, org.refcodes.web.HeaderFieldsAccessor.HeaderFieldsMutator<T extends org.refcodes.web.HeaderFields<?,?>>, org.refcodes.web.HeaderFieldsAccessor.HeaderFieldsProperty<T extends org.refcodes.web.HeaderFields<?,?>>

    Nested classes/interfaces inherited from interface org.refcodes.web.HttpMethodAccessor

    org.refcodes.web.HttpMethodAccessor.HttpMethodBuilder<B extends org.refcodes.web.HttpMethodAccessor.HttpMethodBuilder<B>>, org.refcodes.web.HttpMethodAccessor.HttpMethodMutator, org.refcodes.web.HttpMethodAccessor.HttpMethodProperty

    Nested classes/interfaces inherited from interface org.refcodes.component.LinkComponent

    org.refcodes.component.LinkComponent.LinkAutomaton, org.refcodes.component.LinkComponent.LinkComponentBuilder<B extends org.refcodes.component.LinkComponent.LinkComponentBuilder<B>>

    Nested classes/interfaces inherited from interface org.refcodes.component.Openable

    org.refcodes.component.Openable.OpenAutomaton, org.refcodes.component.Openable.OpenBuilder<B extends org.refcodes.component.Openable.OpenBuilder<B>>

    Nested classes/interfaces inherited from interface org.refcodes.component.OpenedAccessor

    org.refcodes.component.OpenedAccessor.OpenedMutator, org.refcodes.component.OpenedAccessor.OpenedProperty

    Nested classes/interfaces inherited from interface org.refcodes.web.QueryFieldsAccessor

    org.refcodes.web.QueryFieldsAccessor.QueryFieldsBuilder<B extends org.refcodes.web.QueryFieldsAccessor.QueryFieldsBuilder<?>>, org.refcodes.web.QueryFieldsAccessor.QueryFieldsMutator, org.refcodes.web.QueryFieldsAccessor.QueryFieldsProperty

    Nested classes/interfaces inherited from interface org.refcodes.web.RedirectDepthAccessor

    org.refcodes.web.RedirectDepthAccessor.RedirectDepthBuilder<B extends org.refcodes.web.RedirectDepthAccessor.RedirectDepthBuilder<B>>, org.refcodes.web.RedirectDepthAccessor.RedirectDepthMutator, org.refcodes.web.RedirectDepthAccessor.RedirectDepthProperty

    Nested classes/interfaces inherited from interface org.refcodes.web.UrlAccessor

    org.refcodes.web.UrlAccessor.UrlBuilder, org.refcodes.web.UrlAccessor.UrlMutator, org.refcodes.web.UrlAccessor.UrlProperty

  • Field Summary

    Fields inherited from class org.refcodes.web.HttpClientRequest

    _mediaTypeFactoryLookup, DEFAULT_REDIRECT_DEPTH

    Fields inherited from class org.refcodes.web.AbstractHttpRequest

    _headerFields, _httpMethod, _url

  • Constructor Summary

    Constructors
    Constructor
    Description
    RestResponseHandler(org.refcodes.web.HttpMethod aHttpMethod, org.refcodes.web.Url aUrl, Object aRequest, int aRedirectDepth, RestResponseConsumer aResponseConsumer, org.refcodes.web.MediaTypeFactoryLookup aMediaTypeFactoryLookup)
    Instantiates a new RestResponseHandler.
    RestResponseHandler(org.refcodes.web.HttpMethod aHttpMethod, org.refcodes.web.Url aUrl, Object aRequest, RestResponseConsumer aResponseConsumer, org.refcodes.web.MediaTypeFactoryLookup aMediaTypeFactoryLookup)
    Instantiates a new RestResponseHandler.
    RestResponseHandler(org.refcodes.web.HttpMethod aHttpMethod, org.refcodes.web.Url aUrl, RestResponseConsumer aResponseConsumer, int aRedirectDepth, org.refcodes.web.MediaTypeFactoryLookup aMediaTypeFactoryLookup)
    Instantiates a new RestResponseHandler.
    RestResponseHandler(org.refcodes.web.HttpMethod aHttpMethod, org.refcodes.web.Url aUrl, RestResponseConsumer aResponseConsumer, org.refcodes.web.MediaTypeFactoryLookup aMediaTypeFactoryLookup)
    Instantiates a new RestResponseHandler.
    RestResponseHandler(org.refcodes.web.HttpMethod aHttpMethod, org.refcodes.web.Url aUrl, org.refcodes.web.RequestHeaderFields aHeaderFields, Object aRequest, int aRedirectDepth, RestResponseConsumer aResponseConsumer, org.refcodes.web.MediaTypeFactoryLookup aMediaTypeFactoryLookup)
    Instantiates a new RestResponseHandler.
    RestResponseHandler(org.refcodes.web.HttpMethod aHttpMethod, org.refcodes.web.Url aUrl, org.refcodes.web.RequestHeaderFields aHeaderFields, Object aRequest, RestResponseConsumer aResponseConsumer, org.refcodes.web.MediaTypeFactoryLookup aMediaTypeFactoryLookup)
    Instantiates a new RestResponseHandler.
    RestResponseHandler(org.refcodes.web.MediaTypeFactoryLookup aMediaTypeFactoryLookup)
    Instantiates a new RestResponseHandler.

  • Method Summary

    Modifier and Type
    Method
    Description
    static RestResponseHandler
    build(RestClient aRestClient)
    This is a convenience method for easily instantiating the according builder.
    void
    close()
    org.refcodes.component.ConnectionStatus
    getConnectionStatus()
    org.refcodes.web.HttpMethod
    getHttpMethod()
    org.refcodes.web.FormFields
    getQueryFields()
    RestResponseConsumer
    getResponseObserver()
    Retrieves the RestResponseConsumer to which any responses are delegated upon invocation of the onResponse(RestResponseEvent) method.
    org.refcodes.web.Url
    getUrl()
    void
    onResponse(RestResponseEvent aResponse)
    The invoker provides a response context being a RestResponseEvent describing the response being processed upon by your lambda's code.
    void
    open()
    void
    setHeaderFields(org.refcodes.web.RequestHeaderFields aHeaderFields)
    void
    setHttpMethod(org.refcodes.web.HttpMethod aHttpMethod)
    void
    setQueryFields(org.refcodes.web.FormFields aQueryFields)
    void
    setResponseObserver(RestResponseConsumer aLambda)
    Sets the RestResponseConsumer to which any responses are delegated upon invocation of the onResponse(RestResponseEvent) method.
    void
    setUrl(org.refcodes.web.Url aUrl)
    String
    toString()
    RestResponseHandler
    withClose()
    RestResponseHandler
    withCloseIn(int aCloseMillis)
    RestResponseHandler
    withCloseQuietly()
    RestResponseHandler
    withHeaderFields(org.refcodes.web.RequestHeaderFields aRequestHeaderFields)
    RestResponseHandler
    withHttpMethod(org.refcodes.web.HttpMethod aHttpMethod)
    RestResponseHandler
    withOpen()
    RestResponseHandler
    withRedirectDepth(int aRedirectDepth)
    <REQ> RestResponseHandler
    withRequest(REQ aRequest)
    Sets the request for the request property.
    RestResponseHandler
    withResponseObserver(RestResponseConsumer aLambda)
    Builder method for setting the RestResponseConsumer.
    RestResponseHandler
    withUrl(org.refcodes.web.Url aUrl)

    Methods inherited from class org.refcodes.web.HttpClientRequest

    getRedirectDepth, getRequest, setRedirectDepth, setRequest, toHttpBody

    Methods inherited from class org.refcodes.web.AbstractHttpRequest

    getHeaderFields

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    Methods inherited from interface org.refcodes.component.Closable

    closeIn, closeQuietly, closeUnchecked

    Methods inherited from interface org.refcodes.component.Closable.CloseBuilder

    withCloseUnchecked

    Methods inherited from interface org.refcodes.component.ConnectionStatusAccessor

    isOpened

    Methods inherited from interface org.refcodes.web.HeaderFieldsAccessor

    getHeaderFields

    Methods inherited from interface org.refcodes.web.HeaderFieldsAccessor.HeaderFieldsProperty

    letHeaderFields

    Methods inherited from interface org.refcodes.web.HttpMethodAccessor.HttpMethodProperty

    letHttpMethod

    Methods inherited from interface org.refcodes.web.HttpRequestBuilder

    withAddToHeaderFields, withAddToHeaderFields, withAddToHeaderFields, withAddToHeaderFields, withAddToHeaderFields, withAddToQueryFields, withAddToQueryFields, withAddToQueryFields

    Methods inherited from interface org.refcodes.component.Openable

    openUnchecked

    Methods inherited from interface org.refcodes.component.Openable.OpenBuilder

    withOpenUnchecked

    Methods inherited from interface org.refcodes.web.QueryFieldsAccessor.QueryFieldsProperty

    letQueryFields

    Methods inherited from interface org.refcodes.web.RedirectDepthAccessor.RedirectDepthProperty

    letRedirectDepth

  • Constructor Details

    • RestResponseHandler

      public RestResponseHandler(org.refcodes.web.HttpMethod aHttpMethod, org.refcodes.web.Url aUrl, org.refcodes.web.RequestHeaderFields aHeaderFields, Object aRequest, RestResponseConsumer aResponseConsumer, org.refcodes.web.MediaTypeFactoryLookup aMediaTypeFactoryLookup)
      Instantiates a new RestResponseHandler.
      Parameters:
      aHttpMethod - the http method
      aUrl - The Url from which to take the URL specific data.
      aHeaderFields - the Header-Fields
      aRequest - the request
      aResponseConsumer - the response observer
      aMediaTypeFactoryLookup - the media type factory lookup

    • RestResponseHandler

      public RestResponseHandler(org.refcodes.web.HttpMethod aHttpMethod, org.refcodes.web.Url aUrl, RestResponseConsumer aResponseConsumer, org.refcodes.web.MediaTypeFactoryLookup aMediaTypeFactoryLookup)
      Instantiates a new RestResponseHandler.
      Parameters:
      aHttpMethod - the http method
      aUrl - The Url from which to take the URL specific data.
      aResponseConsumer - the response observer
      aMediaTypeFactoryLookup - the media type factory lookup

    • RestResponseHandler

      public RestResponseHandler(org.refcodes.web.MediaTypeFactoryLookup aMediaTypeFactoryLookup)
      Instantiates a new RestResponseHandler.
      Parameters:
      aMediaTypeFactoryLookup - the media type factory lookup

    • RestResponseHandler

      public RestResponseHandler(org.refcodes.web.HttpMethod aHttpMethod, org.refcodes.web.Url aUrl, Object aRequest, RestResponseConsumer aResponseConsumer, org.refcodes.web.MediaTypeFactoryLookup aMediaTypeFactoryLookup)
      Instantiates a new RestResponseHandler.
      Parameters:
      aHttpMethod - the http method
      aUrl - The Url from which to take the URL specific data.
      aRequest - the request
      aResponseConsumer - the response observer
      aMediaTypeFactoryLookup - the media type factory lookup

    • RestResponseHandler

      public RestResponseHandler(org.refcodes.web.HttpMethod aHttpMethod, org.refcodes.web.Url aUrl, RestResponseConsumer aResponseConsumer, int aRedirectDepth, org.refcodes.web.MediaTypeFactoryLookup aMediaTypeFactoryLookup)
      Instantiates a new RestResponseHandler.
      Parameters:
      aHttpMethod - the http method
      aUrl - The Url from which to take the URL specific data.
      aRedirectDepth - The redirect depth provides the count of HTTP-Request and HTTP-Response cycles where the response represents a redirect as of HttpStatusCode.isRedirectStatus(). A value of -1 represents the default behavior, e.g. using HttpURLConnection's redirection means.
      aResponseConsumer - the response observer
      aMediaTypeFactoryLookup - the media type factory lookup

    • RestResponseHandler

      public RestResponseHandler(org.refcodes.web.HttpMethod aHttpMethod, org.refcodes.web.Url aUrl, Object aRequest, int aRedirectDepth, RestResponseConsumer aResponseConsumer, org.refcodes.web.MediaTypeFactoryLookup aMediaTypeFactoryLookup)
      Instantiates a new RestResponseHandler.
      Parameters:
      aHttpMethod - the http method
      aUrl - The Url from which to take the URL specific data.
      aRequest - the request
      aRedirectDepth - The redirect depth provides the count of HTTP-Request and HTTP-Response cycles where the response represents a redirect as of HttpStatusCode.isRedirectStatus(). A value of -1 represents the default behavior, e.g. using HttpURLConnection's redirection means.
      aResponseConsumer - the response observer
      aMediaTypeFactoryLookup - the media type factory lookup

    • RestResponseHandler

      public RestResponseHandler(org.refcodes.web.HttpMethod aHttpMethod, org.refcodes.web.Url aUrl, org.refcodes.web.RequestHeaderFields aHeaderFields, Object aRequest, int aRedirectDepth, RestResponseConsumer aResponseConsumer, org.refcodes.web.MediaTypeFactoryLookup aMediaTypeFactoryLookup)
      Instantiates a new RestResponseHandler.
      Parameters:
      aHttpMethod - the http method
      aUrl - The Url from which to take the URL specific data.
      aHeaderFields - the Header-Fields
      aRequest - the request
      aRedirectDepth - The redirect depth provides the count of HTTP-Request and HTTP-Response cycles where the response represents a redirect as of HttpStatusCode.isRedirectStatus(). A value of -1 represents the default behavior, e.g. using HttpURLConnection's redirection means.
      aResponseConsumer - the response observer
      aMediaTypeFactoryLookup - the media type factory lookup

  • Method Details

    • withRedirectDepth

      public RestResponseHandler withRedirectDepth(int aRedirectDepth)
      Specified by:
      withRedirectDepth in interface org.refcodes.web.RedirectDepthAccessor.RedirectDepthBuilder<RestResponseHandler>

    • setQueryFields

      public void setQueryFields(org.refcodes.web.FormFields aQueryFields)
      Specified by:
      setQueryFields in interface org.refcodes.web.QueryFieldsAccessor.QueryFieldsMutator

    • getQueryFields

      public org.refcodes.web.FormFields getQueryFields()
      Specified by:
      getQueryFields in interface org.refcodes.web.QueryFieldsAccessor

    • withUrl

      public RestResponseHandler withUrl(org.refcodes.web.Url aUrl)
      Specified by:
      withUrl in interface org.refcodes.web.UrlAccessor.UrlBuilder

    • withHttpMethod

      public RestResponseHandler withHttpMethod(org.refcodes.web.HttpMethod aHttpMethod)
      Specified by:
      withHttpMethod in interface org.refcodes.web.HttpMethodAccessor.HttpMethodBuilder<RestResponseHandler>

    • withRequest

      public <REQ> RestResponseHandler withRequest(REQ aRequest)
      Sets the request for the request property.
      Type Parameters:
      REQ - the generic type
      Parameters:
      aRequest - The request to be stored by the request property.
      Returns:
      The builder for applying multiple build operations.

    • onResponse

      public void onResponse(RestResponseEvent aResponse) throws org.refcodes.web.HttpResponseException
      The invoker provides a response context being a RestResponseEvent describing the response being processed upon by your lambda's code. The method works synchronously and waits (blocks the caller's thread) till it finishes execution.
      Specified by:
      onResponse in interface RestResponseConsumer
      Parameters:
      aResponse - The response of type RestResponseEvent describing the response context. Use HttpClientResponse.getResponse(Class) to retrieve the server's response body or AbstractHttpResponse.getHttpStatusCode() to retrieve the respone's HTTP Status-Code.
      Throws:
      org.refcodes.web.HttpResponseException - thrown by a HTTP-Response handling system in case of some unexpected response.

    • getHttpMethod

      public org.refcodes.web.HttpMethod getHttpMethod()
      Specified by:
      getHttpMethod in interface org.refcodes.web.HttpMethodAccessor
      Overrides:
      getHttpMethod in class org.refcodes.web.AbstractHttpRequest

    • setHttpMethod

      public void setHttpMethod(org.refcodes.web.HttpMethod aHttpMethod)
      Specified by:
      setHttpMethod in interface org.refcodes.web.HttpMethodAccessor.HttpMethodMutator

    • getResponseObserver

      public RestResponseConsumer getResponseObserver()
      Retrieves the RestResponseConsumer to which any responses are delegated upon invocation of the onResponse(RestResponseEvent) method.
      Returns:
      The (user defined) RestResponseConsumer to handle responses.

    • setResponseObserver

      public void setResponseObserver(RestResponseConsumer aLambda)
      Sets the RestResponseConsumer to which any responses are delegated upon invocation of the onResponse(RestResponseEvent) method.
      Parameters:
      aLambda - The (user defined) RestResponseConsumer to handle responses, feel free to code it as lambda expression!

    • open

      public void open() throws IOException
      Specified by:
      open in interface org.refcodes.component.Openable
      Throws:
      IOException

    • close

      public void close() throws IOException
      Specified by:
      close in interface org.refcodes.component.Closable
      Throws:
      IOException

    • getConnectionStatus

      public org.refcodes.component.ConnectionStatus getConnectionStatus()
      Specified by:
      getConnectionStatus in interface org.refcodes.component.ConnectionStatusAccessor

    • setHeaderFields

      public void setHeaderFields(org.refcodes.web.RequestHeaderFields aHeaderFields)
      Specified by:
      setHeaderFields in interface org.refcodes.web.HeaderFieldsAccessor.HeaderFieldsMutator<org.refcodes.web.RequestHeaderFields>

    • getUrl

      public org.refcodes.web.Url getUrl()
      Specified by:
      getUrl in interface org.refcodes.web.UrlAccessor
      Overrides:
      getUrl in class org.refcodes.web.AbstractHttpRequest

    • setUrl

      public void setUrl(org.refcodes.web.Url aUrl)
      Specified by:
      setUrl in interface org.refcodes.web.UrlAccessor.UrlMutator

    • withResponseObserver

      public RestResponseHandler withResponseObserver(RestResponseConsumer aLambda)
      Builder method for setting the RestResponseConsumer.
      Parameters:
      aLambda - The (user defined) RestResponseConsumer to handle responses, feel free to code it as lambda expression
      Returns:
      The RestResponseHandler for the sake of a fluent API.

    • withHeaderFields

      public RestResponseHandler withHeaderFields(org.refcodes.web.RequestHeaderFields aRequestHeaderFields)
      Specified by:
      withHeaderFields in interface org.refcodes.web.HeaderFieldsAccessor.HeaderFieldsBuilder<org.refcodes.web.RequestHeaderFields,RestResponseHandler>

    • withOpen

      public RestResponseHandler withOpen() throws IOException
      Specified by:
      withOpen in interface org.refcodes.component.Openable.OpenBuilder<org.refcodes.component.LinkComponent.LinkComponentBuilder<RestResponseHandler>>
      Throws:
      IOException

    • withClose

      public RestResponseHandler withClose() throws IOException
      Specified by:
      withClose in interface org.refcodes.component.Closable.CloseBuilder<org.refcodes.component.LinkComponent.LinkComponentBuilder<RestResponseHandler>>
      Throws:
      IOException

    • withCloseQuietly

      public RestResponseHandler withCloseQuietly()
      Specified by:
      withCloseQuietly in interface org.refcodes.component.Closable.CloseBuilder<org.refcodes.component.LinkComponent.LinkComponentBuilder<RestResponseHandler>>

    • withCloseIn

      public RestResponseHandler withCloseIn(int aCloseMillis)
      Specified by:
      withCloseIn in interface org.refcodes.component.Closable.CloseBuilder<org.refcodes.component.LinkComponent.LinkComponentBuilder<RestResponseHandler>>

    • toString

      public String toString()
      Overrides:
      toString in class org.refcodes.web.HttpClientRequest

    • build

      public static RestResponseHandler build(RestClient aRestClient)
      This is a convenience method for easily instantiating the according builder.
      Parameters:
      aRestClient - the rest client to take care of the caller.
      Returns:
      an instance (using a public implementation) of this builder