From ec88e5157e7ab3cbccee406429f8369384b9e070 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 8 Jan 2026 05:23:26 +0000 Subject: [PATCH 1/3] Add CLAUDE.md documentation for AI assistants Provides comprehensive guidance including: - Project overview and structure - Development commands and workflows - Code conventions and patterns - Testing guidelines - Key design patterns used in the codebase --- CLAUDE.md | 261 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 261 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..9f986a1 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,261 @@ +# CLAUDE.md - AI Assistant Guide for CodeLibs CoreLib + +This document provides guidance for AI assistants working with the CodeLibs CoreLib codebase. + +## Project Overview + +**CodeLibs CoreLib** is a foundational Java utility library providing essential utilities and components for the CodeLibs project ecosystem. It is built with **Java 21** and optimized for modern Java development patterns. + +- **Group ID**: `org.codelibs` +- **Artifact ID**: `corelib` +- **Current Version**: `0.7.2-SNAPSHOT` +- **License**: Apache License 2.0 +- **Build System**: Maven + +## Repository Structure + +``` +corelib/ +├── pom.xml # Maven build configuration +├── src/ +│ ├── main/java/org/codelibs/core/ # Main source code +│ │ ├── CoreLibConstants.java # Core constants (UTF-8, date formats) +│ │ ├── beans/ # Bean manipulation and introspection +│ │ │ ├── converter/ # Type converters for beans +│ │ │ ├── factory/ # BeanDescFactory, ParameterizedClassDescFactory +│ │ │ ├── impl/ # Implementation classes +│ │ │ └── util/ # BeanUtil, BeanMap, CopyOptions +│ │ ├── collection/ # Enhanced collections (LruHashMap, CaseInsensitiveMap) +│ │ ├── concurrent/ # Concurrency utilities +│ │ ├── convert/ # Type conversion utilities (*ConversionUtil) +│ │ ├── crypto/ # Cryptographic utilities (CachedCipher) +│ │ ├── exception/ # Runtime exception wrappers +│ │ ├── io/ # I/O and resource utilities +│ │ ├── jar/ # JAR file utilities +│ │ ├── lang/ # Reflection and language utilities +│ │ ├── log/ # Logging abstraction +│ │ ├── message/ # Message formatting +│ │ ├── misc/ # Miscellaneous (AssertionUtil, Base64Util) +│ │ ├── naming/ # JNDI naming utilities +│ │ ├── net/ # Network utilities (URL, UUID, MIME) +│ │ ├── nio/ # NIO channel operations +│ │ ├── security/ # Security utilities (MessageDigest) +│ │ ├── sql/ # JDBC helper utilities +│ │ ├── stream/ # Stream utilities +│ │ ├── text/ # Text processing (JSON, Tokenizer) +│ │ ├── timer/ # Timer and timeout management +│ │ ├── xml/ # XML processing utilities +│ │ └── zip/ # ZIP file utilities +│ └── test/java/ # Test classes (mirrors main structure) +├── .github/workflows/maven.yml # CI/CD configuration +└── LICENSE # Apache 2.0 License +``` + +## Development Commands + +### Build and Test + +```bash +# Compile the project +mvn clean compile + +# Run all tests +mvn test + +# Run a specific test class +mvn test -Dtest=BeanUtilTest + +# Run a specific test method +mvn test -Dtest=BeanUtilTest#testCopyBeanToBean + +# Build JAR with all verifications +mvn clean package + +# Generate test coverage report (available at target/site/jacoco/index.html) +mvn verify +``` + +### Code Quality + +```bash +# Format code according to project standards (Eclipse formatter) +mvn formatter:format + +# Apply license headers to source files +mvn license:format + +# Full build with formatting +mvn clean package +``` + +## Code Conventions + +### Class Structure + +1. **Utility Classes**: Abstract classes with protected constructors to prevent instantiation + ```java + public abstract class StringUtil { + protected StringUtil() { + } + // Static methods only + } + ``` + +2. **Constants Classes**: Same pattern with protected constructor + ```java + public class CoreLibConstants { + protected CoreLibConstants() { + } + public static final String UTF_8 = "UTF-8"; + } + ``` + +### License Header + +All source files MUST include the Apache 2.0 license header: +```java +/* + * Copyright 2012-2025 CodeLibs Project and the Others. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * ... + */ +``` + +### Argument Validation + +Always validate arguments using `AssertionUtil` at method entry: +```java +public static void process(String value, Object obj) { + AssertionUtil.assertArgumentNotNull("value", value); + AssertionUtil.assertArgumentNotEmpty("obj", obj); + // Method logic +} +``` + +### Exception Handling + +- Wrap checked exceptions in runtime exceptions from `org.codelibs.core.exception` +- Exception classes use error codes (e.g., "ECL0008" for null argument) +- Example pattern: + ```java + // Instead of throwing checked exceptions + throw new NullArgumentException("paramName"); // Uses ECL0008 + throw new EmptyArgumentException("paramName", "ECL0010", asArray("paramName")); + ``` + +### JavaDoc Style + +- All public methods must have JavaDoc +- Include `@param`, `@return`, and `@throws` tags +- Use `{@code null}` for null references +- Use `{@literal true/false}` for boolean values +- Include usage examples where helpful: + ```java + /** + * Capitalizes a string according to JavaBeans conventions. + *

+ * Usage example: + *

+ * 
+   * StringUtil.capitalize("userId")  = "UserId"
+   *
+ * + * @param name the string to capitalize + * @return the capitalized string + */ + ``` + +### Test Structure + +- Tests use JUnit 4 with Hamcrest matchers +- Test class naming: `{ClassName}Test.java` +- Test method naming: `test{MethodName}` or descriptive names +- Use `assertEquals`, `assertTrue`, `assertFalse`, `assertNull`, `assertThat` +- Each test method should have a JavaDoc comment + +```java +public class StringUtilTest { + /** + * @throws Exception + */ + @Test + public void testReplace() throws Exception { + assertEquals("1", "1bc45", StringUtil.replace("12345", "23", "bc")); + } +} +``` + +## Key Design Patterns + +### Factory Pattern +- `BeanDescFactory.getBeanDesc(Class)` - Creates/caches bean descriptors +- `ParameterizedClassDescFactory` - Handles generic type information + +### Builder Pattern +- `CopyOptions` - Fluent configuration for bean copying operations + +### Utility Pattern +- All core functionality via static methods +- Null-safe operations throughout +- Methods return null for null inputs where appropriate + +### Exception Wrapping +- `ClassNotFoundException` → `ClassNotFoundRuntimeException` +- `IOException` → `IORuntimeException` +- Consistent error handling without checked exception pollution + +## Important Notes for AI Assistants + +### When Making Changes + +1. **Always run tests** after modifications: `mvn test` +2. **Format code** before committing: `mvn formatter:format` +3. **Apply license headers** to new files: `mvn license:format` +4. **Maintain backwards compatibility** - deprecate before removing +5. **Follow existing patterns** - study similar classes before adding new ones + +### Naming Conventions + +- Utility classes: `{Feature}Util.java` (e.g., `StringUtil`, `ArrayUtil`) +- Conversion classes: `{Type}ConversionUtil.java` (e.g., `IntegerConversionUtil`) +- Exception classes: `{Name}RuntimeException.java` or `Cl{Name}Exception.java` +- Interface implementations: `{Interface}Impl.java` + +### Package Organization + +- Place new utilities in the appropriate existing package +- Create new packages only when absolutely necessary +- Test classes mirror the main source structure exactly + +### Dependencies + +The project has minimal dependencies (all optional except for testing): +- `slf4j-api` (optional) - Logging facade +- `commons-logging` (optional) - Logging facade +- `junit` (test scope) - Testing framework + +### Java 21 Features + +The codebase leverages Java 21 features: +- Pattern matching in switch expressions +- Sequenced collections support +- Modern stream operations +- Enhanced type inference + +### CI/CD + +- GitHub Actions runs on push/PR to `master` and `*.x` branches +- Uses Temurin JDK 21 +- Runs `mvn -B package` + +## Quick Reference + +| Task | Command | +|------|---------| +| Build | `mvn clean package` | +| Test | `mvn test` | +| Format code | `mvn formatter:format` | +| Add license headers | `mvn license:format` | +| Generate coverage | `mvn verify` | +| Run single test | `mvn test -Dtest=ClassName#methodName` | From f03c66b0ff957b6a2f3cf70702b62f75413eddec Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 8 Jan 2026 05:56:50 +0000 Subject: [PATCH 2/3] Simplify CLAUDE.md by removing non-essential information Remove version info, verbose code examples, and redundant sections. Keep only essential development commands and conventions. --- CLAUDE.md | 272 ++++++++---------------------------------------------- 1 file changed, 41 insertions(+), 231 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9f986a1..2aa0cc9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,261 +1,71 @@ # CLAUDE.md - AI Assistant Guide for CodeLibs CoreLib -This document provides guidance for AI assistants working with the CodeLibs CoreLib codebase. - -## Project Overview - -**CodeLibs CoreLib** is a foundational Java utility library providing essential utilities and components for the CodeLibs project ecosystem. It is built with **Java 21** and optimized for modern Java development patterns. - -- **Group ID**: `org.codelibs` -- **Artifact ID**: `corelib` -- **Current Version**: `0.7.2-SNAPSHOT` -- **License**: Apache License 2.0 -- **Build System**: Maven +Java 21ユーティリティライブラリ。Mavenビルドシステム、Apache License 2.0。 ## Repository Structure ``` -corelib/ -├── pom.xml # Maven build configuration -├── src/ -│ ├── main/java/org/codelibs/core/ # Main source code -│ │ ├── CoreLibConstants.java # Core constants (UTF-8, date formats) -│ │ ├── beans/ # Bean manipulation and introspection -│ │ │ ├── converter/ # Type converters for beans -│ │ │ ├── factory/ # BeanDescFactory, ParameterizedClassDescFactory -│ │ │ ├── impl/ # Implementation classes -│ │ │ └── util/ # BeanUtil, BeanMap, CopyOptions -│ │ ├── collection/ # Enhanced collections (LruHashMap, CaseInsensitiveMap) -│ │ ├── concurrent/ # Concurrency utilities -│ │ ├── convert/ # Type conversion utilities (*ConversionUtil) -│ │ ├── crypto/ # Cryptographic utilities (CachedCipher) -│ │ ├── exception/ # Runtime exception wrappers -│ │ ├── io/ # I/O and resource utilities -│ │ ├── jar/ # JAR file utilities -│ │ ├── lang/ # Reflection and language utilities -│ │ ├── log/ # Logging abstraction -│ │ ├── message/ # Message formatting -│ │ ├── misc/ # Miscellaneous (AssertionUtil, Base64Util) -│ │ ├── naming/ # JNDI naming utilities -│ │ ├── net/ # Network utilities (URL, UUID, MIME) -│ │ ├── nio/ # NIO channel operations -│ │ ├── security/ # Security utilities (MessageDigest) -│ │ ├── sql/ # JDBC helper utilities -│ │ ├── stream/ # Stream utilities -│ │ ├── text/ # Text processing (JSON, Tokenizer) -│ │ ├── timer/ # Timer and timeout management -│ │ ├── xml/ # XML processing utilities -│ │ └── zip/ # ZIP file utilities -│ └── test/java/ # Test classes (mirrors main structure) -├── .github/workflows/maven.yml # CI/CD configuration -└── LICENSE # Apache 2.0 License +src/main/java/org/codelibs/core/ +├── beans/ # Bean操作・イントロスペクション (converter/, factory/, impl/, util/) +├── collection/ # 拡張コレクション (LruHashMap, CaseInsensitiveMap) +├── convert/ # 型変換 (*ConversionUtil) +├── exception/ # ランタイム例外ラッパー +├── io/ # I/O・リソースユーティリティ +├── lang/ # リフレクション・言語ユーティリティ +├── misc/ # AssertionUtil, Base64Util等 +├── text/ # テキスト処理 (JSON, Tokenizer) +└── ... # その他 (crypto, log, net, xml, zip等) +src/test/java/ # テストクラス (mainと同構造) ``` ## Development Commands -### Build and Test - -```bash -# Compile the project -mvn clean compile - -# Run all tests -mvn test - -# Run a specific test class -mvn test -Dtest=BeanUtilTest - -# Run a specific test method -mvn test -Dtest=BeanUtilTest#testCopyBeanToBean - -# Build JAR with all verifications -mvn clean package - -# Generate test coverage report (available at target/site/jacoco/index.html) -mvn verify -``` - -### Code Quality - ```bash -# Format code according to project standards (Eclipse formatter) -mvn formatter:format - -# Apply license headers to source files -mvn license:format - -# Full build with formatting -mvn clean package +mvn test # テスト実行 +mvn test -Dtest=ClassName#methodName # 特定テスト実行 +mvn clean package # ビルド +mvn formatter:format # コードフォーマット +mvn license:format # ライセンスヘッダー適用 +mvn verify # カバレッジレポート生成 ``` ## Code Conventions ### Class Structure -1. **Utility Classes**: Abstract classes with protected constructors to prevent instantiation - ```java - public abstract class StringUtil { - protected StringUtil() { - } - // Static methods only - } - ``` - -2. **Constants Classes**: Same pattern with protected constructor - ```java - public class CoreLibConstants { - protected CoreLibConstants() { - } - public static final String UTF_8 = "UTF-8"; - } - ``` - -### License Header - -All source files MUST include the Apache 2.0 license header: -```java -/* - * Copyright 2012-2025 CodeLibs Project and the Others. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * ... - */ -``` +- **ユーティリティクラス**: `abstract`クラス + `protected`コンストラクタ +- **定数クラス**: 同様のパターン ### Argument Validation -Always validate arguments using `AssertionUtil` at method entry: -```java -public static void process(String value, Object obj) { - AssertionUtil.assertArgumentNotNull("value", value); - AssertionUtil.assertArgumentNotEmpty("obj", obj); - // Method logic -} -``` +メソッド入口で`AssertionUtil`を使用: +- `AssertionUtil.assertArgumentNotNull("argName", value)` +- `AssertionUtil.assertArgumentNotEmpty("argName", value)` ### Exception Handling -- Wrap checked exceptions in runtime exceptions from `org.codelibs.core.exception` -- Exception classes use error codes (e.g., "ECL0008" for null argument) -- Example pattern: - ```java - // Instead of throwing checked exceptions - throw new NullArgumentException("paramName"); // Uses ECL0008 - throw new EmptyArgumentException("paramName", "ECL0010", asArray("paramName")); - ``` - -### JavaDoc Style - -- All public methods must have JavaDoc -- Include `@param`, `@return`, and `@throws` tags -- Use `{@code null}` for null references -- Use `{@literal true/false}` for boolean values -- Include usage examples where helpful: - ```java - /** - * Capitalizes a string according to JavaBeans conventions. - *

- * Usage example: - *

- * 
-   * StringUtil.capitalize("userId")  = "UserId"
-   *
- * - * @param name the string to capitalize - * @return the capitalized string - */ - ``` +- チェック例外を`org.codelibs.core.exception`のランタイム例外でラップ +- エラーコード使用 (例: "ECL0008" = null引数) ### Test Structure -- Tests use JUnit 4 with Hamcrest matchers -- Test class naming: `{ClassName}Test.java` -- Test method naming: `test{MethodName}` or descriptive names -- Use `assertEquals`, `assertTrue`, `assertFalse`, `assertNull`, `assertThat` -- Each test method should have a JavaDoc comment - -```java -public class StringUtilTest { - /** - * @throws Exception - */ - @Test - public void testReplace() throws Exception { - assertEquals("1", "1bc45", StringUtil.replace("12345", "23", "bc")); - } -} -``` - -## Key Design Patterns - -### Factory Pattern -- `BeanDescFactory.getBeanDesc(Class)` - Creates/caches bean descriptors -- `ParameterizedClassDescFactory` - Handles generic type information - -### Builder Pattern -- `CopyOptions` - Fluent configuration for bean copying operations - -### Utility Pattern -- All core functionality via static methods -- Null-safe operations throughout -- Methods return null for null inputs where appropriate - -### Exception Wrapping -- `ClassNotFoundException` → `ClassNotFoundRuntimeException` -- `IOException` → `IORuntimeException` -- Consistent error handling without checked exception pollution - -## Important Notes for AI Assistants - -### When Making Changes - -1. **Always run tests** after modifications: `mvn test` -2. **Format code** before committing: `mvn formatter:format` -3. **Apply license headers** to new files: `mvn license:format` -4. **Maintain backwards compatibility** - deprecate before removing -5. **Follow existing patterns** - study similar classes before adding new ones - -### Naming Conventions - -- Utility classes: `{Feature}Util.java` (e.g., `StringUtil`, `ArrayUtil`) -- Conversion classes: `{Type}ConversionUtil.java` (e.g., `IntegerConversionUtil`) -- Exception classes: `{Name}RuntimeException.java` or `Cl{Name}Exception.java` -- Interface implementations: `{Interface}Impl.java` - -### Package Organization - -- Place new utilities in the appropriate existing package -- Create new packages only when absolutely necessary -- Test classes mirror the main source structure exactly - -### Dependencies - -The project has minimal dependencies (all optional except for testing): -- `slf4j-api` (optional) - Logging facade -- `commons-logging` (optional) - Logging facade -- `junit` (test scope) - Testing framework - -### Java 21 Features - -The codebase leverages Java 21 features: -- Pattern matching in switch expressions -- Sequenced collections support -- Modern stream operations -- Enhanced type inference +- JUnit 4 + Hamcrestマッチャー +- テストクラス: `{ClassName}Test.java` +- テストメソッド: `test{MethodName}` -### CI/CD +## Naming Conventions -- GitHub Actions runs on push/PR to `master` and `*.x` branches -- Uses Temurin JDK 21 -- Runs `mvn -B package` +| 種類 | 命名規則 | +|------|----------| +| ユーティリティ | `{Feature}Util.java` | +| 変換 | `{Type}ConversionUtil.java` | +| 例外 | `{Name}RuntimeException.java` / `Cl{Name}Exception.java` | +| 実装 | `{Interface}Impl.java` | -## Quick Reference +## Important Notes -| Task | Command | -|------|---------| -| Build | `mvn clean package` | -| Test | `mvn test` | -| Format code | `mvn formatter:format` | -| Add license headers | `mvn license:format` | -| Generate coverage | `mvn verify` | -| Run single test | `mvn test -Dtest=ClassName#methodName` | +1. 変更後は必ず `mvn test` を実行 +2. コミット前に `mvn formatter:format` を実行 +3. 新規ファイルには `mvn license:format` でライセンスヘッダー追加 +4. 後方互換性維持 - 削除前に非推奨化 +5. 既存パターンに従う - 類似クラスを参考にする From ec536304f2b200101ea88e3c45cc35175dc71a8b Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 8 Jan 2026 05:58:27 +0000 Subject: [PATCH 3/3] Convert CLAUDE.md to English --- CLAUDE.md | 72 +++++++++++++++++++++++++++---------------------------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 2aa0cc9..6ac7e18 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,71 +1,71 @@ # CLAUDE.md - AI Assistant Guide for CodeLibs CoreLib -Java 21ユーティリティライブラリ。Mavenビルドシステム、Apache License 2.0。 +Java 21 utility library. Maven build system, Apache License 2.0. ## Repository Structure ``` src/main/java/org/codelibs/core/ -├── beans/ # Bean操作・イントロスペクション (converter/, factory/, impl/, util/) -├── collection/ # 拡張コレクション (LruHashMap, CaseInsensitiveMap) -├── convert/ # 型変換 (*ConversionUtil) -├── exception/ # ランタイム例外ラッパー -├── io/ # I/O・リソースユーティリティ -├── lang/ # リフレクション・言語ユーティリティ -├── misc/ # AssertionUtil, Base64Util等 -├── text/ # テキスト処理 (JSON, Tokenizer) -└── ... # その他 (crypto, log, net, xml, zip等) -src/test/java/ # テストクラス (mainと同構造) +├── beans/ # Bean manipulation & introspection (converter/, factory/, impl/, util/) +├── collection/ # Enhanced collections (LruHashMap, CaseInsensitiveMap) +├── convert/ # Type conversion (*ConversionUtil) +├── exception/ # Runtime exception wrappers +├── io/ # I/O & resource utilities +├── lang/ # Reflection & language utilities +├── misc/ # AssertionUtil, Base64Util, etc. +├── text/ # Text processing (JSON, Tokenizer) +└── ... # Others (crypto, log, net, xml, zip, etc.) +src/test/java/ # Test classes (mirrors main structure) ``` ## Development Commands ```bash -mvn test # テスト実行 -mvn test -Dtest=ClassName#methodName # 特定テスト実行 -mvn clean package # ビルド -mvn formatter:format # コードフォーマット -mvn license:format # ライセンスヘッダー適用 -mvn verify # カバレッジレポート生成 +mvn test # Run tests +mvn test -Dtest=ClassName#methodName # Run specific test +mvn clean package # Build +mvn formatter:format # Format code +mvn license:format # Apply license headers +mvn verify # Generate coverage report ``` ## Code Conventions ### Class Structure -- **ユーティリティクラス**: `abstract`クラス + `protected`コンストラクタ -- **定数クラス**: 同様のパターン +- **Utility classes**: `abstract` class + `protected` constructor +- **Constants classes**: Same pattern ### Argument Validation -メソッド入口で`AssertionUtil`を使用: +Use `AssertionUtil` at method entry: - `AssertionUtil.assertArgumentNotNull("argName", value)` - `AssertionUtil.assertArgumentNotEmpty("argName", value)` ### Exception Handling -- チェック例外を`org.codelibs.core.exception`のランタイム例外でラップ -- エラーコード使用 (例: "ECL0008" = null引数) +- Wrap checked exceptions in runtime exceptions from `org.codelibs.core.exception` +- Use error codes (e.g., "ECL0008" = null argument) ### Test Structure -- JUnit 4 + Hamcrestマッチャー -- テストクラス: `{ClassName}Test.java` -- テストメソッド: `test{MethodName}` +- JUnit 4 + Hamcrest matchers +- Test class: `{ClassName}Test.java` +- Test method: `test{MethodName}` ## Naming Conventions -| 種類 | 命名規則 | -|------|----------| -| ユーティリティ | `{Feature}Util.java` | -| 変換 | `{Type}ConversionUtil.java` | -| 例外 | `{Name}RuntimeException.java` / `Cl{Name}Exception.java` | -| 実装 | `{Interface}Impl.java` | +| Type | Pattern | +|------|---------| +| Utility | `{Feature}Util.java` | +| Conversion | `{Type}ConversionUtil.java` | +| Exception | `{Name}RuntimeException.java` / `Cl{Name}Exception.java` | +| Implementation | `{Interface}Impl.java` | ## Important Notes -1. 変更後は必ず `mvn test` を実行 -2. コミット前に `mvn formatter:format` を実行 -3. 新規ファイルには `mvn license:format` でライセンスヘッダー追加 -4. 後方互換性維持 - 削除前に非推奨化 -5. 既存パターンに従う - 類似クラスを参考にする +1. Always run `mvn test` after changes +2. Run `mvn formatter:format` before committing +3. Add license headers to new files with `mvn license:format` +4. Maintain backwards compatibility - deprecate before removing +5. Follow existing patterns - study similar classes first