Doc: improve javadoc and code cleanup

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

src/java/davmail/AbstractServer.java

@@ -174,8 +174,17 @@ public abstract class AbstractServer extends Thread {
         }
     }
 
+    /**
+     * Create a connection handler for the current listener.
+     *
+     * @param clientSocket client socket
+     * @return connection handler
+     */
     public abstract AbstractConnection createConnectionHandler(Socket clientSocket);
 
+    /**
+     * Close server socket
+     */
     public void close() {
         try {
             if (serverSocket != null) {

src/java/davmail/http/DavGatewaySSLProtocolSocketFactory.java

@@ -41,7 +41,6 @@ import java.net.MalformedURLException;
 import java.net.Socket;
 import java.net.URL;
 import java.security.*;
-import java.security.cert.CertificateException;
 
 /**
  * Manual Socket Factory.
@@ -71,8 +70,7 @@ public class DavGatewaySSLProtocolSocketFactory implements SecureProtocolSocketF
 
     private SSLContext sslcontext;
 
-    private SSLContext createSSLContext() throws NoSuchAlgorithmException, KeyManagementException, KeyStoreException,
+    private SSLContext createSSLContext() throws NoSuchAlgorithmException, InvalidAlgorithmParameterException, KeyManagementException, KeyStoreException {
-            InvalidAlgorithmParameterException {
         // PKCS11 client certificate settings
         String pkcs11Library = Settings.getProperty("davmail.ssl.pkcs11Library");
         if (pkcs11Library != null && pkcs11Library.length() > 0) {
@@ -105,7 +103,7 @@ public class DavGatewaySSLProtocolSocketFactory implements SecureProtocolSocketF
         return context;
     }
 
-    private SSLContext getSSLContext() throws NoSuchAlgorithmException, KeyManagementException, KeyStoreException, UnrecoverableKeyException, IOException, CertificateException, InvalidAlgorithmParameterException {
+    private SSLContext getSSLContext() throws NoSuchAlgorithmException, KeyManagementException, KeyStoreException,    InvalidAlgorithmParameterException {
         if (this.sslcontext == null) {
             this.sslcontext = createSSLContext();
         }
@@ -122,10 +120,6 @@ public class DavGatewaySSLProtocolSocketFactory implements SecureProtocolSocketF
             throw new IOException(e + " " + e.getMessage());
         } catch (KeyStoreException e) {
             throw new IOException(e + " " + e.getMessage());
-        } catch (UnrecoverableKeyException e) {
-            throw new IOException(e + " " + e.getMessage());
-        } catch (CertificateException e) {
-            throw new IOException(e + " " + e.getMessage());
         } catch (InvalidAlgorithmParameterException e) {
             throw new IOException(e + " " + e.getMessage());
         }
@@ -140,10 +134,6 @@ public class DavGatewaySSLProtocolSocketFactory implements SecureProtocolSocketF
             throw new IOException(e + " " + e.getMessage());
         } catch (KeyStoreException e) {
             throw new IOException(e + " " + e.getMessage());
-        } catch (UnrecoverableKeyException e) {
-            throw new IOException(e + " " + e.getMessage());
-        } catch (CertificateException e) {
-            throw new IOException(e + " " + e.getMessage());
         } catch (InvalidAlgorithmParameterException e) {
             throw new IOException(e + " " + e.getMessage());
         }
@@ -159,10 +149,6 @@ public class DavGatewaySSLProtocolSocketFactory implements SecureProtocolSocketF
             throw new IOException(e + " " + e.getMessage());
         } catch (KeyStoreException e) {
             throw new IOException(e + " " + e.getMessage());
-        } catch (UnrecoverableKeyException e) {
-            throw new IOException(e + " " + e.getMessage());
-        } catch (CertificateException e) {
-            throw new IOException(e + " " + e.getMessage());
         } catch (InvalidAlgorithmParameterException e) {
             throw new IOException(e + " " + e.getMessage());
         }
@@ -177,10 +163,6 @@ public class DavGatewaySSLProtocolSocketFactory implements SecureProtocolSocketF
             throw new IOException(e + " " + e.getMessage());
         } catch (KeyStoreException e) {
             throw new IOException(e + " " + e.getMessage());
-        } catch (UnrecoverableKeyException e) {
-            throw new IOException(e + " " + e.getMessage());
-        } catch (CertificateException e) {
-            throw new IOException(e + " " + e.getMessage());
         } catch (InvalidAlgorithmParameterException e) {
             throw new IOException(e + " " + e.getMessage());
         }

src/java/davmail/ldap/LdapConnection.java

@@ -843,12 +843,6 @@ public class LdapConnection extends AbstractConnection {
                 if (returningAttributes.contains("uidnumber")) {
                     ldapPerson.put("uidnumber", userName);
                 }
-                // TODO: check if this breaks iCal3
-/*                if (returningAttributes.contains("apple-generateduid")) {
-                    ldapPerson.put("apple-generateduid", userName);
-                    ldapPerson.put("uid", userName);
-                }
-*/
             }
             DavGatewayTray.debug(new BundleMessage("LOG_LDAP_REQ_SEARCH_SEND_PERSON", currentMessageId, ldapPerson.get("uid"), baseContext, ldapPerson));
             sendEntry(currentMessageId, "uid=" + ldapPerson.get("uid") + baseContext, ldapPerson);

src/java/davmail/ui/AboutFrame.java

@@ -21,6 +21,7 @@ package davmail.ui;
 import davmail.DavGateway;
 import davmail.BundleMessage;
 import davmail.ui.tray.DavGatewayTray;
+import davmail.ui.browser.DesktopBrowser;
 
 import javax.imageio.ImageIO;
 import javax.swing.*;
@@ -41,6 +42,9 @@ import java.net.URL;
 public class AboutFrame extends JFrame {
     private final JEditorPane jEditorPane;
 
+    /**
+     * About frame.
+     */
     public AboutFrame() {
         setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE);
         setTitle(BundleMessage.format("UI_ABOUT_DAVMAIL"));
@@ -125,6 +129,9 @@ public class AboutFrame extends JFrame {
     }
 
 
+    /**
+     * Update about frame content with current released version.
+     */
     public void update() {
         jEditorPane.setText(getContent(DavGateway.getReleasedVersion()));
         pack();

src/java/davmail/ui/AcceptCertificateDialog.java

@@ -37,11 +37,23 @@ import java.util.Date;
 public class AcceptCertificateDialog extends JDialog {
     protected boolean accepted;
 
+    /**
+     * Accept status.
+     *
+     * @return true if user accepted certificate
+     */
     public boolean isAccepted() {
         return accepted;
     }
 
-    public void addFieldValue(JPanel panel, String label, String value) {
+    /**
+     * Add a new JLabel to panel with <b>label</b>: value text.
+     *
+     * @param panel certificate details panel
+     * @param label certificate attribute label
+     * @param value certificate attribute value
+     */
+    protected void addFieldValue(JPanel panel, String label, String value) {
         JPanel fieldPanel = new JPanel(new FlowLayout(FlowLayout.LEFT));
         StringBuilder buffer = new StringBuilder();
         buffer.append("<html><b>");
@@ -52,6 +64,11 @@ public class AcceptCertificateDialog extends JDialog {
         panel.add(fieldPanel);
     }
 
+    /**
+     * Accept certificate dialog.
+     *
+     * @param certificate certificate sent by server
+     */
     public AcceptCertificateDialog(X509Certificate certificate) {
         setAlwaysOnTop(true);
         String sha1Hash = DavGatewayX509TrustManager.getFormattedHash(certificate);
@@ -125,6 +142,12 @@ public class AcceptCertificateDialog extends JDialog {
     }
 
 
+    /**
+     * Display certificate accept dialog and get user answer.
+     *
+     * @param certificate certificate sent by server
+     * @return true if user accepted certificate
+     */
     public static boolean isCertificateTrusted(final X509Certificate certificate) {
         final boolean[] answer = new boolean[1];
         try {

src/java/davmail/ui/OSXAdapter.java

@@ -34,14 +34,34 @@ public class OSXAdapter implements InvocationHandler {
 
     static Object macOSXApplication;
 
-    // Pass this method an Object and Method equipped to perform application shutdown logic
+    /**
-    // The method passed should return a boolean stating whether or not the quit should occur
+     * Pass this method an Object and Method equipped to perform application shutdown logic.
+     * The method passed should return a boolean stating whether or not the quit should occur
+     *
+     * @param target      target object
+     * @param quitHandler quit method
+     * @throws InvocationTargetException on error
+     * @throws ClassNotFoundException    on error
+     * @throws NoSuchMethodException     on error
+     * @throws InstantiationException    on error
+     * @throws IllegalAccessException    on error
+     */
     public static void setQuitHandler(Object target, Method quitHandler) throws InvocationTargetException, ClassNotFoundException, NoSuchMethodException, InstantiationException, IllegalAccessException {
         setHandler(new OSXAdapter("handleQuit", target, quitHandler));
     }
 
-    // Pass this method an Object and Method equipped to display application info
+    /**
-    // They will be called when the About menu item is selected from the application menu
+     * Pass this method an Object and Method equipped to display application info
+     * They will be called when the About menu item is selected from the application menu
+     *
+     * @param target       target object
+     * @param aboutHandler about method
+     * @throws InvocationTargetException on error
+     * @throws ClassNotFoundException    on error
+     * @throws NoSuchMethodException     on error
+     * @throws InstantiationException    on error
+     * @throws IllegalAccessException    on error
+     */
     public static void setAboutHandler(Object target, Method aboutHandler) throws InvocationTargetException, IllegalAccessException, NoSuchMethodException, ClassNotFoundException, InstantiationException {
         boolean enableAboutMenu = (target != null && aboutHandler != null);
         if (enableAboutMenu) {
@@ -51,8 +71,18 @@ public class OSXAdapter implements InvocationHandler {
         enableAboutMethod.invoke(macOSXApplication, enableAboutMenu);
     }
 
-    // Pass this method an Object and a Method equipped to display application options
+    /**
-    // They will be called when the Preferences menu item is selected from the application menu
+     * Pass this method an Object and a Method equipped to display application options.
+     * They will be called when the Preferences menu item is selected from the application menu
+     *
+     * @param target       target object
+     * @param prefsHandler preferences method
+     * @throws InvocationTargetException on error
+     * @throws ClassNotFoundException    on error
+     * @throws NoSuchMethodException     on error
+     * @throws InstantiationException    on error
+     * @throws IllegalAccessException    on error
+     */
     public static void setPreferencesHandler(Object target, Method prefsHandler) throws InvocationTargetException, IllegalAccessException, NoSuchMethodException, ClassNotFoundException, InstantiationException {
         boolean enablePrefsMenu = (target != null && prefsHandler != null);
         if (enablePrefsMenu) {
@@ -62,9 +92,19 @@ public class OSXAdapter implements InvocationHandler {
         enablePrefsMethod.invoke(macOSXApplication, enablePrefsMenu);
     }
 
-    // Pass this method an Object and a Method equipped to handle document events from the Finder
+    /**
-    // Documents are registered with the Finder via the CFBundleDocumentTypes dictionary in the
+     * Pass this method an Object and a Method equipped to handle document events from the Finder.
-    // application bundle's Info.plist
+     * Documents are registered with the Finder via the CFBundleDocumentTypes dictionary in the
+     * application bundle's Info.plist
+     *
+     * @param target      target object
+     * @param fileHandler file method
+     * @throws InvocationTargetException on error
+     * @throws ClassNotFoundException    on error
+     * @throws NoSuchMethodException     on error
+     * @throws InstantiationException    on error
+     * @throws IllegalAccessException    on error
+     */
     public static void setFileHandler(Object target, Method fileHandler) throws InvocationTargetException, ClassNotFoundException, NoSuchMethodException, InstantiationException, IllegalAccessException {
         setHandler(new OSXAdapter("handleOpenFile", target, fileHandler) {
             // Override OSXAdapter.callTarget to send information on the
@@ -85,7 +125,16 @@ public class OSXAdapter implements InvocationHandler {
         });
     }
 
-    // setHandler creates a Proxy object from the passed OSXAdapter and adds it as an ApplicationListener
+    /**
+     * setHandler creates a Proxy object from the passed OSXAdapter and adds it as an ApplicationListener.
+     *
+     * @param adapter OSX adapter
+     * @throws InvocationTargetException on error
+     * @throws ClassNotFoundException    on error
+     * @throws NoSuchMethodException     on error
+     * @throws InstantiationException    on error
+     * @throws IllegalAccessException    on error
+     */
     public static void setHandler(OSXAdapter adapter) throws ClassNotFoundException, NoSuchMethodException, InvocationTargetException, IllegalAccessException, InstantiationException {
         Class applicationClass = Class.forName("com.apple.eawt.Application");
         if (macOSXApplication == null) {
@@ -98,24 +147,45 @@ public class OSXAdapter implements InvocationHandler {
         addListenerMethod.invoke(macOSXApplication, osxAdapterProxy);
     }
 
-    // Each OSXAdapter has the name of the EAWT method it intends to listen for (handleAbout, for example),
+    /**
-    // the Object that will ultimately perform the task, and the Method to be called on that Object
+     * Each OSXAdapter has the name of the EAWT method it intends to listen for (handleAbout, for example),
+     * the Object that will ultimately perform the task, and the Method to be called on that Object
+     *
+     * @param proxySignature proxy signature
+     * @param target         target object
+     * @param handler        handler method
+     */
     protected OSXAdapter(String proxySignature, Object target, Method handler) {
         this.proxySignature = proxySignature;
         this.targetObject = target;
         this.targetMethod = handler;
     }
 
-    // Override this method to perform any operations on the event
+    /**
-    // that comes with the various callbacks
+     * Override this method to perform any operations on the event
-    // See setFileHandler above for an example
+     * that comes with the various callbacks.
+     * See setFileHandler above for an example
+     *
+     * @param appleEvent apple event object
+     * @return true on success
+     * @throws InvocationTargetException on error
+     * @throws IllegalAccessException    on error
+     */
     public boolean callTarget(Object appleEvent) throws InvocationTargetException, IllegalAccessException {
         Object result = targetMethod.invoke(targetObject, (Object[]) null);
         return result == null || Boolean.valueOf(result.toString());
     }
 
-    // InvocationHandler implementation
+    /**
-    // This is the entry point for our proxy object; it is called every time an ApplicationListener method is invoked
+     * InvocationHandler implementation.
+     * This is the entry point for our proxy object; it is called every time an ApplicationListener method is invoked
+     *
+     * @param proxy  proxy object
+     * @param method handler method
+     * @param args   method arguments
+     * @return null
+     * @throws Throwable on error
+     */
     public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
         if (isCorrectMethod(method, args)) {
             boolean handled = callTarget(args[0]);
@@ -125,14 +195,30 @@ public class OSXAdapter implements InvocationHandler {
         return null;
     }
 
-    // Compare the method that was called to the intended method when the OSXAdapter instance was created
+    //
-    // (e.g. handleAbout, handleQuit, handleOpenFile, etc.)
+    //
+    /**
+     * Compare the method that was called to the intended method when the OSXAdapter instance was created
+     * (e.g. handleAbout, handleQuit, handleOpenFile, etc.).
+     *
+     * @param method handler method
+     * @param args   method arguments
+     * @return true if method is correct
+     */
     protected boolean isCorrectMethod(Method method, Object[] args) {
         return (targetMethod != null && proxySignature.equals(method.getName()) && args.length == 1);
     }
 
-    // It is important to mark the ApplicationEvent as handled and cancel the default behavior
+    /**
-    // This method checks for a boolean result from the proxy method and sets the event accordingly
+     * It is important to mark the ApplicationEvent as handled and cancel the default behavior.
+     * This method checks for a boolean result from the proxy method and sets the event accordingly
+     *
+     * @param event   event object
+     * @param handled true if event handled
+     * @throws NoSuchMethodException     on error
+     * @throws InvocationTargetException on error
+     * @throws IllegalAccessException    on error
+     */
     protected void setApplicationEventHandled(Object event, boolean handled) throws NoSuchMethodException, InvocationTargetException, IllegalAccessException {
         if (event != null) {
             Method setHandledMethod = event.getClass().getDeclaredMethod("setHandled", new Class[]{boolean.class});

src/java/davmail/ui/PasswordPromptDialog.java

@@ -33,10 +33,20 @@ public class PasswordPromptDialog extends JDialog {
     final JPasswordField passwordField = new JPasswordField(20);
     protected char[] password;
 
+    /**
+     * Get user password.
+     *
+     * @return user password as char array
+     */
     public char[] getPassword() {
         return password;
     }
 
+    /**
+     * Get smartcard password.
+     *
+     * @param prompt password prompt from PKCS11 module
+     */
     public PasswordPromptDialog(String prompt) {
         setAlwaysOnTop(true);
 

src/java/davmail/ui/SettingsFrame.java

@@ -22,6 +22,7 @@ import davmail.BundleMessage;
 import davmail.DavGateway;
 import davmail.Settings;
 import davmail.ui.tray.DavGatewayTray;
+import davmail.ui.browser.DesktopBrowser;
 import org.apache.log4j.Level;
 
 import javax.swing.*;
@@ -272,7 +273,7 @@ public class SettingsFrame extends JFrame {
         return smartcardPanel;
     }
 
-    public JPanel getNetworkSettingsPanel() {
+    protected JPanel getNetworkSettingsPanel() {
         JPanel networkSettingsPanel = new JPanel(new GridLayout(4, 2));
         networkSettingsPanel.setBorder(BorderFactory.createTitledBorder(BundleMessage.format("UI_NETWORK")));
 
@@ -297,7 +298,7 @@ public class SettingsFrame extends JFrame {
         return networkSettingsPanel;
     }
 
-    public JPanel getLoggingSettingsPanel() {
+    protected JPanel getLoggingSettingsPanel() {
         JPanel loggingLevelPanel = new JPanel();
         JPanel leftLoggingPanel = new JPanel(new GridLayout(2, 2));
         JPanel rightLoggingPanel = new JPanel(new GridLayout(2, 2));
@@ -331,6 +332,9 @@ public class SettingsFrame extends JFrame {
         return loggingPanel;
     }
 
+    /**
+     * Reload settings from properties.
+     */
     public void reload() {
         // reload settings in form
         urlField.setText(Settings.getProperty("davmail.url"));
@@ -378,6 +382,9 @@ public class SettingsFrame extends JFrame {
         logFilePathField.setText(Settings.getProperty("davmail.logFilePath"));
     }
 
+    /**
+     * DavMail settings frame.
+     */
     public SettingsFrame() {
         setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE);
         setTitle(BundleMessage.format("UI_DAVMAIL_SETTINGS"));

src/java/davmail/ui/browser/AwtDesktopBrowser.java

@@ -16,7 +16,7 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  */
-package davmail.ui;
+package davmail.ui.browser;
 
 import java.io.IOException;
 import java.net.URI;
@@ -29,6 +29,13 @@ public final class AwtDesktopBrowser {
     private AwtDesktopBrowser() {
     }
 
+    /**
+     * Open default browser at location URI.
+     * User Java 6 Desktop class
+     *
+     * @param location location URI
+     * @throws IOException on error
+     */
     public static void browse(URI location) throws IOException {
         Desktop desktop = Desktop.getDesktop();
         desktop.browse(location);

src/java/davmail/ui/browser/DesktopBrowser.java

@@ -16,9 +16,10 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  */
-package davmail.ui;
+package davmail.ui.browser;
 
 import davmail.ui.tray.DavGatewayTray;
+import davmail.ui.AboutFrame;
 import davmail.BundleMessage;
 
 import java.net.URI;
@@ -31,6 +32,12 @@ public final class DesktopBrowser {
     private DesktopBrowser() {
     }
 
+    /**
+     * Open default browser at location URI.
+     * User Java 6 Desktop class, OSX open command or SWT program launch
+     *
+     * @param location location URI
+     */
     public static void browse(URI location) {
         try {
             // trigger ClassNotFoundException
@@ -66,6 +73,12 @@ public final class DesktopBrowser {
         }
     }
 
+    /**
+     * Open default browser at location.
+     * User Java 6 Desktop class, OSX open command or SWT program launch
+     *
+     * @param location target location
+     */
     public static void browse(String location) {
         try {
             DesktopBrowser.browse(new URI(location));

src/java/davmail/ui/browser/OSXDesktopBrowser.java

@@ -16,7 +16,7 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  */
-package davmail.ui;
+package davmail.ui.browser;
 
 import java.io.IOException;
 import java.net.URI;
@@ -28,6 +28,13 @@ public class OSXDesktopBrowser {
     private OSXDesktopBrowser() {
     }
 
+    /**
+     * Open default browser at location URI.
+     * User OSX open command
+     *
+     * @param location location URI
+     * @throws IOException on error
+     */
     public static void browse(URI location) throws IOException {
        Runtime.getRuntime().exec("open "+location.toString());
     }

src/java/davmail/ui/browser/SwtDesktopBrowser.java

@@ -16,7 +16,7 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  */
-package davmail.ui;
+package davmail.ui.browser;
 
 import org.eclipse.swt.program.Program;
 
@@ -29,6 +29,12 @@ public final class SwtDesktopBrowser {
     private SwtDesktopBrowser() {
     }
 
+    /**
+     * Open default browser at location URI.
+     * User SWT program launch
+     *
+     * @param location location URI
+     */
     public static void browse(URI location) {
         Program.launch(location.toString());
     }