1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.apache.jetspeed.statistics;
18
19 import java.util.List;
20
21 import javax.sql.DataSource;
22
23 import org.apache.jetspeed.request.RequestContext;
24
25 /***
26 * The PortletStatistics interface provides an API for logging portlet
27 * statistics. Each log entry is formatted in the <A
28 * HREF="http://httpd.apache.org/docs/logs.html"> Apache Common Log Format (CLF)
29 * </A>. Each CLF log entry has the following form:
30 * <P>
31 * "%h %l %u %t \"%r\" %>s %b"
32 * <P>
33 * where:
34 * <UL>
35 * <LI><B>%h </B>- remote host</LI>
36 * <LI><B>%l </B>- remote log name</LI>
37 * <LI><B>%u </B>- remote user</LI>
38 * <LI><B>%t </B>- time in common log time format</LI>
39 * <LI><B>%r </B>- first line of HTTP request</LI>
40 * <LI><B>%s </B>- HTTP status code</LI>
41 * <LI><B>%b </B>- number of bytes sent ("-" if no bytes sent).
42 * </UL>
43 * <P>
44 * Here's an example of a CLF log entry:
45 * <P>
46 *
47 * <PRE>
48 *
49 * 192.168.2.3 - johndoe [25/Oct/2005:11:44:40 PDT] "GET
50 * /jetspeed/DatabaseBrowserTest HTTP/1.1" 200 -
51 *
52 * </PRE>
53 *
54 * <P>
55 * The PortletStatistics interface overloads the %r field of the CLF format,
56 * depending on the type of information being logged:
57 * <P>
58 *
59 * <PRE>
60 *
61 * LOG TYPE FORMAT OF %r FIELD -------------- ----------------------------
62 * Portlet access "PORTLET <page-path><portlet-name>" Page access "PAGE
63 * <page-path>" User logout "LOGOUT"
64 *
65 * </PRE>
66 *
67 * @author <a href="mailto:taylor@apache.org">David Sean Taylor </a>
68 * @author <a href="mailto:morciuch@apache.org">Mark Orciuch </a>
69 * @author <a href="mailto:rklein@bluesunrise.com">Richard Klein </a>
70 * @version $Id: $
71 */
72 public interface PortalStatistics
73 {
74 public static final String QUERY_TYPE_PORTLET = "portlet";
75 public static final String QUERY_TYPE_USER = "user";
76 public static final String QUERY_TYPE_PAGE = "page";
77
78 public static final String HTTP_OK = "200";
79
80 public static final String HTTP_UNAUTHORIZED = "401";
81
82 public static final String HTTP_NOT_FOUND = "404";
83
84 public static final String HTTP_INTERNAL_ERROR = "500";
85
86 /***
87 * Logs an access to a portlet.
88 *
89 * @param request
90 * current request info object
91 * @param portlet
92 * portlet being logged
93 * @param statusCode
94 * HTTP status code.
95 * @param msElapsedTime
96 * elapsed time the portlet took to render
97 */
98 public void logPortletAccess(RequestContext request, String portlet,
99 String statusCode, long msElapsedTime);
100
101 /***
102 * Logs an access to a page.
103 *
104 * @param request
105 * current request info object
106 * @param statusCode
107 * HTTP status code
108 * @param msElapsedTime
109 * elapsed time the page took to render
110 */
111 public void logPageAccess(RequestContext request, String statusCode,
112 long msElapsedTime);
113
114 /***
115 * Logs a user logout event. The %s (HTTP status code) field of the log
116 * entry will be set to 200 (OK).
117 *
118 * @param request
119 * current request info object
120 * @param msElapsedTime
121 * elapsed time that the user was logged in
122 */
123 public void logUserLogout(String ipAddress, String userName,
124 long msSessionLength);
125
126 /***
127 * Logs a user logout event. The %s (HTTP status code) field of the log
128 * entry will be set to 200 (OK).
129 *
130 * @param request
131 * current request info object
132 * @param msElapsedLoginTime
133 * time it took the user to login
134 */
135 public void logUserLogin(RequestContext request, long msElapsedLoginTime);
136
137 /***
138 * @return returns the current number of logged in users
139 */
140 public int getNumberOfCurrentUsers();
141
142 /***
143 * force the database loggers to flush out
144 */
145 public void forceFlush();
146
147 /***
148 * @return DataSource in use by the logger useful for writing decent tests
149 */
150 public DataSource getDataSource();
151
152 public AggregateStatistics queryStatistics(StatisticsQueryCriteria criteria)
153 throws InvalidCriteriaException;
154
155 public int getNumberOfLoggedInUsers();
156
157 public List getListOfLoggedInUsers();
158
159 /***
160 * Factory to create new statistics query criteria
161 *
162 * @return a newly create statistics empty criteria
163 */
164 public StatisticsQueryCriteria createStatisticsQueryCriteria();
165
166 /***
167 * Factory to create new, empty, aggregate statistics object.
168 *
169 * @return unpopulated AggregateStatistics object
170 */
171 public AggregateStatistics getDefaultEmptyAggregateStatistics();
172 }