Class BaseAPIActionUtil

java.lang.Object
com.kingsrook.qqq.backend.module.api.actions.BaseAPIActionUtil
public class BaseAPIActionUtil extends Object
Base class for utility functions that make up the unique ways in which an API can be implemented.

  • Field Details

  • Constructor Details

    • BaseAPIActionUtil

      public BaseAPIActionUtil()

  • Method Details

    • doCount

      public CountOutput doCount(QTableMetaData table, CountInput countInput) throws QException
      Throws:
      QException

    • doGet

      public GetOutput doGet(QTableMetaData table, GetInput getInput) throws QException
      Throws:
      QException

    • doInsert

      public InsertOutput doInsert(QTableMetaData table, InsertInput insertInput) throws QException
      Throws:
      QException

    • doQuery

      public QueryOutput doQuery(QTableMetaData table, QueryInput queryInput) throws QException
      OK - so - we will potentially make multiple GET calls to the backend, to fetch up to the full limit from the filter (and, if there is no limit in the filter, then we'll keep fetching until we stop getting results). This is managed internally here by copying the limit into the originalLimit var. Then "limit" in this method becomes the api's "how many to fetch per page" parameter (either the originalLimit, or the api's standard limit). Then we break the loop (return from the method) either when: - we've fetch a total count >= the originalLimit - we got back less than a page full (e.g., we're at the end of the result set). - an async job was cancelled.
      Throws:
      QException

    • doUpdate

      public UpdateOutput doUpdate(QTableMetaData table, UpdateInput updateInput) throws QException
      Throws:
      QException

    • doDelete

      public DeleteOutput doDelete(QTableMetaData table, DeleteInput deleteInput) throws QException
      Throws:
      QException

    • validateResponse

      public void validateResponse(QHttpResponse response, List<QRecord> recordList) throws QException
      Throws:
      QException

    • processGetResponseForCount

      public Integer processGetResponseForCount(QTableMetaData table, QHttpResponse response) throws QException
      Throws:
      QException

    • processSingleRecordGetResponse

      public QRecord processSingleRecordGetResponse(QTableMetaData table, QHttpResponse response) throws QException
      Throws:
      QException

    • processPostResponse

      protected QRecord processPostResponse(QTableMetaData table, QRecord record, QHttpResponse response) throws QException
      Throws:
      QException

    • processGetResponse

      protected int processGetResponse(QTableMetaData table, QHttpResponse response, QueryOutput queryOutput) throws QException
      Throws:
      QException

    • handleResponseError

      protected void handleResponseError(QTableMetaData table, org.apache.http.client.methods.HttpRequestBase request, QHttpResponse response) throws QException
      Throws:
      QException

    • checkForOAuthExpiredToken

      protected void checkForOAuthExpiredToken(QTableMetaData table, org.apache.http.client.methods.HttpRequestBase request, QHttpResponse response) throws OAuthExpiredTokenException
      Throws:
      OAuthExpiredTokenException

    • buildQueryStringForUpdate

      protected String buildQueryStringForUpdate(QTableMetaData table, List<QRecord> recordList) throws QException
      method to build up a query string for updates based on a given QFilter object
      Throws:
      QException

    • buildQueryStringForGet

      protected String buildQueryStringForGet(QQueryFilter filter, Integer limit, Integer skip, Map<String,QFieldMetaData> fields) throws QException
      method to build up a query string based on a given QFilter object
      Throws:
      QException

    • buildQueryStringForDelete

      protected String buildQueryStringForDelete(QQueryFilter filter, List<Serializable> primaryKeys) throws QException
      method to build up delete string based on a given QFilter object
      Throws:
      QException

    • buildUrlSuffixForSingleRecordGet

      public String buildUrlSuffixForSingleRecordGet(Serializable primaryKey) throws QException
      Do a default query string for a single-record GET - e.g., a query for just 1 record.
      Throws:
      QException

    • buildUrlSuffixForSingleRecordGet

      public String buildUrlSuffixForSingleRecordGet(Map<String,Serializable> uniqueKey) throws QException
      Throws:
      QException

    • setupAuthorizationInRequest

      public void setupAuthorizationInRequest(org.apache.http.client.methods.HttpRequestBase request) throws QException
      As part of making a request - set up its authorization header (not just strictly "Authorization", but whatever is needed for auth). Can be overridden if an API uses an authorization type we don't natively support.
      Throws:
      QException

    • addApiKeyQueryParamToRequest

      protected void addApiKeyQueryParamToRequest(org.apache.http.client.methods.HttpRequestBase request) throws QException
      Throws:
      QException

    • getApiKey

      protected String getApiKey() throws QException
      Throws:
      QException

    • getUsernameAndPassword

      protected Pair<String,String> getUsernameAndPassword() throws QException
      Throws:
      QException

    • getOAuth2Token

      public String getOAuth2Token() throws QException
      Throws:
      QException

    • createOAuth2TokenRequest

      protected org.apache.http.client.methods.HttpRequestBase createOAuth2TokenRequest() throws QException
      For doing OAuth2 authentication, create a request for a token.
      Throws:
      QException

    • getClientIdAndSecret

      protected Pair<String,String> getClientIdAndSecret() throws QException
      Throws:
      QException

    • getCharsetForEntity

      protected static Charset getCharsetForEntity()
      Let a subclass change what charset to use for entities (bodies) being posted/put/etc.

    • executeOAuthTokenRequest

      protected org.apache.http.client.methods.CloseableHttpResponse executeOAuthTokenRequest(org.apache.http.impl.client.CloseableHttpClient client, org.apache.http.client.methods.HttpRequestBase request) throws IOException
      one-line method, factored out so mock/tests can override
      Throws:
      IOException

    • executeOAuthTokenRequest

      @Deprecated protected org.apache.http.client.methods.CloseableHttpResponse executeOAuthTokenRequest(org.apache.http.impl.client.CloseableHttpClient client, org.apache.http.client.methods.HttpPost request) throws IOException
      Deprecated.
      one-line method, factored out so mock/tests can override Deprecated, in favor of more generic overload that takes HttpRequestBase
      Throws:
      IOException

    • setupContentTypeInRequest

      protected void setupContentTypeInRequest(org.apache.http.client.methods.HttpRequestBase request)
      As part of making a request - set up its content-type header.

    • getBasicAuthenticationHeader

      protected String getBasicAuthenticationHeader(String apiKey)
      Helper method to create a value for an Authentication header, using just an apiKey - encoded as Basic + base64(apiKey)

    • setupAdditionalHeaders

      public void setupAdditionalHeaders(org.apache.http.client.methods.HttpRequestBase request)
      As part of making a request - set up additional headers. Noop in base - meant to override in subclasses.

    • getBasicAuthenticationHeader

      public String getBasicAuthenticationHeader(String username, String password)
      Helper method to create a value for an Authentication header, using just a username invalid input: '&' password - encoded as Basic + base64(username:password)

    • buildTableUrl

      protected String buildTableUrl(QTableMetaData table)
      Helper method to build the URL for a table. Can be overridden, if a particular API isn't just "base" + "tablePath". Note: you may want to look at the actionInput object, to help figure out what path you need, depending on your API.

    • recordToEntity

      protected org.apache.http.entity.AbstractHttpEntity recordToEntity(QTableMetaData table, QRecord record) throws IOException
      Build an HTTP Entity (e.g., for a PUT or POST) from a QRecord. Can be overridden if an API doesn't do a basic json object. Or, can override a helper method, such as recordToJsonObject.
      Throws:
      IOException

    • recordsToEntity

      protected org.apache.http.entity.AbstractHttpEntity recordsToEntity(QTableMetaData table, List<QRecord> recordList) throws QException
      Build an HTTP Entity (e.g., for a PUT or POST) from a list of QRecords. Can be overridden if an API doesn't do a basic json object. Or, can override a helper method, such as recordToJsonObject.
      Throws:
      QException

    • recordToJsonObject

      protected org.json.JSONObject recordToJsonObject(QTableMetaData table, QRecord record)
      Helper for recordToEntity - builds a basic JSON object. Can be overridden if an API doesn't do a basic json object.

    • jsonObjectToRecord

      protected QRecord jsonObjectToRecord(org.json.JSONObject jsonObject, Map<String,QFieldMetaData> fields) throws QException
      Throws:
      QException

    • getJsonObject

      protected org.json.JSONObject getJsonObject(QHttpResponse response) throws QException
      Throws:
      QException

    • logRequestDetails

      protected void logRequestDetails(QTableMetaData table, org.apache.http.client.methods.HttpRequestBase request) throws QException
      Throws:
      QException

    • getQHttpResponse

      protected QHttpResponse getQHttpResponse(org.apache.http.HttpResponse response) throws Exception
      Throws:
      Exception

    • makeRequest

      public QHttpResponse makeRequest(QTableMetaData table, org.apache.http.client.methods.HttpRequestBase request) throws QException
      Throws:
      QException

    • buildHttpClient

      protected org.apache.http.impl.client.CloseableHttpClient buildHttpClient()
      Build the default HttpClient used by the makeRequest method

    • shouldBeRetryableServerErrorException

      protected boolean shouldBeRetryableServerErrorException(QHttpResponse qResponse)

    • executeHttpRequest

      protected org.apache.http.client.methods.CloseableHttpResponse executeHttpRequest(org.apache.http.client.methods.HttpRequestBase request, org.apache.http.impl.client.CloseableHttpClient httpClient) throws IOException
      one-line method, factored out so mock/tests can override
      Throws:
      IOException

    • logOutboundApiCall

      protected void logOutboundApiCall(org.apache.http.client.methods.HttpRequestBase request, QHttpResponse response)

    • generateOutboundApiLogRecord

      public OutboundAPILog generateOutboundApiLogRecord(org.apache.http.client.methods.HttpRequestBase request, QHttpResponse response)

    • getBackendDetails

      protected APITableBackendDetails getBackendDetails(QTableMetaData tableMetaData)

    • getFieldBackendName

      protected String getFieldBackendName(QFieldMetaData field)

    • urlEncode

      protected String urlEncode(Serializable s)

    • getBackendMetaData

      public APIBackendMetaData getBackendMetaData()
      Getter for backendMetaData

    • setBackendMetaData

      public void setBackendMetaData(APIBackendMetaData backendMetaData)
      Setter for backendMetaData

    • setActionInput

      public void setActionInput(AbstractTableActionInput actionInput)
      Setter for actionInput

    • setSession

      @Deprecated(since="wasn't used.") public void setSession(QSession session)
      Deprecated.
      Setter for session

    • throwUnsupportedCriteriaField

      protected void throwUnsupportedCriteriaField(QFilterCriteria criteria) throws QUserFacingException
      Throws:
      QUserFacingException

    • throwUnsupportedCriteriaOperator

      protected void throwUnsupportedCriteriaOperator(QFilterCriteria criteria) throws QUserFacingException
      Throws:
      QUserFacingException

    • getMillisToSleepAfterEveryCall

      protected long getMillisToSleepAfterEveryCall()

    • getInitialRateLimitBackoffMillis

      protected int getInitialRateLimitBackoffMillis()

    • getInitialServerErrorBackoffMillis

      protected int getInitialServerErrorBackoffMillis()

    • getMaxAllowedRateLimitErrors

      protected int getMaxAllowedRateLimitErrors()

    • getMaxAllowedServerErrors

      protected int getMaxAllowedServerErrors()

    • getApiStandardLimit

      protected Integer getApiStandardLimit()

    • getUpdateMethod

      protected BaseAPIActionUtil.UpdateHttpMethod getUpdateMethod()

    • getMaxResponseMessageLengthForLog

      protected int getMaxResponseMessageLengthForLog()

    • getConnectionTimeoutMillis

      protected int getConnectionTimeoutMillis()
      For the HttpClientBuilder RequestConfig, specify its ConnectionTimeout. See - https://www.baeldung.com/httpclient-timeout - https://hc.apache.org/httpcomponents-client-5.1.x/current/httpclient5/apidocs/org/apache/hc/client5/http/config/RequestConfig.Builder.html

    • getConnectionRequestTimeoutMillis

      protected int getConnectionRequestTimeoutMillis()
      For the HttpClientBuilder RequestConfig, specify its ConnectionRequestTimeout. See - https://www.baeldung.com/httpclient-timeout - https://hc.apache.org/httpcomponents-client-5.1.x/current/httpclient5/apidocs/org/apache/hc/client5/http/config/RequestConfig.Builder.html

    • getSocketTimeoutMillis

      protected int getSocketTimeoutMillis()
      For the HttpClientBuilder RequestConfig, specify its ConnectionRequestTimeout. See - https://www.baeldung.com/httpclient-timeout - https://hc.apache.org/httpcomponents-client-5.1.x/current/httpclient5/apidocs/org/apache/hc/client5/http/config/RequestConfig.Builder.html

    • handleCustomAuthorization

      protected void handleCustomAuthorization(org.apache.http.client.methods.HttpRequestBase request) throws QException
      Throws:
      QException

    • getAPIResponseLogLevel

      protected org.apache.logging.log4j.Level getAPIResponseLogLevel() throws QException
      Throws:
      QException