GUACAMOLE-394: Separate definition of records and record sets into generalized interface.

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

@@ -0,0 +1,78 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.apache.guacamole.net.auth;
+
+import java.util.Date;
+
+/**
+ * A logging record describing when a user started and ended a particular
+ * activity.
+ */
+public interface ActivityRecord {
+
+    /**
+     * Returns the date and time the activity began.
+     *
+     * @return
+     *     The date and time the activity began.
+     */
+    public Date getStartDate();
+
+    /**
+     * Returns the date and time the activity ended, if applicable.
+     *
+     * @return
+     *     The date and time the activity ended, or null if the activity is
+     *     still ongoing or if the end time is unknown.
+     */
+    public Date getEndDate();
+
+    /**
+     * Returns the hostname or IP address of the remote host that performed the
+     * activity associated with this record, if known. If the hostname or IP
+     * address is not known, null is returned.
+     *
+     * @return
+     *     The hostname or IP address of the remote host, or null if this
+     *     information is not available.
+     */
+    public String getRemoteHost();
+
+    /**
+     * Returns the name of the user who performed or is performing the activity
+     * at the times given by this record.
+     *
+     * @return
+     *     The name of the user who performed or is performing the associated
+     *     activity.
+     */
+    public String getUsername();
+
+    /**
+     * Returns whether the activity associated with this record is still
+     * ongoing.
+     *
+     * @return
+     *     true if the activity associated with this record is still ongoing,
+     *     false otherwise.
+     */
+    public boolean isActive();
+
+}

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

@@ -0,0 +1,128 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.apache.guacamole.net.auth;
+
+import java.util.Collection;
+import org.apache.guacamole.GuacamoleException;
+
+/**
+ * A set of all available records related to a type of activity which has a
+ * defined start and end time, such as a user being logged in or connected, or a
+ * subset of those records.
+ *
+ * @param <RecordType>
+ *     The type of ActivityRecord contained within this set.
+ */
+public interface ActivityRecordSet<RecordType extends ActivityRecord> {
+
+    /**
+     * All properties of activity records which can be used as sorting
+     * criteria.
+     */
+    enum SortableProperty {
+
+        /**
+         * The date and time when the activity associated with the record
+         * began.
+         */
+        START_DATE
+
+    };
+
+    /**
+     * Returns all records within this set as a standard Collection.
+     *
+     * @return
+     *      A collection containing all records within this set.
+     *
+     * @throws GuacamoleException
+     *      If an error occurs while retrieving the records within this set.
+     */
+    Collection<RecordType> asCollection() throws GuacamoleException;
+
+    /**
+     * Returns the subset of records which contain the given value. The
+     * properties and semantics involved with determining whether a particular
+     * record "contains" the given value is implementation dependent. This
+     * function may affect the contents of the current ActivityRecordSet. The
+     * contents of the current ActivityRecordSet should NOT be relied upon
+     * after this function is called.
+     *
+     * @param value
+     *     The value which all records within the resulting subset should
+     *     contain.
+     *
+     * @return
+     *     The subset of records which contain the specified value.
+     *
+     * @throws GuacamoleException
+     *     If an error occurs while restricting the current subset.
+     */
+    ActivityRecordSet<RecordType> contains(String value)
+            throws GuacamoleException;
+
+    /**
+     * Returns the subset of records containing only the first
+     * <code>limit</code> records. If the subset has fewer than
+     * <code>limit</code> records, then this function has no effect. This
+     * function may also affect the contents of the current ActivityRecordSet.
+     * The contents of the current ActivityRecordSet should NOT be relied upon
+     * after this function is called.
+     *
+     * @param limit
+     *     The maximum number of records that the new subset should contain.
+     *
+     * @return
+     *     The subset of records that containing only the first
+     *     <code>limit</code> records.
+     *
+     * @throws GuacamoleException
+     *     If an error occurs while limiting the current subset.
+     */
+    ActivityRecordSet<RecordType> limit(int limit) throws GuacamoleException;
+
+    /**
+     * Returns a ActivityRecordSet containing identically the records within
+     * this set, sorted according to the specified criteria. The sort operation
+     * performed is guaranteed to be stable with respect to any past call to
+     * sort(). This function may also affect the contents of the current
+     * ActivityRecordSet. The contents of the current ActivityRecordSet
+     * should NOT be relied upon after this function is called.
+     *
+     * @param property
+     *     The property by which the records within the resulting set should be
+     *     sorted.
+     *
+     * @param desc
+     *     Whether the records should be sorted according to the specified
+     *     property in descending order. If false, records will be sorted
+     *     according to the specified property in ascending order.
+     *
+     * @return
+     *     The ActivityRecordSet, sorted according to the specified criteria.
+     *
+     * @throws GuacamoleException
+     *     If an error occurs while sorting the current subset, or if the given
+     *     property is not supported by the implementation.
+     */
+    ActivityRecordSet<RecordType> sort(SortableProperty property, boolean desc)
+            throws GuacamoleException;
+
+}

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

@@ -19,13 +19,11 @@
 
 package org.apache.guacamole.net.auth;
 
-import java.util.Date;
-
 /**
  * A logging record describing when a user started and ended usage of a
  * particular connection.
  */
-public interface ConnectionRecord {
+public interface ConnectionRecord extends ActivityRecord {
 
     /**
      * Returns the identifier of the connection associated with this
@@ -72,48 +70,4 @@ public interface ConnectionRecord {
      */
     public String getSharingProfileName();
 
-    /**
-     * Returns the date and time the connection began.
-     *
-     * @return The date and time the connection began.
-     */
-    public Date getStartDate();
-
-    /**
-     * Returns the date and time the connection ended, if applicable.
-     *
-     * @return The date and time the connection ended, or null if the
-     *         connection is still running or if the end time is unknown.
-     */
-    public Date getEndDate();
-
-    /**
-     * Returns the hostname or IP address of the remote host that used the
-     * connection associated with this record, if known. If the hostname or IP
-     * address is not known, null is returned.
-     *
-     * @return
-     *     The hostname or IP address of the remote host, or null if this
-     *     information is not available.
-     */
-    public String getRemoteHost();
-
-    /**
-     * Returns the name of the user who used or is using the connection at the
-     * times given by this connection record.
-     *
-     * @return The name of the user who used or is using the associated
-     *         connection.
-     */
-    public String getUsername();
-
-    /**
-     * Returns whether the connection associated with this record is still
-     * active.
-     *
-     * @return true if the connection associated with this record is still
-     *         active, false otherwise.
-     */
-    public boolean isActive();
-
 }

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

@@ -19,39 +19,12 @@
 
 package org.apache.guacamole.net.auth;
 
-import java.util.Collection;
 import org.apache.guacamole.GuacamoleException;
 
 /**
  * The set of all available connection records, or a subset of those records.
  */
-public interface ConnectionRecordSet {
+public interface ConnectionRecordSet extends ActivityRecordSet<ConnectionRecord> {
-
-    /**
-     * All properties of connection records which can be used as sorting
-     * criteria.
-     */
-    enum SortableProperty {
-
-        /**
-         * The date and time when the connection associated with the
-         * connection record began.
-         */
-        START_DATE
-
-    };
-
-    /**
-     * Returns all connection records within this set as a standard Collection.
-     *
-     * @return
-     *      A collection containing all connection records within this set.
-     *
-     * @throws GuacamoleException
-     *      If an error occurs while retrieving the connection records within
-     *      this set.
-     */
-    Collection<ConnectionRecord> asCollection() throws GuacamoleException;
 
     /**
      * Returns the subset of connection records to only those where the
@@ -73,6 +46,7 @@ public interface ConnectionRecordSet {
      * @throws GuacamoleException
      *     If an error occurs while restricting the current subset.
      */
+    @Override
     ConnectionRecordSet contains(String value) throws GuacamoleException;
 
     /**
@@ -93,6 +67,7 @@ public interface ConnectionRecordSet {
      * @throws GuacamoleException
      *     If an error occurs while limiting the current subset.
      */
+    @Override
     ConnectionRecordSet limit(int limit) throws GuacamoleException;
 
     /**
@@ -119,6 +94,7 @@ public interface ConnectionRecordSet {
      * @throws GuacamoleException
      *     If an error occurs while sorting the current subset.
      */
+    @Override
     ConnectionRecordSet sort(SortableProperty property, boolean desc)
             throws GuacamoleException;