docs: protected HttpResponse doRequestWithAuthorization(HttpClient httpclient,
                                                        RequestBuilder requestBuilder,
                                                        Map<String, Object> params,
                                                        AuthenticationType type) {
          // no authorization
          if (type == null || type == AuthenticationType.NONE) {
              HttpUriRequest request = requestBuilder.build();
              try {
                  return httpclient.execute(request);
              } catch (Exception e) {
                  throw new RuntimeException("Could not execute request [" + request.getMethod() + "] " + request.getURI(),
                                             e);
              }
          }
  
          // user/password
          String u = (String) params.get(PARAM_USERNAME);
          String p = (String) params.get(PARAM_PASSWORD);
          if (u == null || p == null) {
              u = this.username;
              p = this.password;
          }
          if (u == null) {
              throw new IllegalArgumentException("Could not find username");
          }
          if (p == null) {
              throw new IllegalArgumentException("Could not find password");
          }
  
          if (type == AuthenticationType.BASIC) {
              // basic auth
              URI requestUri = requestBuilder.getUri();
  
              HttpHost targetHost = new HttpHost(requestUri.getHost(),
                                                 requestUri.getPort(),
                                                 requestUri.getScheme());
  
              // Create AuthCache instance and add it: so that HttpClient thinks that it has already queried (as per the HTTP spec)
              // - generate BASIC scheme object and add it to the local auth cache
              AuthCache authCache = new BasicAuthCache();
              BasicScheme basicAuth = new BasicScheme();
              authCache.put(targetHost,
                            basicAuth);
  
              // - add AuthCache to the execution context:
              HttpClientContext clientContext = HttpClientContext.create();
              CredentialsProvider credsProvider = new BasicCredentialsProvider();
              credsProvider.setCredentials(
                      // specify host and port, since that is safer/more secure
                      new AuthScope(requestUri.getHost(),
                                    requestUri.getPort(),
                                    AuthScope.ANY_REALM),
                      new UsernamePasswordCredentials(u,
                                                      p)
              );
              clientContext.setCredentialsProvider(credsProvider);
              clientContext.setAuthCache(authCache);
  
              // - execute request
              HttpUriRequest request = requestBuilder.build();
              try {
                  return httpclient.execute(targetHost,
                                            request,
                                            clientContext);
              } catch (Exception e) {
                  throw new RuntimeException("Could not execute request with preemptive authentication [" + request.getMethod() + "] " + request.getURI(),
                                             e);
              }
          } else if (type == AuthenticationType.FORM_BASED) {
              // form auth
  
              // 1. do initial request to trigger authentication
              HttpUriRequest request = requestBuilder.build();
              int statusCode = -1;
              try {
                  HttpResponse initialResponse = httpclient.execute(request);
                  statusCode = initialResponse.getStatusLine().getStatusCode();
              } catch (IOException e) {
                  throw new RuntimeException("Could not execute request for form-based authentication",
                                             e);
              } finally {
                  // weird, but this is the method that releases resources, including the connection
                  request.abort();
              }
  
              // 1b. form authentication requests should have a status of 401
              // See: www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2
              if (statusCode != HttpStatus.SC_UNAUTHORIZED) {
                  logger.error("Expected form authentication request with status {} but status on response is {}: proceeding anyways",
                               HttpStatus.SC_UNAUTHORIZED,
                               statusCode);
              }
  
              // 2. do POST form request to authentiate
              String authUrlStr = (String) params.get(PARAM_AUTHURL);
              if (authUrlStr == null) {
                  authUrlStr = authUrl;
              }
              if (authUrlStr == null) {
                  throw new IllegalArgumentException("Could not find authentication url");
              }
              HttpPost authMethod = new HttpPost(authUrlStr);
              List<NameValuePair> formParams = new ArrayList<NameValuePair>(2);
              formParams.add(new BasicNameValuePair("j_username",
                                                    u));
              formParams.add(new BasicNameValuePair("j_password",
                                                    p));
              UrlEncodedFormEntity formEntity;
              try {
                  formEntity = new UrlEncodedFormEntity(formParams);
              } catch (UnsupportedEncodingException uee) {
                  throw new RuntimeException("Could not encode authentication parameters into request body",
                                             uee);
              }
              authMethod.setEntity(formEntity);
              try {
                  httpclient.execute(authMethod);
              } catch (IOException e) {
                  throw new RuntimeException("Could not initialize form-based authentication",
                                             e);
              } finally {
                  authMethod.releaseConnection();
              }
  
              // 3. rebuild request and execute
              request = requestBuilder.build();
              try {
                  return httpclient.execute(request);
              } catch (Exception e) {
                  throw new RuntimeException("Could not execute request [" + request.getMethod() + "] " + request.getURI(),
                                             e);
              }
          } else {
              throw new RuntimeException("Unknown AuthenticationType " + type);
          }
      }