FileDocCategorySizeDatePackage
ExtensibleClient.javaAPI DocGoogle Facebook API v1.589499Sun Nov 11 17:07:02 GMT 2007com.facebook.api

ExtensibleClient

public abstract class ExtensibleClient extends Object implements IFacebookRestClient
Base class for interacting with the Facebook Application Programming Interface (API). Most Facebook API methods map directly to function calls of this class.
Instances of FacebookRestClient should be initialized via calls to {@link #auth_createToken}, followed by {@link #auth_getSession}.
For continually updated documentation, please refer to the Developer Wiki.

Fields Summary
public static URL
SERVER_URL
public static URL
HTTPS_SERVER_URL
protected final String
_secret
protected final String
_apiKey
protected final URL
_serverUrl
protected String
rawResponse
protected String
_sessionKey
protected boolean
_isDesktop
protected long
_userId
protected String
_sessionSecret
filled in when session is established only used for desktop apps
public static int
NUM_AUTOAPPENDED_PARAMS
The number of parameters required for every request.
private static boolean
DEBUG
protected Boolean
_debug
protected File
_uploadFile
protected static final String
CRLF
protected static final String
PREF
protected static final int
UPLOAD_BUFFER_SIZE
public static final String
MARKETPLACE_STATUS_DEFAULT
public static final String
MARKETPLACE_STATUS_NOT_SUCCESS
public static final String
MARKETPLACE_STATUS_SUCCESS
Constructors Summary
protected ExtensibleClient(URL serverUrl, String apiKey, String secret, String sessionKey)



           
    _sessionKey = sessionKey;
    _apiKey = apiKey;
    _secret = secret;
    _serverUrl = (null != serverUrl) ? serverUrl : SERVER_URL;
Methods Summary
public java.lang.Stringauth_createToken()
Call this function and store the result, using it to generate the appropriate login url and then to retrieve the session information.

return
an authentication token

    T d = this.callMethod(FacebookMethod.AUTH_CREATE_TOKEN);
    return extractString(d);
public abstract java.lang.Stringauth_getSession(java.lang.String authToken)
Call this function to retrieve the session information after your user has logged in.

param
authToken the token returned by auth_createToken or passed back to your callback_url.

public longauth_getUserId(java.lang.String authToken)
Call this function to get the user ID.
return
The ID of the current session's user, or -1 if none.
    /*
     * Get the session information if we don't have it; this will populate
       * the user ID as well.
       */
    if (null == this._sessionKey)
      auth_getSession(authToken);
    return this._userId;
  
protected TcallMethod(com.facebook.api.IFacebookMethod method, com.facebook.api.Pair paramPairs)
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.
    return callMethod(method, Arrays.asList(paramPairs));
  
protected TcallMethod(com.facebook.api.IFacebookMethod method, java.util.Collection paramPairs)
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.
    this.rawResponse = null;
    HashMap<String, CharSequence> params =
      new HashMap<String, CharSequence>(2 * method.numTotalParams());

    params.put("method", method.methodName());
    params.put("api_key", _apiKey);
    params.put("v", TARGET_API_VERSION);
    
    String format = getResponseFormat();
    if (null != format) {
      params.put("format", format);
    }
    
    if (method.requiresSession()) {
      params.put("call_id", Long.toString(System.currentTimeMillis()));
      params.put("session_key", _sessionKey);
    }
    CharSequence oldVal;
    for (Pair<String, CharSequence> p : paramPairs) {
      oldVal = params.put(p.first, p.second);
      if (oldVal != null)
        System.err.printf("For parameter %s, overwrote old value %s with new value %s.", p.first,
                          oldVal, p.second);
    }

    assert (!params.containsKey("sig"));
    String signature =
      generateSignature(FacebookSignatureUtil.convert(params.entrySet()), method.requiresSession());
    params.put("sig", signature);

    boolean doHttps = this.isDesktop() && FacebookMethod.AUTH_GET_SESSION.equals(method);
    InputStream data =
      method.takesFile() ? postFileRequest(method.methodName(), params) : postRequest(method.methodName(),
                                                                                      params,
                                                                                      doHttps,
                                                                                      true);
    BufferedReader in = new BufferedReader(new InputStreamReader(data, "UTF-8"));
    StringBuffer buffer = new StringBuffer();
    String line;
    while ((line = in.readLine()) != null) {
      buffer.append(line);
    }
     
    String xmlResp = new String(buffer);
    this.rawResponse = xmlResp;
      
    return parseCallResult(new ByteArrayInputStream(xmlResp.getBytes("UTF-8")), method);
  
private static java.lang.CharSequencedelimit(java.util.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 java.lang.CharSequencedelimit(java.util.Collection entries, java.lang.CharSequence delimiter, java.lang.CharSequence equals, boolean doEncode)
    if (entries == null || entries.isEmpty())
      return null;

    StringBuilder buffer = new StringBuilder();
    boolean notFirst = false;
    for (Map.Entry<String, CharSequence> 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;
  
private static java.lang.Stringencode(java.lang.CharSequence target)
    if (target == null) {
        return "";
    }
    String result = target.toString();
    try {
      result = URLEncoder.encode(result, "UTF8");
    } catch (UnsupportedEncodingException e) {
      System.err.printf("Unsuccessful attempt to encode '%s' into UTF8", result);
    }
    return result;
  
public Tevents_get(java.lang.Long userId, java.util.Collection eventIds, java.lang.Long startTime, java.lang.Long endTime)
Returns all visible events according to the filters specified. This may be used to find all events of a user, or to query specific eids.
param
eventIds filter by these event ID's (optional)
param
userId filter by this user only (optional)
param
startTime UTC lower bound (optional)
param
endTime UTC upper bound (optional)
return
T of events
    ArrayList<Pair<String, CharSequence>> params =
      new ArrayList<Pair<String, CharSequence>>(FacebookMethod.EVENTS_GET.numParams());

    boolean hasUserId = null != userId && 0 != userId;
    boolean hasEventIds = null != eventIds && !eventIds.isEmpty();
    boolean hasStart = null != startTime && 0 != startTime;
    boolean hasEnd = null != endTime && 0 != endTime;

    if (hasUserId)
      params.add(new Pair<String, CharSequence>("uid", Long.toString(userId)));
    if (hasEventIds)
      params.add(new Pair<String, CharSequence>("eids", delimit(eventIds)));
    if (hasStart)
      params.add(new Pair<String, CharSequence>("start_time", startTime.toString()));
    if (hasEnd)
      params.add(new Pair<String, CharSequence>("end_time", endTime.toString()));
    return this.callMethod(FacebookMethod.EVENTS_GET, params);
  
public Tevents_getMembers(java.lang.Number eventId)
Retrieves the membership list of an event
param
eventId event id
return
T consisting of four membership lists corresponding to RSVP status, with keys
'attending', 'unsure', 'declined', and 'not_replied'
    assert (null != eventId);
    return this.callMethod(FacebookMethod.EVENTS_GET_MEMBERS,
                           new Pair<String, CharSequence>("eid", eventId.toString()));
  
protected booleanextractBoolean(T result)
Extracts a Boolean from a result that consists of a Boolean only.
param
result
return
the Boolean
    return 1 == extractInt(result);
  
protected abstract intextractInt(T result)
Extracts an Long from a result that consists of an Long only.
param
result
return
the Long
protected abstract java.lang.LongextractLong(T result)
Extracts an Long from a result that consists of a Long only.
param
result
return
the Long
protected abstract java.lang.StringextractString(T result)
Extracts a String from a T consisting entirely of a String.
param
result
return
the String
protected abstract java.net.URLextractURL(T result)
Extracts a URL from a result that consists of a URL only.
param
result
return
the URL
public booleanfbml_refreshImgSrc(java.lang.String imageUrl)
Recaches the image with the specified imageUrl.
param
imageUrl String representing the image URL to refresh
return
boolean indicating whether the refresh succeeded
    return fbml_refreshImgSrc(new URL(imageUrl));
  
public booleanfbml_refreshImgSrc(java.net.URL imageUrl)
Recaches the image with the specified imageUrl.
param
imageUrl the image URL to refresh
return
boolean indicating whether the refresh succeeded
    return extractBoolean(this.callMethod(FacebookMethod.FBML_REFRESH_IMG_SRC,
                                          new Pair<String, CharSequence>("url",
                                                                         imageUrl.toString())));
  
public booleanfbml_refreshRefUrl(java.net.URL url)
Recaches the referenced url.
param
url the URL to refresh
return
boolean indicating whether the refresh succeeded
    return extractBoolean(this.callMethod(FacebookMethod.FBML_REFRESH_REF_URL,
                                          new Pair<String, CharSequence>("url", url.toString())));
  
public booleanfbml_refreshRefUrl(java.lang.String url)
Recaches the referenced url.
param
url string representing the URL to refresh
return
boolean indicating whether the refresh succeeded
    return fbml_refreshRefUrl(new URL(url));
  
public booleanfbml_setRefHandle(java.lang.String handle, java.lang.String fbmlMarkup)
Associates a "handle" with FBML markup so that the handle can be used within the
fb:ref FBML tag.
A handle is unique within an application and allows an application to publish identical FBML
to many user profiles and do subsequent updates without having to republish FBML for each user.
param
handle - a string, unique within the application, that
param
fbmlMarkup - refer to the FBML documentation for a description of the markup and its role in various contexts
return
a boolean indicating whether the FBML was successfully set
see

Developers Wiki: Fbml.setRefHandle

    return extractBoolean(this.callMethod(FacebookMethod.FBML_SET_REF_HANDLE,
                                          new Pair<String, CharSequence>("handle", handle),
                                          new Pair<String, CharSequence>("fbml", fbmlMarkup)));

  
protected booleanfeedHandler(com.facebook.api.IFacebookMethod feedMethod, java.lang.CharSequence title, java.lang.CharSequence body, java.util.Collection images, java.lang.Integer priority)
Helper function: assembles the parameters used by feed_publishActionOfUser and
feed_publishStoryToUser
param
feedMethod feed_publishStoryToUser / feed_publishActionOfUser
param
title title of the story
param
body body of the story
param
images optional images to be included in he story
param
priority
return
whether the call to feedMethod was successful
    ArrayList<Pair<String, CharSequence>> params =
      new ArrayList<Pair<String, CharSequence>>(feedMethod.numParams());

    params.add(new Pair<String, CharSequence>("title", title));
    if (null != body)
      params.add(new Pair<String, CharSequence>("body", body));
    if (null != priority)
      params.add(new Pair<String, CharSequence>("priority", priority.toString()));

    handleFeedImages(params, images);

    return extractBoolean(this.callMethod(feedMethod, params));
  
public booleanfeed_PublishTemplatizedAction(com.facebook.api.TemplatizedAction action)
      return this.templatizedFeedHandler(FacebookMethod.FEED_PUBLISH_TEMPLATIZED_ACTION, action.getTitleTemplate(), action.getTitleParams(), 
              action.getBodyTemplate(), action.getBodyParams(), action.getBodyGeneral(), action.getPictures(), action.getTargetIds());
  
public booleanfeed_publishActionOfUser(java.lang.CharSequence title, java.lang.CharSequence body)
Publish the notification of an action taken by a user to newsfeed.
param
title the title of the feed story (up to 60 characters, excluding tags)
param
body (optional) the body of the feed story (up to 200 characters, excluding tags)
return
whether the story was successfully published; false in case of permission error
see

Developers Wiki: Feed.publishActionOfUser
    return feed_publishActionOfUser(title, body, null);
  
public booleanfeed_publishActionOfUser(java.lang.CharSequence title, java.lang.CharSequence body, java.util.Collection images)
Publish the notification of an action taken by a user to newsfeed.
param
title the title of the feed story (up to 60 characters, excluding tags)
param
body (optional) the body of the feed story (up to 200 characters, excluding tags)
param
images (optional) up to four pairs of image URLs and (possibly null) link URLs
return
whether the story was successfully published; false in case of permission error
see

Developers Wiki: Feed.publishActionOfUser
    return feedHandler(FacebookMethod.FEED_PUBLISH_ACTION_OF_USER, title, body, images, null);
  
public booleanfeed_publishStoryToUser(java.lang.CharSequence title, java.lang.CharSequence body)
Publish a story to the logged-in user's newsfeed.
param
title the title of the feed story
param
body the body of the feed story
return
whether the story was successfully published; false in case of permission error
see

Developers Wiki: Feed.publishStoryToUser
    return feed_publishStoryToUser(title, body, null, null);
  
public booleanfeed_publishStoryToUser(java.lang.CharSequence title, java.lang.CharSequence body, java.util.Collection images)
Publish a story to the logged-in user's newsfeed.
param
title the title of the feed story
param
body the body of the feed story
param
images (optional) up to four pairs of image URLs and (possibly null) link URLs
return
whether the story was successfully published; false in case of permission error
see

Developers Wiki: Feed.publishStoryToUser
    return feed_publishStoryToUser(title, body, images, null);
  
public booleanfeed_publishStoryToUser(java.lang.CharSequence title, java.lang.CharSequence body, java.lang.Integer priority)
Publish a story to the logged-in user's newsfeed.
param
title the title of the feed story
param
body the body of the feed story
param
priority
return
whether the story was successfully published; false in case of permission error
see

Developers Wiki: Feed.publishStoryToUser
    return feed_publishStoryToUser(title, body, null, priority);
  
public booleanfeed_publishStoryToUser(java.lang.CharSequence title, java.lang.CharSequence body, java.util.Collection images, java.lang.Integer priority)
Publish a story to the logged-in user's newsfeed.
param
title the title of the feed story
param
body the body of the feed story
param
images (optional) up to four pairs of image URLs and (possibly null) link URLs
param
priority
return
whether the story was successfully published; false in case of permission error
see

Developers Wiki: Feed.publishStoryToUser
    return feedHandler(FacebookMethod.FEED_PUBLISH_STORY_TO_USER, title, body, images, priority);
  
public booleanfeed_publishTemplatizedAction(java.lang.Long actorId, java.lang.CharSequence titleTemplate)
Publishes a Mini-Feed story describing an action taken by a user, and
publishes aggregating News Feed stories to the friends of that user.
Stories are identified as being combinable if they have matching templates and substituted values.
param
actorId the user into whose mini-feed the story is being published.
param
titleTemplate markup (up to 60 chars, tags excluded) for the feed story's title
section. Must include the token {actor}.
return
whether the action story was successfully published; false in case
of a permission error
see

Developers Wiki: Feed.publishTemplatizedAction
    return feed_publishTemplatizedAction(actorId, titleTemplate, null, null, null, null, null, null );    
  
public booleanfeed_publishTemplatizedAction(java.lang.Long actorId, java.lang.CharSequence titleTemplate, java.util.Map titleData, java.lang.CharSequence bodyTemplate, java.util.Map bodyData, java.lang.CharSequence bodyGeneral, java.util.Collection targetIds, java.util.Collection images)
Publishes a Mini-Feed story describing an action taken by a user, and
publishes aggregating News Feed stories to the friends of that user.
Stories are identified as being combinable if they have matching templates and substituted values.
param
actorId the user into whose mini-feed the story is being published.
param
titleTemplate markup (up to 60 chars, tags excluded) for the feed story's title
section. Must include the token {actor}.
param
titleData (optional) contains token-substitution mappings for tokens that appear in
titleTemplate. Should not contain mappings for the {actor} or
{target} tokens. Required if tokens other than {actor}
or {target} appear in the titleTemplate.
param
bodyTemplate (optional) markup to be displayed in the feed story's body section.
can include tokens, of the form {token}, to be substituted using
bodyData.
param
bodyData (optional) contains token-substitution mappings for tokens that appear in
bodyTemplate. Required if the bodyTemplate contains tokens other than {actor}
and {target}.
param
bodyGeneral (optional) additional body markup that is not aggregated. If multiple instances
of this templated story are combined together, the markup in the bodyGeneral of
one of their stories may be displayed.
param
targetIds The user ids of friends of the actor, used for stories about a direct action between
the actor and these targets of his/her action. Required if either the titleTemplate or bodyTemplate
includes the token {target}.
param
images (optional) additional body markup that is not aggregated. If multiple instances
of this templated story are combined together, the markup in the bodyGeneral of
one of their stories may be displayed.
return
whether the action story was successfully published; false in case
of a permission error
see

Developers Wiki: Feed.publishTemplatizedAction
    assert null != actorId && actorId > 0 : "Invalid actorId: " + Long.toString(actorId);
    assert null != titleTemplate && !"".equals(titleTemplate); 
    
    FacebookMethod method = FacebookMethod.FEED_PUBLISH_TEMPLATIZED_ACTION;
    ArrayList<Pair<String, CharSequence>> params =
      new ArrayList<Pair<String, CharSequence>>(method.numParams());
    params.add(new Pair<String, CharSequence>("actor_id", actorId.toString()));

    params.add(new Pair<String, CharSequence>("title_template", titleTemplate));
    if (null != titleData && !titleData.isEmpty()) {
      JSONObject titleDataJson = new JSONObject();
      for (String key : titleData.keySet()) {
          try {
              titleDataJson.put(key, titleData.get(key));
          }
          catch (Exception ignored) {}
      }
      params.add(new Pair<String, CharSequence>("title_data", titleDataJson.toString()));
    }
    
    if (null != bodyTemplate && !"".equals(bodyTemplate)) {
      params.add(new Pair<String, CharSequence>("body_template", bodyTemplate));
      if (null != bodyData && !bodyData.isEmpty()) {
        JSONObject bodyDataJson = new JSONObject();
        for (String key : bodyData.keySet()) {
            try {
                bodyDataJson.put(key, bodyData.get(key));
            }
            catch (Exception ignored) {}
        }
        params.add(new Pair<String, CharSequence>("body_data", bodyDataJson.toString()));
      }
    }

    if (null != bodyTemplate && !"".equals(bodyTemplate)) {
      params.add(new Pair<String, CharSequence>("body_template", bodyTemplate));
    }
    
    if (null != targetIds && !targetIds.isEmpty()) {
      params.add(new Pair<String, CharSequence>("target_ids", delimit(targetIds)));      
    }
    
    handleFeedImages(params, images);

    return extractBoolean(this.callMethod(method, params));
  
public booleanfeed_publishTemplatizedAction(java.lang.Integer actorId, java.lang.CharSequence titleTemplate, java.util.Map titleData, java.lang.CharSequence bodyTemplate, java.util.Map bodyData, java.lang.CharSequence bodyGeneral, java.util.Collection targetIds, java.util.Collection images)
deprecated
Use the version that takes a Long for the actorId paramter.
      return this.feed_publishTemplatizedAction((long)actorId.intValue(), titleTemplate, 
              titleData, bodyTemplate, bodyData, bodyGeneral, targetIds, images);
  
public booleanfeed_publishTemplatizedAction(java.lang.String titleTemplate, java.lang.String titleData, java.lang.String bodyTemplate, java.lang.String bodyData, java.lang.String bodyGeneral, java.util.Collection pictures, java.lang.String targetIds)
      return this.templatizedFeedHandler(FacebookMethod.FEED_PUBLISH_TEMPLATIZED_ACTION, titleTemplate, titleData, 
              bodyTemplate, bodyData, bodyGeneral, pictures, targetIds);
  
public Tfql_query(java.lang.CharSequence query)
Retrieves the results of a Facebook Query Language query
param
query : the FQL query statement
return
varies depending on the FQL query
    assert (null != query);
    return this.callMethod(FacebookMethod.FQL_QUERY,
                           new Pair<String, CharSequence>("query", query));
  
public Tfriends_areFriends(long userId1, long userId2)
Retrieves whether two users are friends.
param
userId1
param
userId2
return
T
see

Developers Wiki: Friends.areFriends
    return this.callMethod(FacebookMethod.FRIENDS_ARE_FRIENDS,
                           new Pair<String, CharSequence>("uids1", Long.toString(userId1)),
                           new Pair<String, CharSequence>("uids2", Long.toString(userId2)));
  
public Tfriends_areFriends(java.util.Collection userIds1, java.util.Collection userIds2)
Retrieves whether pairs of users are friends.
Returns whether the first user in userIds1 is friends with the first user in
userIds2, the second user in userIds1 is friends with the second user in
userIds2, etc.
param
userIds1
param
userIds2
return
T
throws
IllegalArgumentException if one of the collections is null, or empty, or if the
collection sizes differ.
see

Developers Wiki: Friends.areFriends
    if (userIds1 == null || userIds2 == null || userIds1.isEmpty() || userIds2.isEmpty()) {
      throw new IllegalArgumentException("Collections passed to friends_areFriends should not be null or empty");
    }
    if (userIds1.size() != userIds2.size()) {
      throw new IllegalArgumentException(String.format("Collections should be same size: got userIds1: %d elts; userIds2: %d elts",
                                                       userIds1.size(), userIds2.size()));
    }

    return this.callMethod(FacebookMethod.FRIENDS_ARE_FRIENDS,
                           new Pair<String, CharSequence>("uids1", delimit(userIds1)),
                           new Pair<String, CharSequence>("uids2", delimit(userIds2)));
  
public Tfriends_get()
Retrieves the friends of the currently logged in user.
return
array of friends
    return this.callMethod(FacebookMethod.FRIENDS_GET);
  
public Tfriends_getAppUsers()
Retrieves the friends of the currently logged in user, who are also users
of the calling application.
return
array of friends
    return this.callMethod(FacebookMethod.FRIENDS_GET_APP_USERS);
  
private java.lang.StringgenerateSignature(java.util.List params, boolean requiresSession)
    String secret = (isDesktop() && requiresSession) ? this._sessionSecret : this._secret;
    return FacebookSignatureUtil.generateSignature(params, secret);
  
public java.lang.StringgetRawResponse()
      return this.rawResponse;
  
public java.lang.StringgetResponseFormat()
The response format in which results to FacebookMethod calls are returned
return
the format: either XML, JSON, or null (API default)
    return null;
  
public java.lang.ObjectgetResponsePOJO()
      if (this.rawResponse == null) {
          return null;
      }
      if ((this.getResponseFormat() != null) && (! "xml".equals(this.getResponseFormat().toLowerCase()))) {
          //JAXB will not work with JSON
          throw new RuntimeException("You can only generate a response POJO when using XML formatted API responses!  JSON users go elsewhere!");
      }
      JAXBContext jc;
      Object pojo = null;
      try {
          jc = JAXBContext.newInstance("com.facebook.api.schema");
          Unmarshaller unmarshaller = jc.createUnmarshaller();
          pojo =  unmarshaller.unmarshal(new ByteArrayInputStream(this.rawResponse.getBytes("UTF-8")));
      } catch (JAXBException e) {
          System.err.println("getResponsePOJO() - Could not unmarshall XML stream into POJO");
          e.printStackTrace();
      }
      catch (NullPointerException e) {
          System.err.println("getResponsePOJO() - Could not unmarshall XML stream into POJO.");
          e.printStackTrace();
      } catch (UnsupportedEncodingException e) {
          System.err.println("getResponsePOJO() - Could not unmarshall XML stream into POJO.");
          e.printStackTrace();
      }
      return pojo;
  
public Tgroups_get(java.lang.Long userId, java.util.Collection groupIds)
Retrieves the groups associated with a user
param
userId Optional: User associated with groups.
A null parameter will default to the session user.
param
groupIds Optional: group ids to query.
A null parameter will get all groups for the user.
return
array of groups
    boolean hasGroups = (null != groupIds && !groupIds.isEmpty());
    if (null != userId)
      return hasGroups ?
             this.callMethod(FacebookMethod.GROUPS_GET, new Pair<String, CharSequence>("uid",
                                                                                       userId.toString()),
                             new Pair<String, CharSequence>("gids", delimit(groupIds))) :
             this.callMethod(FacebookMethod.GROUPS_GET,
                             new Pair<String, CharSequence>("uid", userId.toString()));
    else
      return hasGroups ?
             this.callMethod(FacebookMethod.GROUPS_GET, new Pair<String, CharSequence>("gids",
                                                                                       delimit(groupIds))) :
             this.callMethod(FacebookMethod.GROUPS_GET);
  
public Tgroups_getMembers(java.lang.Number groupId)
Retrieves the membership list of a group
param
groupId the group id
return
a T containing four membership lists of
'members', 'admins', 'officers', and 'not_replied'
    assert (null != groupId);
    return this.callMethod(FacebookMethod.GROUPS_GET_MEMBERS,
                           new Pair<String, CharSequence>("gid", groupId.toString()));
  
protected voidhandleFeedImages(java.util.List params, java.util.Collection images)
Adds image parameters
param
params
param
images
    if (images != null && images.size() > 4) {
      throw new IllegalArgumentException("At most four images are allowed, got " + Integer.toString(images.size()));
    }
    if (null != images && !images.isEmpty()) {
      int image_count = 0;
      for (IPair image : images) {
        ++image_count;
        assert null != image.getFirst() : "Image URL must be provided";
        params.add(new Pair<String, CharSequence>(String.format("image_%d", image_count),
                                                  image.getFirst().toString()));
        if (null != image.getSecond())
          params.add(new Pair<String, CharSequence>(String.format("image_%d_link", image_count),
                                                    image.getSecond().toString()));
      }
    }
  
public booleanisDebug()
return
whether debugging is activated
    return (null == _debug) ? DEBUG : _debug.booleanValue();
  
public booleanisDesktop()
    return this._isDesktop;
  
protected voidlog(java.lang.CharSequence message)
Logs a message. Override this for more detailed logging.
param
message
    System.out.println(message);
  
protected final voidlogException(java.lang.Exception e)
Logs an exception with default message
param
e the exception
    logException("exception", e);
  
protected voidlogException(java.lang.CharSequence msg, java.lang.Exception e)
Logs an exception with an introductory message in addition to the
exception's getMessage().
param
msg message
param
e exception
see
Exception#getMessage
    System.err.println(msg + ":" + e.getMessage());
    e.printStackTrace();
  
public java.lang.Longmarketplace_createListing(java.lang.Long listingId, boolean showOnProfile, com.facebook.api.MarketListing listing)
      return this.marketplace_createListing(listingId, showOnProfile, listing.getAttribs());
  
public java.lang.Longmarketplace_createListing(boolean showOnProfile, com.facebook.api.MarketListing listing)
      return this.marketplace_createListing(null, showOnProfile, listing.getAttribs());
  
public java.lang.Longmarketplace_createListing(java.lang.Boolean showOnProfile, com.facebook.api.MarketplaceListing attrs)
Create a marketplace listing
param
showOnProfile whether the listing can be shown on the user's profile
param
attrs the properties of the listing
return
the id of the created listing
see
MarketplaceListing
see

Developers Wiki: marketplace.createListing
    T result = this.callMethod(FacebookMethod.MARKETPLACE_CREATE_LISTING,
                               new Pair<String, CharSequence>("show_on_profile", showOnProfile ? "1" : "0"),
                               new Pair<String, CharSequence>("listing_id", "0"),
                               new Pair<String, CharSequence>("listing_attrs", attrs.jsonify().toString()));
    return this.extractLong(result);
  
public java.lang.Longmarketplace_createListing(java.lang.Long listingId, boolean showOnProfile, java.lang.String attributes)
      T result = this.callMethod(FacebookMethod.MARKETPLACE_CREATE_LISTING,
              new Pair<String, CharSequence>("show_on_profile", showOnProfile ? "1" : "0"),
              new Pair<String, CharSequence>("listing_id", "0"),
              new Pair<String, CharSequence>("listing_attrs", attributes));
      return this.extractLong(result);
  
public java.lang.Longmarketplace_editListing(java.lang.Long listingId, java.lang.Boolean showOnProfile, com.facebook.api.MarketListing attrs)
      T result = this.callMethod(FacebookMethod.MARKETPLACE_CREATE_LISTING,
              new Pair<String, CharSequence>("show_on_profile", showOnProfile ? "1" : "0"),
              new Pair<String, CharSequence>("listing_id", listingId.toString()),
              new Pair<String, CharSequence>("listing_attrs", attrs.getAttribs()));
      return this.extractLong(result);
  
public java.lang.Longmarketplace_editListing(java.lang.Long listingId, java.lang.Boolean showOnProfile, com.facebook.api.MarketplaceListing attrs)
Modify a marketplace listing
param
listingId identifies the listing to be modified
param
showOnProfile whether the listing can be shown on the user's profile
param
attrs the properties of the listing
return
the id of the edited listing
see
MarketplaceListing
see

Developers Wiki: marketplace.createListing
    T result = this.callMethod(FacebookMethod.MARKETPLACE_CREATE_LISTING,
                               new Pair<String, CharSequence>("show_on_profile", showOnProfile ? "1" : "0"),
                               new Pair<String, CharSequence>("listing_id", listingId.toString()),
                               new Pair<String, CharSequence>("listing_attrs", attrs.jsonify().toString()));
    return this.extractLong(result);
  
public java.util.Listmarketplace_getCategories()
Get the categories available in marketplace.
return
a T listing the marketplace categories
see

Developers Wiki: marketplace.getCategories
    T temp = this.callMethod(FacebookMethod.MARKETPLACE_GET_CATEGORIES);
    List<String> results = new ArrayList<String>();
    if (temp instanceof Document) {
        Document d = (Document)temp;
        NodeList cats = d.getElementsByTagName("marketplace_category");
        for (int count = 0; count < cats.getLength(); count++) {
            results.add(cats.item(count).getFirstChild().getTextContent());
        }
    }
    else {
        JSONObject j = (JSONObject)temp;
        Iterator it = j.keys();
        while (it.hasNext()) {
            try {
                results.add(j.get((String)it.next()).toString());
            }
            catch (Exception ignored) {  }
        }
    }
    return results;
  
public Tmarketplace_getCategoriesObject()
Get the categories available in marketplace.
return
a T listing the marketplace categories
see

Developers Wiki: marketplace.getCategories
    T temp = this.callMethod(FacebookMethod.MARKETPLACE_GET_CATEGORIES);
    return temp;
  
public Tmarketplace_getListings(java.util.Collection listingIds, java.util.Collection userIds)
Fetch marketplace listings, filtered by listing IDs and/or the posting users' IDs.
param
listingIds listing identifiers (required if uids is null/empty)
param
userIds posting user identifiers (required if listingIds is null/empty)
return
a T of marketplace listings
see

Developers Wiki: marketplace.getListings
    
    ArrayList<Pair<String, CharSequence>> params =
      new ArrayList<Pair<String, CharSequence>>(FacebookMethod.MARKETPLACE_GET_LISTINGS.numParams());
    if (null != listingIds && !listingIds.isEmpty()) {
      params.add(new Pair<String, CharSequence>("listing_ids", delimit(listingIds)));
    }
    if (null != userIds && !userIds.isEmpty()) {
      params.add(new Pair<String, CharSequence>("uids", delimit(userIds)));
    }

    assert !params.isEmpty() : "Either listingIds or userIds should be provided";
    return this.callMethod(FacebookMethod.MARKETPLACE_GET_LISTINGS, params);
  
public Tmarketplace_getSubCategories(java.lang.CharSequence category)
Get the subcategories available for a category.
param
category a category, e.g. "HOUSING"
return
a T listing the marketplace sub-categories
see

Developers Wiki: marketplace.getSubCategories
    return this.callMethod(FacebookMethod.MARKETPLACE_GET_SUBCATEGORIES,
                           new Pair<String, CharSequence>("category", category));
  
public booleanmarketplace_removeListing(java.lang.Long listingId, com.facebook.api.MarketListingStatus status)
      return this.marketplace_removeListing(listingId, status.getName());
  
public booleanmarketplace_removeListing(java.lang.Long listingId)
Remove a marketplace listing
param
listingId the listing to be removed
return
boolean indicating whether the listing was removed
see

Developers Wiki: marketplace.removeListing
    return marketplace_removeListing(listingId, MARKETPLACE_STATUS_DEFAULT);
  
public booleanmarketplace_removeListing(java.lang.Long listingId, java.lang.CharSequence status)
Remove a marketplace listing
param
listingId the listing to be removed
param
status MARKETPLACE_STATUS_DEFAULT, MARKETPLACE_STATUS_SUCCESS, or MARKETPLACE_STATUS_NOT_SUCCESS
return
boolean indicating whether the listing was removed
see

Developers Wiki: marketplace.removeListing
    assert MARKETPLACE_STATUS_DEFAULT.equals(status) || MARKETPLACE_STATUS_SUCCESS.equals(status)
           || MARKETPLACE_STATUS_NOT_SUCCESS.equals(status) : "Invalid status: " + status;
    
    T result = this.callMethod(FacebookMethod.MARKETPLACE_REMOVE_LISTING,
                               new Pair<String, CharSequence>("listing_id", listingId.toString()),
                               new Pair<String, CharSequence>("status", status));
    return this.extractBoolean(result);
  
public Tmarketplace_search(java.lang.CharSequence category, java.lang.CharSequence subCategory, java.lang.CharSequence query)
Search for marketplace listings, optionally by category, subcategory, and/or query string.
param
category the category of listings desired (optional except if subcategory is provided)
param
subCategory the subcategory of listings desired (optional)
param
query a query string (optional)
return
a T of marketplace listings
see

Developers Wiki: marketplace.search
    
    ArrayList<Pair<String, CharSequence>> params =
      new ArrayList<Pair<String, CharSequence>>(FacebookMethod.MARKETPLACE_SEARCH.numParams());
    if (null != category && !"".equals(category)) {
      params.add(new Pair<String, CharSequence>("category", category));
      if (null != subCategory && !"".equals(subCategory)) {
        params.add(new Pair<String, CharSequence>("subcategory", subCategory));
      }
    }
    if (null != query && !"".equals(query)) {
      params.add(new Pair<String, CharSequence>("query", category));
    }

    return this.callMethod(FacebookMethod.MARKETPLACE_SEARCH, params);
  
public Tnotifications_get()
Retrieves the outstanding notifications for the session user.
return
a T containing
notification count pairs for 'messages', 'pokes' and 'shares',
a uid list of 'friend_requests', a gid list of 'group_invites',
and an eid list of 'event_invites'
    return this.callMethod(FacebookMethod.NOTIFICATIONS_GET);
  
public java.net.URLnotifications_send(java.util.Collection recipientIds, java.lang.CharSequence notification, java.lang.CharSequence email)
Send a notification message to the specified users.
param
recipientIds the user ids to which the message is to be sent
param
notification the FBML to display on the notifications page
param
email the FBML to send to the specified users via email, or null
if no email should be sent
return
a URL, possibly null, to which the user should be redirected to finalize
the sending of the email
    assert (null != recipientIds && !recipientIds.isEmpty());
    assert (null != notification);
    ArrayList<Pair<String, CharSequence>> args = new ArrayList<Pair<String, CharSequence>>(3);
    args.add(new Pair<String, CharSequence>("to_ids", delimit(recipientIds)));
    args.add(new Pair<String, CharSequence>("notification", notification));
    if (null != email) {
      args.add(new Pair<String, CharSequence>("email", email));
    }
    T result = this.callMethod(FacebookMethod.NOTIFICATIONS_SEND, args);
    return extractURL(result);
  
public Tpages_getInfo(java.util.Collection pageIds, java.util.EnumSet fields)
Retrieves the requested profile fields for the Facebook Pages with the given
pageIds. Can be called for pages that have added the application
without establishing a session.
param
pageIds the page IDs
param
fields a set of page profile fields
return
a T consisting of a list of pages, with each page element
containing the requested fields.
see

Developers Wiki: Pages.getInfo
    if (pageIds == null || pageIds.isEmpty()) {
      throw new IllegalArgumentException("pageIds cannot be empty or null");
    }
    if (fields == null || fields.isEmpty()) {
      throw new IllegalArgumentException("fields cannot be empty or null");
    }
    IFacebookMethod method =
      null == this._sessionKey ? FacebookMethod.PAGES_GET_INFO_NO_SESSION : FacebookMethod.PAGES_GET_INFO;
    return this.callMethod(method,
                           new Pair<String, CharSequence>("page_ids", delimit(pageIds)),
                           new Pair<String, CharSequence>("fields", delimit(fields)));
  
public Tpages_getInfo(java.util.Collection pageIds, java.util.Set fields)
Retrieves the requested profile fields for the Facebook Pages with the given
pageIds. Can be called for pages that have added the application
without establishing a session.
param
pageIds the page IDs
param
fields a set of page profile fields
return
a T consisting of a list of pages, with each page element
containing the requested fields.
see

Developers Wiki: Pages.getInfo
    if (pageIds == null || pageIds.isEmpty()) {
      throw new IllegalArgumentException("pageIds cannot be empty or null");
    }
    if (fields == null || fields.isEmpty()) {
      throw new IllegalArgumentException("fields cannot be empty or null");
    }
    IFacebookMethod method =
      null == this._sessionKey ? FacebookMethod.PAGES_GET_INFO_NO_SESSION : FacebookMethod.PAGES_GET_INFO;
    return this.callMethod(method,
                           new Pair<String, CharSequence>("page_ids", delimit(pageIds)),
                           new Pair<String, CharSequence>("fields", delimit(fields)));
  
public Tpages_getInfo(java.lang.Long userId, java.util.EnumSet fields)
Retrieves the requested profile fields for the Facebook Pages of the user with the given
userId.
param
userId the ID of a user about whose pages to fetch info (defaulted to the logged-in user)
param
fields a set of PageProfileFields
return
a T consisting of a list of pages, with each page element
containing the requested fields.
see

Developers Wiki: Pages.getInfo
    if (fields == null || fields.isEmpty()) {
      throw new IllegalArgumentException("fields cannot be empty or null");
    }
    if (userId == null) {
      userId = this._userId;
    }
    return this.callMethod(FacebookMethod.PAGES_GET_INFO,
                           new Pair<String, CharSequence>("uid",    userId.toString()),
                           new Pair<String, CharSequence>("fields", delimit(fields)));
  
public Tpages_getInfo(java.lang.Long userId, java.util.Set fields)
Retrieves the requested profile fields for the Facebook Pages of the user with the given
userId.
param
userId the ID of a user about whose pages to fetch info (defaulted to the logged-in user)
param
fields a set of page profile fields
return
a T consisting of a list of pages, with each page element
containing the requested fields.
see

Developers Wiki: Pages.getInfo
    if (fields == null || fields.isEmpty()) {
      throw new IllegalArgumentException("fields cannot be empty or null");
    }
    if (userId == null) {
      userId = this._userId;
    }
    return this.callMethod(FacebookMethod.PAGES_GET_INFO,
                           new Pair<String, CharSequence>("uid",    userId.toString()),
                           new Pair<String, CharSequence>("fields", delimit(fields)));
  
public booleanpages_isAdmin(java.lang.Long pageId)
Checks whether the logged-in user for this session is an admin of the page
with the given pageId.
param
pageId the ID of the page
return
true if the logged-in user is an admin
see

Developers Wiki: Pages.isAdmin
    return extractBoolean(this.callMethod(FacebookMethod.PAGES_IS_ADMIN,
                                          new Pair<String, CharSequence>("page_id",
                                                                         pageId.toString())));
  
public booleanpages_isAppAdded(java.lang.Long pageId)
Checks whether a page has added the application
param
pageId the ID of the page
return
true if the page has added the application
see

Developers Wiki: Pages.isAppAdded
    return extractBoolean(this.callMethod(FacebookMethod.PAGES_IS_APP_ADDED,
                                          new Pair<String,CharSequence>("page_id", pageId.toString())));
  
public booleanpages_isFan(java.lang.Long pageId, java.lang.Long userId)
Checks whether a user is a fan of the page with the given pageId.
param
pageId the ID of the page
param
userId the ID of the user (defaults to the logged-in user if null)
return
true if the user is a fan of the page
see

Developers Wiki: Pages.isFan
    return extractBoolean(this.callMethod(FacebookMethod.PAGES_IS_FAN,
                                          new Pair<String,CharSequence>("page_id", pageId.toString()),
                                          new Pair<String,CharSequence>("uid", userId.toString())));
  
public booleanpages_isFan(java.lang.Long pageId)
Checks whether the logged-in user is a fan of the page with the given pageId.
param
pageId the ID of the page
return
true if the logged-in user is a fan of the page
see

Developers Wiki: Pages.isFan
    return extractBoolean(this.callMethod(FacebookMethod.PAGES_IS_FAN,
                                          new Pair<String,CharSequence>("page_id", pageId.toString())));
  
protected abstract TparseCallResult(java.io.InputStream data, com.facebook.api.IFacebookMethod method)
Parses the result of an API call into a T.
param
data an InputStream with the results of a request to the Facebook servers
param
method the method called
throws
FacebookException if data represents an error
throws
IOException if data is not readable
return
a T
private booleanphotos_addTag(java.lang.Long photoId, java.lang.Double xPct, java.lang.Double yPct, java.lang.Long taggedUserId, java.lang.CharSequence tagText)
    assert (null != photoId && !photoId.equals(0));
    assert (null != taggedUserId || null != tagText);
    assert (null != xPct && xPct >= 0 && xPct <= 100);
    assert (null != yPct && yPct >= 0 && yPct <= 100);
    T d =
      this.callMethod(FacebookMethod.PHOTOS_ADD_TAG, new Pair<String, CharSequence>("pid", photoId.toString()),
                      new Pair<String, CharSequence>("tag_uid", taggedUserId.toString()),
                      new Pair<String, CharSequence>("x", xPct.toString()),
                      new Pair<String, CharSequence>("y", yPct.toString()));
    return extractBoolean(d);
  
public booleanphotos_addTag(java.lang.Long photoId, java.lang.CharSequence tagText, java.lang.Double xPct, java.lang.Double yPct)
Adds a tag to a photo.
param
photoId The photo id of the photo to be tagged.
param
xPct The horizontal position of the tag, as a percentage from 0 to 100, from the left of the photo.
param
yPct The list of photos from which to extract photo tags.
param
tagText The text of the tag.
return
whether the tag was successfully added.
    return photos_addTag(photoId, xPct, yPct, null, tagText);
  
public booleanphotos_addTag(java.lang.Long photoId, java.lang.Long taggedUserId, java.lang.Double xPct, java.lang.Double yPct)
Adds a tag to a photo.
param
photoId The photo id of the photo to be tagged.
param
xPct The horizontal position of the tag, as a percentage from 0 to 100, from the left of the photo.
param
yPct The vertical position of the tag, as a percentage from 0 to 100, from the top of the photo.
param
taggedUserId The list of photos from which to extract photo tags.
return
whether the tag was successfully added.
    return photos_addTag(photoId, xPct, yPct, taggedUserId, null);
  
public Tphotos_addTags(java.lang.Long photoId, java.util.Collection tags)
Adds several tags to a photo.
param
photoId The photo id of the photo to be tagged.
param
tags A list of PhotoTags.
return
a list of booleans indicating whether the tag was successfully added.
    assert (photoId > 0);
    assert (null != tags && !tags.isEmpty());
    
    JSONArray jsonTags=new JSONArray();
    for (PhotoTag tag : tags) {
      jsonTags.put(tag.jsonify());
    }

    return this.callMethod(FacebookMethod.PHOTOS_ADD_TAG,
                           new Pair<String, CharSequence>("pid", photoId.toString()),
                           new Pair<String, CharSequence>("tags", jsonTags.toString()));
  
public Tphotos_createAlbum(java.lang.String albumName)
Creates an album.
param
albumName The list of photos from which to extract photo tags.
return
the created album
    return this.photos_createAlbum(albumName, null /*description*/, null /*location*/); 
  
public Tphotos_createAlbum(java.lang.String name, java.lang.String description, java.lang.String location)
Creates an album.
param
name The album name.
param
location The album location (optional).
param
description The album description (optional).
return
an array of photo objects.
    assert (null != name && !"".equals(name));
    ArrayList<Pair<String, CharSequence>> params =
      new ArrayList<Pair<String, CharSequence>>(FacebookMethod.PHOTOS_CREATE_ALBUM.numParams());
    params.add(new Pair<String, CharSequence>("name", name));
    if (null != description)
      params.add(new Pair<String, CharSequence>("description", description));
    if (null != location)
      params.add(new Pair<String, CharSequence>("location", location));
    return this.callMethod(FacebookMethod.PHOTOS_CREATE_ALBUM, params);
  
public Tphotos_get(java.util.Collection photoIds)
Used to retrieve photo objects using the search parameters (one or more of the
parameters must be provided).
param
photoIds retrieve from this list of photos (optional)
return
an T of photo objects.
see
#photos_get(Long, Long, Collection)
see

Developers Wiki: Photos.get
    return photos_get(null /*subjId*/, null /*albumId*/, photoIds);
  
public Tphotos_get(java.lang.Long subjId, java.lang.Long albumId)
Used to retrieve photo objects using the search parameters (one or more of the
parameters must be provided).
param
subjId retrieve from photos associated with this user (optional).
param
albumId retrieve from photos from this album (optional)
return
an T of photo objects.
see
#photos_get(Long, Long, Collection)
see

Developers Wiki: Photos.get
    return photos_get(subjId, albumId, null /*photoIds*/);
  
public Tphotos_get(java.lang.Long subjId, java.util.Collection photoIds)
Used to retrieve photo objects using the search parameters (one or more of the
parameters must be provided).
param
subjId retrieve from photos associated with this user (optional).
param
photoIds retrieve from this list of photos (optional)
return
an T of photo objects.
see
#photos_get(Long, Long, Collection)
see

Developers Wiki: Photos.get
    return photos_get(subjId, null /*albumId*/, photoIds);
  
public Tphotos_get(java.lang.Long subjId)
Used to retrieve photo objects using the search parameters (one or more of the
parameters must be provided).
param
subjId retrieve from photos associated with this user (optional).
return
an T of photo objects.
see
#photos_get(Long, Long, Collection)
see

Developers Wiki: Photos.get
    return photos_get(subjId, null /*albumId*/, null /*photoIds*/); 
  
public Tphotos_get(java.lang.Long subjId, java.lang.Long albumId, java.util.Collection photoIds)
Used to retrieve photo objects using the search parameters (one or more of the
parameters must be provided).
param
subjId retrieve from photos associated with this user (optional).
param
albumId retrieve from photos from this album (optional)
param
photoIds retrieve from this list of photos (optional)
return
an T of photo objects.
see

Developers Wiki: Photos.get
    ArrayList<Pair<String, CharSequence>> params =
      new ArrayList<Pair<String, CharSequence>>(FacebookMethod.PHOTOS_GET.numParams());

    boolean hasUserId = null != subjId && 0 != subjId;
    boolean hasAlbumId = null != albumId && 0 != albumId;
    boolean hasPhotoIds = null != photoIds && !photoIds.isEmpty();
    if (!hasUserId && !hasAlbumId && !hasPhotoIds) {
      throw new IllegalArgumentException("At least one of photoIds, albumId, or subjId must be provided");
    }

    if (hasUserId)
      params.add(new Pair<String, CharSequence>("subj_id", Long.toString(subjId)));
    if (hasAlbumId)
      params.add(new Pair<String, CharSequence>("aid", Long.toString(albumId)));
    if (hasPhotoIds)
      params.add(new Pair<String, CharSequence>("pids", delimit(photoIds)));

    return this.callMethod(FacebookMethod.PHOTOS_GET, params);
  
public Tphotos_getAlbums(java.util.Collection albumIds)
Retrieves album metadata for a list of album IDs.
param
albumIds the ids of albums whose metadata is to be retrieved
return
album objects
see

Developers Wiki: Photos.getAlbums
    return photos_getAlbums(null /*userId*/, albumIds);
  
public Tphotos_getAlbums(java.lang.Long userId)
Retrieves album metadata for albums owned by a user.
param
userId (optional) the id of the albums' owner (optional)
return
album objects
see

Developers Wiki: Photos.getAlbums
    return photos_getAlbums(userId, null /*albumIds*/); 
  
public Tphotos_getAlbums(java.lang.Long userId, java.util.Collection albumIds)
Retrieves album metadata. Pass a user id and/or a list of album ids to specify the albums
to be retrieved (at least one must be provided)
param
userId (optional) the id of the albums' owner (optional)
param
albumIds (optional) the ids of albums whose metadata is to be retrieved
return
album objects
see

Developers Wiki: Photos.getAlbums
    boolean hasUserId = null != userId && userId != 0;
    boolean hasAlbumIds = null != albumIds && !albumIds.isEmpty();
    assert (hasUserId || hasAlbumIds); // one of the two must be provided

    if (hasUserId)
      return (hasAlbumIds) ?
             this.callMethod(FacebookMethod.PHOTOS_GET_ALBUMS, new Pair<String, CharSequence>("uid",
                                                                                              Long.toString(userId)),
                             new Pair<String, CharSequence>("aids", delimit(albumIds))) :
             this.callMethod(FacebookMethod.PHOTOS_GET_ALBUMS,
                             new Pair<String, CharSequence>("uid", Long.toString(userId)));
    else
      return this.callMethod(FacebookMethod.PHOTOS_GET_ALBUMS,
                             new Pair<String, CharSequence>("aids", delimit(albumIds)));
  
public Tphotos_getByAlbum(java.lang.Long albumId, java.util.Collection photoIds)
Used to retrieve photo objects using the search parameters (one or more of the
parameters must be provided).
param
albumId retrieve from photos from this album (optional)
param
photoIds retrieve from this list of photos (optional)
return
an T of photo objects.
see
#photos_get(Integer, Long, Collection)
see

Developers Wiki: Photos.get
    return photos_get(null /*subjId*/, albumId, photoIds);
  
public Tphotos_getByAlbum(java.lang.Long albumId)
Used to retrieve photo objects using the search parameters (one or more of the
parameters must be provided).
param
albumId retrieve from photos from this album (optional)
return
an T of photo objects.
see
#photos_get(Integer, Long, Collection)
see

Developers Wiki: Photos.get
    return photos_get(null /*subjId*/, albumId, null /*photoIds*/);
  
public Tphotos_getTags(java.util.Collection photoIds)
Retrieves the tags for the given set of photos.
param
photoIds The list of photos from which to extract photo tags.
return
the created album
    return this.callMethod(FacebookMethod.PHOTOS_GET_TAGS,
                           new Pair<String, CharSequence>("pids", delimit(photoIds)));
  
public Tphotos_upload(java.io.File photo)
Uploads a photo to Facebook.
param
photo an image file
return
a T with the standard Facebook photo information
see

Developers wiki: Photos.upload
    return photos_upload(photo, null /* caption */ , null /* albumId */);
  
public Tphotos_upload(java.io.File photo, java.lang.String caption)
Uploads a photo to Facebook.
param
photo an image file
param
caption a description of the image contents
return
a T with the standard Facebook photo information
see

Developers wiki: Photos.upload
    return photos_upload(photo, caption, null /* albumId */);
  
public Tphotos_upload(java.io.File photo, java.lang.Long albumId)
Uploads a photo to Facebook.
param
photo an image file
param
albumId the album into which the photo should be uploaded
return
a T with the standard Facebook photo information
see

Developers wiki: Photos.upload
    return photos_upload(photo, null /* caption */, albumId);
  
public Tphotos_upload(java.io.File photo, java.lang.String caption, java.lang.Long albumId)
Uploads a photo to Facebook.
param
photo an image file
param
caption a description of the image contents
param
albumId the album into which the photo should be uploaded
return
a T with the standard Facebook photo information
see

Developers wiki: Photos.upload
    ArrayList<Pair<String, CharSequence>> params =
      new ArrayList<Pair<String, CharSequence>>(FacebookMethod.PHOTOS_UPLOAD.numParams());
    assert (photo.exists() && photo.canRead());
    this._uploadFile = photo;
    if (null != albumId)
      params.add(new Pair<String, CharSequence>("aid", Long.toString(albumId)));
    if (null != caption)
      params.add(new Pair<String, CharSequence>("caption", caption));
    return callMethod(FacebookMethod.PHOTOS_UPLOAD, params);
  
protected java.io.InputStreampostFileRequest(java.lang.String methodName, java.util.Map params)
Helper function for posting a request that includes raw file data, eg {@link #photos_upload}.
param
methodName the name of the method
param
params request parameters (not including the file)
return
an InputStream with the request response
see
#photos_upload
    assert (null != _uploadFile);
    try {
      BufferedInputStream bufin = new BufferedInputStream(new FileInputStream(_uploadFile));

      String boundary = Long.toString(System.currentTimeMillis(), 16);
      URLConnection con = SERVER_URL.openConnection();
      con.setDoInput(true);
      con.setDoOutput(true);
      con.setUseCaches(false);
      con.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);
      con.setRequestProperty("MIME-version", "1.0");

      DataOutputStream out = new DataOutputStream(con.getOutputStream());

      for (Map.Entry<String, CharSequence> entry : params.entrySet()) {
        out.writeBytes(PREF + boundary + CRLF);
        out.writeBytes("Content-disposition: form-data; name=\"" + entry.getKey() + "\"");
        out.writeBytes(CRLF + CRLF);
        out.writeBytes(entry.getValue().toString());
        out.writeBytes(CRLF);
      }

      out.writeBytes(PREF + boundary + CRLF);
      out.writeBytes("Content-disposition: form-data; filename=\"" + _uploadFile.getName() + "\"" +
                     CRLF);
      out.writeBytes("Content-Type: image/jpeg" + CRLF);
      // out.writeBytes("Content-Transfer-Encoding: binary" + CRLF); // not necessary

      // Write the file
      out.writeBytes(CRLF);
      byte b[] = new byte[UPLOAD_BUFFER_SIZE];
      int byteCounter = 0;
      int i;
      while (-1 != (i = bufin.read(b))) {
        byteCounter += i;
        out.write(b, 0, i);
      }
      out.writeBytes(CRLF + PREF + boundary + PREF + CRLF);

      out.flush();
      out.close();

      InputStream is = con.getInputStream();
      return is;
    } catch (Exception e) {
      logException(e);
      return null;
    }
  
private java.io.InputStreampostRequest(java.lang.CharSequence method, java.util.Map params, boolean doHttps, boolean doEncode)
    CharSequence buffer = (null == params) ? "" : delimit(params.entrySet(), "&", "=", doEncode);
    URL serverUrl = (doHttps) ? HTTPS_SERVER_URL : _serverUrl;
    if (isDebug()) {
      StringBuilder debugMsg = new StringBuilder()
        .append(method)
        .append(" POST: ")
        .append(serverUrl.toString())
        .append("?");
      debugMsg.append(buffer);
      log(debugMsg);
    }

    HttpURLConnection conn = (HttpURLConnection) serverUrl.openConnection();
    try {
      conn.setRequestMethod("POST");
    } catch (ProtocolException ex) {
      logException(ex);
    }
    conn.setDoOutput(true);
    conn.connect();
    conn.getOutputStream().write(buffer.toString().getBytes());

    return conn.getInputStream();
  
public Tprofile_getFBML(java.lang.Long userId)
Gets the FBML for a user's profile, including the content for both the profile box
and the profile actions.
param
userId - the user whose profile FBML to set
return
a T containing FBML markup
    return this.callMethod(FacebookMethod.PROFILE_GET_FBML,
                           new Pair<String, CharSequence>("uid", Long.toString(userId)));

  
public booleanprofile_setFBML(java.lang.CharSequence fbmlMarkup, java.lang.Long userId)
Sets the FBML for a user's profile, including the content for both the profile box
and the profile actions.
param
userId - the user whose profile FBML to set
param
fbmlMarkup - refer to the FBML documentation for a description of the markup and its role in various contexts
return
a boolean indicating whether the FBML was successfully set

    return extractBoolean(this.callMethod(FacebookMethod.PROFILE_SET_FBML,
                                          new Pair<String, CharSequence>("uid",
                                                                         Long.toString(userId)),
                                          new Pair<String, CharSequence>("markup", fbmlMarkup)));

  
public voidsetDebug(boolean isDebug)
    _debug = isDebug;
  
public static voidsetDebugAll(boolean isDebug)
    ExtensibleClient.DEBUG = isDebug;
  
public voidsetIsDesktop(boolean isDesktop)
    this._isDesktop = isDesktop;
  
public booleansms_canSend()
      return this.sms_canSend(this.users_getLoggedInUser());      
  
public booleansms_canSend(java.lang.Long userId)
Determines whether this application can send SMS to the user identified by userId
param
userId a user ID
return
true if sms can be sent to the user
see
FacebookExtendedPerm#SMS
see

Developers Wiki: Mobile: Application Generated Messages
    return extractBoolean(this.callMethod(FacebookMethod.SMS_CAN_SEND,
                                          new Pair<String, CharSequence>("uid",
                                                                         userId.toString())));
  
public voidsms_sendMessage(java.lang.Long userId, java.lang.CharSequence message)
Sends a message via SMS to the user identified by userId.
The SMS extended permission is required for success.
param
userId a user ID
param
message the message to be sent via SMS
throws
FacebookException in case of error
throws
IOException
see
FacebookExtendedPerm#SMS
see

Developers Wiki: Mobile: Application Generated Messages
see

Developers Wiki: Mobile: Workflow
    this.callMethod(FacebookMethod.SMS_SEND_MESSAGE,
                    new Pair<String, CharSequence>("uid", userId.toString()),
                    new Pair<String, CharSequence>("message", message),
                    new Pair<String, CharSequence>("req_session", "0"));
  
public intsms_sendMessageWithSession(java.lang.Long userId, java.lang.CharSequence message)
Sends a message via SMS to the user identified by userId, with
the expectation that the user will reply. The SMS extended permission is required for success.
The returned mobile session ID can be stored and used in {@link #sms_sendResponse} when
the user replies.
param
userId a user ID
param
message the message to be sent via SMS
return
a mobile session ID (can be used in {@link #sms_sendResponse})
throws
FacebookException in case of error, e.g. SMS is not enabled
throws
IOException
see
FacebookExtendedPerm#SMS
see

Developers Wiki: Mobile: Application Generated Messages
see

Developers Wiki: Mobile: Workflow
    return extractInt(this.callMethod(FacebookMethod.SMS_SEND_MESSAGE,
                               new Pair<String, CharSequence>("uid", userId.toString()),
                               new Pair<String, CharSequence>("message", message),
                               new Pair<String, CharSequence>("req_session", "1")));
  
public voidsms_sendResponse(java.lang.Integer userId, java.lang.CharSequence response, java.lang.Integer mobileSessionId)
Sends a message via SMS to the user identified by userId in response
to a user query associated with mobileSessionId.
param
userId a user ID
param
response the message to be sent via SMS
param
mobileSessionId the mobile session
throws
FacebookException in case of error
throws
IOException
see
FacebookExtendedPerm#SMS
see

Developers Wiki: Mobile: Application Generated Messages
see

Developers Wiki: Mobile: Workflow
    this.callMethod(FacebookMethod.SMS_SEND_MESSAGE,
                    new Pair<String, CharSequence>("uid", userId.toString()),
                    new Pair<String, CharSequence>("message", response),
                    new Pair<String, CharSequence>("session_id", mobileSessionId.toString()));
  
protected booleantemplatizedFeedHandler(com.facebook.api.FacebookMethod method, java.lang.String titleTemplate, java.lang.String titleData, java.lang.String bodyTemplate, java.lang.String bodyData, java.lang.String bodyGeneral, java.util.Collection pictures, java.lang.String targetIds)
      assert (pictures == null || pictures.size() <= 4);

      long actorId = this.users_getLoggedInUser();
      ArrayList<Pair<String, CharSequence>> params = new ArrayList<Pair<String, CharSequence>>(method.numParams());

      //these are always required parameters
      params.add(new Pair<String, CharSequence>("actor_id", Long.toString(actorId)));
      params.add(new Pair<String, CharSequence>("title_template", titleTemplate));

      //these are optional parameters
      if (titleData != null) {
          params.add(new Pair<String, CharSequence>("title_data", titleData));
      }
      if (bodyTemplate != null) {
          params.add(new Pair<String, CharSequence>("body_template", bodyTemplate));
          if (bodyData != null) {
              params.add(new Pair<String, CharSequence>("body_data", bodyData));
          }
      }
      if (bodyGeneral != null) {
          params.add(new Pair<String, CharSequence>("body_general", bodyGeneral));
      }
      if (pictures != null) {
          int count = 1;
          for (IPair picture : pictures) {
                params.add(new Pair<String, CharSequence>("image_" + count, picture.getFirst().toString()));
                if (picture.getSecond() != null) {
                    params.add(new Pair<String, CharSequence>("image_" + count + "_link", picture.getSecond().toString()));
                }
                count++;
          }
      }
      if (targetIds != null) {
          params.add(new Pair<String, CharSequence>("target_ids", targetIds));
      }
      this.callMethod(method, params);
      return this.rawResponse.contains(">1<"); //a code of '1' indicates success
  
public booleanusers_clearStatus()
Clears the logged-in user's Facebook status.
Requires the status_update extended permission.
return
whether the status was successfully cleared
see
#users_hasAppPermission
see
FacebookExtendedPerm#STATUS_UPDATE
see

Developers Wiki: Users.setStatus
    return extractBoolean(this.callMethod(FacebookMethod.USERS_SET_STATUS,
                                          new Pair<String, CharSequence>("clear", "1")));
  
public Tusers_getInfo(java.util.Collection userIds, java.util.Set fields)
Retrieves the requested info fields for the requested set of users.
param
userIds a collection of user IDs for which to fetch info
param
fields a set of strings describing the info fields desired, such as "last_name", "sex"
return
a T consisting of a list of users, with each user element
containing the requested fields.
    // assertions test for invalid params
    if (null == userIds) {
      throw new IllegalArgumentException("userIds cannot be null");
    }
    if (fields == null || fields.isEmpty()) {
      throw new IllegalArgumentException("fields should not be empty");
    }

    return this.callMethod(FacebookMethod.USERS_GET_INFO,
                           new Pair<String, CharSequence>("uids", delimit(userIds)),
                           new Pair<String, CharSequence>("fields", delimit(fields)));
  
public Tusers_getInfo(java.util.Collection userIds, java.util.EnumSet fields)
Retrieves the requested info fields for the requested set of users.
param
userIds a collection of user IDs for which to fetch info
param
fields a set of ProfileFields
return
a T consisting of a list of users, with each user element
containing the requested fields.
    // assertions test for invalid params
    assert (userIds != null);
    assert (fields != null);
    assert (!fields.isEmpty());

    return this.callMethod(FacebookMethod.USERS_GET_INFO,
                           new Pair<String, CharSequence>("uids", delimit(userIds)),
                           new Pair<String, CharSequence>("fields", delimit(fields)));
  
public longusers_getLoggedInUser()
Retrieves the user ID of the user logged in to this API session
return
the Facebook user ID of the logged-in user
    T result = this.callMethod(FacebookMethod.USERS_GET_LOGGED_IN_USER);
    return extractLong(result);
  
public booleanusers_hasAppPermission(java.lang.CharSequence permission)
Retrieves whether the logged-in user has granted the specified permission
to this application.
param
permission an extended permission (e.g. FacebookExtendedPerm.MARKETPLACE,
"photo_upload")
return
boolean indicating whether the user has the permission
see
FacebookExtendedPerm
see

Developers Wiki: Users.hasAppPermission
    return extractBoolean(this.callMethod(FacebookMethod.USERS_HAS_APP_PERMISSION,
                                          new Pair<String, CharSequence>("ext_perm", permission)));
  
public booleanusers_hasAppPermission(com.facebook.api.Permission perm)
      return this.users_hasAppPermission(perm.getName());
  
public booleanusers_isAppAdded()
Retrieves an indicator of whether the logged-in user has installed the
application associated with the _apiKey.
return
boolean indicating whether the user has installed the app
    return extractBoolean(this.callMethod(FacebookMethod.USERS_IS_APP_ADDED));
  
public booleanusers_setStatus(java.lang.String newStatus, boolean clear)
      if (clear) {
          this.users_clearStatus();
      }
      return this.users_setStatus(newStatus);
  
public booleanusers_setStatus(java.lang.String status)
Sets the logged-in user's Facebook status.
Requires the status_update extended permission.
return
whether the status was successfully set
see
#users_hasAppPermission
see
FacebookExtendedPerm#STATUS_UPDATE
see

Developers Wiki: Users.setStatus
    return extractBoolean(this.callMethod(FacebookMethod.USERS_SET_STATUS,
                                          new Pair<String, CharSequence>("status", status)));