Merge pull request #38 from jui8wang/readme

Readme

Author: krdev

README.md

@@ -1,45 +1,107 @@
 
 
-# IMAP NIO client in Java
-Java IMAP nio client that is designed to scale well for thousands of connections per machine and reduce contention when using large number of threads and cpus.
+# imapnio
+A Java library that supports NIO (Non-blocking I/O) based IMAP clients.
+
+The IMAP NIO client provides a framework to access an IMAP message store using None-blocking I/O mechanism.  This design scales well for thousands of connections per machine and reduces contention when using a large number of threads and CPUs.
 
 
 ## Table of Contents
 
+- [Background](#background)
 - [Install](#install)
 - [Usage](#usage)
 - [Contribute](#contribute)
 - [License](#license)
 
+
+## Background
+
+The traditional accessing IMAP message store uses [JavaMail API](https://www.oracle.com/technetwork/java/javamail/index.html), which requires a blocking I/O. In this case, threads are blocked when performing I/O with the other end. This project was developed to relieve the waiting thread to perform other tasks, and it's design efficiently improves thread utilization to maximize hardware throughput and capacity.
+
+Some of the more distinguishing features of this library are:
+- Highly customizable thread model and server/client idle max limit.
+- Leverages the well-established framework [Netty](https://netty.io/)
+- Future-based design enables a clean separation of IMAP client threads pool versus consumers threads pool. 
+- IMAPv4, [RFC3501](https://tools.ietf.org/html/rfc3501) support.
+- ID command, [RFC2971](https://tools.ietf.org/html/rfc2971) support.
+- IDLE command, [RFC2177](https://tools.ietf.org/html/rfc2177) support
+- MOVE command, [RFC6851](https://tools.ietf.org/html/rfc6851) support
+- UNSELECT command, [RFC3691](https://tools.ietf.org/html/rfc3691) support
+
+This project is ideal for applications that have a high requirement to optimize thread utilization and improve overall resource capacity. Specifically, this is best for situations where users perform a very high level of sessions and communication with the IMAP server.
+ 
 ## Install
 
-This is packaged as a java library and can be imported as maven or gradle dependency in your project. There are no special installation instructions.
-$ mvn clean install
+This is a Java library. After downloading it, compile it using `mvn clean install`
 
-- For contibutors run deploy to do a push to nexus servers
-$ mvn clean deploy -Dgpg.passphrase=[pathPhrase]
+Then, update your project's pom.xml file dependencies, as follows:
+```
+  <dependency>
+      <groupId>com.github.krdev.imapnio</groupId>
+      <artifactId>imapnio.core</artifactId>
+      <version>1.0.23</version>
+  </dependency>
+```
+Finally, import the relevant classes and use this library according to the usage section below.
 
+- For contributors run deploy to do a push to nexus servers
+```
+$ mvn clean deploy -Dgpg.passphrase=[pathPhrase]
+```
 
 ## Usage
 
-Compile and use it as a regular IMAP client.
+The following code examples demonstrate basic functionality relate to connecting to and communicating with IMAP servers.
+
+### Create a client
+```java
+  // Create a IMAPClient instance with number of threads to handle the server requests
+  final int numOfThreadsServed = 5;
+  final IMAPClient imapClient = new IMAPClient(numOfThreadsServed);
+```
+### Establish a session with an IMAP server
+```java
+  // Create a new session via the imap client created above and connect to that server.  For the illustration purpose, 
+  // "imaps://imap.server.com:993" is used
+  final IMAPSession session = imapClient.createSession(new URI("imaps://imap.server.com:993"), new GenericListener(), new LogManager());
+  // connect to the remote server
+  session.connect();
+```
+
+### Execute the IMAP command to IMAP server
+Following codes uses a Capability command as an example.
+
+```java
+  // Instantiates your own IMAPCommandListener instance
+  final IMAPCommandListener listener = new MyOwnIMAPCommandListener();
+  // fire CAPABILITY command with the tag name you want to track
+  final String tagName = "A0001";
+  session.executeCapabilityCommand(tagName, listener);
+```
+
+### Handle the response from IMAP server
+onMessage() method will be called on the registered IMAPCommandListener.  
+Following example shows how to read IMAPResponse sent from the server.
 
 ```java
-    // Create a new session
-    final IMAPSession session = theClient.createSession(new URI("imaps://imap.server.com:993"), new GenericListener(), logManager);
-    // connect to the remote server
-    session.connect();
-    // fire OAUTH2 command
-    session.executeOAuth2Command(...);
+  @Override
+  public void onMessage(final IMAPSession session, final IMAPResponse response) {
+    System.out.println("Response from IMAPServer is==>tag:" + response.getTag() + ",getRest():"
+        + response.getRest() + ",toString():" + response.toString());
+  }
 ```
 
+
 ## Contribute
 
 Please refer to the [contributing.md](Contributing.md) for information about how to get involved. We welcome issues, questions, and pull requests. Pull Requests are welcome.
 
+
 ## Maintainers
 
-Luis Alves: (lafa at verizonmedia.com)
+Luis Alves: lafa@verizonmedia.com
+
 
 ## License