bump javadoc plugin

Reviewed-on: #1

.github/workflows/maven.yml

@@ -0,0 +1,24 @@
+# This workflow will build a Java project with Maven
+# For more information see: https://help.github.com/actions/language-and-framework-guides/building-and-testing-java-with-maven
+
+name: Java CI with Maven
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up JDK 1.8
+      uses: actions/setup-java@v1
+      with:
+        java-version: 1.8
+    - name: Build with Maven
+      run: mvn -B package --file pom.xml

.gitignore

@@ -1,23 +1,4 @@
 
-# Java
-*.class
-*.jar
-*.war
-*.ear
-
-# Scala
-*.class
-*.log
-# sbt specific
-dist/*
-target/
-lib_managed/
-src_managed/
-project/boot/
-project/plugins/project/
-# Scala-IDE specific
-.scala_dependencies
-
 # Maven 
 target/
 
@@ -25,15 +6,22 @@ target/
 build/
 dist/
 #nbproject/
+nb-configuration.xml
+nbactions.xml
 
 # IntelliJ
 .idea/
+*.iml
 
 # Eclipse
 .settings/
 
-# Project 
-Mtik.java
+.classpath
 
-# Jekyll 
-_site/
+.project
+
+# Maven 
+pom.xml.versionsBackup
+
+# MacOS
+.DS_Store

.travis.yml

@@ -0,0 +1 @@
+language: java

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+Thank you for considering contributing to this project. This library is one tiny way I am giving back to the open source community, and I am
+always amazed and humbled when users contribute back. 
+
+There are several ways of contributing to this small open source library:
+
+* You can ask for help
+* You can log a bug
+* You can contribute code
+
+# Ask for help
+If you experience a problem using the mikrotik-java library, the best way to get in touch with me is to either send me an
+email or open an issue on GitHub. While you can seek help on StackOverflow or the Mikrotik Forums (both of which I've seen 
+people do), I do not read those sites often. If you wish to log your question there (it makes sense for it to be searchable or 
+in a place where other interested people can find it) and want me to take a look at it, please send me an email pointing to 
+the question. 
+
+I find that it is very easy to help users of this library if they include the following things which are usually quite relevant:
+
+* A snipped of sample code showing what they're doing 
+* The stack trace (if there is one) when it goes wrong
+* Version of the library they're using
+
+# Log a bug 
+If you are pretty sure you have found a bug in the library, please log a bug by opening an issue on GithHub. When things get buggy, 
+the following information (mostly the same as for asking help) becomes important:
+
+* A snipped of sample code showing what they're doing 
+* The stack trace (if there is one) when it goes wrong
+* Version of the library they're using
+* The version of RouterOS they're connecting to
+
+I take bug reports very seriously, and will usually bring out immediate minor versions to fix show stoppers. 
+
+# Contribute code 
+If you want to contribute code to this library, you're welcome. Please read this section before submitting pull requests.
+
+## If you're fixing a bug
+If you've fixed a bug, please submit the pull request on GitHub. If there is an already existing issue being fixed, please 
+reference that issue so I can look at what you're fixing, and if not, please explain the issue you're fixing in the pull request. 
+
+## If you want new functionality or API changes
+Please contact me via email before you create a pull request for feature additions or API changes. The mikrotik-java library is stable and,
+for it's current purpose, feature complete. The situations in which I will add features to the library or change it's interface are:
+* If Mikrotik adds new RouterOS functionality that requires an API change to remain feature complete
+* If some very bad design flaw in the interface is discovered
+* If somebody has a truly compelling reason for adding to the library. To be compelling means the added functionality must be useful 
+for more users than just the submitter
+* If some new pattern or convention arises in the Java standard libraries that is useful 
+
+I *really* hate declining people's PRs, but I will do so if I don't think they add value as explained above, or if I can't figure out why
+they want the change. For this reason, if you are at all unsure if your PR will be accepted, please contact me and discuss what you want 
+before submitting a PR. 
+
+Gideon 

README.md

@@ -1,26 +1,119 @@
-mikrotik-java
-=============
+# mikrotik-java 
 
-A Java client implementation for the Mikrotik RouterOS API. 
+A Java client library implementation for the Mikrotik RouterOS API. 
 
 This project provides a Java client to manipulate Mikrotik routers using the remote API. Simple things must be easy to do, and complex things must be possible.
 
-*This code is currently pre-release, so in order to use it you will have to clone it locally and compile it yourself. Any part,
-including public interfaces, can change at any time, until I release version 1.0.*
+## Versions
 
-Examples
-========
+![Java CI with Maven](https://github.com/GideonLeGrange/mikrotik-java/workflows/Java%20CI%20with%20Maven/badge.svg)
 
+**The current stable version is 3.0.8**
+
+Version 3.0.8 fixes a null pointer error 
+
+### Changes in version 3.0:
+
+Version 3.0 addresses the problems the API had around TLS encryption. The way secure connections are implemented is changed so that the user has complete control over the creation of TLS sockets. To this end:
+* A new method, `connect(SocketFactory fact, String host, int port, int timeout)`, was added to allow for better user control over sockets and especially encryption.
+* The `connectTLS()` API methods were removed. 
+* Most of the overloaded `connect()` methods were removed. 
+* Added a pre-built `jar` file to the downloads.
+
+Further changes include:
+* The previously deprecated `disconnect()` method is removed. 
+
+#### Versions 1.x and 2.x
+
+Versions 1 and 2 are considered *obsolete* and will no longer be supported or patched. 
+
+## Getting the API
+
+Maven users can use the artifact from Maven Central with this dependency:
+
+```xml
+<dependency>
+  <groupId>me.legrange</groupId>
+  <artifactId>mikrotik</artifactId>
+  <version>3.0.8</version>
+</dependency>
+```
+
+You can also download the pre-built jar file, or a zip or tar.gz file with the source for the latest release [here](https://github.com/GideonLeGrange/mikrotik-java/releases/latest)
+
+## Asking for help or contributing
+
+I welcome contributions, be it bug fixes or other improvements. 
+
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for information on how to contribute to this project.
+
+# Using the API
+
+How to use the API is best illustrated by examples. 
+
+These examples should illustrate how to use this library. Please note that I assume that the user is proficient in Java and understands the Mikrotik command line syntax. The command line syntax gives you an indication of what commands you can pass, but the RouterOS API used by this library does not support everyting. 
+
+Some things to consider when debugging your API calls are:
+* The RouterOS API does not support auto-completion. You need to write out command and parameter names. For example, you can't say `/ip/hotspot/user/add name=john add=10.0.0.1`, you need to write out `address`.
+* You need to quote values with spaces in. You can't say `name=Joe Blogs`, you need to use `name="Joe Blogs"`
+* Exceptions with a root cause of `ApiCommandException` are errors received from the remote RouterOS device and contain the error message received. 
+
+## Opening a connection
 Here is a simple example: Connect to a router and reboot it. 
 
 ```java
 ApiConnection con = ApiConnection.connect("10.0.1.1"); // connect to router
 con.login("admin","password"); // log in to router
 con.execute("/system/reboot"); // execute a command
-con.disconnect(); // disconnect from router
+con.close(); // disconnect from router
+```
+The above example shows a easy way of creating an unencrypted connection using the default API port and timeout, which is useful for development and testing.
+
+### TLS encryption
+
+For production environments, encrypting API traffic is recommended. To do this you need to open a TLS connection to the router by passing an instance of the `SocketFactory` you wish to use to construct the TLS socket to the API:
+
+```java
+ApiConnection con = ApiConnection.connect(SSLSocketFactory.getDefault(), "10.0.1.1", ApiConnection.DEFAULT_TLS_PORT, ApiConnection.DEFAULT_CONNECTION_TIMEOUT);
 ```
 
-A simple example that returns a result: Print all interfaces.
+Above an instance of the default SSL socket factory is passed to the API. This will work as long as the router's certificate has been added to the local key store.  Besides allowing the user to specify the socket factory, the above method also gives full control over the TCP Port and connection timeout. 
+
+RouterOS also supports anonymous TLS. An example showing how to create a socket factory for anonymous TLS is `AnonymousSocketFactory` in the examples directory.
+
+### Connection timeouts
+
+By default, the API will generate an exception if it cannot connect to the specified router. This can take place immediately (typically if the OS returns a 'Connection refused' error), but can also take up to 60 seconds if the router host is firewalled or if there are other network problems. This 60 seconds is the 'default connection timeout' an can be overridded by passing the preferred timeout to the APi as last parameter in a ```connect()``` call. For example:
+
+```java
+   ApiConnection con = ApiConnection.connect(SSLSocketFactory.getDefault(), "10.0.1.1", ApiConnection.DEFAULT_TLS_PORT, 2000); // connect to router on the default API port and fail in 2 seconds
+```	
+
+### Constants
+Some constants are provided in `ApiConnection` to make it easier for users to construct connections with default ports and timeouts:
+
+Constant | Use for | Value 
+---------|---------|------
+DEFAULT_PORT | Default TCP `port` value for unencrypyted connections | 8728
+DEFAULT_TLS_PORT | Default TCP `port` value for encrypyted connections | 8729
+DEFAULT_CONNECTION_TIMEOUT | Default connection `timeout` value (ms) | 60000
+
+### Try with resources 
+
+The API can also be used in a "try with resources" statement which will ensure that the connection is closed:
+
+```java
+        try (ApiConnection con = ApiConnection.connect(SocketFactory.getDefault(), Config.HOST, ApiConnection.DEFAULT_PORT, 2000)) {
+            con.login(Config.USERNAME, Config.PASSWORD);
+            con.execute("/user/add name=eric");
+        }
+```
+
+In following examples the connection, login and disconnection code will not be repeated. In all cases it is assumed that an `ApiConnection` has been established, `login()` has been called, and that the connection is called `con`.
+
+## Reading data 
+
+A simple example that returns a result - Print all interfaces:
 
 
 ```java
@@ -30,21 +123,76 @@ for (Map<String,String> r : rs) {
 }
 ```
 
+Results are returned as a list of maps of String key/value pairs. The reason for this is that a command can return multiple results, which have multpile variables. For example, to print the names of all the interfaces returned in the command above, do:
+
+```java
+for (Map<String, String> map : rs) { 
+  System.out.println(map.get("name"));
+}
+```
+
+### Filtering results
+
 The same query, but with the results filtered: Print all interfaces of type 'vlan'.
 
 ```java
 List<Map<String, String>> rs = con.execute("/interface/print where type=vlan");
 ```
 
-The same query, but we only want certain result fields names Print all interfaces of type 'vlan' and return their name.
+### Selecting returned fields
+
+The same query, but we only want certain result fields names: Print all interfaces of type 'vlan' and return just their name:
 
 ```java
 List<Map<String, String>> rs = con.execute("/interface/print where type=vlan return name");
 ```
 
-We can run asynchrynous commands:
+## Writing data 
 
-This example shows how to run '/interface wireless monitor' and have the result sent to a listener object, which prints it
+Creating, modifying and deleting configuration objects is of course possible.
+
+### Creating an object 
+
+This example shows how to create a new GRE interface: 
+
+```java
+con.execute("/interface/gre/add remote-address=192.168.1.1 name=gre1 keepalive=10");
+```
+
+### Modify an existing object
+
+Change the IP address in the object created by the above example:
+
+```java
+con.execute("/interface/gre/set .id=gre1 remote-address=10.0.1.1"); 
+```
+
+### Remove an existing object
+
+And now remove the object:
+
+```java
+con.execute("/interface/gre/remove .id=gre1"); 
+```
+
+### Un-setting a variable on an object 
+
+Un-setting a variable is a bit different, and you need to use a parameter called `value-name`. This isn't well documented. Let's say you have a firewall rule that was set up like this:
+
+```java
+con.execute("/ip/firewall/filter/add action=accept chain=forward time=00:00:01-01,mon")
+```
+Assuming the rule can be accessed as `.id=*1`, you un-set it by using `value-name` as seen below:
+
+```java 
+con.execute("/ip/firewall/filter/unset .id=*1 value-name=time");
+```
+
+## Asynchronous commands
+
+We can run some commands asynchronously in order to continue receiving updates:
+
+This example shows how to run '/interface wireless monitor' and have the result sent to a listener object, which prints it:
 
 ```java
 String tag = con.execute("/interface/wireless/monitor .id=wlan1 return signal-to-noise", 
@@ -53,37 +201,50 @@ String tag = con.execute("/interface/wireless/monitor .id=wlan1 return signal-to
             public void receive(Map<String, String> result) {
                 System.out.println(result);
             }
+
+           public void error(MikrotikApiException e) {
+               System.out.println("An error occurred: " + e.getMessage());
+           }
+
+           public void completed() {
+                System.out.println("Asynchronous command has finished"); 
+           }
             
         }
   );
 ```
 
-The above command will run and send results asynchrynously as they become available, until it is canceled. The command (identified by the unique String retruned) 
- is cancelled like this:
+The `ResultListener` interface has three methods the user needs to implement:
+* `receive()` is called to receive results produced by the router from the API. 
+* `error()` is called when an exception is raised based on a 'trap' received from the router or another (typically connection) problem.
+* `completed()` is called when the router has indicated that the command has completed or has been cancelled. 
+
+The above command will run and send results asynchronously as they become available, until it is canceled. The command (identified by the unique String returned) is canceled like this:
 
 ```java
 con.cancel(tag);
 ```
 
-More examples will be added shortly. 
+## Command timeouts
 
-TODO
-====
-For 1.0: 
-- More examples
-- More formal documentation
-- Push Javadoc to GitHub
-- Get into Maven Central
+Command timeouts can be used to make sure that synchronous commands either return or fail within a specific time. Command timeouts are separate from the connection timeout used in ```connect()```, and can be set using ```setTimeout()```. Here is an example:
 
-Later:
-- SSL support.
+```java
+ApiConnection con = ApiConnection.connect("10.0.1.1"); // connect to router
+con.setTimeout(5000); // set command timeout to 5 seconds
+con.login("admin","password"); // log in to router
+con.execute("/system/reboot"); // execute a command
+``` 
+ 	
+It is important to note that command timeouts can be set before ```login()``` is called, and can therefore influence the behaviour of login. 
 
-References
-==========
+The default command timeout, if none is set by the user, is 60 seconds. 
+
+# References
 
 The RouterOS API is documented here: http://wiki.mikrotik.com/wiki/Manual:API
 
-Licence
-=======
+# Licence
+
+This library is released under the Apache 2.0 licence. See the [LICENCE.md](LICENCE.md) file
 
-This library is released under the Apache 2.0 licence. See the Licence.md file

pom.xml

@@ -1,84 +1,168 @@
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-    <parent>
-        <groupId>org.sonatype.oss</groupId>
-        <artifactId>oss-parent</artifactId>
-        <version>7</version>
-    </parent>
+<?xml version="1.0" encoding="UTF-8"?>
 
-    <modelVersion>4.0.0</modelVersion>
-
-    <groupId>me.legrange</groupId>
-    <artifactId>mikrotik</artifactId>
-    <version>1.0</version>
-    <packaging>jar</packaging>
-
-    <name>Mikrotik API Java Client Library</name>
-    <url>https://github.com/GideonLeGrange/mikrotik-java</url>
-    <licenses>
-        <license>
-            <name>The Apache Software License, Version 2.0</name>
-            <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
-            <distribution>repo</distribution>
-        </license>
-    </licenses>
-    <scm>
-        <url>git@github.com:GideonLeGrange/mikrotik-java.git</url>
-        <connection>scm:git:git@github.com:GideonLeGrange/mikrotik-java.git</connection>
-        <developerConnection>scm:git:git@github.com:GideonLeGrange/mikrotik-java.git</developerConnection>
-    </scm>
-    <build>
-        <plugins>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-compiler-plugin</artifactId>
-                <version>2.3.2</version>
-                <configuration>
-                    <showDeprecation>true</showDeprecation>
-                </configuration>
-            </plugin>
-            
-            <plugin> 
-                <groupId>org.apache.maven.plugins</groupId> 
-                <artifactId>maven-jar-plugin</artifactId> 
-                <version>2.3.2</version>
-                <executions> 
-                    <execution> 
-                        <id>default-jar</id>
-                        <phase>package</phase> 
-                        <goals> 
-                            <goal>jar</goal> 
-                        </goals> 
-                        <configuration> 
-                            <excludes> 
-                                <exclude>**/examples</exclude> 
-                                <exclude>**/examples/*</exclude> 
-                            </excludes> 
-                        </configuration> 
-                    </execution> 
-                </executions> 
-            </plugin> 
-            
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-javadoc-plugin</artifactId>
-                <version>2.9.1</version>
-                <configuration>
-                    <excludePackageNames>example;*.impl</excludePackageNames>
-                </configuration>
-            </plugin>
-        </plugins>
-    </build>
-    <properties>
-        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    </properties>
-
-    <dependencies>
-        <dependency>
-            <groupId>junit</groupId>
-            <artifactId>junit</artifactId>
-            <version>3.8.1</version>
-            <scope>test</scope>
-        </dependency>
-    </dependencies>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">  
+  <parent> 
+    <groupId>org.sonatype.oss</groupId>  
+    <artifactId>oss-parent</artifactId>  
+    <version>9</version> 
+  </parent>  
+  <modelVersion>4.0.0</modelVersion>  
+  <groupId>me.legrange</groupId>  
+  <artifactId>mikrotik</artifactId>  
+  <version>3.0.8.1</version>  
+  <packaging>jar</packaging>  
+  <name>Mikrotik API Java Client Library</name>  
+  <url>https://github.com/GideonLeGrange/mikrotik-java</url>  
+  <licenses> 
+    <license> 
+      <name>The Apache Software License, Version 2.0</name>  
+      <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>  
+      <distribution>repo</distribution> 
+    </license> 
+  </licenses>  
+  <scm> 
+    <url>git@github.com:GideonLeGrange/mikrotik-java.git</url>  
+    <connection>scm:git:git@github.com:GideonLeGrange/mikrotik-java.git</connection>  
+    <developerConnection>scm:git:git@github.com:GideonLeGrange/mikrotik-java.git</developerConnection> 
+  </scm>  
+  <build> 
+    <plugins> 
+      <plugin> 
+        <groupId>org.apache.maven.plugins</groupId>  
+        <artifactId>maven-compiler-plugin</artifactId>  
+        <version>2.3.2</version>  
+        <configuration> 
+          <showDeprecation>true</showDeprecation>  
+          <source>8</source>  
+          <target>8</target> 
+        </configuration> 
+      </plugin>  
+      <plugin> 
+        <groupId>org.apache.maven.plugins</groupId>  
+        <artifactId>maven-jar-plugin</artifactId>  
+        <version>2.3.2</version>  
+        <executions> 
+          <execution> 
+            <id>default-jar</id>  
+            <phase>package</phase>  
+            <goals> 
+              <goal>jar</goal> 
+            </goals>  
+            <configuration> 
+              <excludes> 
+                <exclude>**/examples</exclude>  
+                <exclude>**/examples/*</exclude> 
+              </excludes> 
+            </configuration> 
+          </execution> 
+        </executions> 
+      </plugin>  
+      <plugin> 
+        <groupId>org.apache.maven.plugins</groupId>  
+        <artifactId>maven-source-plugin</artifactId>  
+        <version>2.2.1</version>  
+        <executions> 
+          <execution> 
+            <id>attach-sources</id>  
+            <goals> 
+              <goal>jar</goal> 
+            </goals> 
+          </execution> 
+        </executions> 
+      </plugin>  
+      <plugin> 
+        <groupId>org.apache.maven.plugins</groupId>  
+        <artifactId>maven-javadoc-plugin</artifactId>  
+        <version>3.7.0</version>  
+        <configuration> 
+          <excludePackageNames>example;*.impl</excludePackageNames> 
+        </configuration>  
+        <executions> 
+          <execution> 
+            <id>attach-javadocs</id>  
+            <goals> 
+              <goal>jar</goal> 
+            </goals> 
+          </execution> 
+        </executions> 
+      </plugin>  
+   </plugins> 
+  </build>  
+  <profiles> 
+    <profile> 
+      <id>release</id>  
+      <build> 
+        <plugins> 
+          <plugin> 
+            <groupId>org.apache.maven.plugins</groupId>  
+            <artifactId>maven-source-plugin</artifactId>  
+            <version>2.4</version>  
+            <executions> 
+              <execution> 
+                <id>attach-sources</id>  
+                <goals> 
+                  <goal>jar</goal> 
+                </goals> 
+              </execution> 
+            </executions> 
+          </plugin>  
+          <plugin> 
+            <groupId>org.apache.maven.plugins</groupId>  
+            <artifactId>maven-javadoc-plugin</artifactId>  
+            <version>2.10.1</version>  
+            <executions> 
+              <execution> 
+                <id>attach-javadocs</id>  
+                <goals> 
+                  <goal>jar</goal> 
+                </goals> 
+              </execution> 
+            </executions> 
+          </plugin>  
+          <plugin> 
+            <groupId>org.apache.maven.plugins</groupId>  
+            <artifactId>maven-gpg-plugin</artifactId>  
+            <version>1.6</version>  
+            <executions> 
+              <execution> 
+                <id>sign-artifacts</id>  
+                <phase>verify</phase>  
+                <goals> 
+                  <goal>sign</goal> 
+                </goals> 
+              </execution> 
+            </executions> 
+          </plugin>  
+          <plugin> 
+            <groupId>org.sonatype.plugins</groupId>  
+            <artifactId>nexus-staging-maven-plugin</artifactId>  
+            <version>1.6.5</version>  
+            <extensions>true</extensions>  
+            <configuration> 
+              <serverId>ossrh</serverId>  
+              <nexusUrl>https://oss.sonatype.org/</nexusUrl>  
+              <autoReleaseAfterClose>true</autoReleaseAfterClose> 
+            </configuration> 
+          </plugin> 
+        </plugins> 
+      </build>  
+      <distributionManagement> 
+        <snapshotRepository> 
+          <id>ossrh</id>  
+          <url>https://oss.sonatype.org/content/repositories/snapshots</url> 
+        </snapshotRepository> 
+      </distributionManagement> 
+    </profile> 
+  </profiles>  
+  <properties> 
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> 
+  </properties>  
+  <dependencies> 
+    <dependency> 
+      <groupId>junit</groupId>  
+      <artifactId>junit</artifactId>  
+      <version>4.13.1</version>  
+      <scope>test</scope> 
+    </dependency>  
+  </dependencies> 
 </project>
-

src/main/java/examples/AddAndModify.java

@@ -0,0 +1,30 @@
+package examples;
+
+import me.legrange.mikrotik.MikrotikApiException;
+
+/**
+ * Example 6: Create and modify object
+ *
+ * @author gideon
+ */
+public class AddAndModify extends Example {
+
+    public static void main(String... args) throws Exception {
+        AddAndModify ex = new AddAndModify();
+        ex.connect();
+        ex.test();
+        ex.disconnect();
+    }
+
+    private void test() throws MikrotikApiException, InterruptedException {
+        System.out.println("Creating interface gre1");
+        con.execute("/interface/gre/add remote-address=1.2.3.4 name=gre1 keepalive=10 comment='test comment'");
+        System.out.println("Adding firewall rule for interface gre1");
+        con.execute("/ip/firewall/filter/add action=drop chain=forward in-interface=gre1 protocol=udp dst-port=78,80");//,80,32");
+        System.out.println("Waiting 10 seconds");
+        Thread.sleep(10000); // 10 seconds for the user to look on the router to see the interface with /interface gre print
+        System.out.println("Changing IP for interface gre1");
+        con.execute("/interface/gre/set remote-address=172.16.1.1 .id=gre1");
+        // now look again and the IP has changed
+    }
+}

src/main/java/examples/AnonymousSocketFactory.java

@@ -0,0 +1,86 @@
+/*
+ * Copyright 2016 gideon.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package examples;
+
+import java.io.IOException;
+import java.net.InetAddress;
+import java.net.Socket;
+import java.net.UnknownHostException;
+import java.util.LinkedList;
+import java.util.List;
+import javax.net.SocketFactory;
+import javax.net.ssl.SSLSocket;
+import javax.net.ssl.SSLSocketFactory;
+
+/**
+ *
+ * @since 3.0
+ * @author Gideon le Grange https://github.com/GideonLeGrange
+ */
+public class AnonymousSocketFactory extends SocketFactory {
+
+    @Override
+    public Socket createSocket() throws IOException {
+        return fixSocket((SSLSocket) SSLSocketFactory.getDefault().createSocket());
+    }
+    
+    @Override
+    public Socket createSocket(String host, int port) throws IOException, UnknownHostException {
+        return fixSocket((SSLSocket) SSLSocketFactory.getDefault().createSocket(host, port));
+    }
+
+    @Override
+    public Socket createSocket(String host, int port, InetAddress localHost, int localPort) throws IOException, UnknownHostException {
+        return fixSocket((SSLSocket) SSLSocketFactory.getDefault().createSocket(host, port, localHost, localPort));
+    }
+
+    @Override
+    public Socket createSocket(InetAddress address, int port) throws IOException {
+        return fixSocket((SSLSocket) SSLSocketFactory.getDefault().createSocket(address, port));
+    }
+
+    @Override
+    public Socket createSocket(InetAddress address, int port, InetAddress localAddress, int localPort) throws IOException {
+        return fixSocket((SSLSocket) SSLSocketFactory.getDefault().createSocket(address, port, localAddress, localPort));
+    }
+    
+    private Socket fixSocket(SSLSocket ssl) {
+        List<String> cs = new LinkedList<>();
+        // not happy with this code. Without it, SSL throws a "Remote host closed connection during handshake" error
+        // caused by a "SSL peer shut down incorrectly" error
+        for (String s : ssl.getSupportedCipherSuites()) {
+            if (s.startsWith("TLS_DH_anon")) {
+                cs.add(s);
+            }
+        }
+        ssl.setEnabledCipherSuites(cs.toArray(new String[]{}));
+        return ssl; 
+    }
+
+    public static SocketFactory getDefault() {
+        if (fact == null) {
+            fact = new AnonymousSocketFactory();
+        }
+        return fact;
+    }
+
+    private AnonymousSocketFactory() {
+
+    }
+
+    private static AnonymousSocketFactory fact;
+
+}

src/main/java/examples/AsyncCommand.java

@@ -9,24 +9,34 @@ import me.legrange.mikrotik.ResultListener;
  *
  * @author gideon
  */
-public class Example4 extends Example {
+public class AsyncCommand extends Example {
 
     public static void main(String... args) throws Exception {
-        Example4 ex = new Example4();
+        AsyncCommand ex = new AsyncCommand();
         ex.connect();
         ex.test();
         ex.disconnect();
     }
 
     private void test() throws MikrotikApiException, InterruptedException {
-       String id = con.execute("/interface/wireless/monitor .id=wlan1", new ResultListener() {
+       String id = con.execute("/interface/wireless/monitor .id=wlan1 .proplist=signal-strength", new ResultListener() {
            private int prev = 0;
 
            public void receive(Map<String, String> result) {
-               int val = Integer.parseInt(result.get("signal-strength"));
+               System.out.println(result);
+/*               int val = Integer.parseInt(result.get("signal-strength"));
                String sym = (val == prev) ? " " : ((val < prev) ? "-" : "+");
                System.out.printf("%d %s\n", val, sym);
                prev = val;
+  */          }
+
+           @Override
+           public void error(MikrotikApiException ex) {
+               throw new RuntimeException(ex.getMessage(), ex);
+           }
+
+           @Override
+           public void completed() {
            }
 
 

src/main/java/examples/AsyncWithErrorHandling.java

@@ -2,17 +2,17 @@ package examples;
 
 import java.util.Map;
 import me.legrange.mikrotik.MikrotikApiException;
-import me.legrange.mikrotik.ResponseListener;
+import me.legrange.mikrotik.ResultListener;
 
 /**
  * Example 5: Asynchronous results, with error and completion. Run a command and receive results, errors and completion notification for it asynchronously with a ResponseListener
  *
  * @author gideon
  */
-public class Example5 extends Example {
+public class AsyncWithErrorHandling extends Example {
 
     public static void main(String... args) throws Exception {
-        Example5 ex = new Example5();
+        AsyncWithErrorHandling ex = new AsyncWithErrorHandling();
         ex.connect();
         ex.test();
         ex.disconnect();
@@ -20,9 +20,10 @@ public class Example5 extends Example {
 
     private void test() throws MikrotikApiException, InterruptedException {
         boolean completed = false;
-       String id = con.execute("/interface/wireless/monitor .id=wlan1", new ResponseListener() {
+       String id = con.execute("/interface/wireless/monitor .id=wlan1", new ResultListener() {
            private int prev = 0;
 
+           @Override
            public void receive(Map<String, String> result) {
                int val = Integer.parseInt(result.get("signal-strength"));
                String sym = (val == prev) ? " " : ((val < prev) ? "-" : "+");
@@ -30,11 +31,13 @@ public class Example5 extends Example {
                prev = val;
            }
 
+           @Override
            public void error(MikrotikApiException ex) {
                System.out.printf("An error ocurred: %s\n", ex.getMessage());
                ex.printStackTrace();
            }
 
+           @Override
            public void completed() {
                System.out.printf("The request has been completed\n");
            }

src/main/java/examples/CharacterSets.java

@@ -0,0 +1,34 @@
+package examples;
+
+import java.util.List;
+import java.util.Map;
+import me.legrange.mikrotik.MikrotikApiException;
+
+/**
+ * Example to show that different character sets may work some times. 
+ *
+ * @author gideon
+ */
+public class CharacterSets extends Example {
+    
+    private static final String JAPANESE = "事報ハヤ久送とゅ歳用ト候新放すルドう二5春園ユヲロ然納レ部悲と被状クヘ芸一ーあぽだ野健い産隊ず";
+    private static final String CRYLLIC = "Лорем ипсум долор сит амет, легере елояуентиам хис ид. Елигенди нолуиссе вих ут. Нихил";
+    private static final String ARABIC = "تجهيز والمانيا تم قام. وحتّى المتاخمة ما وقد. أسر أمدها تكبّد عل. فقد بسبب ترتيب استدعى أم, مما مع غرّة، لأداء. الشتاء، عسكرياً";
+
+    public static void main(String... args) throws Exception {
+        CharacterSets ex = new CharacterSets();
+        ex.connect();
+        ex.test();
+        ex.disconnect();
+    }
+
+    private void test() throws MikrotikApiException {
+        con.execute("/ip/hotspot/user/add name=userJ comment='" + JAPANESE + "'");
+        con.execute("/ip/hotspot/user/add name=userC comment='" + CRYLLIC + "'");
+        con.execute("/ip/hotspot/user/add name=userA comment='" + ARABIC + "'");
+
+        for (Map<String, String> res : con.execute("/ip/hotspot/user/print return name,comment")) {
+            System.out.printf("%s : %s\n", res.get("name"), res.get("comment"));
+        }
+    }
+}

src/main/java/examples/CommandWithWhere.java

@@ -9,10 +9,10 @@ import me.legrange.mikrotik.MikrotikApiException;
  *
  * @author gideon
  */
-public class Example3 extends Example {
+public class CommandWithWhere extends Example {
 
     public static void main(String... args) throws Exception {
-        Example3 ex = new Example3();
+        CommandWithWhere ex = new CommandWithWhere();
         ex.connect();
         ex.test();
         ex.disconnect();

src/main/java/examples/Config.java

@@ -2,14 +2,13 @@ package examples;
 
 /**
  * Config class for examples
+ *
  * @author gideon
  */
 public class Config {
-    
-    
-   public static final String HOST = "10.0.0.3";
-    public static final String USERNAME = "admin";
-    public static final String PASSWORD = "";
-    
- 
+
+    public static final String HOST = "ce2.ter.cpt.adept.za.net";
+    public static final String USERNAME = "adept";
+    public static final String PASSWORD = "34ffp9";
+
 }

src/main/java/examples/ConnectTLSAnonymous.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2015 gideon.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package examples;
+
+import java.util.List;
+import java.util.Map;
+import me.legrange.mikrotik.ApiConnection;
+import me.legrange.mikrotik.MikrotikApiException;
+
+/**
+ * Example: Open an Anonymous TLS connection
+ *
+ * @author gideon
+ */
+public class ConnectTLSAnonymous {
+
+    public static void main(String... args) throws Exception {
+        ConnectTLSAnonymous ex = new ConnectTLSAnonymous();
+        ex.connect();
+        ex.test();
+        ex.disconnect();
+    }
+
+    private void test() throws MikrotikApiException {
+        List<Map<String, String>> results = con.execute("/interface/print");
+        for (Map<String, String> result : results) {
+            System.out.println(result);
+        }
+    }
+
+    protected void connect() throws Exception {
+        con = ApiConnection.connect(AnonymousSocketFactory.getDefault(), Config.HOST, ApiConnection.DEFAULT_TLS_PORT, ApiConnection.DEFAULT_CONNECTION_TIMEOUT);
+        con.login(Config.USERNAME, Config.PASSWORD);
+    }
+
+    protected void disconnect() throws Exception {
+        con.close();
+    }
+
+    private ApiConnection con;
+}

src/main/java/examples/ConnectTLSCertificate.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2015 gideon.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package examples;
+
+import java.util.List;
+import java.util.Map;
+import javax.net.ssl.SSLSocketFactory;
+import me.legrange.mikrotik.ApiConnection;
+import me.legrange.mikrotik.MikrotikApiException;
+
+/**
+ * Example: Open a TLS connection
+ *
+ * @author gideon
+ */
+public class ConnectTLSCertificate {
+
+    public static void main(String... args) throws Exception {
+        ConnectTLSCertificate ex = new ConnectTLSCertificate();
+        ex.connect();
+        ex.test();
+        ex.disconnect();
+    }
+
+    private void test() throws MikrotikApiException {
+        List<Map<String, String>> results = con.execute("/interface/print");
+        for (Map<String, String> result : results) {
+            System.out.println(result);
+        }
+    }
+
+    protected void connect() throws Exception {
+        con = ApiConnection.connect(SSLSocketFactory.getDefault(), Config.HOST, ApiConnection.DEFAULT_TLS_PORT, ApiConnection.DEFAULT_CONNECTION_TIMEOUT);
+        con.login(Config.USERNAME, Config.PASSWORD);
+    }
+
+    protected void disconnect() throws Exception {
+        con.close();
+    }
+
+    private ApiConnection con;
+}

src/main/java/examples/DownloadConfig.java

@@ -0,0 +1,30 @@
+package examples;
+
+import java.util.List;
+import java.util.Map;
+import me.legrange.mikrotik.MikrotikApiException;
+
+/**
+ * Example 7: Dump your complete config
+ *
+ * @author gideon
+ */
+public class DownloadConfig extends Example {
+
+    public static void main(String... args) throws Exception {
+        DownloadConfig ex = new DownloadConfig();
+        ex.connect();
+        ex.test();
+        ex.disconnect();
+    }
+
+    private void test() throws MikrotikApiException, InterruptedException {
+        con.execute("/export file=conf");
+        List<Map<String, String>> res = con.execute("/file/print detail where name=conf.rsc");
+        con.execute("/file/remove .id=conf.rsc");   
+        String text = res.get(0).get("contents");
+            for (String line : text.split("\r")) {
+            System.out.println(line);
+        }
+    }
+}

src/main/java/examples/Example.java

@@ -1,5 +1,6 @@
 package examples;
 
+import javax.net.SocketFactory;
 import me.legrange.mikrotik.ApiConnection;
 
 /**
@@ -9,12 +10,12 @@ import me.legrange.mikrotik.ApiConnection;
  abstract class Example {
      
     protected void connect() throws Exception {
-        con = ApiConnection.connect(Config.HOST);
+        con = ApiConnection.connect(SocketFactory.getDefault(), Config.HOST, ApiConnection.DEFAULT_PORT, 2000);
         con.login(Config.USERNAME, Config.PASSWORD);
     }
 
     protected void disconnect() throws Exception {
-        con.disconnect();
+        con.close();
     }
     
     protected ApiConnection con;

src/main/java/examples/NestedExpressions.java

@@ -0,0 +1,33 @@
+package examples;
+
+import me.legrange.mikrotik.MikrotikApiException;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Example 2: A command that returns results. Print all interfaces
+ *
+ * @author gideon
+ */
+public class NestedExpressions extends Example {
+
+    public static void main(String... args) throws Exception {
+        NestedExpressions ex = new NestedExpressions();
+        ex.connect();
+        ex.test("/ip/firewall/nat/print where (src-address=\"192.168.15.52\" or src-address=\"192.168.15.53\")");
+        ex.test("/ip/firewall/nat/print where chain=api_test and (src-address=192.168.15.52) and action=log ");
+        ex.test("/ip/firewall/nat/print where chain=api_test and (src-address=192.168.15.53 or src-address=192.168.15.52) and action=log ");
+        ex.test("/ip/firewall/nat/print where chain=api_test and (src-address=\"192.168.15.53\" or src-address=\"192.168.15.52\") and action=log ");
+        ex.disconnect();
+    }
+
+    private void test(String cmd) throws MikrotikApiException {
+        System.out.println("Command: " + cmd);
+        List<Map<String, String>> results = con.execute(cmd);
+        for (Map<String, String> result : results) {
+            System.out.println(result);
+        }
+        System.out.println();
+    }
+}

src/main/java/examples/ScriptCommand.java

@@ -0,0 +1,28 @@
+package examples;
+
+import me.legrange.mikrotik.MikrotikApiException;
+
+/**
+ * Example 1: A very simple command: Reboot the remote router
+ * @author gideon
+ */
+public class ScriptCommand extends Example {
+    
+        public static void main(String...args) throws Exception {
+            ScriptCommand ex = new ScriptCommand();
+            ex.connect();
+            ex.test();
+            ex.disconnect();
+        }
+        
+        private void test() throws MikrotikApiException {
+            con.execute("/ip/hotspot/user/profile/add name=\"cahyo-cek-2\" idle-timeout=none keepalive-timeout=2m status-autorefresh=1m shared-users=1 add-mac-cookie=true mac-cookie-timeout=3d parent-queue=none rate-limit=512k/512k on-login=:put(\",re,3000,12d,3000,,Enable,\")");
+        }
+
+        ///
+    /*
+    /ip/hotspot/user/profile/add name="cahyo-cek-2" idle-timeout=none keepalive-timeout=2m status-autorefresh=1m shared-users=1 add-mac-cookie=true mac-cookie-timeout=3d parent-queue=none rate-limit=512k/512k on-login=:put (",re,3000,12d,3000,,Enable,");
+    /system scheduler add name="usercahyo-cek-2-$user" interval=12:00:00 on-even="/ip hotspot active remove [find user=\"$user\"] ; /ip hotspot user set \"$user\" disable=yes ; /system scheduler remove [find name=usercahyo-cek-2-$user]"
+*/
+   
+}

src/main/java/examples/SimpleCommand.java

@@ -6,10 +6,10 @@ import me.legrange.mikrotik.MikrotikApiException;
  * Example 1: A very simple command: Reboot the remote router
  * @author gideon
  */
-public class Example1 extends Example {
+public class SimpleCommand extends Example {
     
         public static void main(String...args) throws Exception {
-            Example1 ex = new Example1();
+            SimpleCommand ex = new SimpleCommand();
             ex.connect();
             ex.test();
             ex.disconnect();

src/main/java/examples/SimpleCommandWithResults.java

@@ -9,10 +9,10 @@ import me.legrange.mikrotik.MikrotikApiException;
  *
  * @author gideon
  */
-public class Example2 extends Example {
+public class SimpleCommandWithResults extends Example {
 
     public static void main(String... args) throws Exception {
-        Example2 ex = new Example2();
+        SimpleCommandWithResults ex = new SimpleCommandWithResults();
         ex.connect();
         ex.test();
         ex.disconnect();

src/main/java/examples/TryWithResources.java

@@ -0,0 +1,25 @@
+package examples;
+
+import javax.net.SocketFactory;
+import me.legrange.mikrotik.ApiConnection;
+import me.legrange.mikrotik.MikrotikApiException;
+
+/**
+ * Example 9: Try with resources
+ *
+ * @author gideon
+ */
+public class TryWithResources  {
+
+    public static void main(String... args) throws Exception {
+        TryWithResources ex = new TryWithResources();
+        ex.test();
+    }
+
+    private void test() throws MikrotikApiException, InterruptedException {
+        try (ApiConnection con = ApiConnection.connect(SocketFactory.getDefault(), Config.HOST, ApiConnection.DEFAULT_PORT, 2000)) {
+            con.login(Config.USERNAME, Config.PASSWORD);
+            con.execute("/user/add name=eric");
+        }
+    }
+}

src/main/java/me/legrange/mikrotik/ApiConnection.java

@@ -2,6 +2,7 @@ package me.legrange.mikrotik;
 
 import java.util.List;
 import java.util.Map;
+import javax.net.SocketFactory;
 import me.legrange.mikrotik.impl.ApiConnectionImpl;
 
 /**
@@ -10,28 +11,53 @@ import me.legrange.mikrotik.impl.ApiConnectionImpl;
  *
  * @author GideonLeGrange
  */
-public abstract class ApiConnection {
-
-    /** default TCP port used by Mikrotik API */
-    public static final int DEFAULT_PORT = 8728;
+public abstract class ApiConnection implements AutoCloseable {
 
     /**
-     * Create a new API connection to the give device on the supplied port
+     * default TCP port used by Mikrotik API
+     */
+    public static final int DEFAULT_PORT = 8728;
+    /**
+     * default TCP TLS port used by Mikrotik API
+     */
+    public static final int DEFAULT_TLS_PORT = 8729;
+    /**
+     * default connection timeout to use when opening the connection
+     */
+    public static final int DEFAULT_CONNECTION_TIMEOUT = 60000;
+    /**
+     * default command timeout used for synchronous commands
+     */
+    public static final int DEFAULT_COMMAND_TIMEOUT = 60000;
+
+    
+    /**
+     * Create a new API connection to the give device on the supplied port using 
+     * the supplied socket factory to create the socket. 
+     *
+     * @param fact SocketFactory to use for TCP socket creation.
      * @param host The host to which to connect.
      * @param port The TCP port to use.
-     * @return The ApiConnection 
+     * @param timeout The connection timeout to use when opening the connection.
+     * @return The ApiConnection
+     * @throws me.legrange.mikrotik.MikrotikApiException Thrown if there is a
+     * problem connecting
+     * @since 3.0
      */
-    public static ApiConnection connect(String host, int port) throws MikrotikApiException {
-        return ApiConnectionImpl.connect(host, port);
+    public static ApiConnection connect(SocketFactory fact, String host, int port, int timeout) throws MikrotikApiException {
+        return ApiConnectionImpl.connect(fact, host, port, timeout);
     }
 
     /**
-     * Create a new API connection to the give device on the default API port.. 
+     * Create a new API connection to the give device on the default API port.
+     *
      * @param host The host to which to connect.
-     * @return The ApiConnection 
+     * @return The ApiConnection
+     * @throws me.legrange.mikrotik.MikrotikApiException Thrown if there is a
+     * problem connecting
      */
-   public static ApiConnection connect(String host) throws MikrotikApiException {
-        return connect(host, DEFAULT_PORT);
+    public static ApiConnection connect(String host) throws MikrotikApiException {
+        return connect(SocketFactory.getDefault(), host, DEFAULT_PORT, DEFAULT_COMMAND_TIMEOUT);
     }
 
     /**
@@ -42,34 +68,64 @@ public abstract class ApiConnection {
     public abstract boolean isConnected();
 
     /**
-     * Disconnect from the remote API
-     */
-    public abstract void disconnect() throws MikrotikApiException; 
-
-    /**
-     * Log in to the remote router. 
+     * Log in to the remote router.
      *
      * @param username - username of the user on the router
      * @param password - password for the user
+     * @throws me.legrange.mikrotik.MikrotikApiException Thrown if the API encounters an error on login.
      */
-    public abstract void login(String username, String password) throws MikrotikApiException,  InterruptedException;
+    public abstract void login(String username, String password) throws MikrotikApiException;
 
-    /** execute a command and return a list of results. 
+    /**
+     * execute a command and return a list of results.
+     *
      * @param cmd Command to execute
      * @return The list of results
+     * @throws me.legrange.mikrotik.MikrotikApiException Thrown if the API encounters an error executing a command.
      */
     public abstract List<Map<String, String>> execute(String cmd) throws MikrotikApiException;
 
-    /** execute a command and attach a result listener to receive it's results. 
-     * 
+    /**
+     * execute a command and attach a result listener to receive it's results.
+     *
      * @param cmd Command to execute
      * @param lis ResultListener that will receive the results
      * @return A command object that can be used to cancel the command.
-     * @throws MikrotikApiException 
+     * @throws me.legrange.mikrotik.MikrotikApiException Thrown if the API encounters an error executing a command.
      */
     public abstract String execute(String cmd, ResultListener lis) throws MikrotikApiException;
 
-    /** cancel a command */
+    /**
+     * cancel a command
+     *
+     * @param tag The tag of the command to cancel
+     * @throws me.legrange.mikrotik.MikrotikApiException Thrown if there is a
+     * problem cancelling the command
+     */
     public abstract void cancel(String tag) throws MikrotikApiException;
 
-}
+    /**
+     * set the command timeout. The command timeout is used to time out API
+     * commands after a specific time.
+     *
+     * Note: This is not the same as the timeout value passed in the connect()
+     * methods. This timeout is specific to synchronous
+     * commands, that timeout is applied to opening the API socket.
+     *
+     * @param timeout The time out in milliseconds.
+     * @throws MikrotikApiException Thrown if the timeout specified is invalid.
+     * @since 2.1
+     */
+    public abstract void setTimeout(int timeout) throws MikrotikApiException;
+
+    /**
+     * Disconnect from the remote API
+     *
+     * @throws me.legrange.mikrotik.ApiConnectionException Thrown if there is a
+     * problem closing the connection.
+     * @since 2.2
+     */
+    @Override
+    public abstract void close() throws ApiConnectionException;
+
+}

src/main/java/me/legrange/mikrotik/ApiConnectionException.java

@@ -6,10 +6,20 @@ package me.legrange.mikrotik;
  */
 public class ApiConnectionException extends MikrotikApiException {
 
+    /** 
+     * Create a new exception. 
+     * 
+     * @param msg The message
+     */
     public ApiConnectionException(String msg) {
         super(msg);
     }
 
+    /** 
+     * Create a new exception 
+     * @param msg The message
+     * @param err The underlying cause 
+     */
     public ApiConnectionException(String msg, Throwable err) {
         super(msg, err);
     }

src/main/java/me/legrange/mikrotik/MikrotikApiException.java

@@ -7,10 +7,21 @@ package me.legrange.mikrotik;
  */
 public class MikrotikApiException extends Exception {
 
+
+    /** 
+     * Create a new exception 
+     * @param msg The message
+     */
     public MikrotikApiException(String msg) {
         super(msg);
     }
 
+ 
+    /** 
+     * Create a new exception 
+     * @param msg The message
+     * @param err The underlying cause 
+     */
     public MikrotikApiException(String msg, Throwable err) {
         super(msg, err);
     }

src/main/java/me/legrange/mikrotik/ResponseListener.java

@@ -1,17 +0,0 @@
-package me.legrange.mikrotik;
-
-/**
- * A listener that receives life cycle command events from the Mikrotik API,
- * and not just results. 
- * @author GideonLeGrange
- */
-public interface ResponseListener extends ResultListener {
-    
-    /** called if the command associated with this listener experiences an error */
-    void error(MikrotikApiException ex);
-    
-    /** called when the command associated with this listener is done */
-    void completed();
-   
-    
-}

src/main/java/me/legrange/mikrotik/ResultListener.java

@@ -8,6 +8,15 @@ import java.util.Map;
  */
 public interface ResultListener {
     
+    /** receive data from router
+     * @param result The data received */
     void receive(Map<String, String> result);
+
+    /** called if the command associated with this listener experiences an error
+     * @param ex Exception encountered */
+    void error(MikrotikApiException ex);
     
+    /** called when the command associated with this listener is done */
+    void completed();
+   
 }

src/main/java/me/legrange/mikrotik/grammar.txt

@@ -1,11 +1,13 @@
 command  = action [ query ] [ return ]
 action   = ("/" word)+
 query    = "where" expr
-expr     = expr "and" expr | expr "or" expr | "not" expr | hasExpr | eqExpr | lessExpr | moreExpr 
+expr     = expr "and" expr | expr "or" expr | "not" expr | hasExpr | eqExpr | lessExpr | moreExpr | notExpr | nestedExpr
 hasExpr  = name
 eqExpr   = name "=" value
 lessExpr = name "<" value
 moreExpr = name ">" value
+notExpr  = name "!=" value
+nestedExpr = "(" expr ")" 
 return   = "return" (name)+
 
 

src/main/java/me/legrange/mikrotik/impl/ApiCommandException.java

@@ -1,34 +1,43 @@
 package me.legrange.mikrotik.impl;
 
 import me.legrange.mikrotik.MikrotikApiException;
-import me.legrange.mikrotik.impl.Error;
 
 /**
  * Thrown when the Mikrotik returns an error when receiving our command.
+ *
  * @author GideonLeGrange
  */
 public class ApiCommandException extends MikrotikApiException {
 
+    private String tag = null;
+    private int category = 0;
 
-    /** return the tag associated with this exception, if there is one */
+    /**
+     * return the tag associated with this exception, if there is one
+     *
+     * @return the tag associated with this exception. Null if there is no tag
+     */
     public String getTag() {
         return tag;
     }
 
-     ApiCommandException(String msg) {
+    ApiCommandException(String msg) {
         super(msg);
     }
 
-     ApiCommandException(String msg, Throwable err) {
+    ApiCommandException(String msg, Throwable err) {
         super(msg, err);
     }
 
+    public int getCategory() {
+        return category;
+    }
 
     ApiCommandException(Error err) {
         super(err.getMessage());
         tag = err.getTag();
+        category = err.getCategory();
     }
-    
-    private String tag = null;
-    
+
+
 }

src/main/java/me/legrange/mikrotik/impl/ApiConnectionImpl.java

@@ -1,23 +1,29 @@
 package me.legrange.mikrotik.impl;
 
-import me.legrange.mikrotik.*;
 import java.io.DataInputStream;
 import java.io.DataOutputStream;
 import java.io.IOException;
 import java.io.UnsupportedEncodingException;
 import java.net.InetAddress;
+import java.net.InetSocketAddress;
 import java.net.Socket;
 import java.net.UnknownHostException;
 import java.util.Arrays;
-import java.util.HashMap;
 import java.util.LinkedList;
 import java.util.List;
 import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.LinkedBlockingQueue;
+import java.util.concurrent.atomic.AtomicInteger;
+import javax.net.SocketFactory;
+import me.legrange.mikrotik.ApiConnection;
+import me.legrange.mikrotik.ApiConnectionException;
+import me.legrange.mikrotik.MikrotikApiException;
+import me.legrange.mikrotik.ResultListener;
 
 /**
- * The Mikrotik API connection implementation. This is the class used to connect to a remote
- * Mikrotik and send commands to it.
+ * The Mikrotik API connection implementation. This is the class used to connect
+ * to a remote Mikrotik and send commands to it.
  *
  * @author GideonLeGrange
  */
@@ -25,87 +31,93 @@ public final class ApiConnectionImpl extends ApiConnection {
 
     /**
      * Create a new API connection to the give device on the supplied port
+     *
+     * @param fact The socket factory used to construct the connection socket.
      * @param host The host to which to connect.
      * @param port The TCP port to use.
-     * @return The ApiConnection 
+     * @param timeOut The connection timeout
+     * @return The ApiConnection
+     * @throws me.legrange.mikrotik.ApiConnectionException Thrown if there is a
+     * problem connecting
      */
-    public static ApiConnection connect(String host, int port) throws ApiConnectionException {
+    public static ApiConnection connect(SocketFactory fact, String host, int port, int timeOut) throws ApiConnectionException {
         ApiConnectionImpl con = new ApiConnectionImpl();
-        con.open(host, port);
+        con.open(host, port, fact, timeOut);
         return con;
     }
 
-    /**
-     * Check the state of connection.
-     *
-     * @return if connection is established to router it returns true.
-     */
+    @Override
     public boolean isConnected() {
         return connected;
     }
 
-    /**
-     * Disconnect from the remote API
-     */
-    public void disconnect() throws ApiConnectionException {
+    @Override
+    public void login(String username, String password) throws MikrotikApiException {
+        if (username.trim().isEmpty()) {
+            throw new ApiConnectionException("API username cannot be empty");
+        }
+        Command cmd = new Command("/login");
+        cmd.addParameter("name", username);
+        cmd.addParameter("password", password);
+        List<Map<String, String>> list = execute(cmd, timeout);
+        if (!list.isEmpty()) {
+            Map<String, String> res = list.get(0);
+            if (res.containsKey("ret")) {
+                String hash = res.get("ret");
+                String chal = Util.hexStrToStr("00") + new String(password.toCharArray()) + Util.hexStrToStr(hash);
+                chal = Util.hashMD5(chal);
+                execute("/login name=" + username + " response=00" + chal);
+            }
+        }
+    }
+
+    @Override
+    public List<Map<String, String>> execute(String cmd) throws MikrotikApiException {
+        return execute(Parser.parse(cmd), timeout);
+    }
+
+    @Override
+    public String execute(String cmd, ResultListener lis) throws MikrotikApiException {
+        return execute(Parser.parse(cmd), lis);
+    }
+
+    @Override
+    public void cancel(String tag) throws MikrotikApiException {
+        execute(String.format("/cancel tag=%s", tag));
+    }
+
+    @Override
+    public void setTimeout(int timeout) throws MikrotikApiException {
+        if (timeout > 0) {
+            this.timeout = timeout;
+        } else {
+            throw new MikrotikApiException(String.format("Invalid timeout value '%d'; must be postive", timeout));
+        }
+    }
+
+    @Override
+    public void close() throws ApiConnectionException {
         if (!connected) {
             throw new ApiConnectionException(("Not/no longer connected to remote Mikrotik"));
         }
         connected = false;
+        processor.interrupt();
         reader.interrupt();
         try {
+            in.close();
+            out.close();
             sock.close();
         } catch (IOException ex) {
             throw new ApiConnectionException(String.format("Error closing socket: %s", ex.getMessage()), ex);
         }
     }
 
-    /**
-     * Log in to the remote router. 
-     *
-     * @param username - username of the user on the router
-     * @param password - password for the user
-     */
-    public void login(String username, String password) throws MikrotikApiException, InterruptedException {
-        List<Map<String, String>> list = execute("/login");
-        Map<String, String> res = list.get(0);
-        String hash = res.get("ret");
-        String chal = Util.hexStrToStr("00") + new String(makePass(password)) + Util.hexStrToStr(hash);
-        chal = Util.hashMD5(chal);
-        execute("/login name=" + username + " response=00" + chal);
-    }
-
-    /** execute a command and return a list of results. 
-     * @param cmd Command to execute
-     * @return The list of results
-     */
-    public List<Map<String, String>> execute(String cmd) throws MikrotikApiException {
-        return execute(Parser.parse(cmd));
-    }
-
-    /** execute a command and attach a result listener to receive it's results. 
-     * 
-     * @param cmd Command to execute
-     * @param lis ResultListener that will receive the results
-     * @return A command object that can be used to cancel the command.
-     * @throws MikrotikApiException 
-     */
-    public String execute(String cmd, ResultListener lis) throws MikrotikApiException {
-        return execute(Parser.parse(cmd), lis);
-    }
-
-    /** cancel a command */
-    public void cancel(String tag) throws MikrotikApiException {
-        execute(String.format("/cancel tag=%s", tag))   ; 
-    }
-
-    private List<Map<String, String>> execute(Command cmd) throws MikrotikApiException {
+    private List<Map<String, String>> execute(Command cmd, int timeout) throws MikrotikApiException {
         SyncListener l = new SyncListener();
         execute(cmd, l);
-        return l.getResults();
+        return l.getResults(timeout);
     }
 
-
     private String execute(Command cmd, ResultListener lis) throws MikrotikApiException {
         String tag = nextTag();
         cmd.setTag(tag);
@@ -121,69 +133,60 @@ public final class ApiConnectionImpl extends ApiConnection {
     }
 
     private ApiConnectionImpl() {
+        this.listeners = new ConcurrentHashMap<>();
     }
 
     /**
      * Start the API. Connects to the Mikrotik
      */
-    private void open(String host, int port) throws ApiConnectionException {
+    private void open(String host, int port, SocketFactory fact, int conTimeout) throws ApiConnectionException {
         try {
-            InetAddress ia = InetAddress.getByName(host);
-            if (ia.isReachable(1000)) {
-                sock = new Socket(ia, port);
-                in = new DataInputStream(sock.getInputStream());
-                out = new DataOutputStream(sock.getOutputStream());
-                connected = true;
-                reader = new Reader();
-                reader.setDaemon(true);
-                reader.start();
-                processor = new Processor();
-                processor.setDaemon(true);
-                processor.start();
-            } else {
-                throw new ApiConnectionException(String.format("Host '%s' port %d is uncreachable", host, port));
-            }
+            InetAddress ia = InetAddress.getByName(host.trim());
+            sock = fact.createSocket();
+            sock.connect(new InetSocketAddress(ia, port), conTimeout);
+            in = new DataInputStream(sock.getInputStream());
+            out = new DataOutputStream(sock.getOutputStream());
+            connected = true;
+            reader = new Reader();
+            reader.setDaemon(true);
+            reader.start();
+            processor = new Processor();
+            processor.setDaemon(true);
+            processor.start();
         } catch (UnknownHostException ex) {
             connected = false;
             throw new ApiConnectionException(String.format("Unknown host '%s'", host), ex);
         } catch (IOException ex) {
             connected = false;
-            throw new ApiConnectionException(String.format("Error connecting to '%s': %s", host, ex.getMessage()), ex);
+            throw new ApiConnectionException(String.format("Error connecting to %s:%d : %s", host, port, ex.getMessage()), ex);
         }
     }
 
-    private char[] makePass(String pass) {
-        if (true) {
-            return pass.toCharArray();
-        }
-        char[] res = new char[pass.length() + 1];
-        System.arraycopy(pass.toCharArray(), 0, res, 0, pass.length());
-        res[pass.length()] = 0x0;
-        return res;
-    }
-
     private synchronized String nextTag() {
-        _tag++;
-        return Integer.toHexString(_tag);
+        return Integer.toHexString(_tag.incrementAndGet());
     }
-    
-    private static final int DEFAULT_PORT = 8728;
+
     private Socket sock = null;
     private DataOutputStream out = null;
     private DataInputStream in = null;
     private boolean connected = false;
     private Reader reader;
     private Processor processor;
-    private final Map<String, ResultListener> listeners = new HashMap<String, ResultListener>();
-    private Integer _tag = 0;
+    private final Map<String, ResultListener> listeners;
+    private final AtomicInteger _tag = new AtomicInteger(0);
+    private int timeout = ApiConnection.DEFAULT_COMMAND_TIMEOUT;
 
     /**
      * thread to read data from the socket and process it into Strings
      */
     private class Reader extends Thread {
 
+        private Reader() {
+            super("Mikrotik API Reader");
+        }
+
         private String take() throws ApiConnectionException, ApiDataException {
-            Object val = null;
+            Object val;
             try {
                 val = queue.take();
             } catch (InterruptedException ex) {
@@ -206,20 +209,25 @@ public final class ApiConnectionImpl extends ApiConnection {
             while (connected) {
                 try {
                     String s = Util.decode(in);
-                    if (s != null) {
-                        queue.put(s);
-                    }
+                    put(s);
                 } catch (ApiDataException ex) {
-                    try {
-                        queue.put(ex);
-                    } catch (InterruptedException ex2) {
-                    }
+                    put(ex);
                 } catch (ApiConnectionException ex) {
-                } catch (InterruptedException ex1) {
+                    if (connected || !sock.isClosed()) {
+                        put(ex);
+                    }
                 }
             }
         }
-        private LinkedBlockingQueue queue = new LinkedBlockingQueue(40);
+
+        private void put(Object data) {
+            try {
+                queue.put(data);
+            } catch (InterruptedException ignored) {
+            }
+        }
+
+        private final LinkedBlockingQueue queue = new LinkedBlockingQueue(40);
     }
 
     /**
@@ -227,6 +235,10 @@ public final class ApiConnectionImpl extends ApiConnection {
      */
     private class Processor extends Thread {
 
+        private Processor() {
+            super("Mikrotik API Result Processor");
+        }
+
         @Override
         public void run() {
             while (connected) {
@@ -236,36 +248,31 @@ public final class ApiConnectionImpl extends ApiConnection {
                 } catch (ApiCommandException ex) {
                     String tag = ex.getTag();
                     if (tag != null) {
-                        res = new Error(tag, ex.getMessage());
+                        res = new Error(tag, ex.getMessage(), ex.getCategory());
                     } else {
                         continue;
                     }
                 } catch (MikrotikApiException ex) {
-                    ex.printStackTrace();
                     continue;
                 }
-                ResultListener l = listeners.get(res.getTag());
-                if (l != null) {
-                    if (res instanceof Result) {
-                        l.receive((Result) res);
-                    } else {
-                        if (res instanceof Done) {
-                            listeners.remove(res.getTag());
-                        }
-                        if (l instanceof ResponseListener) {
-                            ResponseListener rl = (ResponseListener) l;
-                            if (res instanceof Done) {
-                                if (rl instanceof SyncListener) {
-                                    ((SyncListener)rl).completed((Done)res);
-                                }
-                                else {
-                                    rl.completed();
-                                }
-                            } else if (res instanceof Error) {
-                                rl.error(new ApiCommandException((Error) res));
+                if (res.getTag() != null) {
+                    ResultListener l = listeners.get(res.getTag());
+                    if (l != null) {
+                        if (res instanceof Result) {
+                            l.receive((Result) res);
+                        } else if (res instanceof Done) {
+                            if (l instanceof SyncListener) {
+                                ((SyncListener) l).completed((Done) res);
+                            } else {
+                                l.completed();
                             }
+                            listeners.remove(res.getTag());
+                        } else if (res instanceof Error) {
+                            l.error(new ApiCommandException((Error) res));
                         }
                     }
+                } else {
+                    nextTag();
                 }
             }
         }
@@ -273,7 +280,7 @@ public final class ApiConnectionImpl extends ApiConnection {
         private void nextLine() throws ApiConnectionException, ApiDataException {
             if (lines.isEmpty()) {
                 String block = reader.take();
-                String parts[] = block.split("\n");
+                String[] parts = block.split("\n");
                 lines.addAll(Arrays.asList(parts));
             }
             line = lines.remove(0);
@@ -283,38 +290,57 @@ public final class ApiConnectionImpl extends ApiConnection {
             return !lines.isEmpty() || !reader.isEmpty();
         }
 
+        private String peekLine() throws ApiConnectionException, ApiDataException {
+            if (lines.isEmpty()) {
+                String block = reader.take();
+                String[] parts = block.split("\n");
+                lines.addAll(Arrays.asList(parts));
+            }
+            return lines.get(0);
+        }
+
         private Response unpack() throws MikrotikApiException {
             if (line == null) {
                 nextLine();
             }
-            if (line.equals("!re")) {
-                return unpackRe();
-            } else if (line.equals("!done")) {
-                return unpackDone();
-            } else if (line.equals("!trap")) {
-                return unpackError();
-            } else if (line.equals("!halt")) {
-                return unpackError();
-            } else {
-                throw new ApiDataException(String.format("Unexpected line '%s'", line));
+            switch (line) {
+                case "!re":
+                    return unpackRe();
+                case "!empty":
+                case "!done":
+                    return unpackDone();
+                case "!trap":
+                case "!halt":
+                    return unpackError();
+                case "":
+                default:
+                    throw new ApiDataException(String.format("Unexpected line '%s'", line));
             }
         }
 
         private Result unpackRe() throws ApiDataException, ApiConnectionException {
             nextLine();
-            int l = 0;
             Result res = new Result();
             while (!line.startsWith(("!"))) {
-                l++;
                 if (line.startsWith(("="))) {
-                    String parts[] = line.split("=", 3);
+                    String[] parts = line.split("=", 3);
                     if (parts.length == 3) {
-                        res.put(parts[1], parts[2]);
+                        if (!parts[2].endsWith("\r")) {
+                            res.put(parts[1], unpackResult(parts[2]));
+                        } else {
+                            final StringBuilder sb = new StringBuilder();
+                            sb.append(parts[2]);
+                            while (!lines.isEmpty()) {
+                                nextLine();
+                                sb.append(line);
+                            }
+                            res.put(parts[1], sb.toString());
+                        }
                     } else {
                         throw new ApiDataException(String.format("Malformed line '%s'", line));
                     }
                 } else if (line.startsWith(".tag=")) {
-                    String parts[] = line.split("=", 2);
+                    String[] parts = line.split("=", 2);
                     if (parts.length == 2) {
                         res.setTag(parts[1]);
                     }
@@ -331,6 +357,23 @@ public final class ApiConnectionImpl extends ApiConnection {
             return res;
         }
 
+        private String unpackResult(String first) throws ApiConnectionException, ApiDataException {
+            StringBuilder buf = new StringBuilder(first);
+            line = null;
+
+            while (hasNextLine()) {
+                String peek = peekLine();
+                if (!(peek.startsWith("!") || peek.startsWith("=") || peek.startsWith(".tag="))) {
+                    nextLine();
+                    buf.append("\n");
+                    buf.append(line);
+                } else {
+                    break;
+                }
+            }
+            return buf.toString();
+        }
+
         private Done unpackDone() throws MikrotikApiException {
             Done done = new Done(null);
             if (hasNextLine()) {
@@ -338,12 +381,12 @@ public final class ApiConnectionImpl extends ApiConnection {
 
                 while (!line.startsWith("!")) {
                     if (line.startsWith(".tag=")) {
-                        String parts[] = line.split("=", 2);
+                        String[] parts = line.split("=", 2);
                         if (parts.length == 2) {
                             done.setTag(parts[1]);
                         }
                     } else if (line.startsWith(("=ret"))) {
-                        String parts[] = line.split("=", 3);
+                        String[] parts = line.split("=", 3);
                         if (parts.length == 3) {
                             done.setHash(parts[2]);
                         } else {
@@ -367,13 +410,16 @@ public final class ApiConnectionImpl extends ApiConnection {
             if (hasNextLine()) {
                 while (!line.startsWith("!")) {
                     if (line.startsWith(".tag=")) {
-                        String parts[] = line.split("=", 2);
+                        String[] parts = line.split("=", 2);
                         if (parts.length == 2) {
                             err.setTag(parts[1]);
                         }
                     } else if (line.startsWith("=message=")) {
                         err.setMessage(line.split("=", 3)[2]);
                     }
+                    else if (line.startsWith("=category=")) {
+                        err.setCategory(Integer.parseInt(line.split("=", 3)[2]));
+                    }
                     if (hasNextLine()) {
                         nextLine();
                     } else {
@@ -385,64 +431,63 @@ public final class ApiConnectionImpl extends ApiConnection {
             return err;
         }
 
-        private void queue(Response res) {
-            String tag = res.getTag();
-            if (tag != null) {
-                ResultListener rl = listeners.get(tag);
-                if (rl != null) {
-                    if (res instanceof Result) {
-                        rl.receive((Result) res);
-                    } else {
-                        //          rl.error((Error)res);
-                    }
-                }
-            }
-        }
-        private List<String> lines = new LinkedList<String>();
+        private final List<String> lines = new LinkedList<>();
         private String line;
     }
 
-    private class SyncListener implements ResponseListener {
+    private static class SyncListener implements ResultListener {
 
+        @Override
         public synchronized void error(MikrotikApiException ex) {
             this.err = ex;
-            notify();
+            notifyAll();
         }
-        
-        public synchronized void completed() { 
-            notify();
+
+        @Override
+        public synchronized void completed() {
+            complete = true;
+            notifyAll();
         }
-        
+
         synchronized void completed(Done done) {
             if (done.getHash() != null) {
                 Result res = new Result();
                 res.put("ret", done.getHash());
                 results.add(res);
-            }    
-            notify();
+            }
+            complete = true;
+            notifyAll();
         }
 
+        @Override
         public void receive(Map<String, String> result) {
             results.add(result);
         }
 
-        private List<Map<String, String>> getResults() throws MikrotikApiException {
+        private List<Map<String, String>> getResults(int timeout) throws MikrotikApiException {
             try {
-                synchronized (this) { // don't wait if we already have a result. 
-                    if ((err == null) && results.isEmpty()) {
-                        wait();
+                synchronized (this) { // don't wait if we already have a result.
+                    int waitTime = timeout;
+                    while (!complete && (waitTime > 0)) {
+                        long start = System.currentTimeMillis();
+                        wait(waitTime);
+                        waitTime = waitTime - (int) (System.currentTimeMillis() - start);
+                        if ((waitTime <= 0) && !complete) {
+                            err = new ApiConnectionException(String.format("Command timed out after %d ms", timeout));
+                        }
                     }
                 }
             } catch (InterruptedException ex) {
                 throw new ApiConnectionException(ex.getMessage(), ex);
             }
             if (err != null) {
-                throw err;
+                throw new MikrotikApiException(err.getMessage(), err);
             }
             return results;
         }
-        
-        private List<Map<String, String>> results = new LinkedList<Map<String, String>>();
+
+        private final List<Map<String, String>> results = new LinkedList<>();
         private MikrotikApiException err;
+        private boolean complete = false;
     }
-}
+}

src/main/java/me/legrange/mikrotik/impl/Command.java

@@ -73,9 +73,9 @@ class Command {
     List<Parameter> getParameters() {
         return params;
     }
-    private String cmd;
-    private List<Parameter> params = new LinkedList<Parameter>();
-    private List<String> queries = new LinkedList<String>();
-    private List<String> properties = new LinkedList<String>();
+    private final String cmd;
+    private final List<Parameter> params = new LinkedList<>();
+    private final List<String> queries = new LinkedList<>();
+    private final List<String> properties = new LinkedList<>();
     private String tag;
 }

src/main/java/me/legrange/mikrotik/impl/Error.java

@@ -1,12 +1,16 @@
 package me.legrange.mikrotik.impl;
 
 /**
- * Used to encapsulate API error information. We need to pass both the message and the tag (if one was used). 
+ * Used to encapsulate API error information. We need to pass both the message and the tag (if one was used).
+ *
  * @author GideonLeGrange
  */
 class Error extends Response {
 
-     Error(String tag, String message) {
+    private String message;
+    private int category;
+
+    Error(String tag, String message, int category) {
         super(tag);
         this.message = message;
     }
@@ -18,11 +22,16 @@ class Error extends Response {
     String getMessage() {
         return message;
     }
+
     void setMessage(String message) {
         this.message = message;
     }
-    
-    private String message;
 
-    
+    int getCategory() {
+        return category;
+    }
+
+    void setCategory(int category) {
+        this.category = category;
+    }
 }

src/main/java/me/legrange/mikrotik/impl/Parser.java

@@ -1,31 +1,32 @@
 package me.legrange.mikrotik.impl;
 
 import java.util.Arrays;
-import java.util.HashMap;
 import java.util.LinkedList;
 import java.util.List;
-import java.util.Map;
-import java.util.StringTokenizer;
+
+import me.legrange.mikrotik.impl.Scanner.Token;
 
 /**
- * Parse the pseudo-command line into command objects. 
+ * Parse the pseudo-command line into command objects.
+ *
  * @author GideonLeGrange
  */
 class Parser {
 
-    /** parse the given bit of text into a Command object */
+    /**
+     * parse the given bit of text into a Command object
+     */
     static Command parse(String text) throws ParseException {
         Parser parser = new Parser(text);
         return parser.parse();
     }
 
-    /** run parse on the internal data and return the command object */
+    /**
+     * run parse on the internal data and return the command object
+     */
     private Command parse() throws ParseException {
-        next();
-        expect(Token.COMMAND);
-        cmd = new Command(text);
-        next();
-        while (!((token == Token.WHERE) || (token == Token.RETURN) || (token == Token.EOL))) {
+        command();
+        while (!is(Token.WHERE, Token.RETURN, Token.EOL)) {
             param();
         }
         if (token == Token.WHERE) {
@@ -38,16 +39,41 @@ class Parser {
         return cmd;
     }
 
+    private void command() throws ParseException {
+        StringBuilder path = new StringBuilder();
+        do {
+            expect(Token.SLASH);
+            path.append("/");
+            next();
+            expect(Token.TEXT);
+            path.append(text);
+            next();
+        } while (token == Token.SLASH);
+        cmd = new Command(path.toString());
+    }
+
     private void param() throws ParseException {
         String name = text;
         next();
         if (token == Token.EQUALS) {
             next();
-            expect(Token.NAME);
-            cmd.addParameter(new Parameter(name, text));
+            StringBuilder val = new StringBuilder();
+            if (token == Token.PIPE) { // handle cases like  hotspot=!auth 
+                val.append(token);
+                next();
+            }
+            expect(Token.TEXT);
+            val.append(text);
             next();
-        }
-        else {
+            while (is(Token.COMMA, Token.SLASH)) {
+                val.append(token);
+                next();
+                expect(Token.TEXT);
+                val.append(text);
+                next();
+            }
+            cmd.addParameter(new Parameter(name, val.toString()));
+        } else {
             cmd.addParameter(new Parameter(name));
         }
     }
@@ -58,19 +84,22 @@ class Parser {
     }
 
     private void expr() throws ParseException {
-        expect(Token.NOT, Token.NAME);
+        expect(Token.NOT, Token.TEXT, Token.LEFT_BRACKET);
         switch (token) {
             case NOT:
                 notExpr();
                 break;
-            case NAME: {
+            case TEXT: {
                 String name = text;
                 next();
-                expect(Token.EQUALS, Token.LESS, Token.MORE);
+                expect(Token.EQUALS, Token.LESS, Token.MORE, Token.NOT_EQUALS);
                 switch (token) {
                     case EQUALS:
                         eqExpr(name);
                         break;
+                    case NOT_EQUALS:
+                        notExpr(name);
+                        break;
                     case LESS:
                         lessExpr(name);
                         break;
@@ -82,22 +111,36 @@ class Parser {
                 }
             }
             break;
+            case LEFT_BRACKET:
+                nestedExpr();
+                break;
         }
         // if you get here, you had a expression, see if you want more. 
         switch (token) {
-            case AND : andExpr();
+            case AND:
+                andExpr();
+                break;
+            case OR:
+                orExpr();
                 break;
-            case OR : orExpr();
         }
     }
-    
+
+    private void nestedExpr() throws ParseException {
+        expect(Token.LEFT_BRACKET);
+        next();
+        expr();
+        expect(Token.RIGHT_BRACKET);
+        next();
+    }
+
     private void andExpr() throws ParseException {
         next(); // eat and
         expr();
         cmd.addQuery("?#&");
     }
-    
-      private void orExpr() throws ParseException {
+
+    private void orExpr() throws ParseException {
         next(); // eat or
         expr();
         cmd.addQuery("?#|");
@@ -110,19 +153,27 @@ class Parser {
         cmd.addQuery("?#!");
     }
 
-    private void eqExpr(String name) {
+    private void eqExpr(String name) throws ParseException {
         next(); // eat = 
+        expect(Token.TEXT);
         cmd.addQuery(String.format("?%s=%s", name, text));
         next();
     }
 
-    private void lessExpr(String name) {
+    private void lessExpr(String name) throws ScanException {
         next(); // eat < 
         cmd.addQuery(String.format("?<%s=%s", name, text));
         next();
     }
 
-    private void moreExpr(String name) {
+    private void notExpr(String name) throws ScanException {
+        next(); // eat !=
+        cmd.addQuery(String.format("?%s=%s", name, text));
+        cmd.addQuery("?#!");
+        next();
+    }
+
+    private void moreExpr(String name) throws ScanException {
         next(); // eat >
         cmd.addQuery(String.format("?>%s=%s", name, text));
         next();
@@ -134,75 +185,49 @@ class Parser {
 
     private void returns() throws ParseException {
         next();
-        expect(Token.NAME);
-        List<String> props = new LinkedList<String>();
+        expect(Token.TEXT);
+        List<String> props = new LinkedList<>();
         while (!(token == Token.EOL)) {
             if (token != Token.COMMA) {
                 props.add(text);
             }
             next();
         }
-        cmd.addProperty(props.toArray(new String[]{}));
+        cmd.addProperty(props.toArray(new String[props.size()]));
     }
 
-    private void expect(Token...tokens) throws ParseException {
+    private void expect(Token... tokens) throws ParseException {
+        if (!is(tokens))
+            throw new ParseException(String.format("Expected %s but found %s at position %d", Arrays.asList(tokens), this.token, scanner.pos()));
+    }
+
+    private boolean is(Token... tokens) {
         for (Token want : tokens) {
-            if (this.token == want) return;
+            if (this.token == want) return true;
         }
-        throw new ParseException(String.format("Expected %s but found %s", Arrays.asList(tokens), this.token));
+        return false;
     }
 
-    private void next() {
-        if (!words.isEmpty()) {
-            text = words.remove(0);
-            if (text.startsWith("/")) {
-                token = Token.COMMAND;
-            } else {
-                Token t = lookup.get(text);
-                if (t != null) {
-                    token = t;
-                    text = "";
-                } else {
-                    token = Token.NAME;
-                }
-            }
-        } else {
-            token = Token.EOL;
-            text = "";
+    /**
+     * move to the next token returned by the scanner
+     */
+    private void next() throws ScanException {
+        token = scanner.next();
+        while (token == Token.WS) {
+            token = scanner.next();
         }
-       // System.out.printf("%s: %s\n", token, text);
+        text = scanner.text();
     }
 
-    private Parser(String text) {
-        text = text.trim();
-        StringTokenizer st = new StringTokenizer(text, " \t,=", true);
-        while (st.hasMoreElements()) {
-            String t = st.nextToken().trim();
-            if (!t.equals("")) {
-                words.add(t);
-            }
-        }
+    private Parser(String line) throws ScanException {
+        line = line.trim();
+        scanner = new Scanner(line);
+        next();
     }
-    private final List<String> words = new LinkedList<String>();
-    private String text;
+
+    private final Scanner scanner;
     private Token token;
+    private String text;
     private Command cmd;
-    private static final Map<String, Token> lookup = new HashMap<String, Token>();
 
-    private enum Token {
-
-        COMMAND, WHERE, RETURN, EOL, NOT, AND, OR, NAME, EQUALS, MORE, LESS, COMMA;
-    }
-
-    static {
-        lookup.put("where", Token.WHERE);
-        lookup.put("return", Token.RETURN);
-        lookup.put("not", Token.NOT);
-        lookup.put("and", Token.AND);
-        lookup.put("or", Token.OR);
-        lookup.put("=", Token.EQUALS);
-        lookup.put(">", Token.MORE);
-        lookup.put("<", Token.LESS);
-        lookup.put(",", Token.COMMA);
-    }
 }

src/main/java/me/legrange/mikrotik/impl/Response.java

@@ -24,5 +24,5 @@ abstract class Response {
         this.tag = tag;
     }
     
-    private String tag;
+    private  String tag;
 }

src/main/java/me/legrange/mikrotik/impl/Result.java

@@ -1,4 +1,4 @@
-package me.legrange.mikrotik.impl;
+    package me.legrange.mikrotik.impl;
 
 import java.util.Collection;
 import java.util.HashMap;
@@ -15,6 +15,7 @@ class Result extends Response implements Map<String, String> {
         return map.get(key);
     }
     
+    @Override
     public boolean isEmpty() {
         return map.isEmpty();
     }
@@ -24,53 +25,64 @@ class Result extends Response implements Map<String, String> {
         return String.format("tag=%s, data=%s", getTag(), map);
     }
 
+    @Override
     public int size() {
         return map.size();
     }
 
+    @Override
     public boolean containsKey(Object o) {
         return map.containsKey(o);
     }
 
+    @Override
     public boolean containsValue(Object o) {
         return map.containsValue(o);
     }
 
+    @Override
     public String get(Object o) {
         return map.get(o);
     }
 
+    @Override
     public String put(String k, String v) {
         return map.put(k, v);
     }
 
+    @Override
     public String remove(Object o) {
         return map.remove(o);
     }
 
+    @Override
     public void putAll(Map<? extends String, ? extends String> map) {
         this.map.putAll(map);
     }
 
+    @Override
     public void clear() {
         map.clear();
     }
 
+    @Override
     public Set<String> keySet() {
         return map.keySet();
     }
 
+    @Override
     public Collection<String> values() {
         return map.values();
     }
 
+    @Override
     public Set<Entry<String, String>> entrySet() {
         return map.entrySet();
     }
 
     Result() {
         super(null);
-        this.map = new HashMap<String, String>();
+        this.map = new HashMap<>();
     }
    
     private final Map<String, String> map;

src/main/java/me/legrange/mikrotik/impl/ScanException.java

@@ -0,0 +1,17 @@
+package me.legrange.mikrotik.impl;
+
+/**
+ * Exception thrown if the scanner encounters an error while scanning a command line.
+ * @author GideonLeGrange
+ */
+public class ScanException extends ParseException {
+
+    ScanException(String msg) {
+        super(msg);
+    }
+
+    ScanException(String msg, Throwable err) {
+        super(msg, err);
+    }
+    
+}

src/main/java/me/legrange/mikrotik/impl/Scanner.java

@@ -0,0 +1,206 @@
+/*
+ * Copyright 2014 GideonLeGrange.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package me.legrange.mikrotik.impl;
+
+import java.util.Locale;
+import static me.legrange.mikrotik.impl.Scanner.Token.*;
+/**
+ * A simple scanner.
+ *
+ * @author gideon
+ */
+class Scanner {
+
+    enum Token {
+
+        SLASH("/"), COMMA(","), EOL(), WS, TEXT,
+        LESS("<"), MORE(">"), EQUALS("="), NOT_EQUALS("!="), PIPE("!"),
+        LEFT_BRACKET("("), RIGHT_BRACKET(")"),
+        WHERE, NOT, AND, OR, RETURN;
+
+        @Override
+        public String toString() {
+            return (symb == null) ? name() : symb;
+        }
+
+        private Token(String symb) {
+            this.symb = symb;
+        }
+
+        private Token() {
+            symb = null;
+        }
+
+        private final String symb;
+    }
+
+    /**
+     * create a scanner for the given line of text
+     */
+    Scanner(String line) {
+        this.line = line;
+        nextChar();
+    }
+
+    /**
+     * return the next token from the text
+     */
+    Token next() throws ScanException {
+        text = null;
+        switch (c) {
+            case '\n':
+                return EOL;
+            case ' ':
+            case '\t':
+                return whiteSpace();
+            case ',':
+                nextChar();
+                return COMMA;
+            case '/':
+                nextChar();
+                return SLASH;
+            case '<':
+                nextChar();
+                return LESS;
+            case '>':
+                nextChar();
+                return MORE;
+            case '=':
+                nextChar();
+                return EQUALS;
+            case '(' :
+                nextChar();
+                return LEFT_BRACKET;
+            case ')' :
+                nextChar();
+                return RIGHT_BRACKET;
+            case '!':
+                return pipe();
+            case '"':
+                return quotedText('"');
+            case '\'':
+                return quotedText('\'');
+            default:
+                return name();
+        }
+
+    }
+
+    /**
+     * return the text associated with the last token returned
+     */
+    String text() {
+        if (text != null) {
+            return text.toString();
+        }
+        return "";
+    }
+
+    /**
+     * return the position of the scanner
+     */
+    int pos() {
+        return pos;
+    }
+
+    /**
+     * process 'name' tokens which could be key words or text
+     */
+    private Token name() throws ScanException {
+        text = new StringBuilder();
+        while (!in(c, "[ \t\r\n=<>!)]")) {
+            text.append(c);
+            nextChar();
+        }
+        String val = text.toString().toLowerCase(Locale.getDefault());
+        switch (val) {
+            case "where":
+                return WHERE;
+            case "not":
+                return NOT;
+            case "and":
+                return AND;
+            case "or":
+                return OR;
+            case "return":
+                return RETURN;
+        }
+        return TEXT;
+    }
+
+    /**
+     * process quoted text
+     */
+    private Token quotedText(char quote) throws ScanException {
+        nextChar(); // eat the '"'
+        text = new StringBuilder();
+        while (c != quote) {
+            if (c == '\n') {
+                throw new ScanException("Unclosed quoted text, reached end of line.");
+            }
+            text.append(c);
+            nextChar();
+        }
+        nextChar(); // eat the '"'
+        return TEXT;
+    }
+
+    /**
+     * process notEquals !
+     */
+    private Token pipe() {
+        nextChar(); // eat !
+        if (c == '=') {
+            nextChar(); // eat =
+            return NOT_EQUALS;
+        }
+        return PIPE;
+    }
+
+    /**
+     * process white space
+     */
+    private Token whiteSpace() {
+        while ((c == ' ') || (c == '\t')) {
+            nextChar();
+        }
+        return WS;
+    }
+
+    /**
+     * return the next character from the line of text
+     */
+    private void nextChar() {
+        if (pos < line.length()) {
+            c = line.charAt(pos);
+            pos++;
+        } else {
+            c = '\n';
+        }
+    }
+
+    /**
+     * check if the character matches the give expression
+     */
+    private boolean in(char c, String cs) {
+        return ("" + c).matches(cs);
+    }
+
+    private final String line;
+    private int pos = 0;
+    private char c;
+    private StringBuilder text;
+}

src/main/java/me/legrange/mikrotik/impl/Util.java

@@ -4,6 +4,7 @@ import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
 import java.io.UnsupportedEncodingException;
+import java.nio.charset.Charset;
 import java.security.MessageDigest;
 import java.security.NoSuchAlgorithmException;
 import java.util.List;
@@ -71,7 +72,7 @@ final class Util {
                     }
                     buf[i] = (byte) (c & 0xFF);
                 }
-                String res = new String(buf);
+                String res = new String(buf, Charset.forName("UTF-8"));
                 if (result.length() > 0) {
                     result.append("\n");
                 }
@@ -121,11 +122,11 @@ final class Util {
      * @return - converted string.
      */
     static String hexStrToStr(String s) {
-        String ret = "";
+        StringBuilder ret = new StringBuilder();
         for (int i = 0; i < s.length(); i += 2) {
-            ret += (char) Integer.parseInt(s.substring(i, i + 2), 16);
+            ret.append((char) Integer.parseInt(s.substring(i, i + 2), 16));
         }
-        return ret;
+        return ret.toString();
     }
 
     /**
@@ -133,7 +134,7 @@ final class Util {
      * stream.
      */
     private static void encode(String word, OutputStream out) throws UnsupportedEncodingException, IOException {
-        byte bytes[] = word.getBytes("US-ASCII");
+        byte bytes[] = word.getBytes("UTF-8");
         int len = bytes.length;
         if (len < 0x80) {
             out.write(len);