facebookrestclient.java

FACEBOOK上

  }

  /**
   * 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 <a href="http://wiki.developers.facebook.com/index.php/Users.setStatus">
   *      Developers Wiki: Users.setStatus</a>
   */
  public boolean users_clearStatus()
    throws FacebookException, IOException {
    return extractBoolean(this.callMethod(FacebookMethod.USERS_SET_STATUS,
                                          new Pair<String, CharSequence>("clear", "1")));
  }

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

  /**
   * 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(File)
   */
  protected InputStream postFileRequest(String methodName, Map<String, CharSequence> params)
    throws IOException {
    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;
    }
  }

  /**
   * Logs an exception with default message
   * @param e the exception
   */
  protected final void logException(Exception e) {
    logException("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
   */
  protected void logException(CharSequence msg, Exception e) {
    System.err.println(msg + ":" + e.getMessage());
    e.printStackTrace();
  }

  /**
   * Logs a message. Override this for more detailed logging.
   * @param message
   */
  protected void log(CharSequence message) {
    System.out.println(message);
  }

  /**
   * @return whether debugging is activated
   */
  public boolean isDebug() {
    return (null == _debug) ? DEBUG : _debug.booleanValue();
  }

  /**
   * Send a notification message to the specified users on behalf of the logged-in user.
   *
   * @param recipientIds the user ids to which the message is to be sent. if empty,
   *        notification will be sent to logged-in user.
   * @param notification the FBML to be displayed on the notifications page; only a stripped-down 
   *        set of FBML tags that result in text and links is allowed
   * @return a URL, possibly null, to which the user should be redirected to finalize
   * the sending of the email
   * @see <a href="http://wiki.developers.facebook.com/index.php/Notifications.sendEmail">
   *      Developers Wiki: notifications.send</a>
   */
  public void notifications_send(Collection<Integer> recipientIds, CharSequence notification)
    throws FacebookException, IOException {
    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));
    this.callMethod(FacebookMethod.NOTIFICATIONS_SEND, args);
  }

  /**
   * Send a notification message to the logged-in user.
   *
   * @param notification the FBML to be displayed on the notifications page; only a stripped-down 
   *    set of FBML tags that result in text and links is allowed
   * @return a URL, possibly null, to which the user should be redirected to finalize
   * the sending of the email
   * @see <a href="http://wiki.developers.facebook.com/index.php/Notifications.sendEmail">
   *      Developers Wiki: notifications.send</a>
   */
  public void notifications_send(CharSequence notification)
    throws FacebookException, IOException {
    notifications_send(/*recipients*/null, notification);
  }

  /**
   * Sends a notification email to the specified users, who must have added your application.
   * You can send five (5) emails to a user per day. Requires a session key for desktop applications, which may only 
   * send email to the person whose session it is. This method does not require a session for Web applications. 
   * Either <code>fbml</code> or <code>text</code> must be specified.
   * 
   * @param recipientIds up to 100 user ids to which the message is to be sent
   * @param subject the subject of the notification email (optional)
   * @param fbml markup to be sent to the specified users via email; only a stripped-down set of FBML tags
   *    that result in text, links and linebreaks is allowed
   * @param text the plain text to send to the specified users via email
   * @return a comma-separated list of the IDs of the users to whom the email was successfully sent
   * @see <a href="http://wiki.developers.facebook.com/index.php/Notifications.send">
   *      Developers Wiki: notifications.sendEmail</a>
   */
  public String notifications_sendEmail(Collection<Integer> recipientIds, CharSequence subject, CharSequence fbml, CharSequence text)
    throws FacebookException, IOException {
    if (null == recipientIds || recipientIds.isEmpty()) {
      throw new IllegalArgumentException("List of email recipients cannot be empty");
    }
    boolean hasText = null != text && (0 != text.length());
    boolean hasFbml = null != fbml && (0 != fbml.length());
    if (!hasText && !hasFbml) {
      throw new IllegalArgumentException("Text and/or fbml must not be empty");
    }
    ArrayList<Pair<String, CharSequence>> args = new ArrayList<Pair<String, CharSequence>>(4);
    args.add(new Pair<String, CharSequence>("recipients", delimit(recipientIds)));
    args.add(new Pair<String, CharSequence>("subject", subject));
    if (hasText) {
      args.add(new Pair<String, CharSequence>("text", text));
    }
    if (hasFbml) {
      args.add(new Pair<String, CharSequence>("fbml", fbml));
    }
    // this method requires a session only if we're dealing with a desktop app
    T result = this.callMethod(this.isDesktop() ? FacebookMethod.NOTIFICATIONS_SEND_EMAIL
                 : FacebookMethod.NOTIFICATIONS_SEND_EMAIL, args);
    return extractString(result);
  }

  /**
   * Sends a notification email to the specified users, who must have added your application.
   * You can send five (5) emails to a user per day. Requires a session key for desktop applications, which may only
   * send email to the person whose session it is. This method does not require a session for Web applications.
   *
   * @param recipientIds up to 100 user ids to which the message is to be sent
   * @param subject the subject of the notification email (optional)
   * @param fbml markup to be sent to the specified users via email; only a stripped-down set of FBML
   *    that allows only tags that result in text, links and linebreaks is allowed
   * @return a comma-separated list of the IDs of the users to whom the email was successfully sent
   * @see <a href="http://wiki.developers.facebook.com/index.php/Notifications.send">
   *      Developers Wiki: notifications.sendEmail</a>
   */
  public String notifications_sendEmail(Collection<Integer> recipientIds, CharSequence subject, CharSequence fbml)
    throws FacebookException, IOException {
    return notifications_sendEmail(recipientIds, subject, fbml, /*text*/null);
  }

  /**
   * Sends a notification email to the specified users, who must have added your application.
   * You can send five (5) emails to a user per day. Requires a session key for desktop applications, which may only
   * send email to the person whose session it is. This method does not require a session for Web applications.
   *
   * @param recipientIds up to 100 user ids to which the message is to be sent
   * @param subject the subject of the notification email (optional)
   * @param text the plain text to send to the specified users via email
   * @return a comma-separated list of the IDs of the users to whom the email was successfully sent
   * @see <a href="http://wiki.developers.facebook.com/index.php/Notifications.sendEmail">
   *      Developers Wiki: notifications.sendEmail</a>
   */
  public String notifications_sendEmailPlain(Collection<Integer> recipientIds, CharSequence subject, CharSequence text)
    throws FacebookException, IOException {
    return notifications_sendEmail(recipientIds, subject, /*fbml*/null, text);
  }

  /**
   * Extracts a URL from a result that consists of a URL only.
   * @param result
   * @return the URL
   */
  protected abstract URL extractURL(T result)
    throws IOException;

  /**
   * Recaches the image with the specified imageUrl.
   * @param imageUrl String representing the image URL to refresh
   * @return boolean indicating whether the refresh succeeded
   */
  public boolean fbml_refreshImgSrc(String imageUrl)
    throws FacebookException, IOException {
    return fbml_refreshImgSrc(new URL(imageUrl));
  }

  /**
   * Uploads a photo to Facebook.
   * @param photo an image file
   * @return a T with the standard Facebook photo information
   * @see <a href="http://wiki.developers.facebook.com/index.php/Photos.upload">
   *      Developers wiki: Photos.upload</a>
   */
  public T photos_upload(File photo)
    throws FacebookException, IOException {
    return photos_upload(photo, /*caption*/ null, /*albumId*/ null) ;
  }

  /**
   * 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 <a href="http://wiki.developers.facebook.com/index.php/Photos.upload">
   *      Developers wiki: Photos.upload</a>
   */
  public T photos_upload(File photo, String caption)
    throws FacebookException, IOException {
    return photos_upload(photo, caption, /*albumId*/null) ;
  }

  /**
   * 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 <a href="http://wiki.developers.facebook.com/index.php/Photos.upload">
   *      Developers wiki: Photos.upload</a>
   */
  public T photos_upload(File photo, Long albumId)
    throws FacebookException, IOException {
    return photos_upload(photo, /*caption*/null, 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 <a href="http://wiki.developers.facebook.com/index.php/Photos.upload">
   * Developers wiki: Photos.upload</a>
   */
  public T photos_upload(File photo, String caption, Long albumId)
    throws FacebookException, IOException {