STAT-241: improved performance by properly consolidating presence eve…

…nts; added related tests; added option to report against site presence time; added "average presence time per visit" to Visits in overview. Requires "display.users.present=true" and "[email protected]=true" in sakai.properties. Using "presence.events.log = false" won't do it.

git-svn-id: https://source.sakaiproject.org/svn/sitestats/trunk@78669 66ffb92e-73f9-0310-93c1-f5514f145a0a

sitestats/sitestats-api/src/config/org/sakaiproject/sitestats/config/fop/xmlReportToFo.xsl

@@ -84,6 +84,9 @@
                                 </xsl:if>
                                 <xsl:if test="showTotalUnique = 'true'">
                                     <fo:table-column column-width="8.5mm" />
+                                </xsl:if>
+                                <xsl:if test="showDuration = 'true'">
+                                    <fo:table-column column-width="8.5mm" />
                                 </xsl:if>
 								<fo:table-header>
 									<xsl:apply-templates select="datarowheader" />
@@ -206,6 +209,13 @@
                         <xsl:value-of select="th_uniquevisitors" />
                     </fo:block>
                 </fo:table-cell>
+            </xsl:if>
+            <xsl:if test="showDuration = 'true'">
+                <fo:table-cell border-bottom-width="0.75pt" border-bottom-style="dashed" border-bottom-color="#cccccc" padding-bottom="1pt" padding-left="1pt" padding-right="1pt">
+                    <fo:block>
+                        <xsl:value-of select="th_duration" />
+                    </fo:block>
+                </fo:table-cell>
             </xsl:if>
 		</fo:table-row>
 	</xsl:template>
@@ -316,6 +326,13 @@
                         <xsl:value-of select="totalUnique" />
                     </fo:block>
                 </fo:table-cell>
+            </xsl:if>
+            <xsl:if test="showDuration = 'true'">
+                <fo:table-cell padding-left="1pt" padding-right="1pt">
+                    <fo:block wrap-option="no-wrap">
+                        <xsl:value-of select="duration" />
+                    </fo:block>
+                </fo:table-cell>
             </xsl:if>
 		</fo:table-row>
 	</xsl:template>

sitestats/sitestats-api/src/java/org/sakaiproject/sitestats/api/StatsManager.java

@@ -78,6 +78,7 @@ public interface StatsManager {
 	public static final int				Q_TYPE_RESOURCE				= 1;
 	public static final int				Q_TYPE_VISITSTOTALS			= 2;
 	public static final int				Q_TYPE_ACTIVITYTOTALS		= 3;
+	public static final int				Q_TYPE_PRESENCE				= 4;
 	public static final String			T_NONE						= "none";
 	public static final String			T_SITE						= "site";
 	public static final String			T_USER						= "user";
@@ -92,10 +93,12 @@ public interface StatsManager {
 	public static final String			T_TOTAL						= "total";
 	public static final String			T_VISITS					= "visits";
 	public static final String			T_UNIQUEVISITS				= "unique-visits";
+	public static final String			T_DURATION					= "duration";
 	public static final List<String>	TOTALSBY_EVENT_DEFAULT		= Arrays.asList(T_USER, T_EVENT, T_DATE);
 	public static final List<String>	TOTALSBY_RESOURCE_DEFAULT	= Arrays.asList(T_USER, T_RESOURCE, T_RESOURCE_ACTION, T_DATE);
 	public static final List<String>	TOTALSBY_VISITSTOTALS_DEFAULT	= Arrays.asList(T_DATE);
 	public static final List<String>	TOTALSBY_ACTIVITYTOTALS_DEFAULT	= Arrays.asList(T_DATE);
+	public static final List<String>	TOTALSBY_PRESENCE_DEFAULT	= Arrays.asList(T_DATE);
 
 	// ################################################################
 	// Spring bean methods
@@ -275,6 +278,53 @@ public int getEventStatsRowCount(
 			final boolean inverseUserSelection,
 			final List<String> totalsBy);
 
+	/**
+	 * Get presence statistics (totals by user/event/date).
+	 * @param siteId The site ID (can be null)
+	 * @param events List of events to get statistics for (see {@link #getPreferences(String, boolean)}, {@link EventRegistryService}) (can be null)
+	 * @param iDate The initial date (can be null)
+	 * @param fDate The final date (can be null)
+	 * @param userIds The list of user Ids (can be null)
+	 * @param inverseUserSelection match users not in userIds list
+	 * @param page The PagePosition subset of items to return (can be null)
+	 * @param totalsBy Columns to sort by (see {@link #TOTALSBY_EVENT_DEFAULT}, {@link #T_USER}, {@link #T_EVENT}, {@link #T_DATE}, {@link #T_LASTDATE})
+	 * @param sortBy Column to sort by (can be null) (see {@link #T_USER}, {@link #T_EVENT}, {@link #T_DATE}, {@link #T_LASTDATE})
+	 * @param sortAscending Sort ascending?
+	 * @param maxResults Maximum number of results (specify 0 (zero) for no limitation)
+	 * @return a list of {@link EventStat} objects
+	 */
+	public List<Stat> getPresenceStats(
+			final String siteId, 
+			final Date iDate, final Date fDate,
+			final List<String> userIds,
+			final boolean inverseUserSelection,
+			final PagingPosition page, 
+			final List<String> totalsBy,
+			final String sortBy,
+			final boolean sortAscending,
+			final int maxResults);
+
+	/**
+	 * Get row count for presence statistics (totals by user/event/date).
+	 * @param siteId The site ID (can be null)
+	 * @param events List of events to get statistics for (see {@link #getPreferences(String, boolean)}, {@link EventRegistryService}) (can be null)
+	 * @param iDate The initial date (can be null)
+	 * @param fDate The final date (can be null)
+	 * @param userIds The list of user Ids (can be null)
+	 * @param inverseUserSelection match users not in userIds list
+	 * @param page The PagePosition subset of items to return (can be null)
+	 * @param totalsBy Columns to sort by (see {@link #TOTALSBY_EVENT_DEFAULT}, {@link #T_USER}, {@link #T_EVENT}, {@link #T_DATE}, {@link #T_LASTDATE})
+	 * @param sortBy Columns to sort by (can be null)
+	 * @param sortAscending Sort ascending?
+	 * @return Row count.
+	 */
+	public int getPresenceStatsRowCount(
+			final String siteId, 
+			final Date iDate, final Date fDate,
+			final List<String> userIds,
+			final boolean inverseUserSelection,
+			final List<String> totalsBy);
+
 
 	// ################################################################
 	// Resource statistics related methods

sitestats/sitestats-api/src/java/org/sakaiproject/sitestats/api/Util.java

@@ -0,0 +1,36 @@
+/**
+ * $URL$
+ * $Id$
+ *
+ * Copyright (c) 2006-2009 The Sakai Foundation
+ *
+ * Licensed under the Educational Community 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.osedu.org/licenses/ECL-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.sakaiproject.sitestats.api;
+
+import java.io.Serializable;
+
+public class Util implements Serializable {
+	private static final long	serialVersionUID	= 1L;
+
+	public static double round(double val, int places) {
+		long factor = (long) Math.pow(10, places);
+		// Shift the decimal the correct number of places to the right.
+		val = val * factor;
+		// Round to the nearest integer.
+		long tmp = Math.round(val);
+		// Shift the decimal the correct number of places back to the left.
+		return (double) tmp / factor;
+	}
+
+}

sitestats/sitestats-api/src/java/org/sakaiproject/sitestats/api/report/ReportManager.java

@@ -1,6 +1,6 @@
 /**
- * $URL:$
- * $Id:$
+ * $URL$
+ * $Id$
  *
  * Copyright (c) 2006-2009 The Sakai Foundation
  *
@@ -46,6 +46,7 @@ public interface ReportManager {
 	public static final String	WHAT_EVENTS_ALLTOOLS		= "all";
 	public static final String	WHAT_EVENTS					= "what-events";
 	public static final String	WHAT_VISITS					= "what-visits";
+	public static final String	WHAT_PRESENCES				= "what-presences";
 	public static final String	WHAT_VISITS_TOTALS			= "what-visits-totals";
 	public static final String	WHAT_ACTIVITY_TOTALS		= "what-activity-totals";
 	public static final String	HOW_TOTALSBY				= "how-totalsby";

sitestats/sitestats-api/src/java/org/sakaiproject/sitestats/api/report/ReportParams.java

@@ -1,6 +1,6 @@
 /**
- * $URL:$
- * $Id:$
+ * $URL$
+ * $Id$
  *
  * Copyright (c) 2006-2009 The Sakai Foundation
  *
@@ -103,12 +103,12 @@ public void setSiteId(String siteId) {
 		this.siteId = siteId;
 	}
 
-	/** Get the what type selection (see {@link ReportManager#WHAT_EVENTS},{@link ReportManager#WHAT_RESOURCES}, {@link ReportManager#WHAT_VISITS}). */
+	/** Get the what type selection (see {@link ReportManager#WHAT_EVENTS},{@link ReportManager#WHAT_RESOURCES}, {@link ReportManager#WHAT_VISITS}, {@link ReportManager#WHAT_PRESENCES}). */
 	public String getWhat() {
 		return what;
 	}
 
-	/** Set the what type selection (see {@link ReportManager#WHAT_EVENTS},{@link ReportManager#WHAT_RESOURCES}, {@link ReportManager#WHAT_VISITS}). */
+	/** Set the what type selection (see {@link ReportManager#WHAT_EVENTS},{@link ReportManager#WHAT_RESOURCES}, {@link ReportManager#WHAT_VISITS}, {@link ReportManager#WHAT_PRESENCES}). */
 	public void setWhat(String what){
 		this.what = what;
 	}

sitestats/sitestats-bundle/src/resources/Messages.properties

@@ -10,6 +10,7 @@ refresh=refresh
 help=help
 click_to_max=Click to maximize
 last_job_run_date=Last updated on:
+minutes_abbr=min
 
 # Menu/Title
 menu_sitelist=All sites
@@ -86,6 +87,7 @@ overview_title_unique_visits_sum=Users who have visited site
 overview_title_enrolled_users_sum=Site Members
 overview_title_enrolled_users_with_visits_sum=Members who have visited site
 overview_title_enrolled_users_without_visits_sum=Members who have not visited site
+overview_title_presence_time_avg=Average presence time per visit
 # Overview::Activity
 overview_title_activity=Activity
 overview_title_events_sum=Events
@@ -119,6 +121,7 @@ report_what_instructions=Select activity to report.
 report_what_activity=Activity:
 report_what_visits=Visits
 report_what_events=Events
+report_what_presences=Presence Time
 report_what_events_bytool=Select by tool
 report_what_events_byevent=Select by event
 report_what_resources=Resources
@@ -252,6 +255,7 @@ th_resource=Resource
 th_action=Action
 th_visits=Visits
 th_uniquevisitors=Unique visitors
+th_duration=Duration
 action_all=All
 action_new=New
 action_read=Read

sitestats/sitestats-bundle/src/resources/Messages_pt_PT.properties

@@ -10,6 +10,7 @@ help=ajuda
 refresh=actualizar
 click_to_max=Clique para maximizar
 last_job_run_date=\u00daltima actualiza\u00e7\u00e3o em:
+minutes_abbr=min
 
 # Menu/Title
 menu_overview=Resumo
@@ -52,6 +53,7 @@ overview_title_unique_visits_sum=Utilizadores que visitaram a \u00e1rea
 overview_title_enrolled_users_sum=Membros da \u00e1rea
 overview_title_enrolled_users_with_visits_sum=Membros que visitaram a \u00e1rea
 overview_title_enrolled_users_without_visits_sum=Membros que n\u00e3o visitaram a \u00e1rea
+overview_title_presence_time_avg=Tempo m\u00e9dio de presen\u00e7a por visita
 # Overview::Activity
 overview_title_activity=Actividade
 overview_title_events_sum=Eventos
@@ -112,6 +114,7 @@ report_what_resource_action=Limitar \u00e0 ac\u00e7\u00e3o\:
 report_what_resources=Recursos
 report_what_sel_resources=Limitar aos recursos\:
 report_what_visits=Visitas
+report_what_presences=Tempo de Presen\u00e7a
 report_when=Quando?
 report_when_period=Intervalo de tempo:
 report_when_all=Tudo
@@ -218,6 +221,7 @@ th_type=Tipo
 th_user=Nome
 th_visits=Visitas
 th_uniquevisitors=Visitantes \u00fanicos
+th_duration=Dura\u00e7\u00e3o
 action_all=Todos
 action_delete=Eliminar
 action_new=Novo

sitestats/sitestats-help/src/sakai_sitestats/edit-reports.html

@@ -43,6 +43,7 @@ <h4>What?</h4>
                 <li><strong>Resources</strong>: Restricts report to selected files/folders or to files under selected folders.</li>
             </ul>
         </li>
+        <li><strong>Presence Time</strong>: User presence time in site.</li>
     </ul>
 
     <h4>When?</h4>

sitestats/sitestats-help/src/sakai_sitestats/overview.html

@@ -28,6 +28,7 @@ <h3>Summary of site visits</h3>
   <li><strong>Enrolled users in site</strong>: Total number of users that are member of the current site.</li>
   <li><strong>Enrolled users that visited site</strong>: Total number and percentage of users that are site members and have visited the site. This number may be different from <strong>Unique Visits</strong> if there are visits from users that are no longer members of the site.</li>
   <li><strong>Enrolled users that did not visit site</strong>: Total number and percentage of users that are site members and have not visited the site.</li>
+  <li><strong>Average presence time per visit</strong>: Average time an user stays present on the site, per visit.</li>
 </ul>
 A more detailed report can be obtained by clicking on the items above (e.g., clicking on 'Enrolled users that did not visit site' will display a report of all users that never visited the site).
 <p>

sitestats/sitestats-help/src/sakai_sitestats/sitestats-overview.html

@@ -29,7 +29,7 @@ <h3>Things to Consider</h3>
   <li>On the same login session, if an user enters/exits the same site multiple times only one visit will be recorded.</li>
   <li>On the Overview page, resource statistics refers to files from the Resources tool only.</li>
   <li>Site Stats may not be a default tool on the current LMS. To use Site Stats to collect participation data for a course/project site, you must add it to your site using Site Setup (see Adding, editing, or removing tools) and, eventually, ask the system support for authorization (grant permissions).</li>
-  <li>Site visits may not be enabled on the current LMS.</li>
+  <li>Site visits and/or presence time in site may not be enabled on the current LMS.</li>
   <li>Depending on the LMS configuration, statistics may be updated instantly or on a regular time interval (e.g., once per day).</li>
 </ul>
 

sitestats/sitestats-impl-hib/src/java/org/sakaiproject/sitestats/impl/SitePresenceImpl.java

@@ -41,6 +41,7 @@ public boolean equals(Object o) {
 				&& userId.equals(other.getUserId())
 				&& date.equals(other.getDate())
 				&& duration == other.getDuration()
+				&& getCount() == other.getCount()
 				&& lastVisitStartTime == other.getLastVisitStartTime();
 	}
 
@@ -113,7 +114,7 @@ public void setCount(long count) {
 	}
 
 	public long getCount() {
-		return 0;
+		return duration;
 	}
 
 }