Doc: Improve javadoc

git-svn-id: http://svn.code.sf.net/p/davmail/code/trunk@680 3d1905a2-6b24-0410-a738-b14d5a86fcbd

src/java/davmail/exchange/ExchangeSession.java

@@ -981,7 +981,7 @@ public class ExchangeSession {
 
     /**
      * Delete Exchange folder.
-     * 
+     *
      * @param folderName logical folder name
      * @throws IOException on error
      */
@@ -1416,6 +1416,7 @@ public class ExchangeSession {
         /**
          * Load ICS content from Exchange server.
          * User Translate: f header to get MIME event content and get ICS attachment from it
+         *
          * @return ICS (iCalendar) event
          * @throws IOException on error
          */
@@ -1461,6 +1462,7 @@ public class ExchangeSession {
 
         /**
          * Get event name (file name part in URL).
+         *
          * @return event name
          */
         public String getName() {
@@ -1474,6 +1476,7 @@ public class ExchangeSession {
 
         /**
          * Get event etag (last change tag).
+         *
          * @return event etag
          */
         public String getEtag() {
@@ -1483,6 +1486,7 @@ public class ExchangeSession {
 
     /**
      * Search calendar messages in provided folder.
+     *
      * @param folderPath Exchange folder path
      * @return list of calendar messages as Event objects
      * @throws IOException on error
@@ -1498,6 +1502,7 @@ public class ExchangeSession {
 
     /**
      * Search calendar events in provided folder.
+     *
      * @param folderPath Exchange folder path
      * @return list of calendar events
      * @throws IOException on error
@@ -1526,7 +1531,8 @@ public class ExchangeSession {
 
     /**
      * Search calendar events or messages in provided folder matching the search query.
-     * @param folderPath Exchange folder path
+     *
+     * @param folderPath  Exchange folder path
      * @param searchQuery Exchange search query
      * @return list of calendar messages as Event objects
      * @throws IOException on error
@@ -1542,8 +1548,9 @@ public class ExchangeSession {
 
     /**
      * Get event named eventName in folder
+     *
      * @param folderPath Exchange folder path
-     * @param eventName event name
+     * @param eventName  event name
      * @return event object
      * @throws IOException on error
      */
@@ -1558,8 +1565,9 @@ public class ExchangeSession {
 
     /**
      * Delete event named eventName in folder
+     *
      * @param folderPath Exchange folder path
-     * @param eventName event name
+     * @param eventName  event name
      * @return HTTP status
      * @throws IOException on error
      */
@@ -1791,6 +1799,7 @@ public class ExchangeSession {
 
     /**
      * Build and send the MIME message for the provided ICS event.
+     *
      * @param icsBody event in iCalendar format
      * @return HTTP status
      * @throws IOException on error
@@ -1812,11 +1821,12 @@ public class ExchangeSession {
 
     /**
      * Create or update event on the Exchange server
+     *
      * @param folderPath Exchange folder path
-     * @param eventName event name
+     * @param eventName  event name
-     * @param icsBody event body in iCalendar format
+     * @param icsBody    event body in iCalendar format
-     * @param etag previous event etag to detect concurrent updates
+     * @param etag       previous event etag to detect concurrent updates
-     * @param noneMatch if-none-match header value
+     * @param noneMatch  if-none-match header value
      * @return HTTP response event result (status and etag)
      * @throws IOException on error
      */
@@ -2028,7 +2038,7 @@ public class ExchangeSession {
      * Get folder ctag (change tag).
      * This flag changes whenever folder or folder content changes
      *
-     * @param folderPath Exchange folder path 
+     * @param folderPath Exchange folder path
      * @return folder ctag
      * @throws IOException on error
      */
@@ -2099,6 +2109,7 @@ public class ExchangeSession {
 
     /**
      * Get user alias from mailbox display name over Webdav.
+     *
      * @return user alias
      */
     public String getAliasFromMailboxDisplayName() {
@@ -2123,10 +2134,10 @@ public class ExchangeSession {
     /**
      * Build Caldav calendar path for principal and folder name.
      * - prefix is current user mailbox path if principal is current user,
-     *   else prefix is parent folder of current user mailbox path followed by principal
+     * else prefix is parent folder of current user mailbox path followed by principal
      * - suffix according to well known folder names (internationalized on Exchange)
      *
-     * @param principal calendar principal
+     * @param principal  calendar principal
      * @param folderName requested folder name
      * @return Exchange folder path
      * @throws IOException on error
@@ -2204,7 +2215,7 @@ public class ExchangeSession {
     /**
      * Determine user email through various means.
      *
-     * @param hostName Exchange server host name for last failover
+     * @param hostName   Exchange server host name for last failover
      * @param methodPath current httpclient method path
      */
     public void buildEmail(String hostName, String methodPath) {
@@ -2404,10 +2415,10 @@ public class ExchangeSession {
 
     /**
      * Get freebusy info for attendee between start and end date.
-     * 
+     *
-     * @param attendee attendee email
+     * @param attendee       attendee email
      * @param startDateValue start date
-     * @param endDateValue end date
+     * @param endDateValue   end date
      * @return FreeBusy info
      * @throws IOException on error
      */
@@ -2539,6 +2550,7 @@ public class ExchangeSession {
 
         /**
          * Append freebusy information to buffer.
+         *
          * @param buffer String buffer
          */
         public void appendTo(StringBuilder buffer) {
@@ -2548,7 +2560,12 @@ public class ExchangeSession {
             }
         }
     }
-public HttpClient getHttpClient() {
+
-    return httpClient;
+    /**
-}
+     * Return internal HttpClient instance
+     * @return http client
+     */
+    public HttpClient getHttpClient() {
+        return httpClient;
+    }
 }

src/java/davmail/http/DavGatewayHttpClientFacade.java

@@ -18,8 +18,8 @@
  */
 package davmail.http;
 
-import davmail.Settings;
 import davmail.BundleMessage;
+import davmail.Settings;
 import davmail.exception.DavMailException;
 import davmail.ui.tray.DavGatewayTray;
 import org.apache.commons.httpclient.*;
@@ -28,17 +28,16 @@ import org.apache.commons.httpclient.auth.AuthScope;
 import org.apache.commons.httpclient.methods.DeleteMethod;
 import org.apache.commons.httpclient.methods.GetMethod;
 import org.apache.commons.httpclient.methods.StringRequestEntity;
-import org.apache.commons.httpclient.params.HttpMethodParams;
 import org.apache.commons.httpclient.params.HttpClientParams;
+import org.apache.commons.httpclient.params.HttpMethodParams;
 import org.apache.jackrabbit.webdav.DavException;
 import org.apache.jackrabbit.webdav.MultiStatusResponse;
-import org.apache.jackrabbit.webdav.property.DavPropertyNameSet;
 import org.apache.jackrabbit.webdav.client.methods.DavMethodBase;
 import org.apache.jackrabbit.webdav.client.methods.PropFindMethod;
+import org.apache.jackrabbit.webdav.property.DavPropertyNameSet;
 
 import java.io.IOException;
 import java.util.ArrayList;
-import java.net.URL;
 
 /**
  * Create HttpClient instance according to DavGateway Settings
@@ -75,13 +74,22 @@ public final class DavGatewayHttpClientFacade {
         return httpClient;
     }
 
+    /**
+     * Build an HttpClient instance for the provided url and credentials.
+     *
+     * @param url      http(s) url
+     * @param userName user name
+     * @param password user password
+     * @return HttpClient instance
+     * @throws DavMailException on error
+     */
     public static HttpClient getInstance(String url, String userName, String password) throws DavMailException {
         HttpClient httpClient = new HttpClient();
         httpClient.getParams().setParameter(HttpMethodParams.USER_AGENT, IE_USER_AGENT);
         httpClient.getParams().setParameter(HttpClientParams.MAX_REDIRECTS, MAX_REDIRECTS);
         HostConfiguration hostConfig = httpClient.getHostConfiguration();
         try {
-            URI httpURI = new URI(url, true); 
+            URI httpURI = new URI(url, true);
             hostConfig.setHost(httpURI);
             AuthScope authScope = new AuthScope(httpURI.getHost(), httpURI.getPort(), AuthScope.ANY_REALM);
             httpClient.getState().setCredentials(authScope, new UsernamePasswordCredentials(userName, password));
@@ -163,6 +171,12 @@ public final class DavGatewayHttpClientFacade {
         return status;
     }
 
+    /**
+     * Check if status is a redirect (various 30x values).
+     *
+     * @param status Http status
+     * @return true if status is a redirect
+     */
     public static boolean isRedirect(int status) {
         return status == HttpStatus.SC_MOVED_PERMANENTLY
                 || status == HttpStatus.SC_MOVED_TEMPORARILY
@@ -185,6 +199,14 @@ public final class DavGatewayHttpClientFacade {
         return executeFollowRedirects(httpClient, method);
     }
 
+    /**
+     * Execute method with httpClient, follow 30x redirects.
+     *
+     * @param httpClient Http client instance
+     * @param method     Http method
+     * @return last http method after redirects
+     * @throws IOException on error
+     */
     public static HttpMethod executeFollowRedirects(HttpClient httpClient, HttpMethod method) throws IOException {
         HttpMethod currentMethod = method;
         try {
@@ -259,6 +281,14 @@ public final class DavGatewayHttpClientFacade {
         return executeMethod(httpClient, propFindMethod);
     }
 
+    /**
+     * Execute a delete method on the given path with httpClient.
+     *
+     * @param httpClient Http client instance
+     * @param path       Path to be deleted
+     * @return Http status
+     * @throws IOException on error
+     */
     public static int executeDeleteMethod(HttpClient httpClient, String path) throws IOException {
         DeleteMethod deleteMethod = new DeleteMethod(path);
 
@@ -296,6 +326,14 @@ public final class DavGatewayHttpClientFacade {
         return responses;
     }
 
+    /**
+     * Execute method with httpClient.
+     *
+     * @param httpClient Http client instance
+     * @param method     Http method
+     * @return Http status
+     * @throws IOException on error
+     */
     public static int executeHttpMethod(HttpClient httpClient, HttpMethod method) throws IOException {
         int status = 0;
         try {
@@ -322,6 +360,9 @@ public final class DavGatewayHttpClientFacade {
         }
     }
 
+    /**
+     * Stop HttpConnectionManager.
+     */
     public static void stop() {
         if (multiThreadedHttpConnectionManager != null) {
             if (httpConnectionManagerThread != null) {
@@ -332,6 +373,9 @@ public final class DavGatewayHttpClientFacade {
         }
     }
 
+    /**
+     * Create and start a new HttpConnectionManager, close idle connections every minute. 
+     */
     public static void start() {
         if (multiThreadedHttpConnectionManager == null) {
             multiThreadedHttpConnectionManager = new MultiThreadedHttpConnectionManager();

src/java/davmail/http/DavGatewayX509TrustManager.java

@@ -42,6 +42,12 @@ import java.io.InputStreamReader;
 public class DavGatewayX509TrustManager implements X509TrustManager {
     private final X509TrustManager standardTrustManager;
 
+    /**
+     * Create a new custom X509 trust manager.
+     *
+     * @throws NoSuchAlgorithmException on error
+     * @throws KeyStoreException        on error
+     */
     public DavGatewayX509TrustManager() throws NoSuchAlgorithmException, KeyStoreException {
         TrustManagerFactory factory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
         factory.init((KeyStore) null);
@@ -130,6 +136,12 @@ public class DavGatewayX509TrustManager implements X509TrustManager {
         return yes.equals(answer);
     }
 
+    /**
+     * Get rdn value from principal dn.
+     *
+     * @param principal security principal
+     * @return rdn
+     */
     public static String getRDN(Principal principal) {
         String dn = principal.getName();
         int start = dn.indexOf('=');
@@ -141,6 +153,12 @@ public class DavGatewayX509TrustManager implements X509TrustManager {
         }
     }
 
+    /**
+     * Build a formatted certificate serial string.
+     *
+     * @param certificate X509 certificate
+     * @return formatted serial
+     */
     public static String getFormattedSerial(X509Certificate certificate) {
         StringBuilder builder = new StringBuilder();
         String serial = certificate.getSerialNumber().toString(16);
@@ -153,6 +171,12 @@ public class DavGatewayX509TrustManager implements X509TrustManager {
         return builder.toString().toUpperCase();
     }
 
+    /**
+     * Build a formatted hash string.
+     *
+     * @param certificate X509 certificate
+     * @return formatted hash
+     */
     public static String getFormattedHash(X509Certificate certificate) {
         String sha1Hash;
         try {
@@ -167,7 +191,13 @@ public class DavGatewayX509TrustManager implements X509TrustManager {
         return sha1Hash;
     }
 
-    public static String formatHash(byte[] buffer) {
+    /**
+     * Format byte buffer to a hexadecimal hash string.
+     *
+     * @param buffer byte array
+     * @return hexadecimal hash string
+     */
+    protected static String formatHash(byte[] buffer) {
         StringBuilder builder = new StringBuilder();
         for (int i = 0; i < buffer.length; i++) {
             if (i > 0) {

src/java/davmail/imap/ImapServer.java

@@ -28,6 +28,9 @@ import java.net.Socket;
  * Pop3 server
  */
 public class ImapServer extends AbstractServer {
+    /**
+     * Default IMAP port
+     */
     public static final int DEFAULT_PORT = 143;
 
     /**

src/java/davmail/ldap/LdapConnection.java

@@ -295,7 +295,11 @@ public class LdapConnection extends AbstractConnection {
      */
     int ldapVersion = LDAP_VERSION3;
 
-    // Initialize the streams and start the thread
+    /**
+     * Initialize the streams and start the thread.
+     *
+     * @param clientSocket LDAP client socket
+     */
     public LdapConnection(Socket clientSocket) {
         super(LdapConnection.class.getSimpleName(), clientSocket);
         try {

src/java/davmail/ldap/LdapServer.java

@@ -27,6 +27,9 @@ import java.net.Socket;
  * LDAP server, handle LDAP directory requests.
  */
 public class LdapServer extends AbstractServer {
+    /**
+     * Default LDAP port
+     */
     public static final int DEFAULT_PORT = 389;
 
     /**

src/java/davmail/pop/PopServer.java

@@ -28,6 +28,9 @@ import java.net.Socket;
  * Pop3 server
  */
 public class PopServer extends AbstractServer {
+    /**
+     * Default POP port
+     */
     public static final int DEFAULT_PORT = 110;
 
     /**

src/java/davmail/smtp/SmtpConnection.java

@@ -39,7 +39,11 @@ import java.util.ArrayList;
  */
 public class SmtpConnection extends AbstractConnection {
 
-    // Initialize the streams and start the thread
+    /**
+     * Initialize the streams and start the thread.
+     *
+     * @param clientSocket SMTP client socket
+     */
     public SmtpConnection(Socket clientSocket) {
         super(SmtpConnection.class.getSimpleName(), clientSocket, null);
     }

src/java/davmail/smtp/SmtpServer.java

@@ -23,7 +23,13 @@ import davmail.AbstractServer;
 
 import java.net.Socket;
 
+/**
+ * SMTP server, handle message send requests.
+ */
 public class SmtpServer extends AbstractServer {
+    /**
+     * Default SMTP Caldav port
+     */
     public static final int DEFAULT_PORT = 25;
 
     /**