com.facebook.api.FacebookRestClient Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of facebook-java-api Show documentation
Facebook Java Library
There is a newer version: 2.0.0
/*
 +---------------------------------------------------------------------------+
 | Facebook Development Platform Java Client                                 |
 +---------------------------------------------------------------------------+
 | Copyright (c) 2007 Facebook, Inc.                                         |
 | All rights reserved.                                                      |
 |                                                                           |
 | Redistribution and use in source and binary forms, with or without        |
 | modification, are permitted provided that the following conditions        |
 | are met:                                                                  |
 |                                                                           |
 | 1. Redistributions of source code must retain the above copyright         |
 |    notice, this list of conditions and the following disclaimer.          |
 | 2. Redistributions in binary form must reproduce the above copyright      |
 |    notice, this list of conditions and the following disclaimer in the    |
 |    documentation and/or other materials provided with the distribution.   |
 |                                                                           |
 | THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR      |
 | IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
 | OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.   |
 | IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,          |
 | INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT  |
 | NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
 | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY     |
 | THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT       |
 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF  |
 | THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.         |
 +---------------------------------------------------------------------------+
 | For help with this library, contact [email protected]          |
 +---------------------------------------------------------------------------+
 */

package com.facebook.api;

import java.io.BufferedInputStream;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.DataOutputStream;
import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.UnsupportedEncodingException;
import java.lang.reflect.Method;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.ProtocolException;
import java.net.URL;
import java.net.URLConnection;
import java.net.URLEncoder;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Date;
import java.util.EnumSet;
import java.util.HashMap;
import java.util.Iterator;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;

import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBException;
import javax.xml.bind.Unmarshaller;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.ParserConfigurationException;

import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;
import org.w3c.dom.Document;
import org.w3c.dom.Node;
import org.w3c.dom.NodeList;
import org.xml.sax.SAXException;

import com.facebook.api.schema.FriendsGetResponse;
import com.facebook.api.schema.Listing;
import com.facebook.api.schema.MarketplaceGetCategoriesResponse;
import com.facebook.api.schema.MarketplaceGetListingsResponse;
import com.facebook.api.schema.MarketplaceGetSubCategoriesResponse;
import com.facebook.api.schema.MarketplaceSearchResponse;

/**
 * A FacebookRestClient that uses the XML result format. This means results from calls to the Facebook API are returned as XML and transformed into instances of Document.
 * 
 * Allocate an instance of this class to make Facebook API requests.
 */
public class FacebookRestClient implements IFacebookRestClient {

	/**
	 * API version to request when making calls to the server
	 */
	public static final String TARGET_API_VERSION = "1.0";
	/**
	 * Flag indicating an erroneous response
	 */
	public static final String ERROR_TAG = "error_response";
	/**
	 * Facebook API server, part 1
	 */
	public static final String FB_SERVER = "api.facebook.com/restserver.php";
	/**
	 * Facebook API server, part 2a
	 */
	public static final String SERVER_ADDR = "http://" + FB_SERVER;
	/**
	 * Facebook API server, part 2b
	 */
	public static final String HTTPS_SERVER_ADDR = "https://" + FB_SERVER;
	/**
	 * Facebook API server, part 3a
	 */
	public static URL SERVER_URL = null;
	/**
	 * Facebook API server, part 3b
	 */
	public static URL HTTPS_SERVER_URL = null;
	protected static JAXBContext JAXB_CONTEXT;
	static {
		try {
			JAXB_CONTEXT = JAXBContext.newInstance( "com.facebook.api.schema" );
			SERVER_URL = new URL( SERVER_ADDR );
			HTTPS_SERVER_URL = new URL( HTTPS_SERVER_ADDR );
		}
		catch ( MalformedURLException e ) {
			System.err.println( "MalformedURLException: " + e.getMessage() );
			System.exit( 1 );
		}
		catch ( JAXBException e ) {
			JAXB_CONTEXT = null;
			System.err.println( "Could not get JAXB context:  " + e.getMessage() );
			e.printStackTrace();
		}
	}

	// used so that executeBatch can return the correct types in its list, without killing efficiency.
	private static final Map RETURN_TYPES;
	static {
		RETURN_TYPES = new HashMap();
		Method[] candidates = FacebookRestClient.class.getMethods();
		// this loop is inefficient, but it only executes once per JVM, so it doesn't really matter
		for ( FacebookMethod method : EnumSet.allOf( FacebookMethod.class ) ) {
			String name = method.methodName();
			name = name.substring( name.indexOf( "." ) + 1 );
			name = name.replace( ".", "_" );
			for ( Method candidate : candidates ) {
				if ( candidate.getName().equalsIgnoreCase( name ) ) {
					String typeName = candidate.getReturnType().getName().toLowerCase();
					// possible types are Document, String, Boolean, Integer, Long, void
					if ( typeName.indexOf( "document" ) != -1 ) {
						RETURN_TYPES.put( method, "default" );
					} else if ( typeName.indexOf( "string" ) != -1 ) {
						RETURN_TYPES.put( method, "string" );
					} else if ( typeName.indexOf( "bool" ) != -1 ) {
						RETURN_TYPES.put( method, "bool" );
					} else if ( typeName.indexOf( "long" ) != -1 ) {
						RETURN_TYPES.put( method, "long" );
					} else if ( typeName.indexOf( "int" ) != -1 ) {
						RETURN_TYPES.put( method, "int" );
					} else if ( ( typeName.indexOf( "applicationpropertyset" ) != -1 ) || ( typeName.indexOf( "list" ) != -1 ) || ( typeName.indexOf( "url" ) != -1 )
							|| ( typeName.indexOf( "map" ) != -1 ) || ( typeName.indexOf( "object" ) != -1 ) ) {
						// we don't autobox these for now, the user can parse them on their own
						RETURN_TYPES.put( method, "default" );
					} else {
						RETURN_TYPES.put( method, "void" );
					}
					break;
				}
			}
		}
	}

	protected final String _secret;
	protected final String _apiKey;
	protected URL _serverUrl;
	protected String rawResponse;
	protected boolean namespaceAware = true;

	protected String _sessionKey; // filled in when session is established
	protected Long _expires; // also filled in when session is established
	protected boolean _isDesktop = false;
	protected String _sessionSecret; // only used for desktop apps
	protected long _userId;
	protected int _timeout;
	protected int _readTimeout;
	protected boolean batchMode;
	protected List queries;

	protected String permissionsApiKey = null;

	protected List friendsList; // to save making the friends.get api call, this will get prepopulated on canvas pages
	public Boolean added; // to save making the users.isAppAdded api call, this will get prepopulated on canvas pages


	/**
	 * number of params that the client automatically appends to every API call
	 */
	public static int NUM_AUTOAPPENDED_PARAMS = 6;
	protected static boolean DEBUG = false;
	protected Boolean _debug = null;

	protected File _uploadFile = null;
	protected static final String CRLF = "\r\n";
	protected static final String PREF = "--";
	protected static final int UPLOAD_BUFFER_SIZE = 512;

	public static final String MARKETPLACE_STATUS_DEFAULT = "DEFAULT";
	public static final String MARKETPLACE_STATUS_NOT_SUCCESS = "NOT_SUCCESS";
	public static final String MARKETPLACE_STATUS_SUCCESS = "SUCCESS";

	/**
	 * Constructor
	 * 
	 * @param apiKey
	 *            the developer's API key
	 * @param secret
	 *            the developer's secret key
	 */
	public FacebookRestClient( String apiKey, String secret ) {
		this( SERVER_URL, apiKey, secret, null );
	}

	/**
	 * Constructor
	 * 
	 * @param apiKey
	 *            the developer's API key
	 * @param secret
	 *            the developer's secret key
	 * @param connectionTimeout
	 *            the connection timeout to apply when making API requests to Facebook, in milliseconds
	 */
	public FacebookRestClient( String apiKey, String secret, int connectionTimeout ) {
		this( SERVER_URL, apiKey, secret, null, connectionTimeout );
	}

	/**
	 * Constructor
	 * 
	 * @param apiKey
	 *            the developer's API key
	 * @param secret
	 *            the developer's secret key
	 * @param sessionKey
	 *            the session-id to use
	 */
	public FacebookRestClient( String apiKey, String secret, String sessionKey ) {
		this( SERVER_URL, apiKey, secret, sessionKey );
	}

	/**
	 * Constructor
	 * 
	 * @param apiKey
	 *            the developer's API key
	 * @param secret
	 *            the developer's secret key
	 * @param sessionKey
	 *            the session-id to use
	 * @param connectionTimeout
	 *            the connection timeout to apply when making API requests to Facebook, in milliseconds
	 */
	public FacebookRestClient( String apiKey, String secret, String sessionKey, int connectionTimeout ) {
		this( SERVER_URL, apiKey, secret, sessionKey, connectionTimeout );
	}

	/**
	 * Constructor
	 * 
	 * @param serverAddr
	 *            the URL of the Facebook API server to use, allows overriding of the default API server.
	 * @param apiKey
	 *            the developer's API key
	 * @param secret
	 *            the developer's secret key
	 * @param sessionKey
	 *            the session-id to use
	 * 
	 * @throws MalformedURLException
	 *             if the specified serverAddr is invalid
	 */
	public FacebookRestClient( String serverAddr, String apiKey, String secret, String sessionKey ) throws MalformedURLException {
		this( new URL( serverAddr ), apiKey, secret, sessionKey );
	}

	/**
	 * Constructor
	 * 
	 * @param serverAddr
	 *            the URL of the Facebook API server to use, allows overriding of the default API server.
	 * @param apiKey
	 *            the developer's API key
	 * @param secret
	 *            the developer's secret key
	 * @param sessionKey
	 *            the session-id to use
	 * @param connectionTimeout
	 *            the connection timeout to apply when making API requests to Facebook, in milliseconds
	 * 
	 * @throws MalformedURLException
	 *             if the specified serverAddr is invalid
	 */
	public FacebookRestClient( String serverAddr, String apiKey, String secret, String sessionKey, int connectionTimeout ) throws MalformedURLException {
		this( new URL( serverAddr ), apiKey, secret, sessionKey, connectionTimeout );
	}

	/**
	 * Constructor
	 * 
	 * @param serverUrl
	 *            the URL of the Facebook API server to use, allows overriding of the default API server.
	 * @param apiKey
	 *            the developer's API key
	 * @param secret
	 *            the developer's secret key
	 * @param sessionKey
	 *            the session-id to use
	 */
	public FacebookRestClient( URL serverUrl, String apiKey, String secret, String sessionKey ) {
		_sessionKey = sessionKey;
		_apiKey = apiKey;
		_secret = secret;
		_serverUrl = ( null != serverUrl ) ? serverUrl : SERVER_URL;
		_timeout = -1;
		_readTimeout = -1;
		_userId = -1;
		batchMode = false;
		queries = new ArrayList();
	}

	public boolean isNamespaceAware() {
		return namespaceAware;
	}

	public void setNamespaceAware( boolean v ) {
		this.namespaceAware = v;
	}

	public void beginPermissionsMode( String apiKey ) {
		this.permissionsApiKey = apiKey;
	}

	public void endPermissionsMode() {
		this.permissionsApiKey = null;
	}

	public JAXBContext getJaxbContext() {
		return JAXB_CONTEXT;
	}

	public void setJaxbContext( JAXBContext context ) {
		JAXB_CONTEXT = context;
	}

	/**
	 * Return the object's session-key property. This method does not call the Facebook API server.
	 * 
	 * @return the session-key stored in the API client.
	 */
	public String _getSessionKey() {
		return _sessionKey;
	}

	/**
	 * Set/override the session-key used by the client.
	 * 
	 * @param key
	 *            the new key to use.
	 */
	public void _setSessionKey( String key ) {
		_sessionKey = key;
	}

	/**
	 * Return the object's 'expires' property. This method does not call the Facebook API server.
	 * 
	 * @return the expiration value stored in the API client.
	 */
	public Long _getExpires() {
		return _expires;
	}

	/**
	 * Set/override the session expiration timestamp used by the client.
	 * 
	 * @param _expires
	 *            the new timestamp to use.
	 */
	public void _setExpires( Long _expires ) {
		this._expires = _expires;
	}

	/**
	 * Return the object's user-id property. This method does not call the Facebook API server.
	 * 
	 * @return the user-id stored in the API client.
	 */
	public long _getUserId() {
		return _userId;
	}

	/**
	 * Set/override the user-id stored in the client.
	 * 
	 * @param id
	 *            the new user-id to use.
	 */
	public void _setUserId( long id ) {
		_userId = id;
	}

	/**
	 * Return the object's 'friendsList' property. This method does not call the Facebook API server.
	 * 
	 * @return the friends-list stored in the API client.
	 */
	public List _getFriendsList() {
		return friendsList;
	}

	/**
	 * Set/override the list of friends stored in the client.
	 * 
	 * @param friendsList
	 *            the new list to use.
	 */
	public void _setFriendsList( List friendsList ) {
		this.friendsList = friendsList;
	}

	/**
	 * Constructor
	 * 
	 * @param serverUrl
	 *            the URL of the Facebook API server to use, allows overriding of the default API server.
	 * @param apiKey
	 *            the developer's API key
	 * @param secret
	 *            the developer's secret key
	 * @param sessionKey
	 *            the session-id to use
	 * @param connectionTimeout
	 *            the connection timeout to apply when making API requests to Facebook, in milliseconds
	 */
	public FacebookRestClient( URL serverUrl, String apiKey, String secret, String sessionKey, int connectionTimeout ) {
		this( serverUrl, apiKey, secret, sessionKey, connectionTimeout, -1 );
		_timeout = connectionTimeout;
	}

	/**
	 * Constructor
	 * 
	 * @param serverUrl
	 *            the URL of the Facebook API server to use, allows overriding of the default API server.
	 * @param apiKey
	 *            the developer's API key
	 * @param secret
	 *            the developer's secret key
	 * @param sessionKey
	 *            the session-id to use
	 * @param connectionTimeout
	 *            the connection timeout to apply when making API requests to Facebook, in milliseconds
	 * @param readTimeout
	 *            the read timeout to apply when making API requests to Facebook, in milliseconds
	 */
	public FacebookRestClient( URL serverUrl, String apiKey, String secret, String sessionKey, int connectionTimeout, int readTimeout ) {
		this( serverUrl, apiKey, secret, sessionKey );
		_timeout = connectionTimeout;
		_readTimeout = readTimeout;
	}

	/**
	 * The response format in which results to FacebookMethod calls are returned
	 * 
	 * @return the format: either XML, JSON, or null (API default)
	 */
	public String getResponseFormat() {
		return "xml";
	}

	/**
	 * Set global debugging on.
	 * 
	 * @param isDebug
	 *            true to enable debugging false to disable debugging
	 */
	public static void setDebugAll( boolean isDebug ) {
		FacebookRestClient.DEBUG = isDebug;
	}

	/**
	 * Set debugging on for this instance only.
	 * 
	 * @param isDebug
	 *            true to enable debugging false to disable debugging
	 */
	// FIXME: do we really need both of these?
	public void setDebug( boolean isDebug ) {
		_debug = isDebug;
	}

	/**
	 * Check to see if debug mode is enabled.
	 * 
	 * @return true if debugging is enabled false otherwise
	 */
	public boolean isDebug() {
		return ( null == _debug ) ? FacebookRestClient.DEBUG : _debug.booleanValue();
	}

	/**
	 * Check to see if the client is running in desktop mode.
	 * 
	 * @return true if the client is running in desktop mode false otherwise
	 */
	public boolean isDesktop() {
		return this._isDesktop;
	}

	/**
	 * Enable/disable desktop mode.
	 * 
	 * @param isDesktop
	 *            true to enable desktop application mode false to disable desktop application mode
	 */
	public void setIsDesktop( boolean isDesktop ) {
		this._isDesktop = isDesktop;
	}

	/**
	 * Prints out the DOM tree.
	 * 
	 * @param n
	 *            the parent node to start printing from
	 * @param prefix
	 *            string to append to output, should not be null
	 */
	public void printDom( Node n, String prefix ) {
		if ( !isDebug() ) {
			return;
		}
		String outString = prefix;
		if ( n.getNodeType() == Node.TEXT_NODE ) {
			outString += "'" + n.getTextContent().trim() + "'";
		} else {
			outString += n.getNodeName();
		}
		System.out.println( outString );
		NodeList children = n.getChildNodes();
		int length = children.getLength();
		for ( int i = 0; i < length; i++ ) {
			printDom( children.item( i ), prefix + "  " );
		}
	}

	private static CharSequence delimit( Collection iterable ) {
		// could add a thread-safe version that uses StringBuffer as well
		if ( iterable == null || iterable.isEmpty() ) {
			return null;
		}
		StringBuilder buffer = new StringBuilder();
		boolean notFirst = false;
		for ( Object item : iterable ) {
			if ( notFirst ) {
				buffer.append( "," );
			} else {
				notFirst = true;
			}
			buffer.append( item.toString() );
		}
		return buffer;
	}

	protected static CharSequence delimit( Collection> entries, CharSequence delimiter, CharSequence equals, boolean doEncode ) {
		if ( entries == null || entries.isEmpty() ) {
			return null;
		}
		StringBuilder buffer = new StringBuilder();
		boolean notFirst = false;
		for ( Map.Entry entry : entries ) {
			if ( notFirst ) {
				buffer.append( delimiter );
			} else {
				notFirst = true;
			}
			CharSequence value = entry.getValue();
			buffer.append( entry.getKey() ).append( equals ).append( doEncode ? encode( value ) : value );
		}
		return buffer;
	}

	/**
	 * Call the specified method, with the given parameters, and return a DOM tree with the results.
	 * 
	 * @param method
	 *            the fieldName of the method
	 * @param paramPairs
	 *            a list of arguments to the method
	 * @throws Exception
	 *             with a description of any errors given to us by the server.
	 */
	protected Document callMethod( IFacebookMethod method, Pair... paramPairs ) throws FacebookException, IOException {
		return callMethod( method, Arrays.asList( paramPairs ) );
	}

	/**
	 * Starts a batch of queries. Any API calls made after invoking 'beginBatch' will be deferred until the next time you call 'executeBatch', at which time they will be
	 * processed as a batch query. All API calls made in the interim will return null as their result.
	 */
	public void beginBatch() {
		this.batchMode = true;
		this.queries = new ArrayList();
	}

	/**
	 * Executes a batch of queries. You define the queries to execute by calling 'beginBatch' and then invoking the desired API methods that you want to execute as part
	 * of your batch as normal. Invoking this method will then execute the API calls you made in the interim as a single batch query.
	 * 
	 * @param serial
	 *            set to true, and your batch queries will always execute serially, in the same order in which your specified them. If set to false, the Facebook API
	 *            server may execute your queries in parallel and/or out of order in order to improve performance.
	 * 
	 * @return a list containing the results of the batch execution. The list will be ordered such that the first element corresponds to the result of the first query in
	 *         the batch, and the second element corresponds to the result of the second query, and so on. The types of the objects in the list will match the type
	 *         normally returned by the API call being invoked (so calling users_getLoggedInUser as part of a batch will place a Long in the list, and calling friends_get
	 *         will place a Document in the list, etc.).
	 * 
	 * The list may be empty, it will never be null.
	 * 
	 * @throws FacebookException
	 * @throws IOException
	 */
	public List executeBatch( boolean serial ) throws FacebookException, IOException {
		this.batchMode = false;
		List