GUACAMOLE-1123: Fixes to comments, method scope, and minor code tweaks.

extensions/guacamole-auth-jdbc/modules/guacamole-auth-jdbc-base/src/main/java/org/apache/guacamole/auth/jdbc/connection/ConnectionRecordSet.java

@@ -46,7 +46,8 @@ public class ConnectionRecordSet extends ModeledActivityRecordSet<ConnectionReco
     
     /**
      * The identifier of the connection to which this record set should be
-     * limited, if any.
+     * limited, if any. If null, the set should contain all records readable
+     * by the user making the request.
      */
     private String identifier = null;
     
@@ -58,7 +59,9 @@ public class ConnectionRecordSet extends ModeledActivityRecordSet<ConnectionReco
      *     The user that created or retrieved this object.
      * 
      * @param identifier
-     *     The connection identifier to which this record set should be limited.
+     *     The connection identifier to which this record set should be limited,
+     *     or null if the record set should contain all records readable by the
+     *     currentUser.
      */
     protected void init(ModeledAuthenticatedUser currentUser, String identifier) {
         super.init(currentUser);

extensions/guacamole-auth-jdbc/modules/guacamole-auth-jdbc-base/src/main/java/org/apache/guacamole/auth/jdbc/sharing/connection/SharedConnection.java

@@ -158,7 +158,7 @@ public class SharedConnection implements Connection {
     @Override
     public List<? extends ConnectionRecord> getHistory()
             throws GuacamoleException {
-        return Collections.<ConnectionRecord>emptyList();
+        throw new GuacamoleUnsupportedException("SharedConnection objects do not provide history.");
     }
     
     @Override

extensions/guacamole-auth-jdbc/modules/guacamole-auth-jdbc-base/src/main/java/org/apache/guacamole/auth/jdbc/sharing/user/SharedUser.java

@@ -104,10 +104,7 @@ public class SharedUser implements User {
     @Deprecated
     @Override
     public List<ActivityRecord> getHistory() throws GuacamoleException {
-
+        throw new GuacamoleUnsupportedException("SharedUser objects do not provide login history.");
-        // History is not recorded for shared users
-        return Collections.<ActivityRecord>emptyList();
-
     }
     
     @Override

extensions/guacamole-auth-jdbc/modules/guacamole-auth-jdbc-base/src/main/java/org/apache/guacamole/auth/jdbc/user/UserRecordSet.java

@@ -44,8 +44,26 @@ public class UserRecordSet extends ModeledActivityRecordSet<ActivityRecord> {
     @Inject
     private UserService userService;
     
+    /**
+     * The identifier that indicates which user object these records should be
+     * limited to, if any. If null is specified (the default) then all records
+     * that are readable by the current user will be retrieved.
+     */
     private String identifier = null;
     
+    /**
+     * Initialize this UserRecordSet with currentUser requesting the login
+     * records, and, optionally, the identifier of the user to which records
+     * should be limited.
+     * 
+     * @param currentUser
+     *     The user requesting login history.
+     * 
+     * @param identifier 
+     *     The identifier of the user whose login history should be contained
+     *     in this record set, or null if the record set should contain all
+     *     records readable by the currentUser.
+     */
     protected void init(ModeledAuthenticatedUser currentUser, String identifier) {
         super.init(currentUser);
         this.identifier = identifier;

guacamole-ext/src/main/java/org/apache/guacamole/net/auth/Connection.java

@@ -19,6 +19,7 @@
 
 package org.apache.guacamole.net.auth;
 
+import java.util.ArrayList;
 import java.util.Date;
 import java.util.List;
 import java.util.Set;
@@ -100,17 +101,23 @@ public interface Connection extends Identifiable, Connectable, Attributes {
      * connections are first), and then in descending order of start time
      * (newer connections are first).
      *
+     * @deprecated 
+     *     This function has been deprecated in favor of
+     *     {@link getConnectionHistory}, which returns the connection history
+     *     as an ActivityRecordSet that can be easily sorted and filtered.
+     *     While the getHistory() method is provided for API compatibility,
+     *     new implementations should avoid use of this method and, instead,
+     *     implement the getConnectionHistory() method.
+     * 
      * @return A list of ConnectionRecrods representing the usage history
      *         of this Connection.
      *
      * @throws GuacamoleException If an error occurs while reading the history
      *                            of this connection, or if permission is
      *                            denied.
-     * 
-     * @deprecated Use {@link getConnectionHistory} instead.
      */
     @Deprecated
-    public List<? extends ConnectionRecord> getHistory() throws GuacamoleException;
+    List<? extends ConnectionRecord> getHistory() throws GuacamoleException;
 
     /**
      * Returns an ActivityRecordSet containing ConnectionRecords that
@@ -127,7 +134,7 @@ public interface Connection extends Identifiable, Connectable, Attributes {
      *     If an error occurs retrieving history for this Connection, or if
      *     permission to retrieve the history is denied.
      */
-    public ActivityRecordSet<ConnectionRecord> getConnectionHistory()
+    ActivityRecordSet<ConnectionRecord> getConnectionHistory()
             throws GuacamoleException;
     
     /**

guacamole-ext/src/main/java/org/apache/guacamole/net/auth/User.java

@@ -19,6 +19,7 @@
 
 package org.apache.guacamole.net.auth;
 
+import java.util.ArrayList;
 import java.util.Date;
 import java.util.List;
 import org.apache.guacamole.GuacamoleException;
@@ -95,6 +96,13 @@ public interface User extends Identifiable, Attributes, Permissions {
      * sessions are first), and then in descending order of start time
      * (newer sessions are first).
      *
+     * @deprecated
+     *     This function is deprecated in favor of {@link getUserHistory}, which
+     *     returns the login history as an ActivityRecordSet which supports
+     *     various sort and filter functions. While this continues to be defined
+     *     for API compatibility, new implementation should avoid this function
+     *     and use getUserHistory(), instead.
+     * 
      * @return
      *     A list of ActivityRecords representing the login history of this
      *     User.
@@ -102,9 +110,6 @@ public interface User extends Identifiable, Attributes, Permissions {
      * @throws GuacamoleException
      *     If an error occurs while reading the history of this user, or if
      *     permission is denied.
-     * 
-     * @deprecated
-     *     Use {@link getUserHistory} instead.
      */
     @Deprecated
     List<? extends ActivityRecord> getHistory() throws GuacamoleException;
@@ -124,7 +129,7 @@ public interface User extends Identifiable, Attributes, Permissions {
      *     If an error occurs retrieving this user's login history, or if
      *     permission to retrieve login history is denied.
      */
-    public ActivityRecordSet<ActivityRecord> getUserHistory()
+    ActivityRecordSet<ActivityRecord> getUserHistory()
             throws GuacamoleException;
 
     /**

guacamole/src/main/java/org/apache/guacamole/rest/connection/APIConnectionWrapper.java

@@ -143,7 +143,8 @@ public class APIConnectionWrapper implements Connection {
     @Deprecated
     @Override
     public List<? extends ConnectionRecord> getHistory() throws GuacamoleException {
-        return Collections.<ConnectionRecord>emptyList();
+        throw new GuacamoleUnsupportedException("APIConnectionWrapper does not "
+                + "support retrieving connection history.");
     }
     
     @Override

guacamole/src/main/java/org/apache/guacamole/rest/history/ActivityRecordSetResource.java

@@ -84,7 +84,7 @@ public abstract class ActivityRecordSetResource<InternalRecordType extends Activ
      *     A new record object containing the same data as the given internal
      *     record, but intended for use in interchange.
      */
-    public abstract ExternalRecordType toExternalRecord(InternalRecordType record);
+    protected abstract ExternalRecordType toExternalRecord(InternalRecordType record);
 
     /**
      * Retrieves the list of activity records stored within the underlying

guacamole/src/main/java/org/apache/guacamole/rest/history/ConnectionHistoryResource.java

@@ -42,7 +42,7 @@ public class ConnectionHistoryResource extends ActivityRecordSetResource<Connect
     }
 
     @Override
-    public APIConnectionRecord toExternalRecord(ConnectionRecord record) {
+    protected APIConnectionRecord toExternalRecord(ConnectionRecord record) {
         return new APIConnectionRecord(record);
     }
 

guacamole/src/main/java/org/apache/guacamole/rest/history/UserHistoryResource.java

@@ -41,7 +41,7 @@ public class UserHistoryResource extends ActivityRecordSetResource<ActivityRecor
     }
 
     @Override
-    public APIActivityRecord toExternalRecord(ActivityRecord record) {
+    protected APIActivityRecord toExternalRecord(ActivityRecord record) {
         return new APIActivityRecord(record);
     }
 

guacamole/src/main/java/org/apache/guacamole/rest/user/APIUserWrapper.java

@@ -143,7 +143,7 @@ public class APIUserWrapper implements User {
     @Deprecated
     @Override
     public List<? extends ActivityRecord> getHistory() throws GuacamoleException {
-        return Collections.<ActivityRecord>emptyList();
+        throw new GuacamoleUnsupportedException("APIUserWrapper does not provide login history.");
     }
     
     @Override