Merge pull request spring-attic#11 from habuma/master

A few small improvements and polish.

docs/src/info/changelog.txt

@@ -1,3 +1,16 @@
+Spring Social LinkedIn 1.0.0 Release Candidate 1 (February 21, 2012)
+====================================================================
+Improvements:
+ - Added start and count parameters to ConnectionOperations.getConnections()
+   to support pagination of results. (SOCIALLI-13)
+ - Changed JSON property names sent in request for invitation to connect--
+   CommunicationOperations.connectTo()--to better align with LinkedIn's
+   API documentation. (SOCIALLI-17)
+
+Misc:
+ - Renamed ApiStandardProfileRequest to ConnectionAuthorization
+ - Added more JavaDoc
+
 Spring Social LinkedIn 1.0.0 Milestone 5 (January 23, 2012)
 ===========================================================
 Bug Fixes:

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/CodeAndName.java

@@ -18,8 +18,9 @@
 import java.io.Serializable;
 
 /**
- * Contains LinkedIn structure which contains a code and a name for that code
- * 
+ * Contains LinkedIn structure which contains a code and a name for that code.
+ * The LinkedIn API returns a code/name pair for several of its fields (e.g., product category, company type, etc).
+ * This class generically captures the code/name pair for a field.
  * @author Robert Drysdale
  */
 public class CodeAndName implements Serializable {

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/CommunicationOperations.java

@@ -22,7 +22,6 @@
  * users on LinkedIn
  * 
  * @author Robert Drysdale
- *
  */
 public interface CommunicationOperations {
 
@@ -47,15 +46,16 @@ public interface CommunicationOperations {
 	void sendMessage(String subject, String body, String... recipientIds);
 
 	/**
-	 * Send a connect invitation message to recipientId
-	 * Requires id from LinkedInProfile object
+	 * Send a connect invitation message to recipientId.
+	 * When sending a connection invitation for a LinkedIn profile by ID, you must also provide a {@link ConnectionAuthorization} object.
+	 * This object is available from a {@link LinkedInProfile} object after doing a search.
 	 * 
 	 * @param subject The subject of message
 	 * @param body The body or text of message (does not support html)
 	 * @param recipientId Id of recipient
-	 * @param apiStandardProfileRequest Part of LinkedInProfile returned when perfroming a search
+	 * @param connectionAuthorization authorization required to create a connection the connection.
 	 */
-	void connectTo(String subject, String body, String recipientId, ApiStandardProfileRequest apiStandardProfileRequest);
+	void connectTo(String subject, String body, String recipientId, ConnectionAuthorization connectionAuthorization);
 
 	/**
 	 * Send a connect invitation message to and email (for users not on LinkedIn)

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/Companies.java

@@ -20,9 +20,9 @@
  * Search Result for querying companies
  * 
  * @author Robert Drysdale
- *
  */
 public class Companies extends SearchResult {
+
 	private static final long serialVersionUID = 1L;
 
 	private List<Company> companies;

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/Company.java

@@ -20,6 +20,8 @@
 
 /**
  * Model class representing a Company
+ * 
+ * @author Robert Drysdale
  */
 public class Company implements Serializable {
 

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/CompanyJobUpdate.java

@@ -17,10 +17,17 @@
 
 import java.io.Serializable;
 
+/**
+ * Model class representing a Company Job Update
+ * 
+ * @author Robert Drysdale
+ */
 public class CompanyJobUpdate implements Serializable {
+
 	private static final long serialVersionUID = 1L;
 
 	private String action;
+
 	private Job job;
 
 	public CompanyJobUpdate(String action, Job job) {

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/CompanyOperations.java

@@ -18,7 +18,7 @@
 import java.util.List;
 
 /**
- *	Operations related to Companies on LinkedIn
+ * Operations related to Companies on LinkedIn
  * 
  * @author Robert Drysdale
  */
@@ -78,6 +78,13 @@ public interface CompanyOperations {
 	 */
 	void stopFollowingCompany(int id);
 
+	/**
+	 * Get products for a company.
+	 * @param companyId the ID of the company to get products for.
+	 * @param start The starting point in the result set. Used with count for pagination.
+	 * @param count The number of products to return. Used with start for pagination.
+	 * @return the products for the specified company.
+	 */
 	Products getProducts(int companyId, int start, int count);
 
 }

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/ApiStandardProfileRequest.java → spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/ConnectionAuthorization.java

@@ -17,14 +17,22 @@
 
 import java.io.Serializable;
 
-public class ApiStandardProfileRequest implements Serializable {
+/**
+ * Carries authorization information required for connecting to another LinkedIn user by their ID.
+ * Obtained via a {@link LinkedInProfile} after a user profile search.
+ * 
+ * @author Robert Drysdale
+ * @author habuma
+ */
+public class ConnectionAuthorization implements Serializable {
+
+	private static final long serialVersionUID = 1L;
 
-	private static final long serialVersionUID = -4957171160371820101L;
-
 	private final String name;
+
 	private final String value;
 
-	public ApiStandardProfileRequest(String name, String value) {
+	public ConnectionAuthorization(String name, String value) {
 		this.name = name;
 		this.value = value;
 	}

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/ConnectionOperations.java

@@ -25,16 +25,22 @@
 public interface ConnectionOperations {
 
 	/**
-	 * Retrieves the 1st-degree connections from the current user's network.
-	 * 
+	 * Retrieves up to 500 of the 1st-degree connections from the current user's network.
 	 * @return the user's connections
 	 */
 	List<LinkedInProfile> getConnections();
 
+	/**
+	 * Retrieves the 1st-degree connections from the current user's network.
+	 * @param start The starting location in the result set. Used with count for pagination.
+	 * @param count The number of connections to return. The maximum value is 500. Used with start for pagination.
+	 * @return the user's connections
+	 */
+	List<LinkedInProfile> getConnections(int start, int count);
+
 	/**
 	 * Retrieve Network Statistics for User
 	 * Contains Count of First Degree and Second Degree Connections
-	 * 
 	 * @return Network Statistics
 	 */
 	NetworkStatistics getNetworkStatistics();

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/GroupSettings.java

@@ -25,6 +25,7 @@
  * @author Robert Drysdale
  */
 public class GroupSettings implements Serializable {
+
 	private static final long serialVersionUID = 1L;
 
 	private final Boolean allowMessagesFromMembers;

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/ImAccount.java

@@ -21,7 +21,6 @@
  * Model class representing IM (Instance Message) Account Details for a Profile on LinkedIn
  *  
  * @author Robert Drysdale
- *
  */
 public class ImAccount implements Serializable {
 

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/JobSearchParameters.java

@@ -19,7 +19,7 @@
 
 /**
  * Search parameters to search for jobs.
- * Leave parameters as null to turn off.
+ * Null parameters will not be used as search criteria.
  * 
  * @author Robert Drysdale
  */

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/LinkedIn.java

@@ -20,16 +20,9 @@
 import org.springframework.web.client.RestOperations;
 
 /**
- * <p>
- * Interface specifying a basic set of operations for interacting with LinkedIn.
- * Implemented by {@link LinkedInTemplate}.
- * </p>
- * 
- * <p>
- * Many of the methods contained in this interface require OAuth authentication
- * with LinkedIn. When a method's description speaks of the "current user", it
- * is referring to the user for whom the access token has been issued.
- * </p>
+ * Interface specifying a basic set of operations for interacting with LinkedIn. Implemented by {@link LinkedInTemplate}.
+ * Many of the methods contained in this interface require OAuth authentication with LinkedIn. 
+ * When a method's description speaks of the "current user", it is referring to the user for whom the access token has been issued.
  * 
  * @author Craig Walls
  * @author Robert Drysdale

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/LinkedInConnections.java

@@ -15,14 +15,17 @@
  */
 package org.springframework.social.linkedin.api;
 
+import java.io.Serializable;
 import java.util.List;
 
 /**
  * A model class containing a list of a user's connections on LinkedIn.
  * 
  * @author Craig Walls
  */
-public class LinkedInConnections {
+public class LinkedInConnections implements Serializable {
+
+	private static final long serialVersionUID = 1L;
 
 	private List<LinkedInProfile> connections;
 

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/LinkedInDate.java

@@ -15,14 +15,17 @@
  */
 package org.springframework.social.linkedin.api;
 
+import java.io.Serializable;
+
 /**
  * LinkedIn Date which just contains year, month and day
  * 
  * @author Robert Drysdale
- *
  */
-public class LinkedInDate {
+public class LinkedInDate implements Serializable {
 
+	private static final long serialVersionUID = 1L;
+
 	private final int year;
 
 	private final int month;

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/LinkedInNetworkUpdate.java

@@ -21,6 +21,7 @@
 
 /**
  * Model class containing a user's LinkedIn Network update information.
+ * 
  * @author Robert Drysdale
  */
 public class LinkedInNetworkUpdate implements Serializable {

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/LinkedInNetworkUpdates.java

@@ -15,14 +15,17 @@
  */
 package org.springframework.social.linkedin.api;
 
+import java.io.Serializable;
 import java.util.List;
 
 /**
  * A model class containing a list of a user's network updates on LinkedIn.
  * 
  * @author Robert Drysdale
  */
-public class LinkedInNetworkUpdates {
+public class LinkedInNetworkUpdates implements Serializable {
+
+	private static final long serialVersionUID = 1L;
 
 	private List<LinkedInNetworkUpdate> updates;
 

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/LinkedInProfile.java

@@ -19,6 +19,7 @@
 
 /**
  * Model class containing a user's LinkedIn profile information.
+ * 
  * @author Craig Walls
  */
 public class LinkedInProfile implements Serializable {
@@ -43,7 +44,7 @@ public class LinkedInProfile implements Serializable {
 
 	private String summary;
 
-	private ApiStandardProfileRequest apiStandardProfileRequest;
+	private ConnectionAuthorization connectionAuthorization;
 
 	public LinkedInProfile(String id, String firstName, String lastName, String headline, String industry, String publicProfileUrl, UrlResource siteStandardProfileRequest, String profilePictureUrl) {
 		this.id = id;
@@ -121,10 +122,10 @@ public String getSummary() {
 	}
 
 	/**
-	 * @return auth information required for connecting to user
+	 * @return Authorization information required for connecting to this user.
 	 */
-	public ApiStandardProfileRequest getApiStandardProfileRequest() {
-		return apiStandardProfileRequest;
+	public ConnectionAuthorization getConnectionAuthorization() {
+		return connectionAuthorization;
 	}
 
 }

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/Location.java

@@ -18,7 +18,7 @@
 import java.io.Serializable;
 
 /**
- * Location
+ * Model class representing a location.
  * 
  * @author Robert Drysdale
  */

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/MemberGroup.java

@@ -18,7 +18,7 @@
 import java.io.Serializable;
 
 /**
- * Member Group 
+ * Model class representing a Member Group. 
  * 
  * @author Robert Drysdale
  */

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/NetworkStatistics.java

@@ -21,9 +21,9 @@
  * Network Statistics 
  * 
  * @author Robert Drysdale
- *
  */
 public class NetworkStatistics implements Serializable {
+
 	private static final long serialVersionUID = 1L;
 
 	private final int firstDegreeCount;

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/NetworkUpdateParameters.java

@@ -20,7 +20,7 @@
 import java.util.List;
 
 /**
- * Model Object passed to getNetworkUpdates() to control what parameters are set on the Http GET request to LinkedIn Network Updates API.
+ * Model Object passed to getNetworkUpdates() to control what parameters are set on the HTTP GET request to LinkedIn Network Updates API.
  * 
  * @author Robert Drysdale
  */

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/PhoneNumber.java

@@ -21,7 +21,6 @@
  * Phone Number
  * 
  * @author Robert Drysdale
- *
  */
 public class PhoneNumber implements Serializable {
 

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/Post.java

@@ -19,10 +19,14 @@
 import java.util.Date;
 import java.util.List;
 
+/**
+ * Model class representing a Post.
+ * 
+ * @author Robert Drysdale
+ */
 public class Post implements Serializable {
 
-	private static final long serialVersionUID = 1L;
-
+	private static final long serialVersionUID = 1L;	
 
 	private final LinkedInProfile creator;
 

spring-social-linkedin/src/main/java/org/springframework/social/linkedin/api/Product.java

@@ -20,12 +20,12 @@
 import java.util.List;
 
 /**
- * Product
+ * Model class representing a product.
  * 
  * @author Robert Drysdale
- *
  */
 public class Product implements Serializable {
+
 	private static final long serialVersionUID = 1L;
 
 	private final Date creationTimestamp;