or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

async-operations.md buffer-management.md filter-chain.md index.md protocol-codecs.md service-abstractions.md session-management.md transport-layer.md

tile.json

tessl/maven-org-apache-mina--mina-core

Apache MINA Core is a network application framework for building high-performance, scalable network applications with event-driven, asynchronous I/O over various transports including TCP/IP and UDP/IP via Java NIO.

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:maven/org.apache.mina/mina-core@2.2.x

To install, run

npx @tessl/cli install tessl/maven-org-apache-mina--mina-core@2.2.0

Apache MINA Core 2.2.4

Apache MINA Core is a network application framework that helps developers create high-performance and scalable network applications. It provides a unified API for various transports such as TCP/IP and UDP/IP via Java NIO.

Package Information

Maven Dependency:

<dependency>
    <groupId>org.apache.mina</groupId>
    <artifactId>mina-core</artifactId>
    <version>2.2.4</version>
</dependency>

Java Requirements: Java 8+

Core Imports

// Core service abstractions
import org.apache.mina.core.service.IoAcceptor;
import org.apache.mina.core.service.IoConnector;
import org.apache.mina.core.service.IoHandler;
import org.apache.mina.core.service.IoHandlerAdapter;

// Session management
import org.apache.mina.core.session.IoSession;
import org.apache.mina.core.session.IoSessionConfig;

// Transport implementations
import org.apache.mina.transport.socket.nio.NioSocketAcceptor;
import org.apache.mina.transport.socket.nio.NioSocketConnector;
import org.apache.mina.transport.socket.nio.NioDatagramAcceptor;
import org.apache.mina.transport.socket.nio.NioDatagramConnector;

// Filters and filter chain
import org.apache.mina.core.filterchain.DefaultIoFilterChainBuilder;
import org.apache.mina.filter.codec.ProtocolCodecFilter;
import org.apache.mina.filter.logging.LoggingFilter;

// Async operations
import org.apache.mina.core.future.ConnectFuture;
import org.apache.mina.core.future.WriteFuture;

// Buffer management
import org.apache.mina.core.buffer.IoBuffer;

// Network addresses
import java.net.InetSocketAddress;

Basic Usage

Creating a TCP Server

// Create acceptor for incoming connections
IoAcceptor acceptor = new NioSocketAcceptor();

// Add logging filter for debugging
acceptor.getFilterChain().addLast("logger", new LoggingFilter());

// Set the handler that will process incoming messages
acceptor.setHandler(new IoHandlerAdapter() {
    @Override
    public void sessionOpened(IoSession session) throws Exception {
        System.out.println("Session opened: " + session.getRemoteAddress());
    }

    @Override
    public void messageReceived(IoSession session, Object message) throws Exception {
        // Echo received message back to client
        session.write(message);
    }

    @Override
    public void exceptionCaught(IoSession session, Throwable cause) throws Exception {
        cause.printStackTrace();
        session.closeNow();
    }
});

// Bind to port 8080 and start accepting connections
acceptor.bind(new InetSocketAddress(8080));
System.out.println("Server started on port 8080");

Creating a TCP Client

// Create connector for outgoing connections
IoConnector connector = new NioSocketConnector();

// Add logging filter
connector.getFilterChain().addLast("logger", new LoggingFilter());

// Set the handler for client-side processing
connector.setHandler(new IoHandlerAdapter() {
    @Override
    public void sessionOpened(IoSession session) throws Exception {
        System.out.println("Connected to server");
        // Send a message to the server
        session.write(IoBuffer.wrap("Hello Server!".getBytes()));
    }

    @Override
    public void messageReceived(IoSession session, Object message) throws Exception {
        IoBuffer buffer = (IoBuffer) message;
        System.out.println("Received: " + new String(buffer.array()));
        session.closeNow();
    }
});

// Connect to the server
ConnectFuture future = connector.connect(new InetSocketAddress("localhost", 8080));
future.awaitUninterruptibly();

if (future.isConnected()) {
    System.out.println("Connection established");
    IoSession session = future.getSession();
    // Session is ready for communication
}

Architecture

Apache MINA Core follows a modular, filter-based architecture:

Application Layer
        ↕
   IoHandler
        ↕
  Filter Chain → [Filter1] → [Filter2] → [CodecFilter] → [LoggingFilter]
        ↕
   IoService (Acceptor/Connector)
        ↕
   IoSession
        ↕
  Transport Layer (TCP/UDP/VM Pipe)

Key Components:

IoService: Base abstraction for acceptors and connectors
IoSession: Represents a connection between two endpoints
IoHandler: Application logic for handling I/O events
IoFilter: Intercepts and processes I/O events (similar to servlet filters)
IoBuffer: MINA's enhanced ByteBuffer implementation
Transport: Pluggable transport implementations (NIO Socket, Datagram, VM Pipe)

Capabilities

Session Management

Comprehensive session lifecycle management with attributes and idle detection:

// Session lifecycle events
public class SessionHandler extends IoHandlerAdapter {
    @Override
    public void sessionCreated(IoSession session) throws Exception {
        // Set session attributes
        session.setAttribute("startTime", System.currentTimeMillis());
    }

    @Override
    public void sessionOpened(IoSession session) throws Exception {
        // Configure session-specific settings
        session.getConfig().setReadBufferSize(2048);
        session.getConfig().setIdleTime(IdleStatus.BOTH_IDLE, 10);
    }

    @Override
    public void sessionIdle(IoSession session, IdleStatus status) throws Exception {
        // Handle idle sessions (timeout management)
        if (status == IdleStatus.BOTH_IDLE) {
            session.closeNow();
        }
    }
}

Service Abstractions

Unified API for acceptors and connectors with comprehensive lifecycle management:

// Acceptor configuration and management
NioSocketAcceptor acceptor = new NioSocketAcceptor();
acceptor.setReuseAddress(true);
acceptor.getSessionConfig().setReadBufferSize(2048);
acceptor.getSessionConfig().setIdleTime(IdleStatus.BOTH_IDLE, 10);

// Bind to multiple addresses
acceptor.bind(new InetSocketAddress(8080));
acceptor.bind(new InetSocketAddress(8443));

// Service statistics and management
IoServiceStatistics stats = acceptor.getStatistics();
long totalSessions = stats.getCumulativeManagedSessionCount();

Filter Chain

Powerful filter-based processing pipeline for request/response handling:

// Building filter chains
DefaultIoFilterChainBuilder chain = acceptor.getFilterChain();

// Add built-in filters
chain.addLast("ssl", new SslFilter(sslContext));
chain.addLast("codec", new ProtocolCodecFilter(new TextLineCodecFactory()));
chain.addLast("logger", new LoggingFilter());
chain.addLast("executor", new ExecutorFilter());

// Custom filter implementation
public class CustomFilter extends IoFilterAdapter {
    @Override
    public void messageReceived(NextFilter nextFilter, IoSession session, Object message) 
            throws Exception {
        // Pre-process message
        String processed = preProcess((String) message);
        nextFilter.messageReceived(session, processed);
    }
}

Transport Layer

Multiple transport implementations with consistent API:

// TCP/IP Socket transport
NioSocketAcceptor tcpAcceptor = new NioSocketAcceptor();
NioSocketConnector tcpConnector = new NioSocketConnector();

// UDP Datagram transport
NioDatagramAcceptor udpAcceptor = new NioDatagramAcceptor();
NioDatagramConnector udpConnector = new NioDatagramConnector();

// APR Socket transport (high-performance, requires APR library)
AprSocketAcceptor aprAcceptor = new AprSocketAcceptor();
AprSocketConnector aprConnector = new AprSocketConnector();

// Serial Communication transport (RS232/COM ports)
SerialConnector serialConnector = new SerialConnector();

// VM Pipe (in-memory) transport
VmPipeAcceptor pipeAcceptor = new VmPipeAcceptor();
VmPipeConnector pipeConnector = new VmPipeConnector();

// Transport-specific configuration
SocketSessionConfig socketConfig = tcpAcceptor.getSessionConfig();
socketConfig.setSendBufferSize(64 * 1024);
socketConfig.setTcpNoDelay(true);

Buffer Management

Advanced buffer operations with auto-expansion and pooling:

// Creating and manipulating IoBuffers
IoBuffer buffer = IoBuffer.allocate(1024);
buffer.setAutoExpand(true);
buffer.setAutoShrink(true);

// Writing data
buffer.putString("Hello", Charset.forName("UTF-8"));
buffer.putInt(42);

// Reading data
buffer.flip();
String message = buffer.getString(Charset.forName("UTF-8").newDecoder());
int number = buffer.getInt();

// Buffer utilities
String hexDump = buffer.getHexDump();
IoBuffer duplicate = buffer.duplicate();

Async Operations

Comprehensive Future-based asynchronous operations:

// Asynchronous connection
ConnectFuture connectFuture = connector.connect(address);
connectFuture.addListener(new IoFutureListener<ConnectFuture>() {
    @Override
    public void operationComplete(ConnectFuture future) {
        if (future.isConnected()) {
            IoSession session = future.getSession();
            // Handle successful connection
        } else {
            // Handle connection failure
            Throwable cause = future.getException();
        }
    }
});

// Asynchronous write operations
WriteFuture writeFuture = session.write(message);
writeFuture.awaitUninterruptibly();
if (writeFuture.isWritten()) {
    // Message sent successfully
}

Protocol Codecs

Flexible codec system for message encoding/decoding:

// Text line protocol codec
TextLineCodecFactory codecFactory = new TextLineCodecFactory(
    Charset.forName("UTF-8"), 
    LineDelimiter.CRLF, 
    LineDelimiter.LF
);

// Object serialization codec
ObjectSerializationCodecFactory objectCodec = new ObjectSerializationCodecFactory();

// Adding codec to filter chain
filterChain.addLast("codec", new ProtocolCodecFilter(codecFactory));

// Custom codec implementation
public class CustomCodecFactory implements ProtocolCodecFactory {
    @Override
    public ProtocolEncoder getEncoder(IoSession session) throws Exception {
        return new CustomEncoder();
    }

    @Override
    public ProtocolDecoder getDecoder(IoSession session) throws Exception {
        return new CustomDecoder();
    }
}

Error Handling

// Comprehensive error handling in IoHandler
public class RobustHandler extends IoHandlerAdapter {
    @Override
    public void exceptionCaught(IoSession session, Throwable cause) throws Exception {
        if (cause instanceof IOException) {
            // Handle I/O errors
            LOGGER.warn("I/O error on session {}: {}", session.getId(), cause.getMessage());
        } else if (cause instanceof ProtocolCodecException) {
            // Handle codec errors
            LOGGER.error("Protocol error on session {}: {}", session.getId(), cause.getMessage());
        } else {
            // Handle unexpected errors
            LOGGER.error("Unexpected error on session " + session.getId(), cause);
        }
        
        // Close session on critical errors
        session.closeNow();
    }
}

Apache MINA Core provides a robust foundation for building networked applications with its clean abstractions, powerful filtering system, and comprehensive async I/O support.