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/
 
@@ -30,16 +11,17 @@ nbactions.xml
 
 # IntelliJ
 .idea/
+*.iml
 
 # Eclipse
 .settings/
 
-# Project 
-Mtik.java
-
-# Jekyll 
-_site/
-
 .classpath
 
 .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,82 +1,119 @@
-mikrotik-java
-=============
+# mikrotik-java 
 
 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.
 
-Versions
---------
+## Versions
 
-This library uses [semantic versioning](http://semver.org/)
+![Java CI with Maven](https://github.com/GideonLeGrange/mikrotik-java/workflows/Java%20CI%20with%20Maven/badge.svg)
 
-The current stable version is 2.0.2. 
+**The current stable version is 3.0.8**
 
-* Fixed bug #13 - processor thread wasn't being stopped on disconnect(), causing non-exit of application in some cases. 
+Version 3.0.8 fixes a null pointer error 
 
-Previous 2.0 versions:
+### Changes in version 3.0:
 
-* 2.0.1 fixed parsing of !=, < and > operators in a where clause. 
-* 2.0.0 changed ResultListener to receive errors and completion notifications. This version is not backwards compatible with version 1.x. 
+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.
 
-Previous 1.1 versions:
+Further changes include:
+* The previously deprecated `disconnect()` method is removed. 
 
-* 1.1.5 fixed even more comamnd line parsing bugs.
-* 1.1.4 fixed command line parsing bugs #7 and #8.
-* 1.1.3 fixed severe command line parsing bugs, #3, #4 and #5.
-* 1.1.2 added support for handling multi-line results, like for example /file print. 
-* 1.1 added TLS (SSL) support to encrypt API traffic. 
+#### Versions 1.x and 2.x
 
-The latest development version is 2.0.0 which is available using the 2.0.0 branch. 
+Versions 1 and 2 are considered *obsolete* and will no longer be supported or patched. 
 
+## Getting the API
 
-Getting the API
----------------
+Maven users can use the artifact from Maven Central with this dependency:
 
-You can clone or fork the repository. Alternatively, you can get the jar from Maven Central.
+```xml
+<dependency>
+  <groupId>me.legrange</groupId>
+  <artifactId>mikrotik</artifactId>
+  <version>3.0.8</version>
+</dependency>
+```
 
-Contributing
-------------
+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)
 
-I welcome contributions, be it bug fixes or other improvements. If you fix or change something, please submit a pull request. If you want to report a bug, please open an issue. 
+## Asking for help or contributing
 
+I welcome contributions, be it bug fixes or other improvements. 
 
-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.
+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
 ```
-If your router does not use the default API port, the port can be specified when connecting: 
+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("10.0.1.1", 1337); // connect to router on port 1337
+ApiConnection con = ApiConnection.connect(SSLSocketFactory.getDefault(), "10.0.1.1", ApiConnection.DEFAULT_TLS_PORT, ApiConnection.DEFAULT_CONNECTION_TIMEOUT);
 ```
 
-To open an encrypted (TLS) connection is as simple, assuming the default API-SSL port is used:
+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.connectTLS("10.0.1.1"); // connect to router using TLS
+   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
 ```	
 
-#### Notes about TLS: 
-* Currently only anonymous TLS is supported, not certificates. 
-* There is a compatibility problem between the current versions of RouterOS supporting API over TLS and the Java Cryptography Extension (JCE) in Java 7 and earlier. TLS encryption works in Java 8 and later. For more information, feel free to contact me. 
+### 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 
 
-In following examples the connection, login and disconnection code will not be repeated. 
+The API can also be used in a "try with resources" statement which will ensure that the connection is closed:
 
-Reading data 
-------------
+```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");
+        }
+```
 
-A simple example that returns a result: Print all interfaces.
+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
@@ -104,14 +141,13 @@ List<Map<String, String>> rs = con.execute("/interface/print where type=vlan");
 
 ### 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.
+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");
 ```
 
-Writing data 
-------------
+## Writing data 
 
 Creating, modifying and deleting configuration objects is of course possible.
 
@@ -139,8 +175,20 @@ And now remove the object:
 con.execute("/interface/gre/remove .id=gre1"); 
 ```
 
-Asynchronous commands
----------------------
+### 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:
 
@@ -166,21 +214,37 @@ String tag = con.execute("/interface/wireless/monitor .id=wlan1 return signal-to
   );
 ```
 
+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);
 ```
 
-From version 2.0.0 of the API the error() and completed() methods are part of the ResultListener interface. 
+## Command timeouts
 
-References
-==========
+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:
+
+```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. 
+
+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](LICENCE.md) file
 

pom.xml

@@ -1,17 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
 <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>2.0.2</version>
+  <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> 
@@ -34,11 +33,10 @@
         <version>2.3.2</version>  
         <configuration> 
           <showDeprecation>true</showDeprecation>  
-                    <source>1.7</source>
-                    <target>1.7</target>
+          <source>8</source>  
+          <target>8</target> 
         </configuration> 
       </plugin>  
-            
       <plugin> 
         <groupId>org.apache.maven.plugins</groupId>  
         <artifactId>maven-jar-plugin</artifactId>  
@@ -75,7 +73,7 @@
       <plugin> 
         <groupId>org.apache.maven.plugins</groupId>  
         <artifactId>maven-javadoc-plugin</artifactId>  
-                <version>2.9.1</version>
+        <version>3.7.0</version>  
         <configuration> 
           <excludePackageNames>example;*.impl</excludePackageNames> 
         </configuration>  
@@ -88,16 +86,45 @@
           </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.5</version>
+            <version>1.6</version>  
             <executions> 
               <execution> 
-                        <configuration>
-                            <keyname>8D1FA6CF</keyname>
-                        </configuration>
                 <id>sign-artifacts</id>  
                 <phase>verify</phase>  
                 <goals> 
@@ -109,27 +136,33 @@
           <plugin> 
             <groupId>org.sonatype.plugins</groupId>  
             <artifactId>nexus-staging-maven-plugin</artifactId>  
-                <version>1.6.2</version>
+            <version>1.6.5</version>  
             <extensions>true</extensions>  
             <configuration> 
-                    <serverId>sonatype-nexus-staging</serverId>
+              <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>3.8.1</version>
+      <version>4.13.1</version>  
       <scope>test</scope> 
     </dependency>  
   </dependencies> 
 </project>
-

src/main/java/examples/AddAndModify.java

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

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,10 +9,10 @@ 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();

src/main/java/examples/AsyncWithErrorHandling.java

@@ -9,10 +9,10 @@ import me.legrange.mikrotik.ResultListener;
  *
  * @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();
@@ -23,6 +23,7 @@ public class Example5 extends Example {
        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.1.134";
-    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

@@ -9,10 +9,10 @@ import me.legrange.mikrotik.MikrotikApiException;
  *
  * @author gideon
  */
-public class Example7 extends Example {
+public class DownloadConfig extends Example {
 
     public static void main(String... args) throws Exception {
-        Example7 ex = new Example7();
+        DownloadConfig ex = new DownloadConfig();
         ex.connect();
         ex.test();
         ex.disconnect();
@@ -21,7 +21,7 @@ public class Example7 extends Example {
     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 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/Example8.java

@@ -1,28 +0,0 @@
-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 Example8 extends Example {
-
-    public static void main(String... args) throws Exception {
-        Example8 ex = new Example8();
-        ex.connect();
-        ex.test();
-        ex.disconnect();
-    }
-
-    private void test() throws MikrotikApiException, InterruptedException {
-       List<Map<String, String>> res = con.execute("/ip/hotspot/user/print where uptime!=1");
-        for (Map<String, String> r : res) {
-            System.out.println(r);
-        } 
-//        con.execute("/ip/firewall/filter/add chain=forward hotspot=!auth protocol=tcp src-port=8000-8084");
-    }
-}

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,50 +11,53 @@ import me.legrange.mikrotik.impl.ApiConnectionImpl;
  *
  * @author GideonLeGrange
  */
-public abstract class ApiConnection {
+public abstract class ApiConnection implements AutoCloseable {
 
     /**
-     * Create a new API connection to the give device on the supplied port, using anonymous TLS for encryption.
+     * 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.
+     * @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
+     * @throws me.legrange.mikrotik.MikrotikApiException Thrown if there is a
+     * problem connecting
+     * @since 3.0
      */
-    public static ApiConnection connectTLS(String host, int port) throws MikrotikApiException {
-        return ApiConnectionImpl.connect(host, port, true);
-    }
-    
-    
-    /**
-     * Create a new API connection to the give device on the default API port, using anonymous TLS for encryption. 
-     * @param host The host to which to connect.
-     * @return The ApiConnection 
-     * @throws me.legrange.mikrotik.MikrotikApiException Thrown if there is a problem connecting
-     */
-    public static ApiConnection connectTLS(String host) throws MikrotikApiException {
-        return ApiConnectionImpl.connect(host, DEFAULT_TLS_PORT, true);
-    }
-
-
-    /**
-     * Create a new API connection to the give device on the supplied port
-     * @param host The host to which to connect.
-     * @param port The TCP port to use.
-     * @return The ApiConnection 
-     * @throws me.legrange.mikrotik.MikrotikApiException Thrown if there is a problem connecting
-     */
-    public static ApiConnection connect(String host, int port) throws MikrotikApiException {
-        return ApiConnectionImpl.connect(host, port, false);
+    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.
+     *
      * @param host The host to which to connect.
      * @return The ApiConnection
-     * @throws me.legrange.mikrotik.MikrotikApiException Thrown if there is a problem connecting
+     * @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);
+        return connect(SocketFactory.getDefault(), host, DEFAULT_PORT, DEFAULT_COMMAND_TIMEOUT);
     }
 
     /**
@@ -63,46 +67,65 @@ public abstract class ApiConnection {
      */
     public abstract boolean isConnected();
 
-    /**
-     * Disconnect from the remote API
-     * @throws me.legrange.mikrotik.MikrotikApiException Thrown if there is a problem disconnecting
-     */
-    public abstract void disconnect() throws MikrotikApiException; 
-
     /**
      * 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
-     * @throws java.lang.InterruptedException
+     * @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
+     * @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 canceling the command */
+     * @throws me.legrange.mikrotik.MikrotikApiException Thrown if there is a
+     * problem cancelling the command
+     */
     public abstract void cancel(String tag) throws MikrotikApiException;
 
-    /** default TCP port used by Mikrotik API */
-    private static final int DEFAULT_PORT = 8728;
-    /** default TCP TLS port used by Mikrotik API */
-    private static final int DEFAULT_TLS_PORT = 8729;
+    /**
+     * 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/grammar.txt

@@ -1,12 +1,13 @@
 command  = action [ query ] [ return ]
 action   = ("/" word)+
 query    = "where" expr
-expr     = expr "and" expr | expr "or" expr | "not" expr | hasExpr | eqExpr | lessExpr | moreExpr | notExpr
+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

@@ -4,13 +4,19 @@ import me.legrange.mikrotik.MikrotikApiException;
 
 /**
  * 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. Null if there is no tag*/
+    /**
+     * 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;
     }
@@ -23,12 +29,15 @@ public class ApiCommandException extends MikrotikApiException {
         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

@@ -5,6 +5,7 @@ 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;
@@ -13,8 +14,8 @@ import java.util.List;
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.LinkedBlockingQueue;
-import javax.net.ssl.SSLSocket;
-import javax.net.ssl.SSLSocketFactory;
+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;
@@ -31,37 +32,71 @@ 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.
-     * @param secure Is TLS required
+     * @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, boolean secure) throws ApiConnectionException {
+    public static ApiConnection connect(SocketFactory fact, String host, int port, int timeOut) throws ApiConnectionException {
         ApiConnectionImpl con = new ApiConnectionImpl();
-        con.open(host, port, secure);
+        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
-     *
-     * @throws me.legrange.mikrotik.ApiConnectionException Thrown if there is a
-     * problem disconnecting
-     */
     @Override
-    public void disconnect() throws ApiConnectionException {
+    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"));
         }
@@ -69,69 +104,18 @@ public final class ApiConnectionImpl extends ApiConnection {
         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
-     * @throws me.legrange.mikrotik.MikrotikApiException
-     * @throws java.lang.InterruptedException
-     */
-    @Override
-    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(password.toCharArray()) + 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
-     * @throws me.legrange.mikrotik.MikrotikApiException
-     */
-    @Override
-    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
-     */
-    @Override
-    public String execute(String cmd, ResultListener lis) throws MikrotikApiException {
-        return execute(Parser.parse(cmd), lis);
-    }
-
-    /**
-     * cancel a command
-     * @param tag
-     * @throws me.legrange.mikrotik.MikrotikApiException Thrown if an error is experienced while canceling the 
-     */
-    @Override
-    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 {
@@ -152,24 +136,14 @@ public final class ApiConnectionImpl extends ApiConnection {
         this.listeners = new ConcurrentHashMap<>();
     }
 
-    /**
-     * Start the API. Connects to the Mikrotik without using encryption
-     */
-    private void open(String host, int port) throws ApiConnectionException {
-        open(host, port, false);
-    }
-
     /**
      * Start the API. Connects to the Mikrotik
      */
-    private void open(String host, int port, boolean secure) throws ApiConnectionException {
+    private void open(String host, int port, SocketFactory fact, int conTimeout) throws ApiConnectionException {
         try {
-            InetAddress ia = InetAddress.getByName(host);
-            if (secure) {
-                sock = openSSLSocket(ia, port);
-            } else {
-                sock = new Socket(ia, 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;
@@ -188,28 +162,10 @@ public final class ApiConnectionImpl extends ApiConnection {
         }
     }
 
-    /**
-     * open and configure a SSL socket.
-     */
-    private Socket openSSLSocket(InetAddress ia, int port) throws IOException {
-        SSLSocket ssl = (SSLSocket) SSLSocketFactory.getDefault().createSocket(ia, port);
-        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;
+    private synchronized String nextTag() {
+        return Integer.toHexString(_tag.incrementAndGet());
     }
 
-    private synchronized String nextTag() {
-        _tag++;
-        return Integer.toHexString(_tag);
-    }
-    private static final int DEFAULT_PORT = 8728;
     private Socket sock = null;
     private DataOutputStream out = null;
     private DataInputStream in = null;
@@ -217,15 +173,20 @@ public final class ApiConnectionImpl extends ApiConnection {
     private Reader reader;
     private Processor processor;
     private final Map<String, ResultListener> listeners;
-    private Integer _tag = 0;
+    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) {
@@ -248,18 +209,24 @@ 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) {
+                    put(ex);
+                } catch (ApiConnectionException ex) {
+                    if (connected || !sock.isClosed()) {
+                        put(ex);
+                    }
+                }
+            }
+        }
+
+        private void put(Object data) {
             try {
-                        queue.put(ex);
-                    } catch (InterruptedException ex2) {
-                    }
-                } catch (ApiConnectionException | InterruptedException ex) {
-                }
+                queue.put(data);
+            } catch (InterruptedException ignored) {
             }
         }
+
         private final LinkedBlockingQueue queue = new LinkedBlockingQueue(40);
     }
 
@@ -268,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) {
@@ -277,13 +248,14 @@ 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) {
                     continue;
                 }
+                if (res.getTag() != null) {
                     ResultListener l = listeners.get(res.getTag());
                     if (l != null) {
                         if (res instanceof Result) {
@@ -299,13 +271,16 @@ public final class ApiConnectionImpl extends ApiConnection {
                             l.error(new ApiCommandException((Error) res));
                         }
                     }
+                } else {
+                    nextTag();
+                }
             }
         }
 
         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);
@@ -315,6 +290,15 @@ 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();
@@ -322,12 +306,13 @@ public final class ApiConnectionImpl extends ApiConnection {
             switch (line) {
                 case "!re":
                     return unpackRe();
+                case "!empty":
                 case "!done":
                     return unpackDone();
                 case "!trap":
-                    return unpackError();
                 case "!halt":
                     return unpackError();
+                case "":
                 default:
                     throw new ApiDataException(String.format("Unexpected line '%s'", line));
             }
@@ -335,23 +320,27 @@ public final class ApiConnectionImpl extends ApiConnection {
 
         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) {
                         if (!parts[2].endsWith("\r")) {
-                            res.put(parts[1], parts[2]);
+                            res.put(parts[1], unpackResult(parts[2]));
                         } else {
-                            res.put(parts[1], unpackMultiLine(parts[2]));
+                            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]);
                     }
@@ -368,12 +357,20 @@ public final class ApiConnectionImpl extends ApiConnection {
             return res;
         }
 
-        private String unpackMultiLine(String head) throws ApiConnectionException, ApiDataException {
-            StringBuilder buf = new StringBuilder(head);
-            do {
+        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);
-            } while (line.endsWith("\r"));
+                } else {
+                    break;
+                }
+            }
             return buf.toString();
         }
 
@@ -384,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 {
@@ -413,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 {
@@ -431,34 +431,22 @@ 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 final List<String> lines = new LinkedList<>();
         private String line;
     }
 
-    private class SyncListener implements ResultListener {
+    private static class SyncListener implements ResultListener {
 
         @Override
         public synchronized void error(MikrotikApiException ex) {
             this.err = ex;
-            notify();
+            notifyAll();
         }
 
         @Override
         public synchronized void completed() {
-            notify();
+            complete = true;
+            notifyAll();
         }
 
         synchronized void completed(Done done) {
@@ -467,7 +455,8 @@ public final class ApiConnectionImpl extends ApiConnection {
                 res.put("ret", done.getHash());
                 results.add(res);
             }
-            notify();
+            complete = true;
+            notifyAll();
         }
 
         @Override
@@ -475,11 +464,17 @@ public final class ApiConnectionImpl extends ApiConnection {
             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();
+                    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) {
@@ -490,7 +485,9 @@ public final class ApiConnectionImpl extends ApiConnection {
             }
             return results;
         }
+
         private final List<Map<String, String>> results = new LinkedList<>();
         private MikrotikApiException err;
+        private boolean complete = false;
     }
 }

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

@@ -2,11 +2,15 @@ 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).
+ *
  * @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

@@ -3,21 +3,27 @@ package me.legrange.mikrotik.impl;
 import java.util.Arrays;
 import java.util.LinkedList;
 import java.util.List;
+
 import me.legrange.mikrotik.impl.Scanner.Token;
 
 /**
  * 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 {
         command();
         while (!is(Token.WHERE, Token.RETURN, Token.EOL)) {
@@ -67,8 +73,7 @@ class Parser {
                 next();
             }
             cmd.addParameter(new Parameter(name, val.toString()));
-        }
-        else {
+        } else {
             cmd.addParameter(new Parameter(name));
         }
     }
@@ -79,7 +84,7 @@ class Parser {
     }
 
     private void expr() throws ParseException {
-        expect(Token.NOT, Token.TEXT);
+        expect(Token.NOT, Token.TEXT, Token.LEFT_BRACKET);
         switch (token) {
             case NOT:
                 notExpr();
@@ -106,16 +111,29 @@ 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();
+            case OR:
+                orExpr();
                 break;
         }
     }
 
+    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();
@@ -175,7 +193,7 @@ class Parser {
             }
             next();
         }
-        cmd.addProperty(props.toArray(new String[]{}));
+        cmd.addProperty(props.toArray(new String[props.size()]));
     }
 
     private void expect(Token... tokens) throws ParseException {
@@ -190,7 +208,9 @@ class Parser {
         return false;
     }
 
-    /** move to the next token returned by the scanner */
+    /**
+     * move to the next token returned by the scanner
+     */
     private void next() throws ScanException {
         token = scanner.next();
         while (token == Token.WS) {

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

@@ -15,6 +15,7 @@
  */
 package me.legrange.mikrotik.impl;
 
+import java.util.Locale;
 import static me.legrange.mikrotik.impl.Scanner.Token.*;
 /**
  * A simple scanner.
@@ -27,6 +28,7 @@ class Scanner {
 
         SLASH("/"), COMMA(","), EOL(), WS, TEXT,
         LESS("<"), MORE(">"), EQUALS("="), NOT_EQUALS("!="), PIPE("!"),
+        LEFT_BRACKET("("), RIGHT_BRACKET(")"),
         WHERE, NOT, AND, OR, RETURN;
 
         @Override
@@ -79,6 +81,12 @@ class Scanner {
             case '=':
                 nextChar();
                 return EQUALS;
+            case '(' :
+                nextChar();
+                return LEFT_BRACKET;
+            case ')' :
+                nextChar();
+                return RIGHT_BRACKET;
             case '!':
                 return pipe();
             case '"':
@@ -113,11 +121,11 @@ class Scanner {
      */
     private Token name() throws ScanException {
         text = new StringBuilder();
-        while (!in(c, "[ \t\r\n=<>!]")) {
+        while (!in(c, "[ \t\r\n=<>!)]")) {
             text.append(c);
             nextChar();
         }
-        String val = text.toString().toLowerCase();
+        String val = text.toString().toLowerCase(Locale.getDefault());
         switch (val) {
             case "where":
                 return WHERE;
@@ -184,17 +192,6 @@ class Scanner {
         }
     }
 
-    /**
-     * look ahead one character
-     */
-    private char peek() {
-        if (pos < line.length()) {
-            return line.charAt(pos);
-        } else {
-            return '\n';
-        }
-    }
-
     /**
      * check if the character matches the give expression
      */

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);

src/test/java/me/legrange/mikrotik/ApiConnectionTest.java

@@ -1,31 +0,0 @@
-package me.legrange.mikrotik;
-
-import java.util.List;
-import java.util.Map;
-
-import junit.framework.TestCase;
-
-public class ApiConnectionTest extends TestCase {
-
-	private static final String HOSTNAME = "192.168.88.1";
-	private static final String ADMIN = "admin";
-	private static final String PASSWORD = "plasma";
-
-	public void testConnectTLSStringInt() throws MikrotikApiException, InterruptedException {
-/*		ApiConnection connect = ApiConnection.connectTLS(HOSTNAME, 8729);
-		connect.login(ADMIN, PASSWORD);
-		List<Map<String, String>> result = connect.execute("/system/resource/print");
-
-		assertEquals(1, result.size());
-		assertEquals("MikroTik", result.get(0).get("platform")); */
-	}
-
-	public void testConnectStringInt() throws MikrotikApiException, InterruptedException {
-/*		ApiConnection connect = ApiConnection.connect(HOSTNAME, 8728);
-		connect.login(ADMIN, PASSWORD);
-		List<Map<String, String>> result = connect.execute("/system/resource/print");
-
-		assertEquals(1, result.size());
-		assertEquals("MikroTik", result.get(0).get("platform")); */
-	}
-}