001/*
002 * Copyright (c) 2010-2024 Mark Allen, Norbert Bartels.
003 *
004 * Permission is hereby granted, free of charge, to any person obtaining a copy
005 * of this software and associated documentation files (the "Software"), to deal
006 * in the Software without restriction, including without limitation the rights
007 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
008 * copies of the Software, and to permit persons to whom the Software is
009 * furnished to do so, subject to the following conditions:
010 *
011 * The above copyright notice and this permission notice shall be included in
012 * all copies or substantial portions of the Software.
013 *
014 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
015 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
016 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
017 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
018 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
019 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
020 * THE SOFTWARE.
021 */
022package com.restfb.exception.generator;
023
024import com.restfb.exception.FacebookGraphException;
025import com.restfb.exception.FacebookJsonMappingException;
026import com.restfb.exception.FacebookResponseStatusException;
027
028/**
029 * Generator to convert Facebook error JSON into RestFB Exceptions.
030 *
031 * <p>
032 * Provides methods to convert graph api errors and batch errors.
033 */
034public interface FacebookExceptionGenerator {
035
036  /**
037   * API error response 'error' attribute name.
038   */
039  String ERROR_ATTRIBUTE_NAME = "error";
040
041  /**
042   * API error response 'type' attribute name.
043   */
044  String ERROR_TYPE_ATTRIBUTE_NAME = "type";
045
046  /**
047   * API error response 'error_user_title' attribute name.
048   */
049  String ERROR_USER_TITLE_ATTRIBUTE_NAME = "error_user_title";
050
051  /**
052   * API error response 'error_user_msg' attribute name.
053   */
054  String ERROR_USER_MSG_ATTRIBUTE_NAME = "error_user_msg";
055
056  /**
057   * API error response 'message' attribute name.
058   */
059  String ERROR_MESSAGE_ATTRIBUTE_NAME = "message";
060
061  /**
062   * API error response 'code' attribute name.
063   */
064  String ERROR_CODE_ATTRIBUTE_NAME = "code";
065
066  String ERROR_IS_TRANSIENT_NAME = "is_transient";
067
068  /**
069   * API error response 'error_subcode' attribute name.
070   */
071  String ERROR_SUBCODE_ATTRIBUTE_NAME = "error_subcode";
072
073  /**
074   * Batch API error response 'error' attribute name.
075   */
076  String BATCH_ERROR_ATTRIBUTE_NAME = "error";
077
078  /**
079   * Batch API error response 'error_description' attribute name.
080   */
081  String BATCH_ERROR_DESCRIPTION_ATTRIBUTE_NAME = "error_description";
082
083  /**
084   * Throws an exception if Facebook returned an error response. Using the Graph API, it's possible to see both the new
085   * Graph API-style errors as well as Legacy API-style errors, so we have to handle both here. This method extracts
086   * relevant information from the error JSON and throws an exception which encapsulates it for end-user consumption.
087   * <p>
088   * For Graph API errors:
089   * <p>
090   * If the {@code error} JSON field is present, we've got a response status error for this API call.
091   * <p>
092   * For Legacy errors (e.g. FQL):
093   * <p>
094   * If the {@code error_code} JSON field is present, we've got a response status error for this API call.
095   *
096   * @param json
097   *          The JSON returned by Facebook in response to an API call.
098   * @param httpStatusCode
099   *          The HTTP status code returned by the server, e.g. 500.
100   * @throws FacebookGraphException
101   *           If the JSON contains a Graph API error response.
102   * @throws FacebookResponseStatusException
103   *           If the JSON contains an Legacy API error response.
104   * @throws FacebookJsonMappingException
105   *           If an error occurs while processing the JSON.
106   */
107  void throwFacebookResponseStatusExceptionIfNecessary(String json, Integer httpStatusCode);
108
109  /**
110   * If the {@code error} and {@code error_description} JSON fields are present, we've got a response status error for
111   * this batch API call. Extracts relevant information from the JSON and throws an exception which encapsulates it for
112   * end-user consumption.
113   *
114   * @param json
115   *          The JSON returned by Facebook in response to a batch API call.
116   * @param httpStatusCode
117   *          The HTTP status code returned by the server, e.g. 500.
118   * @throws FacebookResponseStatusException
119   *           If the JSON contains an error code.
120   * @throws FacebookJsonMappingException
121   *           If an error occurs while processing the JSON.
122   * @since 1.6.5
123   */
124  void throwBatchFacebookResponseStatusExceptionIfNecessary(String json, Integer httpStatusCode);
125}