Modernize project: update deps, add tests, CI, formatting, and improve docs

.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: Java CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+permissions:
+  contents: read
+
+jobs:
+  format:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up JDK 11
+      uses: actions/setup-java@v4
+      with:
+        java-version: '11'
+        distribution: 'temurin'
+        cache: maven
+
+    - name: Check code formatting
+      run: mvn -B spotless:check
+
+  build:
+    runs-on: ubuntu-latest
+    needs: format
+
+    strategy:
+      matrix:
+        java-version: [ '11', '17', '21' ]
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up JDK ${{ matrix.java-version }}
+      uses: actions/setup-java@v4
+      with:
+        java-version: ${{ matrix.java-version }}
+        distribution: 'temurin'
+        cache: maven
+
+    - name: Build with Maven
+      run: mvn -B clean verify --file pom.xml
+
+    - name: Upload test results
+      uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: test-results-java-${{ matrix.java-version }}
+        path: target/surefire-reports/
+        retention-days: 7

.gitignore

@@ -0,0 +1,16 @@
+# Maven build output
+target/
+
+# IDE files
+.classpath
+.project
+.settings/
+*.iml
+.idea/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log

README.md

@@ -1,8 +1,148 @@
-pb4mina
-=======
+# pb4mina
 
-Protocol buffer encoder/decoder for mina/java servers
+[![Java CI](https://github.com/meros/java-pb4mina/actions/workflows/ci.yml/badge.svg)](https://github.com/meros/java-pb4mina/actions/workflows/ci.yml)
+[![Java Version](https://img.shields.io/badge/java-11%2B-blue)](https://www.oracle.com/java/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-Status
----
-No plans, this is a quick PoC project only
+Protocol Buffer encoder/decoder for [Apache MINA](https://mina.apache.org/) Java network application framework.
+
+## Description
+
+pb4mina provides a seamless integration between Google Protocol Buffers and Apache MINA, enabling efficient binary message serialization for network applications. It handles message framing using a 4-byte fixed-length header, making it suitable for TCP-based communication.
+
+## Features
+
+- **Protocol Buffer Integration**: Encode and decode Protocol Buffer messages over MINA sessions
+- **Length-Prefixed Framing**: Messages are framed with a 4-byte fixed32 length header for reliable message boundaries
+- **Session-Safe Decoder**: Stateful decoder maintains per-session state for handling partial messages
+- **Shared Encoder**: Thread-safe encoder shared across all sessions for efficiency
+
+## Requirements
+
+- Java 11 or higher
+- Apache Maven 3.6+
+
+## Installation
+
+Add the following dependency to your `pom.xml`:
+
+```xml
+<dependency>
+    <groupId>org.meros</groupId>
+    <artifactId>pb4mina</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+</dependency>
+```
+
+## Usage
+
+### Basic Setup
+
+1. Create a message factory that returns builders for your Protocol Buffer messages:
+
+```java
+import com.google.protobuf.Message.Builder;
+import org.meros.pb4mina.ProtoBufMessageFactory;
+
+public class MyMessageFactory implements ProtoBufMessageFactory {
+    @Override
+    public Builder createProtoBufMessage() {
+        return MyProtoBufMessage.newBuilder();
+    }
+}
+```
+
+2. Add the codec filter to your MINA filter chain:
+
+```java
+import org.apache.mina.core.filterchain.DefaultIoFilterChainBuilder;
+import org.meros.pb4mina.ProtoBufCoderFilter;
+
+DefaultIoFilterChainBuilder filterChain = acceptor.getFilterChain();
+filterChain.addLast("codec", new ProtoBufCoderFilter(new MyMessageFactory()));
+```
+
+3. Handle messages in your IoHandler:
+
+```java
+@Override
+public void messageReceived(IoSession session, Object message) {
+    MyProtoBufMessage protoMessage = (MyProtoBufMessage) message;
+    // Process the message
+}
+
+@Override
+public void messageSent(IoSession session, Object message) {
+    // Message was sent successfully
+}
+```
+
+### Sending Messages
+
+Simply write Protocol Buffer messages to the session:
+
+```java
+MyProtoBufMessage message = MyProtoBufMessage.newBuilder()
+    .setField("value")
+    .build();
+session.write(message);
+```
+
+## Wire Format
+
+Messages are transmitted using the following format:
+
+```
++----------------+------------------+
+| Length (4 bytes) | Protobuf Data  |
++----------------+------------------+
+```
+
+- **Length**: 4-byte fixed32 (little-endian) containing the size of the protobuf data
+- **Protobuf Data**: The serialized Protocol Buffer message
+
+## Building from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/meros/java-pb4mina.git
+cd java-pb4mina
+
+# Build and run tests
+mvn clean verify
+
+# Install to local repository
+mvn install
+```
+
+## Code Formatting
+
+This project uses [Spotless](https://github.com/diffplug/spotless) with Google Java Format for code formatting.
+
+```bash
+# Check formatting
+mvn spotless:check
+
+# Apply formatting
+mvn spotless:apply
+```
+
+## Dependencies
+
+| Dependency | Version | Description |
+|------------|---------|-------------|
+| Apache MINA Core | 2.0.27 | Network application framework |
+| Protocol Buffers | 3.25.5 | Serialization library |
+| SLF4J | 2.0.16 | Logging facade |
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is open source. See the repository for license details.
+
+## Status
+
+This is a proof-of-concept project. It is not actively maintained but contributions are welcome.

pom.xml

@@ -2,36 +2,96 @@
 	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 	<modelVersion>4.0.0</modelVersion>
 
-	<groupId>org.meros.app</groupId>
-	<artifactId>minaserver</artifactId>
-	<version>1.0-SNAPSHOT</version>
+	<groupId>org.meros</groupId>
+	<artifactId>pb4mina</artifactId>
+	<version>1.0.0-SNAPSHOT</version>
 	<packaging>jar</packaging>
 
-	<name>MINA test server</name>
-	<url>http://maven.apache.org</url>
+	<name>pb4mina</name>
+	<description>Protocol Buffer encoder/decoder for Apache MINA</description>
+	<url>https://github.com/meros/java-pb4mina</url>
+
+	<properties>
+		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+		<maven.compiler.source>11</maven.compiler.source>
+		<maven.compiler.target>11</maven.compiler.target>
+		<mina.version>2.0.27</mina.version>
+		<protobuf.version>3.25.5</protobuf.version>
+		<slf4j.version>2.0.16</slf4j.version>
+		<junit.version>5.11.3</junit.version>
+	</properties>
 
 	<dependencies>
 		<dependency>
 			<groupId>org.apache.mina</groupId>
 			<artifactId>mina-core</artifactId>
-			<version>2.0.1</version>
+			<version>${mina.version}</version>
 		</dependency>
 		<dependency>
 			<groupId>com.google.protobuf</groupId>
 			<artifactId>protobuf-java</artifactId>
-			<version>2.3.0</version>
+			<version>${protobuf.version}</version>
 		</dependency>
 		<dependency>
 			<groupId>org.slf4j</groupId>
 			<artifactId>slf4j-api</artifactId>
-			<version>1.6.1</version>
+			<version>${slf4j.version}</version>
+		</dependency>
+		<dependency>
+			<groupId>org.slf4j</groupId>
+			<artifactId>slf4j-simple</artifactId>
+			<version>${slf4j.version}</version>
+			<scope>runtime</scope>
 		</dependency>
+		<!-- Test dependencies -->
 		<dependency>
-  <groupId>org.slf4j</groupId>
-  <artifactId>slf4j-simple</artifactId>
-  <version>1.6.1</version>
-</dependency>
+			<groupId>org.junit.jupiter</groupId>
+			<artifactId>junit-jupiter</artifactId>
+			<version>${junit.version}</version>
+			<scope>test</scope>
+		</dependency>
+		<dependency>
+			<groupId>org.mockito</groupId>
+			<artifactId>mockito-core</artifactId>
+			<version>5.14.2</version>
+			<scope>test</scope>
+		</dependency>
 	</dependencies>
-	<modules>
-	</modules>
+
+	<build>
+		<plugins>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-compiler-plugin</artifactId>
+				<version>3.13.0</version>
+			</plugin>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-surefire-plugin</artifactId>
+				<version>3.5.2</version>
+			</plugin>
+			<plugin>
+				<groupId>com.diffplug.spotless</groupId>
+				<artifactId>spotless-maven-plugin</artifactId>
+				<version>2.43.0</version>
+				<configuration>
+					<java>
+						<googleJavaFormat>
+							<version>1.19.2</version>
+							<style>GOOGLE</style>
+						</googleJavaFormat>
+						<removeUnusedImports/>
+					</java>
+				</configuration>
+				<executions>
+					<execution>
+						<goals>
+							<goal>check</goal>
+						</goals>
+						<phase>validate</phase>
+					</execution>
+				</executions>
+			</plugin>
+		</plugins>
+	</build>
 </project>