001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.jetspeed.statistics;
018:
019: import java.util.List;
020:
021: import javax.sql.DataSource;
022:
023: import org.apache.jetspeed.request.RequestContext;
024:
025: /**
026: * The PortletStatistics interface provides an API for logging portlet
027: * statistics. Each log entry is formatted in the <A
028: * HREF="http://httpd.apache.org/docs/logs.html"> Apache Common Log Format (CLF)
029: * </A>. Each CLF log entry has the following form:
030: * <P>
031: * "%h %l %u %t \"%r\" %>s %b"
032: * <P>
033: * where:
034: * <UL>
035: * <LI><B>%h </B>- remote host</LI>
036: * <LI><B>%l </B>- remote log name</LI>
037: * <LI><B>%u </B>- remote user</LI>
038: * <LI><B>%t </B>- time in common log time format</LI>
039: * <LI><B>%r </B>- first line of HTTP request</LI>
040: * <LI><B>%s </B>- HTTP status code</LI>
041: * <LI><B>%b </B>- number of bytes sent ("-" if no bytes sent).
042: * </UL>
043: * <P>
044: * Here's an example of a CLF log entry:
045: * <P>
046: *
047: * <PRE>
048: *
049: * 192.168.2.3 - johndoe [25/Oct/2005:11:44:40 PDT] "GET
050: * /jetspeed/DatabaseBrowserTest HTTP/1.1" 200 -
051: *
052: * </PRE>
053: *
054: * <P>
055: * The PortletStatistics interface overloads the %r field of the CLF format,
056: * depending on the type of information being logged:
057: * <P>
058: *
059: * <PRE>
060: *
061: * LOG TYPE FORMAT OF %r FIELD -------------- ----------------------------
062: * Portlet access "PORTLET <page-path><portlet-name>" Page access "PAGE
063: * <page-path>" User logout "LOGOUT"
064: *
065: * </PRE>
066: *
067: * @author <a href="mailto:taylor@apache.org">David Sean Taylor </a>
068: * @author <a href="mailto:morciuch@apache.org">Mark Orciuch </a>
069: * @author <a href="mailto:rklein@bluesunrise.com">Richard Klein </a>
070: * @version $Id: $
071: */
072: public interface PortalStatistics {
073: public static final String QUERY_TYPE_PORTLET = "portlet";
074: public static final String QUERY_TYPE_USER = "user";
075: public static final String QUERY_TYPE_PAGE = "page";
076:
077: public static final String HTTP_OK = "200";
078:
079: public static final String HTTP_UNAUTHORIZED = "401";
080:
081: public static final String HTTP_NOT_FOUND = "404";
082:
083: public static final String HTTP_INTERNAL_ERROR = "500";
084:
085: /**
086: * Logs an access to a portlet.
087: *
088: * @param request
089: * current request info object
090: * @param portlet
091: * portlet being logged
092: * @param statusCode
093: * HTTP status code.
094: * @param msElapsedTime
095: * elapsed time the portlet took to render
096: */
097: public void logPortletAccess(RequestContext request,
098: String portlet, String statusCode, long msElapsedTime);
099:
100: /**
101: * Logs an access to a page.
102: *
103: * @param request
104: * current request info object
105: * @param statusCode
106: * HTTP status code
107: * @param msElapsedTime
108: * elapsed time the page took to render
109: */
110: public void logPageAccess(RequestContext request,
111: String statusCode, long msElapsedTime);
112:
113: /**
114: * Logs a user logout event. The %s (HTTP status code) field of the log
115: * entry will be set to 200 (OK).
116: *
117: * @param request
118: * current request info object
119: * @param msElapsedTime
120: * elapsed time that the user was logged in
121: */
122: public void logUserLogout(String ipAddress, String userName,
123: long msSessionLength);
124:
125: /**
126: * Logs a user logout event. The %s (HTTP status code) field of the log
127: * entry will be set to 200 (OK).
128: *
129: * @param request
130: * current request info object
131: * @param msElapsedLoginTime
132: * time it took the user to login
133: */
134: public void logUserLogin(RequestContext request,
135: 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(
153: StatisticsQueryCriteria criteria)
154: throws InvalidCriteriaException;
155:
156: public int getNumberOfLoggedInUsers();
157:
158: public List getListOfLoggedInUsers();
159:
160: /**
161: * Factory to create new statistics query criteria
162: *
163: * @return a newly create statistics empty criteria
164: */
165: public StatisticsQueryCriteria createStatisticsQueryCriteria();
166:
167: /**
168: * Factory to create new, empty, aggregate statistics object.
169: *
170: * @return unpopulated AggregateStatistics object
171: */
172: public AggregateStatistics getDefaultEmptyAggregateStatistics();
173: }
|