Add HTTP server example using Netty and PerlOnJava

[fglock]

Summary

This PR adds a complete HTTP server example that demonstrates how to implement web pages in Perl using Netty/Jetty with PerlOnJava.

What's New

A new example at examples/http_server/ showing:

• ✅ HTTP server using Netty with request handlers written in Perl
• ✅ Clean separation: Java handles HTTP/networking, Perl handles business logic
• ✅ Thread-safe implementation using single event loop (documented)
• ✅ Multiple working endpoints (home, API, forms, time, env, echo, 404)
• ✅ Proper hash reference passing using RuntimeHash.createHashRef()
• ✅ Comprehensive documentation with architecture diagrams
• ✅ Automated build system and tests

Files Added

• HttpServerExample.java - Netty-based HTTP server
• handler.pl - Perl request handlers with routing
• Makefile - Complete build system (auto-downloads Netty JARs)
• README.md - Full documentation with debugging tips
• test.sh - Automated endpoint tests
• .gitignore - Ignores compiled/downloaded files

Quick Start

cd examples/http_server
make run

Then visit http://localhost:8080 or test with:

curl http://localhost:8080/
curl http://localhost:8080/api/users
make test

Technical Highlights

Thread Safety

PerlOnJava is currently not thread-safe (global state in static fields). This example uses a single-threaded event loop to safely handle concurrent requests via async I/O. This approach is:

• ✅ Safe - no race conditions
• ✅ Efficient for I/O-bound workloads
• ✅ Handles thousands of concurrent connections
• ✅ Well-documented in code and README

Future: When multiplicity is implemented (see dev/design/concurrency.md), a runtime pool can be used for true parallel request handling.

Proper Perl API Usage

Uses --disassemble to understand internal APIs:

./jperl --disassemble -e 'my $hash = { foo => "bar" };' 2>&1 | grep createHashRef

This revealed that hash references should be created using:

RuntimeScalar hashRef = RuntimeHash.createHashRef(request);

This matches how PerlOnJava compiles { key => value } syntax internally.

Testing

All endpoints tested and working:

• ✅ Home page (HTML)
• ✅ API endpoints (JSON)
• ✅ POST form handling
• ✅ Dynamic content (time, env)
• ✅ Query parameters (echo)
• ✅ 404 handling

Documentation

The README includes:

• Architecture diagrams
• Thread safety explanation
• Quick start guide
• Customization examples
• Troubleshooting section
• Debugging tips using --disassemble
• Performance considerations
• Future improvements (multiplicity)

Related Issues

Addresses the question: "Is there a way to implement web pages in Perl using netty/jetty?"

Answer: Yes! This example shows exactly how to do it.

Checklist

• Code compiles and runs
• All endpoints tested
• Documentation complete
• Thread safety properly handled
• Build system works (auto-downloads deps)
• Tests pass
• .gitignore included
• Follows existing example patterns (like ExifToolExample)

Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com