FileDocCategorySizeDatePackage
IFacebookRestClient.javaAPI DocGoogle Facebook API v1.570127Sun Nov 11 17:04:46 GMT 2007com.facebook.api

IFacebookRestClient

public interface IFacebookRestClient
Generic interface for a FacebookRestClient, parameterized by output format. For continually updated documentation, please refer to the Developer Wiki.

Fields Summary
public static final String
TARGET_API_VERSION
public static final String
ERROR_TAG
public static final String
FB_SERVER
public static final String
SERVER_ADDR
public static final String
HTTPS_SERVER_ADDR
Constructors Summary
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

public 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.

public java.lang.Stringdata_getUserPreference(java.lang.Integer prefId)
Lookup a single preference value for the current user.

param
prefId the id of the preference to lookup. This should be an integer value from 0-200.
return
The value of that preference, or null if it is not yet set.
throws
FacebookException if an error happens when executing the API call.
throws
IOException if a communication/network error happens.

public java.util.Mapdata_getUserPreferences()
Get a map containing all preference values set for the current user.

return
a map of preference values, keyed by preference id. The map will contain all preferences that have been set for the current user. If there are no preferences currently set, the map will be empty. The map returned will never be null.
throws
FacebookException if an error happens when executing the API call.
throws
IOException if a communication/network error happens.

public voiddata_setUserPreference(java.lang.Integer prefId, java.lang.String value)
Set a user-preference value. The value can be any string up to 127 characters in length, while the preference id can only be an integer between 0 and 200. Any preference set applies only to the current user of the application. To clear a user-preference, specify null as the value parameter. The values of "0" and "" will be stored as user-preferences with a literal value of "0" and "" respectively.

param
prefId the id of the preference to set, an integer between 0 and 200.
param
value the value to store, a String of up to 127 characters in length.
throws
FacebookException if an error happens when executing the API call.
throws
IOException if a communication/network error happens.

public voiddata_setUserPreferences(java.util.Map values, boolean replace)
Set multiple user-preferences values. The values can be strings up to 127 characters in length, while the preference id can only be an integer between 0 and 200. Any preferences set apply only to the current user of the application. To clear a user-preference, specify null as its value in the map. The values of "0" and "" will be stored as user-preferences with a literal value of "0" and "" respectively.

param
value the values to store, specified in a map. The keys should be preference-id values from 0-200, and the values should be strings of up to 127 characters in length.
param
replace set to true if you want to remove any pre-existing preferences before writing the new ones set to false if you want the new preferences to be merged with any pre-existing preferences
throws
FacebookException if an error happens when executing the API call.
throws
IOException if a communication/network error happens.

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

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'

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

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

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

public booleanfbml_refreshRefUrl(java.net.URL url)
Recaches the referenced url.

param
url the URL to refresh
return
boolean indicating whether the refresh succeeded

public booleanfbml_setRefHandle(java.lang.String handle, java.lang.String markup)
Associates the specified FBML markup with the specified handle/id. The markup can then be referenced using the fb:ref FBML tag, to allow a given snippet to be reused easily across multiple users, and also to allow the application to update the fbml for multiple users more easily without having to make a seperate call for each user, by just changing the FBML markup that is associated with the handle/id.

param
handle the id to associate the specified markup with. Put this in fb:ref FBML tags to reference your markup.
param
markup the FBML markup to store.
throws
FacebookException if an error happens when executing the API call.
throws
IOException if a communication/network error happens.

public booleanfeed_PublishTemplatizedAction(com.facebook.api.TemplatizedAction action)
Publishes a templatized action for the current user. The action will appear in their minifeed, and may appear in their friends' newsfeeds depending upon a number of different factors. When a template match exists between multiple distinct users (like "Bob recommends Bizou" and "Sally recommends Bizou"), the feed entries may be combined in the newfeed (to something like "Bob and sally recommend Bizou"). This happens automatically, and *only* if the template match between the two feed entries is identical.

Feed entries are not aggregated for a single user (so "Bob recommends Bizou" and "Bob recommends Le Charm" *will not* become "Bob recommends Bizou and Le Charm").

If the user's action involves one or more of their friends, list them in the 'targetIds' parameter. For example, if you have "Bob says hi to Sally and Susie", and Sally's UID is 1, and Susie's UID is 2, then pass a 'targetIds' paramters of "1,2". If you pass this parameter, you can use the "{target}" token in your templates. Probably it also makes it more likely that Sally and Susie will see the feed entry in their newsfeed, relative to any other friends Bob might have. It may be a good idea to always send a list of all the user's friends, and avoid using the "{target}" token, to maximize distribution of the story through the newsfeed.

The only strictly required parameter is 'titleTemplate', which must contain the "{actor}" token somewhere inside of it. All other parameters, options, and tokens are optional, and my be set to null if being omitted.

Not that stories will only be aggregated if *all* templates match and *all* template parameters match, so if two entries have the same templateTitle and titleData, but a different bodyTemplate, they will not aggregate. Probably it's better to use bodyGeneral instead of bodyTemplate, for the extra flexibility it provides.


Note that this method is replacing 'feed_publishActionOfUser', which has been deprecated by Facebook. For specific details, visit http://wiki.developers.facebook.com/index.php/Feed.publishTemplatizedAction

param
action a TemplatizedAction instance that represents the feed data to publish
return
a Document representing the XML response returned from the Facebook API server.
throws
FacebookException if any number of bad things happen
throws
IOException

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
deprecated
Facebook will be removing this API call. Please use feed_publishTemplatizedAction instead.

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
deprecated
Facebook will be removing this API call. Please use feed_publishTemplatizedAction instead.

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

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

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

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

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

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

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)
Publishes a templatized action for the current user. The action will appear in their minifeed, and may appear in their friends' newsfeeds depending upon a number of different factors. When a template match exists between multiple distinct users (like "Bob recommends Bizou" and "Sally recommends Bizou"), the feed entries may be combined in the newfeed (to something like "Bob and sally recommend Bizou"). This happens automatically, and *only* if the template match between the two feed entries is identical.

Feed entries are not aggregated for a single user (so "Bob recommends Bizou" and "Bob recommends Le Charm" *will not* become "Bob recommends Bizou and Le Charm").

If the user's action involves one or more of their friends, list them in the 'targetIds' parameter. For example, if you have "Bob says hi to Sally and Susie", and Sally's UID is 1, and Susie's UID is 2, then pass a 'targetIds' paramters of "1,2". If you pass this parameter, you can use the "{target}" token in your templates. Probably it also makes it more likely that Sally and Susie will see the feed entry in their newsfeed, relative to any other friends Bob might have. It may be a good idea to always send a list of all the user's friends, and avoid using the "{target}" token, to maximize distribution of the story through the newsfeed.

The only strictly required parameter is 'titleTemplate', which must contain the "{actor}" token somewhere inside of it. All other parameters, options, and tokens are optional, and my be set to null if being omitted.

Not that stories will only be aggregated if *all* templates match and *all* template parameters match, so if two entries have the same templateTitle and titleData, but a different bodyTemplate, they will not aggregate. Probably it's better to use bodyGeneral instead of bodyTemplate, for the extra flexibility it provides.


Note that this method is replacing 'feed_publishActionOfUser', which has been deprecated by Facebook. For specific details, visit http://wiki.developers.facebook.com/index.php/Feed.publishTemplatizedAction

param
titleTemplate the template for the title of the feed entry, this must contain the "(actor}" token. Any other tokens are optional, i.e. "{actor} recommends {place}".
param
titleData JSON-formatted values for any tokens used in titleTemplate, with the exception of "{actor}" and "{target}", which Facebook populates automatically, i.e. "{place: "Bizou"}".
param
bodyTemplate the template for the body of the feed entry, works the same as 'titleTemplate', but is not required to contain the "{actor}" token.
param
bodyData works the same as titleData
param
bodyGeneral non-templatized content for the body, may contain markup, may not contain tokens.
param
pictures a list of up to 4 images to display, with optional hyperlinks for each one.
param
targetIds a comma-seperated list of the UID's of any friend(s) who are involved in this feed action (if there are any), this specifies the value of the "{target}" token. If you use this token in any of your templates, you must specify a value for this parameter.
return
a Document representing the XML response returned from the Facebook API server.
throws
FacebookException if any number of bad things happen
throws
IOException

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)
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
see
Developers Resources: Feed Preview Console
deprecated
use the version that specified the actorId as a Long instead. UID's *are not ever to be* expressed as Integers.

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

public Tfriends_areFriends(long userId1, long userId2)
Retrieves whether two users are friends.

param
userId1
param
userId2
return
T
see
Developers Wiki: Friends.areFriends

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
see
Developers Wiki: Friends.areFriends

public Tfriends_get()
Retrieves the friends of the currently logged in user.

return
array of friends

public Tfriends_getAppUsers()
Retrieves the friends of the currently logged in user, who are also users of the calling application.

return
array of friends

public java.lang.StringgetRawResponse()
Returns a string representation for the last API response recieved from Facebook, exactly as sent by the API server. Note that calling this method consumes the data held in the internal buffer, and thus it may only be called once per API call.

return
a String representation of the last API response sent by Facebook

public java.lang.ObjectgetResponsePOJO()
Returns a JAXB object of the type that corresponds to the last API call made on the client. Each Facebook Platform API call that returns a Document object has a JAXB response object associated with it. The naming convention is generally intuitive. For example, if you invoke the 'user_getInfo' API call, the associated JAXB response object is 'UsersGetInfoResponse'.

An example of how to use this method:

FacebookRestClient client = new FacebookRestClient("apiKey", "secretKey", "sessionId");
client.friends_get();
FriendsGetResponse response = (FriendsGetResponse)client.getResponsePOJO();
List friends = response.getUid();

This is particularly useful in the case of API calls that return a Document object, as working with the JAXB response object is generally much simple than trying to walk/parse the DOM by hand.

This method can be safely called multiple times, though note that it will only return the response-object corresponding to the most recent Facebook Platform API call made.

Note that you must cast the return value of this method to the correct type in order to do anything useful with it.

return
a JAXB POJO ("Plain Old Java Object") of the type that corresponds to the last API call made on the client. Note that you must cast this object to its proper type before you will be able to do anything useful with it.

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

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'

public booleanisDebug()
Check to see if debug mode is enabled.

return
true if debug is enabled false otherwise

public booleanisDesktop()
Check to see if the client is running in desktop-app mode

return
true if the app is running in desktop mode. false otherwise

public java.lang.Longmarketplace_createListing(java.lang.Boolean showOnProfile, com.facebook.api.MarketplaceListing attrs)
Create a marketplace listing. The create_listing extended permission is required.

param
showOnProfile whether
return
the id of the created listing
see
#users_hasAppPermission
see
FacebookExtendedPerm#MARKETPLACE
see
Developers Wiki: marketplace.createListing
deprecated
provided for legacy support only. Please use the version that takes a MarketListing instead.

public java.lang.Longmarketplace_createListing(java.lang.Long listingId, boolean showOnProfile, java.lang.String attributes)
Create a new marketplace listing, or modify an existing one.

param
listingId the id of the listing to modify, set to 0 (or null) to create a new listing.
param
showOnProfile set to true to show the listing on the user's profile (Facebook appears to ignore this setting).
param
attributes JSON-encoded attributes for this listing.
return
the id of the listing created (or modified).
throws
FacebookException if an error happens when executing the API call.
throws
IOException if a communication/network error happens.

public java.lang.Longmarketplace_createListing(java.lang.Long listingId, boolean showOnProfile, com.facebook.api.MarketListing listing)
Create a new marketplace listing, or modify an existing one.

param
listingId the id of the listing to modify, set to 0 (or null) to create a new listing.
param
showOnProfile set to true to show the listing on the user's profile, set to false to prevent the listing from being shown on the profile.
param
listing the listing to publish.
return
the id of the listing created (or modified).
throws
FacebookException if an error happens when executing the API call.
throws
IOException if a communication/network error happens.

public java.lang.Longmarketplace_createListing(boolean showOnProfile, com.facebook.api.MarketListing listing)
Create a new marketplace listing.

param
showOnProfile set to true to show the listing on the user's profile, set to false to prevent the listing from being shown on the profile.
param
listing the listing to publish.
return
the id of the listing created (or modified).
throws
FacebookException if an error happens when executing the API call.
throws
IOException if a communication/network error happens.

public java.lang.Longmarketplace_editListing(java.lang.Long listingId, java.lang.Boolean showOnProfile, com.facebook.api.MarketplaceListing attrs)
Modify a marketplace listing. The create_listing extended permission is required.

return
the id of the edited listing
see
Developers Wiki: marketplace.createListing
deprecated
provided for legacy support only. Please use the version that takes a MarketListing instead.

public java.lang.Longmarketplace_editListing(java.lang.Long listingId, java.lang.Boolean showOnProfile, com.facebook.api.MarketListing 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

public java.util.Listmarketplace_getCategories()
Get the categories available in marketplace.

return
a T listing the marketplace categories
see
Developers Wiki: marketplace.getCategories

public Tmarketplace_getCategoriesObject()
Get the categories available in marketplace.

return
a T listing the marketplace categories
see
Developers Wiki: marketplace.getCategories
deprecated
use the version that returns a List instead.

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

public java.util.Listmarketplace_getListings(java.util.List listingIds, java.util.List uids)
Retrieve listings from the marketplace. The listings can be filtered by listing-id or user-id (or both).

param
listingIds the ids of listings to filter by, only listings matching the specified ids will be returned.
param
uids the ids of users to filter by, only listings submitted by those users will be returned.
return
A list of marketplace listings that meet the specified filter criteria.
throws
FacebookException if an error happens when executing the API call.
throws
IOException if a communication/network error happens.

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

public java.util.Listmarketplace_getSubCategories()
Return a list of all valid Marketplace subcategories.

return
a list of marketplace subcategories allowed by Facebook.
throws
FacebookException if an error happens when executing the API call.
throws
IOException if a communication/network error happens.

public booleanmarketplace_removeListing(java.lang.Long listingId)
Remove a marketplace listing. The create_listing extended permission is required.

param
listingId the listing to be removed
return
boolean indicating whether the listing was removed
see
#users_hasAppPermission
see
FacebookExtendedPerm#MARKETPLACE
see
Developers Wiki: marketplace.removeListing

public booleanmarketplace_removeListing(java.lang.Long listingId, java.lang.CharSequence status)
Remove a marketplace listing. The create_listing extended permission is required.

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
#users_hasAppPermission
see
FacebookExtendedPerm#MARKETPLACE
see
Developers Wiki: marketplace.removeListing
deprecated
provided for legacy support only. Please use the version that takes a MarketListingStatus instead.

public booleanmarketplace_removeListing(java.lang.Long listingId, com.facebook.api.MarketListingStatus status)
Remove a listing from the marketplace by id.

param
listingId the id of the listing to remove.
param
status the status to apply when removing the listing. Should be one of MarketListingStatus.SUCCESS or MarketListingStatus.NOT_SUCCESS.
return
true if the listing was successfully removed false otherwise
throws
FacebookException if an error happens when executing the API call.
throws
IOException if a communication/network error happens.

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
deprecated
provided for legacy support only. Please use the alternate version instead.

public java.util.Listmarketplace_search(com.facebook.api.MarketListingCategory category, com.facebook.api.MarketListingSubcategory subcategory, java.lang.String searchTerm)
Search the marketplace listings by category, subcategory, and keyword.

param
category the category to search in, optional (unless subcategory is specified).
param
subcategory the subcategory to search in, optional.
param
searchTerm the keyword to search for, optional.
return
a list of marketplace entries that match the specified search parameters.
throws
FacebookException if an error happens when executing the API call.
throws
IOException if a communication/network error happens.

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'

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

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

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

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
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

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
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

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

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

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

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

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.

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.

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.

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

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.

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

public voidsetDebug(boolean isDebug)
Toggle debug mode.

param
isDebug set to true to enable debug set to false to disable debug

public voidsetIsDesktop(boolean isDesktop)
Set the client to run in desktop-app mode.

param
isDesktop set to true to enable desktop mode set to false to disable desktop mode

public booleansms_canSend()
Check to see if the application is permitted to send SMS messages to the current application user.

return
true if the application is presently able to send SMS messages to the current user false otherwise
throws
FacebookException if an error happens when executing the API call.
throws
IOException if a communication/network error happens.

public booleansms_canSend(java.lang.Long userId)
Check to see if the application is permitted to send SMS messages to the specified user.

param
userId the UID of the user to check permissions for
return
true if the application is presently able to send SMS messages to the specified user false otherwise
throws
FacebookException if an error happens when executing the API call.
throws
IOException if a communication/network error happens.

public java.lang.Integersms_send(java.lang.String message, java.lang.Integer smsSessionId, boolean makeNewSession)
Send an SMS message to the current application user.

param
message the message to send.
param
smsSessionId the SMS session id to use, note that that is distinct from the user's facebook session id. It is used to allow applications to keep track of individual SMS conversations/threads for a single user. Specify null if you do not want/need to use a session for the current message.
param
makeNewSession set to true to request that Facebook allocate a new SMS session id for this message. The allocated id will be returned as the result of this API call. You should only set this to true if you are passing a null 'smsSessionId' value. Otherwise you already have a SMS session id, and do not need a new one.
return
an integer specifying the value of the session id alocated by Facebook, if one was requested. If a new session id was not requested, this method will return null.
throws
FacebookException if an error happens when executing the API call.
throws
IOException if a communication/network error happens.

public java.lang.Integersms_send(java.lang.Long userId, java.lang.String message, java.lang.Integer smsSessionId, boolean makeNewSession)
Send an SMS message to the specified user.

param
userId the id of the user to send the message to.
param
message the message to send.
param
smsSessionId the SMS session id to use, note that that is distinct from the user's facebook session id. It is used to allow applications to keep track of individual SMS conversations/threads for a single user. Specify null if you do not want/need to use a session for the current message.
param
makeNewSession set to true to request that Facebook allocate a new SMS session id for this message. The allocated id will be returned as the result of this API call. You should only set this to true if you are passing a null 'smsSessionId' value. Otherwise you already have a SMS session id, and do not need a new one.
return
an integer specifying the value of the session id alocated by Facebook, if one was requested. If a new session id was not requested, this method will return null.
throws
FacebookException if an error happens when executing the API call.
throws
IOException if a communication/network error happens.

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

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

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

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.

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.

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

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
deprecated
provided for legacy support only. Please use the alternate version.

public booleanusers_hasAppPermission(com.facebook.api.Permission perm)
Check to see if the user has granted the app a specific external permission. In order to be granted a permission, an application must direct the user to a URL of the form: http://www.facebook.com/authorize.php?api_key=[YOUR_API_KEY]&v=1.0&ext_perm=[PERMISSION NAME]

param
perm the permission to check for
return
true if the user has granted the application the specified permission false otherwise
throws
FacebookException if an error happens when executing the API call.
throws
IOException if a communication/network error happens.

public booleanusers_isAppAdded()
Retrieves an indicator of whether the logged-in user has added the application associated with the _apiKey.

return
boolean indicating whether the user has added the app
see
Developers Wiki: Users.isAppAdded

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

public booleanusers_setStatus(java.lang.String newStatus, boolean clear)
Set the user's profile status message. This requires that the user has granted the application the 'status_update' permission, otherwise the call will return an error. You can use 'users_hasAppPermission' to check to see if the user has granted your app the abbility to update their status.

param
newStatus the new status message to set.
param
clear whether or not to clear the old status message.
return
true if the call succeeds false otherwise
throws
FacebookException if an error happens when executing the API call.
throws
IOException if a communication/network error happens.