facebookrestclient.java

FACEBOOK上

    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);
  }

  /**
   * Creates an album.
   * @param albumName The list of photos from which to extract photo tags.
   * @return the created album
   */
  public T photos_createAlbum(String albumName)
    throws FacebookException, IOException {
    return this.photos_createAlbum(albumName, null, /*description*/null) /*location*/;
  }

  /**
   * 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 boolean photos_addTag(Long photoId, Integer taggedUserId, Double xPct, Double yPct)
    throws FacebookException, IOException {
    return photos_addTag(photoId, xPct, yPct, taggedUserId, null);
  }

  /**
   * 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 T photos_addTags(Long photoId, Collection<PhotoTag> tags)
    throws FacebookException, IOException {
    assert (photoId > 0);
    assert (null != tags && !tags.isEmpty());

    JSONArray jsonTags = new JSONArray();
    for (PhotoTag tag : tags) {
      jsonTags.add(tag.jsonify());
    }

    return this.callMethod(FacebookMethod.PHOTOS_ADD_TAG,
                           new Pair<String, CharSequence>("pid", photoId.toString()),
                           new Pair<String, CharSequence>("tags", jsonTags.toString()));
  }

  public void setIsDesktop(boolean isDesktop) {
    this._isDesktop = isDesktop;
  }

  /**
   * 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 T events_get(Integer userId, Collection<Long> eventIds, Long startTime, Long endTime)
    throws FacebookException, IOException {
    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", Integer.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);
  }

  /**
   * 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 boolean profile_setFBML(CharSequence fbmlMarkup, Integer userId)
    throws FacebookException, IOException {

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

  }

  /**
   * Associates a "<code>handle</code>" with FBML markup so that the handle can be used within the
   * <a href="http://wiki.developers.facebook.com/index.php/Fb:ref">fb:ref</a> 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 <a href="http://wiki.developers.facebook.com/index.php/Fbml.setRefHandle">
   *      Developers Wiki: Fbml.setRefHandle</a>
   */
  public boolean fbml_setRefHandle(CharSequence handle, CharSequence fbmlMarkup)
    throws FacebookException, IOException {

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

  }

  /**
   * Determines whether this application can send SMS to the user identified by <code>userId</code>
   * @param userId a user ID
   * @return true if sms can be sent to the user
   * @see FacebookExtendedPerm#SMS
   * @see <a href="http://wiki.developers.facebook.com/index.php/Mobile#Application_generated_messages">
   *      Developers Wiki: Mobile: Application Generated Messages</a>
   */
  public boolean sms_canSend(Integer userId)
    throws FacebookException, IOException {
    return extractBoolean(this.callMethod(FacebookMethod.SMS_CAN_SEND,
                                          new Pair<String, CharSequence>("uid",
                                                                         userId.toString())));
  }

  /**
   * Sends a message via SMS to the user identified by <code>userId</code> in response 
   * to a user query associated with <code>mobileSessionId</code>.
   *
   * @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 <a href="http://wiki.developers.facebook.com/index.php/Mobile#Application_generated_messages">
   * Developers Wiki: Mobile: Application Generated Messages</a>
   * @see <a href="http://wiki.developers.facebook.com/index.php/Mobile#Workflow">
   * Developers Wiki: Mobile: Workflow</a>
   */
  public void sms_sendResponse(Integer userId, CharSequence response, Integer mobileSessionId)
    throws FacebookException, IOException {
    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()));
  }

  /**
   * Sends a message via SMS to the user identified by <code>userId</code>.
   * 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 <a href="http://wiki.developers.facebook.com/index.php/Mobile#Application_generated_messages">
   * Developers Wiki: Mobile: Application Generated Messages</a>
   * @see <a href="http://wiki.developers.facebook.com/index.php/Mobile#Workflow">
   * Developers Wiki: Mobile: Workflow</a>
   */
  public void sms_sendMessage(Integer userId, CharSequence message)
    throws FacebookException, IOException {
    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"));
  }

  /**
   * Sends a message via SMS to the user identified by <code>userId</code>, 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 <a href="http://wiki.developers.facebook.com/index.php/Mobile#Application_generated_messages">
   *      Developers Wiki: Mobile: Application Generated Messages</a>
   * @see <a href="http://wiki.developers.facebook.com/index.php/Mobile#Workflow">
   *      Developers Wiki: Mobile: Workflow</a>
   */
  public int sms_sendMessageWithSession(Integer userId, CharSequence message)
    throws FacebookException, IOException {
    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")));
  }


  /**
   * Delimits a collection entries into a single CharSequence, using <code>delimiter</code>
   * to delimit each entry, and <code>equals</code> to delimit the key from the value inside
   * each entry.
   * @param entries
   * @param delimiter used to delimit one entry from another
   * @param equals used to delimit key from value
   * @param doEncode whether to encode the value of each entry
   * @return a CharSequence that contains all the entries, appropriately delimited
   */
  protected static CharSequence delimit(Collection<Map.Entry<String, CharSequence>> entries,
                                        CharSequence delimiter, 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;
  }

  /**
   * 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 T photos_createAlbum(String name, String description, String location)
    throws FacebookException, IOException {
    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 void setDebug(boolean isDebug) {
    _debug = isDebug;
  }

  /**
   * Extracts a Boolean from a result that consists of a Boolean only.
   * @param result
   * @return the Boolean
   */
  protected boolean extractBoolean(T result) {
    return 1 == extractInt(result);
  }

  /**
   * Extracts an Integer from a result that consists of an Integer only.
   * @param result
   * @return the Integer
   */
  protected abstract int extractInt(T result);

  /**
   * Extracts an Long from a result that consists of a Long only.
   * @param result
   * @return the Long
   */
  protected abstract Long extractLong(T result);

  /**
   * 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 <a href="http://wiki.developers.facebook.com/index.php/Photos.getAlbums">
   *      Developers Wiki: Photos.getAlbums</a>
   */
  public T photos_getAlbums(Collection<Long> albumIds)
    throws FacebookException, IOException {
    re