Table of Contents
- Table of Contents
- Can MINA...?
- Can I use MINA to create client (or server) applications?
- Can MINA handle text protocols such as HTTP?
- Can MINA handle complex binary protocols such as LDAP?
- Can I implement protocols that keeps connection alive with MINA?
- Does MINA support SSL/TLS and SASL out-of-the-box?
- Do I need to make my IoHandler thread-safe?
- What transport types can MINA support except TCP/IP and UDP/IP?
- Does MINA support multicast?
- How do I...?
- How can I store session-specific information?
- How can I separate an event handler into multiple handlers when I implement complex business logic?
- How do I close my sessions and dispose my Connector?
- How can I reconnect to server after my client session is closed?
- When should I implement my protocol handler using filters?
- How can I detect when the remote peer doesn't send a response message for my request message?
- How can I let MINA log messages using my favorite logging framework (i.e. Log4J)?
- I get OutOfMemoryError or response timeout and connection reset under heavy load.
- No data is writtin out to the session even if the buffer is not empty.
- I created an SSL client with MINA, but it doesn't initiate any handshake after the session is open.
- Why does SocketConnector send several messages as one message?
- I get InvalidClassChangeError.
- My server fails with java.net.SocketException: Too many files open
What does MINA mean?
- an acronym for 'Multipurpose Infrastructure for Network Applications'
- A girl's name
- 'South' in Japanese
- 'Mine' (as in mineshaft) in Spanish and Portuguese
- Look at here for more meanings.
What transport does MINA support?
MINA currently supports TCP and UDP based on Java NIO API, provides support for serial port communication, and transports based on Apache Portable Runtime.
How does MINA perform?
Which version of MINA should I use?
Use the latest point-release of 1.0 (for Java 1.4) or 2.0 (for Java 5 or above). 1.0 and 1.1 aren't maintained anymore, unless someone propose some patches.
What is required to build/run MINA?
JDK 1.5 or above is required to build MINA. But MINA runs perfect with JDK 1.4 only if you don't use SSLFilter which uses Java 5 SSLEngine. This means JDK 1.5 or above is required for you to use SSL with MINA.
MINA core module depends on two libraries, SLF4J and backport-util-concurrent (for 1.0):
SLF4J (Simple Logging Facade for Java), a logging framework from the author of Log4J. SLF4J is very similar to Commons-Logging, but it doesn't cause any class loader issues at all. SLF4J provides bindings for Log4J, JDK 1.4 logging API, and NLog4J. Please put an appropriate SLF4J JAR file which corresponds to your favorite logging framework to the classpath as SLF4J documentation explains.
backport-util-concurrent is a backport implementation of
java.util.concurrent package which was introduced in JDK 1.5. MINA 1.0 uses it to retain the runtime compatibility with JDK 1.4. Please note that MINA 1.1 or above depends on
java.util.concurrent package directly, and therefore doesn't depend on it anymore.
How can I get help?
How / What can I contribute?
You can contribute anything related with MINA; examples, useful codecs for existing protocols, tutorials, feature improvements, bug fixes, benchmarks, and whatever. Please contact us without hesitation.
Can I use MINA to create client (or server) applications?
Yes. You can create both client and server applications with MINA. Please take a look at
Can MINA handle text protocols such as HTTP?
Can MINA handle complex binary protocols such as LDAP?
Yes. Please take a look at the SumUp example. There is no full ASN.1 support yet, but we will implement it someday and you can contribute to make it available sooner.
Can I implement protocols that keeps connection alive with MINA?
Yes. MINA doesn't close any connections unless you called
IoSession.close() or connection is closed by the remote peer.
Does MINA support SSL/TLS and SASL out-of-the-box?
We support SSL/TLS out-of-the-box. Please refer to
SSLFilter. It also provides a way to implement
StartTLS. JDK 1.5 provides complete SASL support which works well with MINA.
Do I need to make my IoHandler thread-safe?
It depends on your implementation. If you access the resource which is shared across multiple sessions, you have to make it thread-safe. If the resource is not shared at all and accessed by only one session (e.g. storing context information as a session attribute), then you don't need to make it thread-safe. It is because all events generated by MINA are transmitted to your handler in order (when using the Executor Filter), and the newer event is not processed if the event handler method for the older event for the same session hasn't returned yet.
What transport types can MINA support except TCP/IP and UDP/IP?
Virtually all kind of transport types. MINA API is designed to be transport-independent. You can implement any transport type support only if you can conform to MINA API. Support for Pre-1.4 I/O (aka BIO), reliable multicast, Java Communications API, and file I/O are planned.
Does MINA support multicast?
Not yet. Java NIO doesn't support multicast yet. Multicast for NIO will be available in Java SE 7, Dolphin. We are seriously considering to implement multicasts using pre-1.4 Java API.
How do I...?
How can I store session-specific information?
Sessions are capable of custom attributes that you can add or remove at any time. These custom attributes are not shared between sessions; it is designed to store session specific information.
How can I separate an event handler into multiple handlers when I implement complex business logic?
Please refer to
How do I close my sessions and dispose my Connector?
You have to do it in two steps : first close your sessions, then dispose the connector. Of course, if you dispose your Connector first, then all the sessions will be closed. Here is the code :
How can I reconnect to server after my client session is closed?
Here is an example code:
Possibly it would be better to extract this code to a method like 'reconnect()' so that it can reusable in more than one place.
When should I implement my protocol handler using filters?
IoFilter is usually considered reusable just like we think about Servlet filters. Please implement commonly used business logic such as authorization and logging as a filter. In case you implement just complex multi-layer protocols like Kerberos, you could consider using
How can I detect when the remote peer doesn't send a response message for my request message?
You can't use
sessionIdle event simply here. You'll have to use
java.util.concurrent.ScheduledExecutor (or OpenSymphony Quartz as an alternative). Schedule a timeout task to be executed on timeout situation for each request message, and cancel it when you receive the corresponding response message.
How can I let MINA log messages using my favorite logging framework (i.e. Log4J)?
Please refer to 'Swapping implementations at deployment time' section in the SLF4J Manual.
OutOfMemoryError or response timeout and connection reset under heavy load.
We recommend to switch the default buffer type to 'heap' by inserting the following code before you start a server:
If you prefer direct buffers to heap buffers, JVM might have ran out of direct memory. Please try increasing maximum direct memory size using
-XX:MaxDirectMemorySize option (e.g.
No data is writtin out to the session even if the buffer is not empty.
Please make sure if you called
ByteBuffer.flip() to flip the buffer before writing the buffer out. It is a common mistake NIO beginners make.
I created an SSL client with MINA, but it doesn't initiate any handshake after the session is open.
Please make sure you called
SSLFilter.setUseClientMode(true) before you initiate a connection. Server developers will also have to disconnect users who doesn't initiate SSL handshake by setting
IoSession.readerIdleTime and closing the session in
Why does SocketConnector send several messages as one message?
For example, I tried using SocketConnector to send "abc" and "def", but it sent "abcdef". Is it a MINA bug?
No, this is due to your OS trying to send packets more efficiently (see http://en.wikipedia.org/wiki/Nagle_algorithm). You can enable/disable Nagle's algorithm by a call to SocketSessionConfig.setTcpNoDelay(), e.g.:
However, even if you do this you cannot expect one session.write(bytes) in MINA to correspond to one TCP packet on your network. You should probably implement your own MINA ProtocolDecoder to handle the assembly of incoming bytes into message objects. The TextLineCodec is a good start if the protocol you're implementing is based on text lines. For a more advanced example have a look at the SumUp example in the MINA distribution.
Please make sure if you are using the appropriate SLF4J version. You will get
InvalidClassChangeError if you are using outdated SLF4J release.
My server fails with java.net.SocketException: Too many files open
Network sockets are treated like files and your operating system has a limit to the number of file handles it can manage. Running out of file handles is usually due to a large number of clients connecting and disconnecting frequently. As specified by TCP, after being closed sockets remain in the TIME_WAIT state for some additional time. The reason is to ensure that delayed packets arrive on the correct socket. In Windows, the default TIME_WAIT timeout is 4 minutes, in Linux it is 60 seconds.
Change the timeout in Windows
- Run regedit to start the Registry Editor
- Locate the following key: HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\tcpip\Parameters
- Add a new value named TcpTimedWaitDelay asa decimal and set the desired timeout in seconds (30-300)
Change the timeout in Linux
- Update the configuration value by running (30 seconds used in the example)
- Restart the networking component, for example by running