Gojara Doc

git-svn-id: http://svn.igniterealtime.org/svn/repos/openfire/trunk@13680 b35dd754-fafc-0310-a699-88a17e54d16e

src/plugins/gojara/src/java/org/jivesoftware/openfire/plugin/gojara/database/DatabaseManager.java

@@ -16,16 +16,15 @@ import org.jivesoftware.database.DbConnectionManager;
 import org.jivesoftware.util.JiveGlobals;
 
 /**
- * @author Holger Bergunde, Axel-Frederik Brand
- * 	 This class is used to store logs in the database. A
- *   log entry is representated by {@link LogEntry}
+ * @author Holger Bergunde, Axel-Frederik Brand This class is used to store logs in the database. A log entry is
+ *         representated by {@link LogEntry}
  */
 public class DatabaseManager {
 
 	private static Logger Log = Logger.getLogger(DatabaseManager.class);
 
 	private static volatile DatabaseManager _myself;
-	//Logging
+	// Logging
 	private static final String COUNT_LOG_ENTRIES = "SELECT count(*) FROM ofGojaraStatistics";
 	private static final String COUNT_PACKAGES_ODLER = "SELECT count(*) FROM ofGojaraStatistics WHERE messageType like ? AND component = ? AND messageDate > ?";
 	private static final String GET_ALL_LOGS = "SELECT * FROM ofGojaraStatistics ORDER BY logID desc LIMIT 100";
@@ -35,17 +34,18 @@ public class DatabaseManager {
 	private static final String CLEAN_OLD_DATA = "DELETE FROM ofGojaraStatistics WHERE messageDate < ?";
 	private static final String GET_LOGS_DATE_LIMIT_COMPONENT = "SELECT * FROM ofGojaraStatistics WHERE messageDate > ? AND component = ? ORDER BY messageDate DESC LIMIT ?";
 	private final int _dbCleanMinutes;
-	//Session
+	// Session
 	private static final String ADD_SESSION_ENTRY = "INSERT INTO ofGojaraSessions(username, transport, lastActivity) VALUES (?,?,?)";
 	private static final String UPDATE_SESSION_ENTRY = "UPDATE ofGojaraSessions SET lastActivity = ? WHERE username = ? AND transport = ?";
 	private static final String GET_SESSION_ENTRIES_FOR_USERNAME = "SELECT * FROM ofGojaraSessions WHERE username = ? ORDER BY lastActivity DESC";
 	private static final String DELETE_SESSION_ENTRY = "DELETE FROM ofGojaraSessions WHERE username = ? AND transport = ?";
 	private static final String GET_SESSION_COUNT = "SELECT count(*) FROM ofGojaraSessions";
+
 	private DatabaseManager() {
 
 		/*
-		 * Load time from globals if it is set. It represents the minutes the
-		 * log entries stay in database until they will get deleted
+		 * Load time from globals if it is set. It represents the minutes the log entries stay in database until they
+		 * will get deleted
 		 */
 		// TODO: Use PropertyEventListener to check if cleaner.minutes have
 		// changed
@@ -125,8 +125,7 @@ public class DatabaseManager {
 	}
 
 	/*
-	 * Cleans log entries older than 60 minutes if
-	 * plugin.remoteroster.log.cleaner.minutes is not set
+	 * Cleans log entries older than 60 minutes if plugin.remoteroster.log.cleaner.minutes is not set
 	 */
 	private void cleanOldLogEntries() {
 		Connection con = null;
@@ -149,16 +148,13 @@ public class DatabaseManager {
 	 * Adds new log entry for specified component.
 	 * 
 	 * @param component
-	 *            subdomain of the external component. e.g.
-	 *            icq.myjabberserver.com
+	 *            subdomain of the external component. e.g. icq.myjabberserver.com
 	 * @param type
-	 *            string representation of the class. normaly it is like
-	 *            {@link org.xmpp.packet}
+	 *            string representation of the class. normaly it is like {@link org.xmpp.packet}
 	 * @param from
 	 *            full qualified JID of user or component this packet was from
 	 * @param to
-	 *            full qualified JID of user or component this packet was
-	 *            adressed to
+	 *            full qualified JID of user or component this packet was adressed to
 	 */
 	public void addNewLogEntry(String component, String type, String from, String to) {
 		Connection con = null;
@@ -182,8 +178,7 @@ public class DatabaseManager {
 	}
 
 	/**
-	 * This method return the last 100 log entries. Every entry is one string
-	 * and added to a ArrayList
+	 * This method return the last 100 log entries. Every entry is one string and added to a ArrayList
 	 * 
 	 * @return each log as string in a list
 	 * */
@@ -203,8 +198,8 @@ public class DatabaseManager {
 				String type = rs.getString(3);
 				String component = rs.getString(6);
 				Timestamp date = rs.getTimestamp(2);
-				String res = "From: " + from + " To: " + to + " Type: " + type + " Timestamp: " + date.toString()
-						+ "Component: " + component;
+				String res = "From: " + from + " To: " + to + " Type: " + type + " Timestamp: " + date.toString() + "Component: "
+						+ component;
 				_result.add(res);
 			}
 		}
@@ -254,16 +249,14 @@ public class DatabaseManager {
 	}
 
 	/**
-	 * Counts the number of log entries in the databse that are older than
-	 * specified value
+	 * Counts the number of log entries in the databse that are older than specified value
 	 * 
 	 * @param component
 	 *            subdomain of the component the packages were flown by
 	 * @param packetClass
 	 *            the class the packet was instance of
 	 * @param minutes
-	 *            the log entry should not be older than (timestamp should be
-	 *            smaller than currentTime - minutes)
+	 *            the log entry should not be older than (timestamp should be smaller than currentTime - minutes)
 	 * @return number of rows found in database or -1 if there was an error
 	 */
 	public int getPacketCountOlderThan(String component, @SuppressWarnings("rawtypes") Class packetClass, int minutes) {
@@ -287,10 +280,10 @@ public class DatabaseManager {
 		}
 		return -1;
 	}
-	
+
 	/**
-	 * Trys to update SessionEntry for given user/transport combination. If update does not
-	 * work due to no record being there, it inserts record.
+	 * Trys to update SessionEntry for given user/transport combination. If update does not work due to no record being
+	 * there, it inserts record.
 	 */
 	public void insertOrUpdateSession(String transport, String user, long time) {
 		Connection con = null;
@@ -318,13 +311,13 @@ public class DatabaseManager {
 			DbConnectionManager.closeConnection(pstmt, con);
 		}
 	}
-	
+
 	public int removeSessionEntry(String transport, String user) {
 		int result = 0;
 		Log.info("I would now hit the DB and remove " + transport + " " + user);
 		Connection con = null;
 		PreparedStatement pstmt = null;
-		
+
 		try {
 			con = DbConnectionManager.getConnection();
 			pstmt = con.prepareStatement(DELETE_SESSION_ENTRY);
@@ -338,7 +331,7 @@ public class DatabaseManager {
 		}
 		return result;
 	}
-	
+
 	public ArrayList<SessionEntry> getSessionEntriesFor(String username) {
 		ArrayList<SessionEntry> result = new ArrayList<SessionEntry>();
 		Connection con = null;
@@ -353,7 +346,7 @@ public class DatabaseManager {
 				String user = rs.getString(1);
 				String transport = rs.getString(2);
 				long lastActivity = rs.getLong(3);
-				SessionEntry res = new SessionEntry(user,transport,lastActivity);
+				SessionEntry res = new SessionEntry(user, transport, lastActivity);
 				result.add(res);
 			}
 
@@ -365,16 +358,15 @@ public class DatabaseManager {
 		}
 		return result;
 	}
-	
+
 	public ArrayList<SessionEntry> getAllSessionEntries(String orderAttr, String order) {
 		String allowedAttr = "username transport lastActivity";
 		String allowedOrder = "ASC DESC";
-		if ((orderAttr == null || order == null) 
-				|| (!allowedAttr.contains(orderAttr) || !allowedOrder.contains(order))) {
-			//Use default case if sorting attributes are not correct.
+		if ((orderAttr == null || order == null) || (!allowedAttr.contains(orderAttr) || !allowedOrder.contains(order))) {
+			// Use default case if sorting attributes are not correct.
 			orderAttr = "username";
 			order = "DESC";
-		} 
+		}
 
 		ArrayList<SessionEntry> result = new ArrayList<SessionEntry>();
 		Connection con = null;
@@ -388,7 +380,7 @@ public class DatabaseManager {
 				String user = rs.getString(1);
 				String transport = rs.getString(2);
 				long lastActivity = rs.getLong(3);
-				SessionEntry res = new SessionEntry(user,transport,lastActivity);
+				SessionEntry res = new SessionEntry(user, transport, lastActivity);
 				result.add(res);
 			}
 			pstmt.close();
@@ -399,7 +391,7 @@ public class DatabaseManager {
 		}
 		return result;
 	}
-	
+
 	public int getNumberOfRegistrations() {
 		int result = 0;
 		Connection con = null;

src/plugins/gojara/src/java/org/jivesoftware/openfire/plugin/gojara/sessions/GatewaySession.java

@@ -3,14 +3,15 @@ package org.jivesoftware.openfire.plugin.gojara.sessions;
 import java.util.Date;
 
 /**
- * @author axel.frederik.brand
  * Class for storing Gateway Session Objects for Iteration for JSP
+ * 
+ * @author axel.frederik.brand
  */
 public class GatewaySession {
 	private String username;
 	private String transport;
 	private Date lastActivity;
-	
+
 	public GatewaySession(String username, String transport, Date lastActivity) {
 		this.username = username;
 		this.transport = transport;
@@ -33,6 +34,5 @@ public class GatewaySession {
 	public String toString() {
 		return "GatewaySession [username=" + username + ", transport=" + transport + ", lastActivity=" + lastActivity + "]";
 	}
-	
 
 }

src/plugins/gojara/src/java/org/jivesoftware/openfire/plugin/gojara/sessions/SortLastActivity.java

@@ -2,7 +2,13 @@ package org.jivesoftware.openfire.plugin.gojara.sessions;
 
 import java.util.Comparator;
 
-public class SortLastActivity implements Comparator<GatewaySession>{
+/**
+ * Comparator to sort GatewaySessions
+ * 
+ * @author axel.frederik.brand
+ * 
+ */
+public class SortLastActivity implements Comparator<GatewaySession> {
 
 	public int compare(GatewaySession gws1, GatewaySession gws2) {
 		return gws1.getLastActivity().compareTo(gws2.getLastActivity());

src/plugins/gojara/src/java/org/jivesoftware/openfire/plugin/gojara/sessions/SortTransport.java

@@ -2,7 +2,13 @@ package org.jivesoftware.openfire.plugin.gojara.sessions;
 
 import java.util.Comparator;
 
-public class SortTransport implements Comparator<GatewaySession>{
+/**
+ * Comparator to sort GatewaySessions
+ * 
+ * @author axel.frederik.brand
+ * 
+ */
+public class SortTransport implements Comparator<GatewaySession> {
 
 	public int compare(GatewaySession gws1, GatewaySession gws2) {
 		return gws1.getTransport().compareTo(gws2.getTransport());

src/plugins/gojara/src/java/org/jivesoftware/openfire/plugin/gojara/sessions/SortUserName.java

@@ -2,8 +2,14 @@ package org.jivesoftware.openfire.plugin.gojara.sessions;
 
 import java.util.Comparator;
 
-public class SortUserName implements Comparator<GatewaySession>{
-	
+/**
+ * Comparator to sort GatewaySessions
+ * 
+ * @author axel.frederik.brand
+ * 
+ */
+public class SortUserName implements Comparator<GatewaySession> {
+
 	public int compare(GatewaySession gw1, GatewaySession gw2) {
 		return gw1.getUsername().compareTo(gw2.getUsername());
 	}

src/plugins/gojara/src/java/org/jivesoftware/openfire/plugin/gojara/sessions/TransportSessionManager.java

@@ -13,8 +13,10 @@ import org.slf4j.LoggerFactory;
 import org.xmpp.packet.JID;
 
 /**
+ * This is the central point for doing anything Gojara GatewaySession related, we can add component session, add
+ * gatewaysession etc
+ * 
  * @author axel.frederik.brand
- *	This is the central point for doing anything Gojara GatewaySession Related
  */
 public class TransportSessionManager {
 	private static TransportSessionManager myself;
@@ -38,11 +40,21 @@ public class TransportSessionManager {
 		return myself;
 	}
 
+	/**
+	 * adds a subdomain to watched transports
+	 * 
+	 * @param subdomain
+	 */
 	public void addTransport(String subdomain) {
 		transportSessions.put(subdomain, new ConcurrentHashMap<String, Date>());
 		Log.info("Added key to transportSessionMap: " + subdomain);
 	}
 
+	/**
+	 * removes subdomain from watched transports
+	 * 
+	 * @param subdomain
+	 */
 	public void removeTransport(String subdomain) {
 		Map<String, Date> disconnectedUsers = transportSessions.remove(subdomain);
 		Log.info("Removed " + subdomain + "from TransportSessionMap " + disconnectedUsers.toString());
@@ -52,11 +64,25 @@ public class TransportSessionManager {
 	public boolean isTransportActive(String subdomain) {
 		return transportSessions.containsKey(subdomain) ? true : false;
 	}
+
+	/**
+	 * register is seperate because a user may register to transport but not connect to it, e.g. with wrong credentials.
+	 * we still want to keep track of those registrations so we know they happened and we can reset them
+	 * 
+	 * @param transport
+	 * @param user
+	 */
 	public void registerUserTo(String transport, String user) {
-		//This ofc is not a session yet, so we just keep the registration in db to track eventual unsuccessful registers
 		db.insertOrUpdateSession(transport, user, 0);
 	}
-	
+
+	/**
+	 * Add the session of user that connected to gateway and update or create timestamp for session
+	 * 
+	 * @param transport
+	 * @param user
+	 * @return
+	 */
 	public boolean connectUserTo(String transport, String user) {
 		if (transportSessions.get(transport) != null) {
 			long millis = System.currentTimeMillis();
@@ -82,6 +108,14 @@ public class TransportSessionManager {
 		return transportSessions.get(transport).containsKey(user);
 	}
 
+	/**
+	 * Removing a registration will cause a unregister msg being sent to Spectrum2 for this specific User/Gateway
+	 * combination Also it will be removed from our db.
+	 * 
+	 * @param transport
+	 * @param user
+	 * @return
+	 */
 	public String removeRegistrationOfUser(String transport, String user) {
 		int result = db.removeSessionEntry(transport, user);
 		if (result == 0) {
@@ -96,22 +130,25 @@ public class TransportSessionManager {
 	public final Map<String, Map<String, Date>> getSessions() {
 		return transportSessions;
 	}
-	
-	
+
 	/**
-	 * Puts all Sessions into an ArrayList of GatewaySession Objects, and sorts it according to specified sorting attributes.
-	 * @param sortby username, transport or LoginTime
-	 * @param sortorder ASC or DESC
+	 * Puts all Sessions into an ArrayList of GatewaySession Objects, and sorts it according to specified sorting
+	 * attributes.
+	 * 
+	 * @param sortby
+	 *            username, transport or LoginTime
+	 * @param sortorder
+	 *            ASC or DESC
 	 * @return Sorted/Unsorted ArrayList of GatewaySession Objects
 	 */
-	public ArrayList<GatewaySession> getSessionsSorted(String sortby, String sortorder){
+	public ArrayList<GatewaySession> getSessionsSorted(String sortby, String sortorder) {
 		ArrayList<GatewaySession> result = new ArrayList<GatewaySession>();
 		for (String key : transportSessions.keySet()) {
 			for (String user : transportSessions.get(key).keySet()) {
 				result.add(new GatewaySession(user, key, transportSessions.get(key).get(user)));
 			}
 		}
-		
+
 		if (sortby.equals("username")) {
 			Collections.sort(result, new SortUserName());
 		} else if (sortby.equals("transport")) {
@@ -119,15 +156,14 @@ public class TransportSessionManager {
 		} else if (sortby.equals("loginTime")) {
 			Collections.sort(result, new SortLastActivity());
 		}
-		if (sortorder.equals("DESC")){
+		if (sortorder.equals("DESC")) {
 			Collections.reverse(result);
 		}
-		return  result;
+		return result;
 	}
 
-	
 	/**
-	 * @return  count of recognized active Sessions
+	 * @return count of recognized active Sessions
 	 */
 	public int getNumberOfActiveSessions() {
 		int result = 0;
@@ -136,9 +172,10 @@ public class TransportSessionManager {
 		}
 		return result;
 	}
-	
+
 	/**
 	 * Searches for Sessions with given Username and returns them as ArrList
+	 * 
 	 * @param username
 	 * @return
 	 */
@@ -153,8 +190,10 @@ public class TransportSessionManager {
 		}
 		return userconnections;
 	}
+
 	/**
 	 * Returns Registrations associated with Username
+	 * 
 	 * @param username
 	 * @return ArrayList of SessionEntries
 	 */
@@ -163,13 +202,13 @@ public class TransportSessionManager {
 	}
 
 	/**
-	 * Validation for correctness of attributes is done in DB Manager, returns default sorting: username ASC when not
-	 * correct
+	 * Get all registrations sorted by attribute and order. Validation for correctness of attributes is done in DB
+	 * Manager, returns default sorting: username ASC when not valid
 	 */
 	public ArrayList<SessionEntry> getAllRegistrations(String orderAttr, String order) {
 		return db.getAllSessionEntries(orderAttr, order);
 	}
-	
+
 	public int getNumberOfRegistrations() {
 		return db.getNumberOfRegistrations();
 	}

src/plugins/gojara/src/java/org/jivesoftware/openfire/plugin/gojara/utils/JspHelper.java

@@ -5,12 +5,14 @@ import java.util.Date;
 import java.util.Map;
 
 /**
- * @author axel.frederik.brand
- *	Helper for generating specificly linked helper columns. 
+ * @author axel.frederik.brand Helper for some functions we call from gojara registration / session jsps
  */
 public class JspHelper {
-	
+
 	/**
+	 * Create a link that leads to the same page, sorted by the attribute clicked on. The sorting Order depends on the
+	 * current sorting order. If element is not the one currently sorted by, its always ASC, else DESC
+	 * 
 	 * @param column
 	 * @param sortParams
 	 * @return String with html in it
@@ -18,17 +20,17 @@ public class JspHelper {
 	public static String sortingHelperRegistrations(String column, Map<String, String> sortParams) {
 		String link_beginning = "<a href=\"gojara-RegistrationsOverview.jsp?sortby=";
 		return helpMe(column, sortParams, link_beginning);
- 	}
-	
+	}
+
 	public static String sortingHelperSessions(String column, Map<String, String> sortParams) {
 		String link_beginning = "<a href=\"gojara-activeSessions.jsp?sortby=";
 		return helpMe(column, sortParams, link_beginning);
 	}
-	
+
 	private static String helpMe(String column, Map<String, String> sortParams, String link_beginning) {
 		String image_asc = "<img alt=\"sorted ASC\" src=\"/images/sort_ascending.gif\">";
 		String image_desc = "<img alt=\"sorted DESC\" src=\"/images/sort_descending.gif\">";
-		
+
 		String ending = "";
 		if (column.equals("username"))
 			ending = "User Name:";
@@ -38,10 +40,10 @@ public class JspHelper {
 			ending = "Last Login was at:";
 		else if (column.equals("loginTime"))
 			ending = "Login Time:";
-		else 
+		else
 			ending = "i dont want to be here";
 		ending += "</a>";
-		
+
 		String sortinglink = "";
 		if (sortParams.containsValue(column)) {
 			if (sortParams.containsValue("ASC")) {
@@ -55,9 +57,11 @@ public class JspHelper {
 		}
 		return sortinglink;
 	}
-	
+
 	/**
-	 * Compares specified date to current date and returns String explaining how much Minutes / Hours / Days has passed since then
+	 * Compares specified date to current date and returns String explaining how much Minutes / Hours / Days has passed
+	 * since then
+	 * 
 	 * @param oldDate
 	 * @return
 	 */
@@ -65,12 +69,12 @@ public class JspHelper {
 		Timestamp stamp = new Timestamp(System.currentTimeMillis());
 		Date currentDate = new Date(stamp.getTime());
 		long diff = currentDate.getTime() - oldDate.getTime();
-		
+
 		long diffSeconds = diff / 1000 % 60;
 		long diffMinutes = diff / (60 * 1000) % 60;
 		long diffHours = diff / (60 * 60 * 1000) % 24;
 		long diffDays = diff / (24 * 60 * 60 * 1000);
-		
+
 		return "" + diffSeconds + " Seconds " + diffMinutes + " Minutes " + diffHours + " Hours " + diffDays + " Days ago";
 	}
 }