001/**
002 * Copyright (c) 2010-2019 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;
023
024import static com.restfb.util.StringUtils.isBlank;
025import static com.restfb.util.StringUtils.trimToEmpty;
026import static java.lang.String.format;
027
028import java.io.IOException;
029import java.util.List;
030
031/**
032 * Specifies how a class that sends {@code HTTP} requests to the Facebook API endpoint must operate.
033 * 
034 * @author <a href="http://restfb.com">Mark Allen</a>
035 */
036public interface WebRequestor {
037  /**
038   * Encapsulates an HTTP response body and status code.
039   * 
040   * @author <a href="http://restfb.com">Mark Allen</a>
041   */
042  class Response {
043    /**
044     * HTTP response status code (e.g. 200).
045     */
046    private Integer statusCode;
047
048    /**
049     * HTTP response body as text.
050     */
051    private String body;
052
053    /**
054     * Creates a response with the given HTTP status code and response body as text.
055     * 
056     * @param statusCode
057     *          The HTTP status code of the response.
058     * @param body
059     *          The response body as text.
060     */
061    public Response(Integer statusCode, String body) {
062      this.statusCode = statusCode;
063      this.body = trimToEmpty(body);
064    }
065
066    /**
067     * Gets the HTTP status code.
068     * 
069     * @return The HTTP status code.
070     */
071    public Integer getStatusCode() {
072      return statusCode;
073    }
074
075    /**
076     * Gets the HTTP response body as text.
077     * 
078     * @return The HTTP response body as text.
079     */
080    public String getBody() {
081      return body;
082    }
083
084    /**
085     * @see java.lang.Object#toString()
086     */
087    @Override
088    public String toString() {
089      if (isBlank(getBody())) {
090        return format("HTTP status code %d and an empty response body.", getStatusCode());
091      }
092      return format("HTTP status code %d and response body: %s", getStatusCode(), getBody());
093    }
094  }
095
096  /**
097   * Given a Facebook API endpoint URL, execute a {@code GET} against it.
098   * 
099   * @param url
100   *          The URL to make a {@code GET} request for, including URL parameters.
101   * @return HTTP response data.
102   * @throws IOException
103   *           If an error occurs while performing the {@code GET} operation.
104   * @since 1.5
105   */
106  Response executeGet(String url) throws IOException;
107
108  /**
109   * Given a Facebook API endpoint URL and parameter string, execute a {@code POST} to the endpoint URL.
110   * 
111   * @param url
112   *          The URL to {@code POST} to.
113   * @param parameters
114   *          The parameters to be {@code POST}ed.
115   * @return HTTP response data.
116   * @throws IOException
117   *           If an error occurs while performing the {@code POST}.
118   */
119  Response executePost(String url, String parameters) throws IOException;
120
121  /**
122   * Given a Facebook API endpoint URL and parameter string, execute a {@code POST} to the endpoint URL.
123   * 
124   * @param url
125   *          The URL to {@code POST} to.
126   * @param parameters
127   *          The parameters to be {@code POST}ed.
128   * @param binaryAttachments
129   *          Optional binary attachments to be included in the {@code POST} body (e.g. photos and videos).
130   * @return HTTP response data.
131   * @throws IOException
132   *           If an error occurs while performing the {@code POST}.
133   */
134  Response executePost(String url, String parameters, List<BinaryAttachment> binaryAttachments) throws IOException;
135
136  /**
137   * Given a Facebook API endpoint URL and parameter string, execute a {@code DELETE} to the endpoint URL.
138   * 
139   * @param url
140   *          The URL to submit the {@code DELETE} to.
141   * @return HTTP response data.
142   * @throws IOException
143   *           If an error occurs while performing the {@code DELETE}.
144   */
145  Response executeDelete(String url) throws IOException;
146
147  /**
148   * Provides access to the facebook header information.
149   * 
150   * The fields <code>x-fb-rev</code>, <code>x-fb-trace-id</code> and <code>x-fb-debug</code> are checked and returned
151   * in a single container of the type {@link DebugHeaderInfo}
152   * 
153   * @return container with the explained facebook debug header information
154   */
155  DebugHeaderInfo getDebugHeaderInfo();
156}