Release v2.0.0

Author: ecovaci

README.md

@@ -1,45 +1,78 @@
 # winfoom
-### Basic Proxy Facade for NTLM, Kerberos and SOCKS 5 proxies
+### Basic Proxy Facade for NTLM, Kerberos, SOCKS and Proxy Auto Config file proxies
 
 [![Build Status](https://travis-ci.com/ecovaci/winfoom.svg?branch=master)](https://travis-ci.com/github/ecovaci/winfoom)
 
-Winfoom is an HTTP(s) proxy server facade that allows applications to authenticate through a NTML/Kerberos HTTP authenticated proxy server or SOCKS 5 proxy server, typically used in corporate environments, 
-without having to deal with the actual handshake.
+# Overview
+Winfoom is an HTTP(s) proxy server facade that allows applications to authenticate through the following proxies: 
 
-A lot of software applications have problems when dealing with an authenticated proxy server's protocol. Winfoom sits between the corporate proxy and applications and offloads the authentication and the proxy's protocol, acting as a facade. This way, the software application will only have to deal with a basic proxy with no authentication.
+* NTML or Kerberos HTTP authenticated proxy
+* SOCKS version 4 or 5, with or without authentication
+* Proxy Auto Config files
+
+typically used in corporate environments, without having to deal with the actual handshake.
+
+A lot of software applications have problems when dealing with an authenticated proxy server's protocol. 
+Winfoom sits between the corporate proxy and applications and offloads the authentication and the proxy's protocol, acting as a facade. 
+This way, the software application will only have to deal with a basic proxy with no authentication.
 
 An example of such a facade for NTLM proxies is [CNTLM](http://cntlm.sourceforge.net/)
 
-### Instalation
+# Getting Started
+## Download Winfoom
+### Download prepackaged
+To try out Winfoom without needing to download the source and package it, check out the [releases](https://github.com/ecovaci/winfoom/releases) for a prepackaged `winfoom.zip`.
+Winfoom is a Java application and comes with a release that includes a Java environment [AdoptOpenJDK](https://github.com/AdoptOpenJDK/openjdk11-binaries/releases/download/jdk-11.0.5%2B10/OpenJDK11U-jdk_x64_windows_hotspot_11.0.5_10.msi),
+so you don't have to install anything.
+
+### Build from source code
+If you decide to build the executable *jar* file from the source code, you would need these prerequisites:
+* Java JDK 11(+)
+* Maven 3.x version
+
+First download  the source code from [releases](https://github.com/ecovaci/winfoom/releases) and unzip it.
+
+Then open a terminal and execute this command inside the `winfoom-x.x.x` directory:
 
+```
+ mvn clean package
+```
+
+Now you should have the generated executable *jar* file under the *target* directory.
+
+## Run Winfoom
 > 👉 Note: Winfoom only works on Windows OS!
 
-Winfoom is a Java application and comes with a release that includes a Java environment [AdoptOpenJDK](https://github.com/AdoptOpenJDK/openjdk11-binaries/releases/download/jdk-11.0.5%2B10/OpenJDK11U-jdk_x64_windows_hotspot_11.0.5_10.msi),
-so you don't have to install anything. 
+The prepackaged `winfoom.zip` contains a single executable file: `launch.bat`. 
 
-Starting with v1.5.1, the release contains a single executable file: `launch.bat`. 
 Available commands:
- 
 * `launch.bat` launches the application using the bundled JRE.
 * `launch.bat --debug` launches the application using the bundled JRE in debug mode.
 * `launch.bat --systemjre` launches the application using your system JRE - you'll need a JRE v.11 (at least).
 * `launch.bat --debug --systemjre`  launches the application using your system JRE in debug mode.
 
-The installation is pretty basic, just unzip the content of the released archive then double-click on `launch.bat` file.
+The fastest way to run Winfoom is by double-click on `launch.bat` file.
 
-The application log file is placed under `logs` directory.
+## Winfoom's logs
+The application log file is placed under `<user.home.dir>/.winfoom/logs` directory.
 
-### Configuration
-
-Winfoom has a graphical user interface that allows the user to configure the proxy type (HTTP or SOCKS5), the proxy host, port and the URL for testing the settings.
-These fields are pre-filled with the values gathered from your system.
-
-![winfoom_gui](https://github.com/ecovaci/winfoom/blob/master/assets/img/winfoom_gui.png)
+## Configuration
+Winfoom has a graphical user interface that allows configuration.
+ 
+The first thing to select is the proxy type:
+1) `HTTP` - if the remote proxy is NTLM, KERBEROS or any other HTTP proxy
+2) `SOCKS4` - if the remote proxy is SOCKS version 4
+3) `SOCKS5` - if the remote proxy is SOCKS version 5
+4) `PAC` - if the proxy is using a Proxy Auto Config file
+5) `DIRECT` - no proxy, used for various testing environments
 
-For SOCKS proxy type, if authentication is required use the `Config` button to provide user/password. 
+Then fill in the required fields. You can use the field's tooltip to get more information.
 
-> 👉 Note: For HTTP proxy type, Winfoom uses the current user credentials to authenticate to the remote proxy, there is no need to provide them!
+### Authentication
+* For HTTP proxy type, Winfoom uses the current Windows user credentials to authenticate to the remote proxy.
+* For SOCKS5 proxy type, the user/password need the be provided when required.
 
+### Test
 To test it, open a browser, let's say Firefox and configure proxy like this:
 
 ![firefox](https://github.com/ecovaci/winfoom/blob/master/assets/img/firefox.png)
@@ -49,34 +82,18 @@ Now you should be able to access any URL without Firefox asking for credentials.
 _If you don't have an available proxy, you still can test WinFoom by installing [WinGate](https://www.wingate.com/) and configure it to act 
 as a NTML proxy._
 
-### Build from source code
-
-If you decide to build the executable *jar* file from source code, you would need these prerequisites:
-
-* Java JDK 11(+)
-* Maven 3.x version
-* Git for Windows
-
-Then open a terminal and execute the commands:
-
-1) `git clone https://github.com/ecovaci/winfoom.git`
-2) `cd winfoom`
-3) `mvn clean package`
-
-Now you should have the generated executable *jar* file under the *target* directory.
-
-### Todo
 
-   - Performance tests.
+# Todo
+   - Linux/MacOS porting.
 
-### Coding Guidance
+# Coding Guidance
 
 Please review these docs below about coding practices.
 
 * [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)
 * [Java Code Conventions](https://www.oracle.com/technetwork/java/codeconventions-150003.pdf)   
 
-### Feedback
+# Feedback
 
 Any feedback or suggestions are welcome. 
 It is hosted with an Apache 2.0 license so issues, forks and PRs are most appreciated.

pom.xml

@@ -23,7 +23,7 @@
     </parent>
     <groupId>org.kpax</groupId>
     <artifactId>winfoom</artifactId>
-    <version>2.0.0-SNAPSHOT</version>
+    <version>2.0.0-RELEASE</version>
 
     <name>winfoom</name>
     <url>https://github.com/ecovaci/winfoom</url>

src/main/java/org/kpax/winfoom/FoomApplication.java

@@ -12,10 +12,8 @@
 
 package org.kpax.winfoom;
 
-import org.apache.commons.io.IOUtils;
 import org.kpax.winfoom.config.ProxyConfig;
 import org.kpax.winfoom.config.SystemConfig;
-import org.kpax.winfoom.util.InputOutputs;
 import org.kpax.winfoom.util.JarUtils;
 import org.kpax.winfoom.util.SwingUtils;
 import org.kpax.winfoom.view.AppFrame;
@@ -98,12 +96,12 @@ private static void checkAppVersion() throws IOException {
         if (Files.exists(systemPropertiesPath)) {
             Properties systemProperties = PropertiesLoaderUtils.loadProperties(
                     new FileSystemResource(systemPropertiesPath.toFile()));
-            String existingVersion = systemProperties.getProperty("releaseVersion");
-            logger.debug("existingVersion [{}]", existingVersion);
-            String actualVersion = JarUtils.getVersion(FoomApplication.class);
-            logger.debug("actualVersion [{}]", actualVersion);
+            String existingVersion = systemProperties.getProperty("app.version");
+            logger.info("existingVersion [{}]", existingVersion);
+            String actualVersion = FoomApplication.class.getPackage().getImplementationVersion();
+            logger.info("actualVersion [{}]", actualVersion);
 
-            if (!actualVersion.equals(existingVersion)) {
+            if (actualVersion != null && !actualVersion.equals(existingVersion)) {
                 logger.info("Different versions found: existent = {} , actual = {}", existingVersion, actualVersion);
 
                 Path backupDirPath = appHomePath.resolve(existingVersion);

src/main/java/org/kpax/winfoom/config/ProxyConfig.java

@@ -257,7 +257,7 @@ public void save() throws IOException, ConfigurationException {
         config.setProperty("local.port", this.localPort);
         config.setProperty("proxy.test.url", this.proxyTestUrl);
         config.setProperty("proxy.username", proxyType.isSocks5() ? this.proxyUsername : null);
-        config.setProperty("proxy.storePassword", proxyType.isSocks5() ? this.proxyStorePassword : null);
+        config.setProperty("proxy.storePassword", proxyType.isSocks5() ? this.proxyStorePassword : false);
         config.setProperty("proxy.pac.fileLocation", proxyType.isPac() ? this.proxyPacFileLocation : null);
 
         if (proxyType.isPac()) {
@@ -276,6 +276,16 @@ public void save() throws IOException, ConfigurationException {
         }
 
         propertiesBuilder.save();
+
+        //
+        // Refresh config values
+        //
+        setProxyHost(config.getString("proxy.host"));
+        setProxyPort(config.getInt("proxy.port"));
+        setProxyUsername(config.getString("proxy.username"));
+        setProxyStorePassword(config.getBoolean("proxy.storePassword"));
+        setProxyPacFileLocation(config.getString("proxy.pac.fileLocation"));
+        this.proxyPassword = config.getString("proxy.password");
     }
 
     @Override

src/main/java/org/kpax/winfoom/config/SystemConfig.java

@@ -18,7 +18,6 @@
 import org.apache.commons.configuration2.builder.fluent.Configurations;
 import org.apache.commons.configuration2.ex.ConfigurationException;
 import org.apache.http.client.config.RequestConfig;
-import org.kpax.winfoom.util.JarUtils;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -111,18 +110,8 @@ public class SystemConfig {
     @Value("${useSystemProperties:false}")
     private boolean useSystemProperties;
 
-    @Value("${releaseVersion:Unknown}")
-    private String releaseVersion;
-
-    @PostConstruct
-    public void init() {
-        try {
-            logger.info("Get application version from manifest file");
-            releaseVersion = JarUtils.getVersion(getClass());
-        } catch (Exception e) {
-            logger.warn("Error on getting application version from MANIFEST file, using Unknown");
-        }
-    }
+    @Value("${app.version}")
+    private String appVersion;
 
     public Integer getMaxConnectionsPerRoute() {
         return maxConnectionsPerRoute;
@@ -132,8 +121,8 @@ public Integer getMaxConnections() {
         return maxConnections;
     }
 
-    public String getReleaseVersion() {
-        return releaseVersion;
+    public String getAppVersion() {
+        return appVersion;
     }
 
     public boolean isUseSystemProperties() {
@@ -193,8 +182,7 @@ public void save() throws ConfigurationException, IOException, IllegalAccessExce
             for (Field field : this.getClass().getDeclaredFields()) {
                 Value valueAnnotation = field.getAnnotation(Value.class);
                 if (valueAnnotation != null) {
-                    String value = valueAnnotation.value();
-                    String propName = value.replaceAll("[${}]", "").split(":")[0];
+                    String propName = valueAnnotation.value().replaceAll("[${}]", "").split(":")[0];
                     config.setProperty(propName, field.get(this));
                 }
             }

src/main/java/org/kpax/winfoom/proxy/ProxyBlacklist.java

@@ -47,7 +47,7 @@ public class ProxyBlacklist {
     private ProxyConfig proxyConfig;
 
     /**
-     * Attempts to blacklist proxy. Does nothing if the blacklisting is disabled.<br>
+     * Attempts to blacklist a proxy. Does nothing if the blacklisting is disabled.<br>
      * If the proxy is already blacklisted, it keeps the existent timeout.
      *
      * @param proxyInfo the proxy to be blacklisted.

src/main/java/org/kpax/winfoom/util/JarUtils.java

@@ -23,13 +23,14 @@ private JarUtils() {
 
     /**
      * Gets the {@code Implementation-Version}  attribute from jar's MANIFEST.MF file.
+     * Only accurate when the application is packaged as JAR file.
      *
-     * @param cls the class
      * @return the application's version as it appears in the pom.xml file.
      * @throws IOException
      */
-    public static String getVersion(Class<?> cls) throws IOException {
-        Object version = new Manifest(cls.getResourceAsStream("/META-INF/MANIFEST.MF"))
+    @Deprecated
+    public static String getAppVersion() throws IOException {
+        Object version = new Manifest(JarUtils.class.getResourceAsStream("/META-INF/MANIFEST.MF"))
                 .getMainAttributes()
                 .get(Attributes.Name.IMPLEMENTATION_VERSION);
         if (version != null) {

src/main/java/org/kpax/winfoom/util/Message.java

@@ -13,13 +13,21 @@
 package org.kpax.winfoom.util;
 
 /**
+ * It encapsulates a GUI message.
+ *
  * @author Eugen Covaci {@literal [email protected]}
  * Created on 2/28/2020
  */
 public final class Message {
 
+    /**
+     * The message type.
+     */
     private final MessageType type;
 
+    /**
+     * The message text.
+     */
     private final String text;
 
     private Message(MessageType type, String text) {

src/main/java/org/kpax/winfoom/util/SwingUtils.java

@@ -37,20 +37,12 @@ public class SwingUtils {
 
     private static final String DLG_WARN_TITLE = "Warning";
 
-    public static void setFont(final Component component, final Font font) {
-        component.setFont(font);
-        if (component instanceof JMenu) {
-            JMenu menu = (JMenu) component;
-            for (int i = 0; i < menu.getItemCount(); i++) {
-                setFont(menu.getItem(i), font);
-            }
-        } else if (component instanceof Container) {
-            for (Component child : ((Container) component).getComponents()) {
-                setFont(child, font);
-            }
-        }
-    }
-
+    /**
+     * Enable/disable a component and all it's sub-components.
+     *
+     * @param component the {@link Component} to be enabled/disabled.
+     * @param enabled   {@code true} or {@code false}.
+     */
     public static void setEnabled(final Component component, final boolean enabled) {
         component.setEnabled(enabled);
         if (component instanceof Container) {
@@ -60,6 +52,11 @@ public static void setEnabled(final Component component, final boolean enabled)
         }
     }
 
+    /**
+     * Accepts an input value only if it is valid.
+     *
+     * @param spinner the {@link JSpinner} instance.
+     */
     public static void commitsOnValidEdit(final JSpinner spinner) {
         JComponent comp = spinner.getEditor();
         JFormattedTextField field = (JFormattedTextField) comp.getComponent(0);
@@ -94,6 +91,12 @@ public static void showWarningMessage(Component parentComponent, String title, S
         showMessage(parentComponent, title, message, JOptionPane.WARNING_MESSAGE);
     }
 
+    /**
+     * It executes a {@link Runnable}, showing a waiting cursor until the execution ends.
+     *
+     * @param runnable the {@link Runnable} instance (not null)
+     * @param frame    the current {@link JFrame}
+     */
     public static void executeRunnable(final Runnable runnable, final JFrame frame) {
         Validate.notNull(runnable, "runnable cannot be null");
         Validate.notNull(frame, "frame cannot be null");
@@ -110,6 +113,13 @@ public static void executeRunnable(final Runnable runnable, final JFrame frame)
         thread.start();
     }
 
+    /**
+     * It loads an image from a specified classpath location.
+     *
+     * @param cls used to localize the image URL.
+     * @param filename the image's filename.
+     * @return the loaded {@link Image}.
+     */
     public static Image loadImage(Class<?> cls, String filename) {
         try {
             URL resource = cls.getResource("/img/" + filename);

src/main/java/org/kpax/winfoom/view/AppFrame.java

@@ -573,7 +573,7 @@ private JMenuItem getMntmAbout() {
             mntmAbout = new JMenuItem("About");
             mntmAbout.setIcon(new TunedImageIcon("dialog-information.png"));
             mntmAbout.addActionListener(e -> SwingUtils.showInfoMessage(this, "About", "Winfoom - Basic Proxy Facade" +
-                    "\nVersion: " + systemConfig.getReleaseVersion()
+                    "\nVersion: " + systemConfig.getAppVersion()
                     + "\nProject home page: https://github.com/ecovaci/winfoom"
                     + "\nLicense: Apache 2.0"));
         }
@@ -583,10 +583,9 @@ private JMenuItem getMntmAbout() {
     // ------- End Menu
 
     private JTextField createTextField(String text) {
-        JTextField textField = new JTextField();
+        JTextField textField = new JTextField(text);
         textField.setPreferredSize(new Dimension(220, 25));
         textField.setMinimumSize(new Dimension(6, 25));
-        textField.setText(text);
         return textField;
     }
 
@@ -599,6 +598,7 @@ private JSpinner createJSpinner(Integer value) {
         return jSpinner;
     }
 
+
     private void disableAll() {
         SwingUtils.setEnabled(getContentPane(), false);
     }