Refine a few PageOperations methods. Introduce a facebookOperations() method to return page-specific FacebookTemplate. SOCIALFB-181

Author: Craig Walls

spring-social-facebook/src/main/java/org/springframework/social/facebook/api/GraphApi.java

@@ -111,6 +111,16 @@ public interface GraphApi {
 	 */
 	String publish(String objectId, String connectionName, MultiValueMap<String, Object> data);	
 
+	/**
+	 * Publishes data to an object. 
+	 * Requires appropriate permission to publish to the object connection.
+	 * This differs from publish() only in that it doesn't attempt to extract the ID from the response.
+	 * This is because some publish operations do not return an ID in the response.
+	 * @param objectId the object ID to publish to.
+	 * @param data the data to publish to the object.
+	 */
+	void post(String objectId, MultiValueMap<String, Object> data);
+
 	/**
 	 * Publishes data to an object's connection. 
 	 * Requires appropriate permission to publish to the object connection.
@@ -120,7 +130,7 @@ public interface GraphApi {
 	 * @param connectionName the connection name to publish to.
 	 * @param data the data to publish to the connection.
 	 */
-	void post(String objectId, String connectionName, MultiValueMap<String, String> data);
+	void post(String objectId, String connectionName, MultiValueMap<String, Object> data);
 
 	/**
 	 * Deletes an object.

spring-social-facebook/src/main/java/org/springframework/social/facebook/api/MediaOperations.java

@@ -93,6 +93,19 @@ public interface MediaOperations {
 	 */
 	String createAlbum(String name, String description);
 
+	/**
+	 * Creates a new photo album.
+	 * Requires "user_photos" permission.
+	 * @param ownerId the owner of the album, possibly a page ID.
+	 * @param name the name of the album.
+	 * @param description the album's description.
+	 * @return the ID of the newly created album.
+	 * @throws ApiException if there is an error while communicating with Facebook.
+	 * @throws InsufficientPermissionException if the user has not granted "user_photos" permission.
+	 * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token.
+	 */
+	String createAlbum(String ownerId, String name, String description);
+	
 	/**
 	 * Retrieves an album's image as an array of bytes. Returns the image in Facebook's "normal" type.
 	 * Requires "user_photos" permission if the album is not public.

spring-social-facebook/src/main/java/org/springframework/social/facebook/api/PageOperations.java

@@ -35,6 +35,13 @@ public interface PageOperations {
 	 */
 	Page getPage(String pageId);
 
+	/**
+	 * Updates page information.
+	 * Requires that the application is granted "manage_pages" permission and that the authenticated user be an administrator of the page.
+	 * @param pageUpdate a {@link PageUpdate} object that carries the fields to update on the page.
+	 */
+	void updatePage(PageUpdate pageUpdate);
+	
 	/**
 	 * Checks whether the logged-in user for this session is an admin of the page with the given page ID.
 	 * Requires "manage_pages" permission.
@@ -164,4 +171,11 @@ public interface PageOperations {
 	 */
 	Account getAccount(String pageId);
 
+	/**
+	 * Returns a {@link Facebook} instance that will act on behalf of the given page.
+	 * @param pageId the page to create a {@link Facebook} instance for.
+	 * @return a {@link Facebook} instance for the page.
+	 */
+	Facebook facebookOperations(String pageId);
+	
 }

spring-social-facebook/src/main/java/org/springframework/social/facebook/api/PagePostData.java

@@ -22,7 +22,7 @@
 /**
  * An object that represents a new post to be created. 
  * Offers a builder-like way of creating a new post.
- * Given to {@link FeedOperations#post(PagePostData)}.
+ * Given to {@link PageOperations#post(PagePostData)}.
  * @author Craig Walls
  */
 public class PagePostData {
@@ -71,7 +71,7 @@ public PagePostData message(String message) {
 	 * @param picture A preview image associated with the link. May be null.
 	 * @param name Overwrites the title of the link preview. May be null.
 	 * @param caption Overwrites the caption of the link preview. May be null.
-	 * @description Overwrites the caption of hte link preview. May be null.
+	 * @param description Overwrites the caption of hte link preview. May be null.
 	 * @return the PagePostData object for additional configuration
 	 */
 	public PagePostData link(String linkUrl, String picture, String name, String caption, String description) {

spring-social-facebook/src/main/java/org/springframework/social/facebook/api/PageUpdate.java

@@ -0,0 +1,102 @@
+/*
+ * Copyright 2015 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.social.facebook.api;
+
+import org.springframework.util.LinkedMultiValueMap;
+import org.springframework.util.MultiValueMap;
+
+/**
+ * An object that captures data used to update a Page.
+ * @author Craig Walls
+ */
+public class PageUpdate {
+
+	private final String pageId;
+	
+	private String about;
+	
+	private String bio;
+	
+	private String cover;
+	
+	private String name;
+	
+	private Integer offsetX;
+	
+	private Integer offsetY;
+
+	private Float zoomScaleX;
+
+	private Float zoomScaleY;
+
+	private Float focusX;
+
+	private Float focusY;
+	
+	/**
+	 * Creates a new {@link PageUpdate}.
+	 * @param pageId The ID of the page to update.
+	 */
+	public PageUpdate(String pageId) {
+		this.pageId = pageId;
+	}
+	
+	public String getPageId() {
+		return pageId;
+	}
+	
+	public PageUpdate about(String about) {
+		this.about = about;
+		return this;
+	}
+	
+	public PageUpdate bio(String bio) {
+		this.bio = bio;
+		return this;
+	}
+	
+	public PageUpdate cover(String cover, Integer offsetX, Integer offsetY, Float zoomScaleX, Float zoomScaleY, Float focusX, Float focusY) {
+		this.cover = cover;
+		this.offsetX = offsetX;
+		this.offsetY = offsetY;
+		this.zoomScaleX = zoomScaleX;
+		this.zoomScaleY = zoomScaleY;
+		this.focusX = focusX;
+		this.focusY = focusY;
+		return this;
+	}
+	
+	public PageUpdate name(String name) {
+		this.name = name;
+		return this;
+	}
+	
+	public MultiValueMap<String, Object> toRequestParameters() {
+		MultiValueMap<String, Object> parameters = new LinkedMultiValueMap<String, Object>();
+		if (about != null) { parameters.add("about", about); }
+		if (bio != null) { parameters.add("bio", bio); }
+		if (cover != null) { parameters.add("cover", cover); }
+		if (name != null) { parameters.add("name", name); }
+		if (offsetX != null) { parameters.add("offset_x", offsetX.toString()); }
+		if (offsetY != null) { parameters.add("offset_y", offsetY.toString()); }
+		if (zoomScaleX != null) { parameters.add("zoom_scale_x", zoomScaleX.toString()); }
+		if (zoomScaleY != null) { parameters.add("zoom_scale_y", zoomScaleY.toString()); }
+		if (focusX != null) { parameters.add("focus_x", focusX.toString()); }
+		if (focusY != null) { parameters.add("focus_y", focusY.toString()); }
+		return parameters;
+	}
+
+}

spring-social-facebook/src/main/java/org/springframework/social/facebook/api/PostData.java

@@ -77,7 +77,7 @@ public PostData message(String message) {
 	 * @param picture A preview image associated with the link. May be null.
 	 * @param name Overwrites the title of the link preview. May be null.
 	 * @param caption Overwrites the caption of the link preview. May be null.
-	 * @description Overwrites the caption of hte link preview. May be null.
+	 * @param description Overwrites the caption of hte link preview. May be null.
 	 * @return the PagePostData object for additional configuration
 	 */
 	public PostData link(String linkUrl, String picture, String name, String caption, String description) {

spring-social-facebook/src/main/java/org/springframework/social/facebook/api/impl/AchievementTemplate.java

@@ -64,7 +64,7 @@ public AchievementType getAchievementType(String achievementTypeId) {
 	}
 
 	public void createAchievementType(String achievementTypeUrl, int displayOrder) {
-		MultiValueMap<String, String> data = new LinkedMultiValueMap<String, String>();
+		MultiValueMap<String, Object> data = new LinkedMultiValueMap<String, Object>();
 		data.set("achievement", achievementTypeUrl);
 		data.set("display_order", String.valueOf(displayOrder));
 		graphApi.post("app", "achievements", data);

spring-social-facebook/src/main/java/org/springframework/social/facebook/api/impl/EventTemplate.java

@@ -109,15 +109,15 @@ public PagedList<EventInvitee> getDeclined(String eventId) {
 	}
 
 	public void acceptInvitation(String eventId) {
-		graphApi.post(eventId, "attending", new LinkedMultiValueMap<String, String>());
+		graphApi.post(eventId, "attending", new LinkedMultiValueMap<String, Object>());
 	}
 
 	public void maybeInvitation(String eventId) {
-		graphApi.post(eventId, "maybe", new LinkedMultiValueMap<String, String>());
+		graphApi.post(eventId, "maybe", new LinkedMultiValueMap<String, Object>());
 	}
 
 	public void declineInvitation(String eventId) {
-		graphApi.post(eventId, "declined", new LinkedMultiValueMap<String, String>());
+		graphApi.post(eventId, "declined", new LinkedMultiValueMap<String, Object>());
 	}
 
 	public PagedList<Event> search(String query) {

spring-social-facebook/src/main/java/org/springframework/social/facebook/api/impl/FacebookTemplate.java

@@ -284,9 +284,14 @@ public String publish(String objectId, String connectionType, MultiValueMap<Stri
 		return (String) response.get("id");
 	}
 
-	public void post(String objectId, String connectionType, MultiValueMap<String, String> data) {
-		URI uri = URIBuilder.fromUri(GRAPH_API_URL + objectId + "/" + connectionType).build();
-		getRestTemplate().postForObject(uri, new LinkedMultiValueMap<String, String>(data), String.class);
+	public void post(String objectId, MultiValueMap<String, Object> data) {
+		post(objectId, null, data);
+	}
+	
+	public void post(String objectId, String connectionType, MultiValueMap<String, Object> data) {
+		String connectionPath = connectionType != null ? "/" + connectionType : "";
+		URI uri = URIBuilder.fromUri(GRAPH_API_URL + objectId + connectionPath).build();
+		getRestTemplate().postForObject(uri, new LinkedMultiValueMap<String, Object>(data), String.class);
 	}
 
 	public void delete(String objectId) {

spring-social-facebook/src/main/java/org/springframework/social/facebook/api/impl/LikeTemplate.java

@@ -32,7 +32,7 @@ public LikeTemplate(GraphApi graphApi) {
 	}
 
 	public void like(String objectId) {
-		graphApi.post(objectId, "likes", new LinkedMultiValueMap<String, String>());
+		graphApi.post(objectId, "likes", new LinkedMultiValueMap<String, Object>());
 	}
 
 	public void unlike(String objectId) {

spring-social-facebook/src/main/java/org/springframework/social/facebook/api/impl/PageTemplate.java

@@ -21,20 +21,22 @@
 
 import org.springframework.core.io.Resource;
 import org.springframework.social.facebook.api.Account;
+import org.springframework.social.facebook.api.Facebook;
 import org.springframework.social.facebook.api.FacebookLink;
 import org.springframework.social.facebook.api.GraphApi;
 import org.springframework.social.facebook.api.Page;
 import org.springframework.social.facebook.api.PageAdministrationException;
 import org.springframework.social.facebook.api.PageOperations;
 import org.springframework.social.facebook.api.PagePostData;
+import org.springframework.social.facebook.api.PageUpdate;
 import org.springframework.social.facebook.api.PagedList;
 import org.springframework.util.LinkedMultiValueMap;
 import org.springframework.util.MultiValueMap;
 
 class PageTemplate implements PageOperations {
 
 	private final GraphApi graphApi;
-
+	
 	public PageTemplate(GraphApi graphApi) {
 		this.graphApi = graphApi;
 	}
@@ -43,6 +45,14 @@ public Page getPage(String pageId) {
 		return graphApi.fetchObject(pageId, Page.class);
 	}
 
+	public void updatePage(PageUpdate pageUpdate) {
+		String pageId = pageUpdate.getPageId();
+		String pageAccessToken = getAccessToken(pageId);
+		MultiValueMap<String, Object> map = pageUpdate.toRequestParameters();
+		map.add("access_token", pageAccessToken);
+		graphApi.post(pageId, map);
+	}
+	
 	public boolean isPageAdmin(String pageId) {
 		return getAccount(pageId) != null;
 	}
@@ -119,6 +129,10 @@ public Account getAccount(String pageId) {
 		}
 		return accountCache.get(pageId);
 	}
+	
+	public Facebook facebookOperations(String pageId) {
+		return new FacebookTemplate(getAccessToken(pageId));
+	}
 
 	// private helper methods