Update for Facebook v2.0

Author: Craig Walls

build.gradle

@@ -44,6 +44,13 @@ configure(allprojects - docProjects) {
         testCompile "org.springframework:spring-test:$springVersion"
     }
 
+    ext.javadocLinks = [
+        "http://docs.oracle.com/javase/7/docs/api/",
+        "http://docs.oracle.com/javaee/7/api/",
+        "http://docs.spring.io/spring/docs/${springVersion}/javadoc-api/",
+        "http://docs.jboss.org/jbossas/javadoc/4.0.5/connector/"
+    ] as String[]
+
     // servlet-api (2.5) and tomcat-servlet-api (3.0) classpath entries should not be
     // exported to dependent projects in Eclipse to avoid false compilation errors due
     // to changing APIs across these versions
@@ -62,10 +69,6 @@ configure(allprojects - docProjects) {
     }
 }
 
-ext.javadocLinks = [
-    "http://docs.jboss.org/jbossas/javadoc/4.0.5/connector"
-] as String[]
-
 configure(subprojects - docProjects) { subproject ->
     apply from: "${rootProject.projectDir}/publish-maven.gradle"
 
@@ -82,9 +85,15 @@ configure(subprojects - docProjects) { subproject ->
     }
 
     javadoc {
+        description = "Generates project-level javadoc for use in -javadoc jar"
+
         options.memberLevel = org.gradle.external.javadoc.JavadocMemberLevel.PROTECTED
         options.author = true
         options.header = project.name
+        options.links(project.ext.javadocLinks)
+        if (JavaVersion.current().isJava8Compatible()) {
+            options.addStringOption('Xdoclint:none', '-quiet')
+        }
         //options.overview = "${projectDir}/src/main/java/overview.html"
     }
 
@@ -195,6 +204,9 @@ configure(rootProject) {
         options.header = rootProject.description
         options.overview = "src/api/overview.html"
         options.links(project.ext.javadocLinks)
+        if (JavaVersion.current().isJava8Compatible()) {
+            options.addStringOption('Xdoclint:none', '-quiet')
+        }
 
         source subprojects.collect { project ->
             project.sourceSets.main.allJava

spring-social-facebook-web/src/main/java/org/springframework/social/facebook/web/CanvasSignInController.java

@@ -84,7 +84,7 @@ public CanvasSignInController(ConnectionFactoryLocator connectionFactoryLocator,
 
 	/**
 	 * The URL or path to redirect to after successful canvas authorization.
-	 * Defaults to "/".
+	 * @param postSignInUrl the url to redirect to after successful canvas authorization. Defaults to "/".
 	 */
 	public void setPostSignInUrl(String postSignInUrl) {
 		this.postSignInUrl = postSignInUrl;
@@ -94,15 +94,15 @@ public void setPostSignInUrl(String postSignInUrl) {
 	 * The URL or path to redirect to if a user declines authorization.
 	 * The redirect will happen in the top-level window. 
 	 * If you want the redirect to happen in the canvas iframe, then override the {@link #postDeclineView()} method to return a different implementation of {@link View}.
-	 * Defaults to "http://www.facebook.com".
+	 * @param postDeclineUrl the url to redirect to after a user declines authorization. Defaults to "http://www.facebook.com".
 	 */
 	public void setPostDeclineUrl(String postDeclineUrl) {
 		this.postDeclineUrl = postDeclineUrl;
 	}
 
 	/**
 	 * The scope to request during authorization.
-	 * Defaults to null (no scope will be requested; Facebook will offer their default scope).
+	 * @param scope the scope to request. Defaults to null (no scope will be requested; Facebook will offer their default scope).
 	 */
 	public void setScope(String scope) {
 		this.scope = scope;
@@ -160,6 +160,7 @@ public View error(@RequestParam("error") String error, @RequestParam("error_desc
 	/**
 	 * View that redirects the top level window to the URL defined in postDeclineUrl property after user declines to authorize application.
 	 * May be overridden for custom views, particularly in the case where the post-decline view should be rendered in-canvas.
+	 * @return a view to display after a user declines authoriation. Defaults as a redirect to postDeclineUrl
 	 */
 	protected View postDeclineView() {
 		return new TopLevelWindowRedirect() {

spring-social-facebook-web/src/main/java/org/springframework/social/facebook/web/FacebookCookieParser.java

@@ -35,6 +35,10 @@ public class FacebookCookieParser {
 
 	/**
 	 * Looks for a Facebook cookie for the given API Key and returns its data as key/value pairs in a Map.
+	 * @param cookies an array of Cookie objects
+	 * @param appId the application's Facebook App ID
+	 * @param appSecret the application's Facebook App Secret
+	 * @return a Map containing the Facebook cookie data
 	 */
 	public static Map<String, String> getFacebookCookieData(Cookie[] cookies, String appId, String appSecret) {
 		if (cookies != null) {

spring-social-facebook-web/src/main/java/org/springframework/social/facebook/web/FacebookCookieValue.java

@@ -33,13 +33,15 @@
 
 	/**
 	 * The specific element of the cookie to be bound (e.g., "uid", "expires", etc)
+	 * @return the cookie element name
 	 */
 	public String value() default "";
 
 	/**
 	 * Whether the Facebook cookie value is required.
 	 * Default is true, leading to an exception being thrown in case the Facebook cookie is missing or if the value can't be found in the cookie. 
 	 * Switch this to false if you prefer a null in case of the missing cookie/value.
+	 * @return true if the cookie value is required
 	 */
 	boolean required() default true;
 }

spring-social-facebook-web/src/main/java/org/springframework/social/facebook/web/FacebookInitTag.java

@@ -31,7 +31,7 @@ public class FacebookInitTag extends TagSupport {
 
 	/**
 	 * Sets the application's Facebook ID.
-	 * @param appId
+	 * @param appId the applicatin's Facebook App ID
 	 */
 	public void setAppId(String appId) {
 		this.appId = appId;

spring-social-facebook-web/src/main/java/org/springframework/social/facebook/web/FacebookWebArgumentResolver.java

@@ -41,6 +41,8 @@ public class FacebookWebArgumentResolver implements WebArgumentResolver {
 	/**
 	 * Construct a FacebookWebArgumentResolver given the Facebook app id and secret.
 	 * The application secret will be used to verify the cookie signature.
+	 * @param appId the application's Facebook App ID
+	 * @param appSecret the application's Facebook App Secret
 	 */
 	public FacebookWebArgumentResolver(String appId, String appSecret) {
 		this.appId = appId;

spring-social-facebook-web/src/main/java/org/springframework/social/facebook/web/RealTimeUpdate.java

@@ -35,14 +35,14 @@ public class RealTimeUpdate {
 	private List<Entry> entries;
 
 	/**
-	 * The object type that changed (e.g., "user", "page", etc).
+	 * @return the object type that changed (e.g., "user", "page", etc).
 	 */
 	public String getObject() {
 		return object;
 	}
 
 	/**
-	 * Entries that changed. Multiple change entries for multiple objects may be given in a single update.
+	 * @return the entries that changed. Multiple change entries for multiple objects may be given in a single update.
 	 */
 	public List<Entry> getEntries() {
 		return entries;
@@ -63,22 +63,21 @@ public static class Entry {
 		private List<String> changedFields;
 
 		/**
-		 * The ID of the object that changed (e.g., if the object is a "user", then this is the user's Facebook ID).
+		 * @return the ID of the object that changed (e.g., if the object is a "user", then this is the user's Facebook ID).
 		 */
 		public long getId() {
 			return id;
 		}
 
 		/**
-		 * The time of the change in seconds since Jan 1, 1970.
+		 * @return the time of the change in seconds since Jan 1, 1970.
 		 */
 		public long getTime() {
 			return time;
 		}
 
 		/**
-		 * A list of the fields that changed on the object.
-		 * {@link UpdateHandler} implementations may use this as a clue to know what data to fetch to see the details of the change.
+		 * @return a list of the fields that changed on the object. {@link UpdateHandler} implementations may use this as a clue to know what data to fetch to see the details of the change.
 		 */
 		public List<String> getChangedFields() {
 			return changedFields;

spring-social-facebook-web/src/main/java/org/springframework/social/facebook/web/RealTimeUpdateController.java

@@ -62,6 +62,7 @@ public class RealTimeUpdateController {
 	 * Constructs a RealTimeUpdateController.
 	 * @param tokens A map of subscription names to verification tokens.
 	 * @param updateHandlers A list of {@link UpdateHandler} implementations to handle incoming updates.
+	 * @param applicationSecret the application's Facebook App Secret
 	 */
 	public RealTimeUpdateController(Map<String, String> tokens, List<UpdateHandler> updateHandlers, String applicationSecret) {
 		this.tokens = tokens;
@@ -90,6 +91,8 @@ public RealTimeUpdateController(Map<String, String> tokens, List<UpdateHandler>
 	 * @param subscription The subscription name.
 	 * @param payload The request body payload.
 	 * @param signature The SHA1 signature of the request.
+	 * @return a String with the response back to Facebook
+	 * @throws Exception an Exception if anything goes wrong while processing the update
 	 */
 	@RequestMapping(value="/{subscription}", method=POST)
 	public @ResponseBody String receiveUpdate(

spring-social-facebook-web/src/main/java/org/springframework/social/facebook/web/SignedRequest.java

@@ -33,6 +33,7 @@
 	 * Whether the signed_request parameter is required.
 	 * Default is true, leading to an exception being thrown in case signed_request is missing. 
 	 * Switch this to false if you prefer a null in case of a missing signed_request parameter.
+	 * @return true if the parameter is required
 	 */
 	boolean required() default true;
 }

spring-social-facebook-web/src/main/java/org/springframework/social/facebook/web/SignedRequestDecoder.java

@@ -54,6 +54,7 @@ public SignedRequestDecoder(String secret) {
 	 * Decodes a signed request, returning the payload of the signed request as a Map
 	 * @param signedRequest the value of the signed_request parameter sent by Facebook.
 	 * @return the payload of the signed request as a Map
+	 * @throws SignedRequestException if there is an error decoding the signed request
 	 */
 	@SuppressWarnings("unchecked")
 	public Map<String, ?> decodeSignedRequest(String signedRequest) throws SignedRequestException {
@@ -64,7 +65,9 @@ public SignedRequestDecoder(String secret) {
 	 * Decodes a signed request, returning the payload of the signed request as a specified type.
 	 * @param signedRequest the value of the signed_request parameter sent by Facebook.
 	 * @param type the type to bind the signed_request to.
+	 * @param <T> the Java type to bind the signed_request to.
 	 * @return the payload of the signed request as an object
+	 * @throws SignedRequestException if there is an error decoding the signed request
 	 */
 	public <T> T decodeSignedRequest(String signedRequest, Class<T> type) throws SignedRequestException {
 		String[] split = signedRequest.split("\\.");