|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +MessagePack-Java is a binary serialization library that provides a fast and compact alternative to JSON. The project consists of two main modules: |
| 8 | +- **msgpack-core**: Standalone MessagePack implementation with no external dependencies |
| 9 | +- **msgpack-jackson**: Jackson integration for object mapping capabilities |
| 10 | + |
| 11 | +## Essential Development Commands |
| 12 | + |
| 13 | +### Build and Compile |
| 14 | +```bash |
| 15 | +./sbt compile # Compile source code |
| 16 | +./sbt test:compile # Compile source and test code |
| 17 | +./sbt package # Create JAR files |
| 18 | +``` |
| 19 | + |
| 20 | +### Testing |
| 21 | +```bash |
| 22 | +./sbt test # Run all tests |
| 23 | +./sbt ~test # Run tests continuously on file changes |
| 24 | +./sbt testOnly *TestClass # Run specific test class |
| 25 | +./sbt "testOnly *TestClass -- -z pattern" # Run tests matching pattern |
| 26 | + |
| 27 | +# Test with universal buffer mode (for compatibility testing) |
| 28 | +./sbt test -J-Dmsgpack.universal-buffer=true |
| 29 | +``` |
| 30 | + |
| 31 | +### Code Quality |
| 32 | +```bash |
| 33 | +./sbt jcheckStyle # Run checkstyle (Facebook Presto style) |
| 34 | +./sbt scalafmtAll # Format Scala test code |
| 35 | +``` |
| 36 | + |
| 37 | +### Publishing |
| 38 | +```bash |
| 39 | +./sbt publishLocal # Install to local .ivy2 repository |
| 40 | +./sbt publishM2 # Install to local .m2 Maven repository |
| 41 | +``` |
| 42 | + |
| 43 | +## Architecture Overview |
| 44 | + |
| 45 | +### Core API Structure |
| 46 | +The main entry point is the `MessagePack` factory class which creates: |
| 47 | +- **MessagePacker**: Serializes objects to MessagePack binary format |
| 48 | +- **MessageUnpacker**: Deserializes MessagePack binary data |
| 49 | + |
| 50 | +Key locations: |
| 51 | +- Core interfaces: `msgpack-core/src/main/java/org/msgpack/core/` |
| 52 | +- Jackson integration: `msgpack-jackson/src/main/java/org/msgpack/jackson/dataformat/` |
| 53 | + |
| 54 | +### Buffer Management System |
| 55 | +MessagePack uses an efficient buffer abstraction layer: |
| 56 | +- **MessageBuffer**: Platform-optimized buffer implementations |
| 57 | + - Uses `sun.misc.Unsafe` for performance when available |
| 58 | + - Falls back to ByteBuffer on restricted platforms |
| 59 | +- **MessageBufferInput/Output**: Manages buffer sequences for streaming |
| 60 | + |
| 61 | +### Jackson Integration |
| 62 | +The msgpack-jackson module provides: |
| 63 | +- **MessagePackFactory**: Jackson JsonFactory implementation |
| 64 | +- **MessagePackMapper**: Pre-configured ObjectMapper for MessagePack |
| 65 | +- Support for field IDs (integer keys) for compact serialization |
| 66 | +- Extension type support including timestamps |
| 67 | + |
| 68 | +### Testing Structure |
| 69 | +- **msgpack-core tests**: Written in Scala using AirSpec framework |
| 70 | + - Location: `msgpack-core/src/test/scala/` |
| 71 | +- **msgpack-jackson tests**: Written in Java using JUnit |
| 72 | + - Location: `msgpack-jackson/src/test/java/` |
| 73 | + |
| 74 | +## Important JVM Options |
| 75 | + |
| 76 | +For JDK 17+ compatibility, these options are automatically added: |
| 77 | +``` |
| 78 | +--add-opens=java.base/java.nio=ALL-UNNAMED |
| 79 | +--add-opens=java.base/sun.nio.ch=ALL-UNNAMED |
| 80 | +``` |
| 81 | + |
| 82 | +## Code Style Requirements |
| 83 | +- Java code follows Facebook Presto style (enforced by checkstyle) |
| 84 | +- Scala test code uses Scalafmt with 180 character line limit |
| 85 | +- Checkstyle runs automatically during compilation |
| 86 | +- No external dependencies allowed in msgpack-core |
| 87 | + |
| 88 | +## Key Design Principles |
| 89 | +1. **Zero Dependencies**: msgpack-core has no external dependencies |
| 90 | +2. **Platform Optimization**: Uses platform-specific optimizations when available |
| 91 | +3. **Streaming Support**: Both streaming and object-based APIs |
| 92 | +4. **Type Safety**: Immutable Value hierarchy for type-safe data handling |
| 93 | +5. **Extension Support**: Extensible type system for custom data types |
0 commit comments