You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mina.apache.org by el...@apache.org on 2012/10/15 10:09:44 UTC
svn commit: r1398208 - in /mina/site/trunk/content/mina/userguide/ch1:
ch1.mdtext first_steps.mdtext nio_overview.mdtext why_mina.mdtext
Author: elecharny
Date: Mon Oct 15 08:09:44 2012
New Revision: 1398208
URL: http://svn.apache.org/viewvc?rev=1398208&view=rev
Log:
Augmented the content of the chapter one pages
Added:
mina/site/trunk/content/mina/userguide/ch1/why_mina.mdtext
Modified:
mina/site/trunk/content/mina/userguide/ch1/ch1.mdtext
mina/site/trunk/content/mina/userguide/ch1/first_steps.mdtext
mina/site/trunk/content/mina/userguide/ch1/nio_overview.mdtext
Modified: mina/site/trunk/content/mina/userguide/ch1/ch1.mdtext
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/mina/userguide/ch1/ch1.mdtext?rev=1398208&r1=1398207&r2=1398208&view=diff
==============================================================================
--- mina/site/trunk/content/mina/userguide/ch1/ch1.mdtext (original)
+++ mina/site/trunk/content/mina/userguide/ch1/ch1.mdtext Mon Oct 15 08:09:44 2012
@@ -18,8 +18,12 @@ Notice: Licensed to the Apache Softwa
# Chapter 1 - Getting Started
+In this chapter, we will give you first sense of what is **MINA**, what is **NIO**, why we developped a framework on top of **NIO** and what you will find inside.
+We will also show you how to run a very simple example of a server run with **MINA**
+
1. [NIO Overview](nio_overview.html)
-2. [Features](features.html)
-3. [First Steps](first_steps.html)
-4. [Summary](summary.html)
+1. [Why MINA ?](why_mina.html)
+1. [Features](features.html)
+1. [First Steps](first_steps.html)
+1. [Summary](summary.html)
Modified: mina/site/trunk/content/mina/userguide/ch1/first_steps.mdtext
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/mina/userguide/ch1/first_steps.mdtext?rev=1398208&r1=1398207&r2=1398208&view=diff
==============================================================================
--- mina/site/trunk/content/mina/userguide/ch1/first_steps.mdtext (original)
+++ mina/site/trunk/content/mina/userguide/ch1/first_steps.mdtext Mon Oct 15 08:09:44 2012
@@ -18,13 +18,25 @@ Notice: Licensed to the Apache Softwa
# First Steps
+We will show you how easy it is to use MINA, running a very simple example provided with the **MINA** package.
+
+The first thing you have to do is to setup your evnvironment when you want to use **MINA** in your application. We will describe what you need to install and how to run a **MINA** program. Nothing fancy, just a first taste of **MINA**...
+
## Download
-Download the latest MINA release from Downloads Section
+First, you have to download the latest **MINA** release from [Downloads Section](../../downloads.html). Just take the latest version, unless you have very good reasons not to do so...
+
+Generally speaking, if you are going to use **Maven** to build your project, you won't even have to download anything, as soon as you will depend on a repository which already contains the **MINA** libraries : you just tell your **Maven** poms that you want to use the **MINA** jars you need.
## What's inside
-After the download is complete, extract the content of tar.gz or zip file to local hard drive. The downloaded compressed file has following contents
+After the download is complete, extract the content of _tar.gz_ or _zip_ file to local hard drive. The downloaded compressed file has following contents
+
+On UNIX system, type :
+
+ $ tar xzpf apache-mina-2.0.7-tar.gz
+
+In the _apache-mina-2.0.7_ directory, you will get :
|
+- dist
@@ -40,31 +52,47 @@ After the download is complete, extract
## Content Details
-* _dist_ - Contains jars for the MINA library code
+* _dist_ - Contains jars for the **MINA** library code
* _docs_ - Contains API docs and Code xrefs
-* _lib_ - Contains all needed jars for all the libraries needed for using MINA
+* _lib_ - Contains all needed jars for all the libraries needed for using **MINA**
Additional to these, the base directory has couple of license and notice files
-# Running First MINA Program
+# Running your first MINA program
-Well, we have downloaded the release, lets run our first MINA example, shipped with the release.
+Well, we have downloaded the release, let's run our first **MINA** example, shipped with the release.
Put the following jars in the classpath
-* mina-core-2.0.0.jar
-* mina-example-2.0.0.jar
-* slf4j-api-1.5.11.jar
-* slf4j-log4j12-1.5.0.jar
-* log4j-1.2.15.jar
-
-<DIV class="panelMacro"><TABLE class="tipMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD><B>Logging Tip</B><BR>Log4J 1.2 users: slf4j-api.jar, slf4j-log4j12.jar, and Log4J 1.2.x<BR>
-Log4J 1.3 users: slf4j-api.jar, slf4j-log4j13.jar, and Log4J 1.3.x<BR>
-java.util.logging users: slf4j-api.jar and slf4j-jdk14.jar<BR>
-IMPORTANT: Please make sure you are using the right slf4j-*.jar that matches to your logging framework.<BR>
-For instance, slf4j-log4j12.jar and log4j-1.3.x.jar can not be used together, and will malfunction.<BR>
-If you don't need a logging framework you can use slf4j-nop.jar for no logging or slf4j-simple.jar for<BR>
-very basic logging.</TD></TR></TABLE></DIV>
+* mina-core-2.0.7.jar
+* mina-example-2.0.7.jar
+* slf4j-api-1.6.6.jar
+* slf4j-log4j12-1.6.6.jar
+* log4j-1.2.17.jar
+
+<DIV class="panelMacro">
+ <TABLE class="tipMacro">
+ <COLGROUP>
+ <COL width="24">
+ <COL>
+ </COLGROUP>
+ <TR>
+ <TD valign="top">
+ <IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0">
+ </TD>
+ <TD>
+ <B>Logging Tip</B><BR>
+ Log4J 1.2 users: slf4j-api.jar, slf4j-log4j12.jar, and Log4J 1.2.x<BR>
+ Log4J 1.3 users: slf4j-api.jar, slf4j-log4j13.jar, and Log4J 1.3.x<BR>
+ java.util.logging users: slf4j-api.jar and slf4j-jdk14.jar<BR>
+ IMPORTANT: Please make sure you are using the right slf4j-*.jar that matches to your logging framework.<BR>
+ For instance, slf4j-log4j12.jar and log4j-1.3.x.jar can not be used together, and will malfunction.<BR>
+ If you don't need a logging framework you can use slf4j-nop.jar for no logging or slf4j-simple.jar for<BR>
+ very basic logging.
+ </TD>
+ </TR>
+ </TABLE>
+</DIV>
On the command prompt, issue the following command :
@@ -76,4 +104,4 @@ Issue following command to telnet
telnet 127.0.0.1 9123
-Well, we have run our first MINA program. Please try other sample programs shipped with MINA as examples.
+Well, we have run our first **MINA** program. Please try other sample programs shipped with **MINA** as examples.
Modified: mina/site/trunk/content/mina/userguide/ch1/nio_overview.mdtext
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/mina/userguide/ch1/nio_overview.mdtext?rev=1398208&r1=1398207&r2=1398208&view=diff
==============================================================================
--- mina/site/trunk/content/mina/userguide/ch1/nio_overview.mdtext (original)
+++ mina/site/trunk/content/mina/userguide/ch1/nio_overview.mdtext Mon Oct 15 08:09:44 2012
@@ -18,7 +18,7 @@ Notice: Licensed to the Apache Softwa
# NIO Overview
-NIO API's were introduced in Java 1.4 and had since been used for wide number of applications. NIO API's allows IO operations without blocking the processing with it.
+**NIO** _API_'s were introduced in **Java 1.4** and had since been used for wide number of applications. **NIO** _API_'s allows **IO** operations without blocking the processing with it.
The `java.nio.*` package contains following key constructs
Added: mina/site/trunk/content/mina/userguide/ch1/why_mina.mdtext
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/mina/userguide/ch1/why_mina.mdtext?rev=1398208&view=auto
==============================================================================
--- mina/site/trunk/content/mina/userguide/ch1/why_mina.mdtext (added)
+++ mina/site/trunk/content/mina/userguide/ch1/why_mina.mdtext Mon Oct 15 08:09:44 2012
@@ -0,0 +1,52 @@
+Title: Why MINA
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+# Why MINA ?
+
+Writing some network application is generrally seen as a burden, and a low level development. It's a area which is not frequently studied or known by developpers, either because it has ben studied in school a long time ago and everything has been forgotten, or because the complexity of this network layer is frequently hidden by higher level layers, so you never get deep into it.
+
+Add that when it comes to asynchronous IO, an extra layer of complexity comes into play : time.
+
+The big difference between **BIO** (Blocking IO) and **NIO** (Non-Blocking IO) is that in **BIO**, you send a request, and you wait until you get the response. On the server side, it means one thread wil be associated with any incoming connection, so you won't have to deal with the complexity of multiplexing the connections. In **NIO**, on the other hand, you have to deal with the synchronous nature of a non-blocking system, wich means that your application will be invoked when some events occur. In **NIO**, you don't call and wait for a result, you send a command and you are informed when the result is ready.
+
+## The need of a framework
+
+Considering those differences, and teh fact that most of the applications are usually expecting a blocking mode when invoking the network layer, the best solution is to hide this aspect by writing a framework that mimic a blocking mode. This is what **MINA** does !
+
+But **MINA** does more. It provides a common IO vision to an application that needs to communicate over **TCP**, **UDP** or whatever mechanism. If we consider only **TCP** and **UDP**, one is a connected protocol (**TCP**) when the other one is connectionless (**UDP**). **MINA** masks this difference, and make you focus on the two parts that are important for your application : the applicive code and the application protocol encoding/decoding.
+
+**MINA** does not only handles **TCP** and **UDP**, it's also offering a layer on top of serial communication (**RSC232**), over **VmpPipe** or **APR**.
+
+Last, not least, **MINA** is a network framework that has been specifically designed to work either on the client side and on teh server side. Writing a server make it critical to have a scalable system, which is tunnable to fit the server needs, in term of performance and memory usage : this is what **MINA** is good for, still making it easy to devlop you server.
+
+## When to use MINA ?
+
+This is a intersting question ! **MINA** does not expect to be the best possible choice in any case. There are a few elements to consider when considering using **MINA**. Let's list them :
+
+ * Ease of use
+ When you have no special performance requirements, **MINA** is probably a good choice as it allows you to dvelop a server or a client easily, without having to deal with the various parameters and use cases to handle when writing the same application on top of **BIO** or **NIO**. You can probably write your server with a few tens of lines, and there are a few pitfalls in which you are likely to fall
+
+ * A high number of connected users
+ **BIO** is definitively faster that **NIO**. The difference is something like 30% in favor of **BIO**. This is true for up to a few thousands of connected users, but up to a point, the **BIO** approach just stop scaling : you won't e able to handle millions of connected users using one thread per user ! **NIO** can. Now, one other aspect is that the time spent in the **MINA** part of your code is probably non significant, compared to whatever your application will consumme. At some point, it's probably not worthful to spend many times more energy writing a faster network layer on your own for a gain which will be barely noticable.
+
+ * A proven system
+ **MINA** is used by tens of applications all over the world. There are some *Apache* projects based on **MINA**, and they are working pretty well. This is some kind of guarantee that ypu won't have to spend hours on some cryptic errors in your own implementation of the network layer.
+
+ * Existing supportd protocols
+ **MINA** comes with various implemented existing protocols : HTTP, XML, TCP, LDAP, DHCP, NTP, DNS, XMPP, SSH, FTP... At some point, **MINA** can be seen not only as a **NIO** framework, but as a network layer with some protocol implementation. One of **MINA** feature in the near future is to offer a collection of existing protocol you can use.
+