domaframework
diff --git a/‎CLAUDE.md‎
Lines changed: 7 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 7 additions & 0 deletions
diff --git a/‎doma-core/JMH_SETUP.md‎
Lines changed: 152 additions & 0 deletions b/‎doma-core/JMH_SETUP.md‎
Lines changed: 152 additions & 0 deletions
diff --git a/‎doma-core/README_BENCHMARK.md‎
Lines changed: 63 additions & 0 deletions b/‎doma-core/README_BENCHMARK.md‎
Lines changed: 63 additions & 0 deletions
diff --git a/‎doma-core/build.gradle.kts‎
Lines changed: 58 additions & 0 deletions b/‎doma-core/build.gradle.kts‎
Lines changed: 58 additions & 0 deletions
@@ -86,6 +86,13 @@ When modifying annotation processors or entity/domain classes, the `ap` property
 ### Code Formatting
 All code must pass Spotless formatting checks. The build automatically applies formatting, but you can run `./gradlew spotlessCheck` to verify compliance before committing.
 
+**IMPORTANT**: Always run `./gradlew spotlessApply` before committing changes to ensure consistent code formatting across the project.
+
+### Import Statement Guidelines
+- Do not use wildcard imports (e.g., `import java.util.*;`) in Java code
+- Always use explicit imports for each class (e.g., `import java.util.List;`, `import java.util.Map;`)
+- This improves code readability and makes dependencies explicit
+
 ### Database Compatibility Testing
 When making changes that affect SQL generation or JDBC operations, run tests against multiple databases using `./gradlew testAll` to ensure compatibility.
 
 
@@ -0,0 +1,152 @@
+# JMH Configuration for doma-core
+
+This document explains how JMH (Java Microbenchmark Harness) is configured in the doma-core module using the JMH Gradle plugin.
+
+## Configuration Details
+
+### Plugin Configuration
+
+The JMH plugin is configured in `gradle/libs.versions.toml`:
+```toml
+[plugins]
+jmh = { id = "me.champeau.jmh", version = "0.7.3" }
+```
+
+And applied in `doma-core/build.gradle.kts`:
+```kotlin
+plugins {
+    alias(libs.plugins.jmh)
+}
+```
+
+### JMH Settings
+
+The benchmark configuration supports multiple profiles for different use cases:
+
+#### Development Profile (Default - Fast)
+```bash
+./gradlew :doma-core:jmh                        # Uses dev profile by default
+./gradlew :doma-core:jmh -Pjmh.profile=dev     # Explicit dev profile
+```
+- **Time**: ~30 seconds for all benchmarks
+- **Iterations**: 1 measurement, 1 warmup
+- **Forks**: 1
+- **Duration**: 1 second per iteration
+- **Use case**: Quick feedback during development
+
+#### CI Profile (Balanced)
+```bash
+./gradlew :doma-core:jmh -Pjmh.profile=ci
+```
+- **Time**: ~3-5 minutes for all benchmarks
+- **Iterations**: 3 measurement, 2 warmup
+- **Forks**: 1
+- **Duration**: 3 seconds per iteration
+- **Use case**: Continuous integration, pull request validation
+
+#### Production Profile (Accurate)
+```bash
+./gradlew :doma-core:jmh -Pjmh.profile=production
+```
+- **Time**: ~20-30 minutes for all benchmarks
+- **Iterations**: 10 measurement, 5 warmup
+- **Forks**: 3
+- **Duration**: 10 seconds per iteration
+- **Use case**: Release benchmarks, performance regression analysis
+
+The JMH task is configured to bypass Gradle's caching mechanism to ensure benchmarks always run and provide fresh performance measurements.
+
+### Dependency Management
+
+The JMH plugin automatically handles all JMH dependencies including:
+- `org.openjdk.jmh:jmh-core`
+- `org.openjdk.jmh:jmh-generator-annprocess`
+- Code generation and annotation processing
+
+No manual dependency configuration is required.
+
+### Benchmark Source Location
+
+Benchmark classes are located in:
+- `src/jmh/java/org/seasar/doma/internal/util/SqlTokenUtilBenchmark.java`
+- `src/jmh/java/org/seasar/doma/internal/jdbc/sql/SqlTokenizerBenchmark.java`
+
+## Available Gradle Tasks
+
+### `./gradlew :doma-core:jmh`
+Runs all JMH benchmarks with the configured settings:
+- 5 measurement iterations (10 seconds each by default)
+- 3 warmup iterations (10 seconds each by default)
+- 2 forks
+- Results in nanoseconds
+- JVM args: `-Xms2G -Xmx2G`
+
+### `./gradlew :doma-core:jmhJar`
+Creates a self-contained JAR file with all benchmarks.
+
+### `./gradlew :doma-core:jmhCompileGeneratedClasses`
+Compiles JMH generated classes.
+
+### `./gradlew :doma-core:jmhRunBytecodeGenerator`
+Runs the JMH bytecode generator.
+
+## Running Specific Benchmarks
+
+### Method 1: Configure in build.gradle.kts
+You can configure the JMH plugin to run specific benchmarks by modifying the build file:
+```kotlin
+jmh {
+    includes.set(listOf(".*SqlTokenUtil.*"))  // Run only SqlTokenUtil benchmarks
+    excludes.set(listOf(".*classic.*"))       // Exclude classic benchmarks
+}
+```
+
+### Method 2: Dynamic filtering with Gradle properties
+The current build script already supports dynamic filtering:
+```kotlin
+val jmhIncludes: String? = findProperty("jmh.includes") as String?
+jmh {
+    iterations.set(5)
+    warmupIterations.set(3)
+    fork.set(2)
+    timeUnit.set("ns")
+    resultFormat.set("TEXT")
+    jvmArgs.set(listOf("-Xms2G", "-Xmx2G"))
+
+    if (jmhIncludes != null) {
+        includes.set(listOf(jmhIncludes))
+    }
+}
+```
+
+Then run with:
+```bash
+./gradlew :doma-core:jmh -Pjmh.includes=".*SqlTokenUtil.*"
+```
+
+## Writing Benchmarks
+
+1. Create benchmark classes in `src/jmh/java`
+2. Annotate with JMH annotations like `@Benchmark`, `@State`, `@Setup`
+3. Configuration is handled by the Gradle plugin, not annotations
+4. Follow JMH best practices for microbenchmarking
+
+Example structure:
+```java
+@BenchmarkMode(Mode.AverageTime)
+@OutputTimeUnit(TimeUnit.NANOSECONDS)
+@State(Scope.Benchmark)
+public class MyBenchmark {
+    @Benchmark
+    public void testMethod() {
+        // benchmark code
+    }
+}
+```
+
+## Troubleshooting
+
+If benchmarks don't run:
+1. Ensure benchmark classes are in `src/jmh/java`
+2. Check that the JMH plugin is properly applied
+3. Clean and rebuild: `./gradlew :doma-core:clean :doma-core:jmh`
@@ -0,0 +1,63 @@
+# Performance Benchmarks
+
+This module contains JMH benchmarks comparing the performance of optimized implementations
+with their classic counterparts:
+
+1. **SqlTokenUtil** (`org.seasar.doma.internal.util`) - Character classification utilities
+2. **SqlTokenizer** (`org.seasar.doma.internal.jdbc.sql`) - SQL tokenization and parsing
+
+## Benchmark Locations
+
+- `src/jmh/java/org/seasar/doma/internal/util/SqlTokenUtilBenchmark.java`
+- `src/jmh/java/org/seasar/doma/internal/jdbc/sql/SqlTokenizerBenchmark.java`
+
+## Running the Benchmarks
+
+From the project root directory:
+
+### Quick Development Testing (Default)
+```bash
+./gradlew :doma-core:jmh                        # Fast ~30 seconds
+```
+
+### Balanced Testing
+```bash
+./gradlew :doma-core:jmh -Pjmh.profile=ci      # Moderate ~3-5 minutes
+```
+
+### Production Quality Benchmarks
+```bash
+./gradlew :doma-core:jmh -Pjmh.profile=production  # Accurate ~20-30 minutes
+```
+
+## Benchmark Parameters
+
+The benchmark parameters are configured using the JMH Gradle plugin:
+
+- **Forks**: 2 (number of JVM instances)
+- **Warmup**: 3 iterations, 10 seconds each (JMH default)
+- **Measurement**: 5 iterations, 10 seconds each (JMH default)
+- **Time Unit**: Nanoseconds (average time per operation)
+- **JVM Args**: `-Xms2G -Xmx2G`
+
+## Expected Results
+
+### SqlTokenUtil
+The optimized implementation using bitmasks should show significant performance improvements:
+- `isWordPart`: ~30-50% faster for ASCII characters
+- `isWhitespace`: ~20-40% faster for common whitespace
+
+### SqlTokenizer
+The optimized tokenizer should show improvements across different SQL types:
+- Simple SQL: ~15-25% faster
+- Complex SQL: ~20-30% faster
+- Comment-heavy SQL: ~25-35% faster (due to optimized comment parsing)
+- Keyword-heavy SQL: ~20-30% faster (due to optimized keyword detection)
+- Directive-heavy SQL: ~30-40% faster (due to streamlined directive parsing)
+
+## Understanding the Results
+
+- Lower values are better (measured in nanoseconds per operation)
+- The `optimized*` benchmarks test the current implementations
+- The `classic*` benchmarks test the preserved original implementations
+- Different SQL types test various aspects of tokenizer performance
@@ -1,5 +1,63 @@
+plugins {
+    alias(libs.plugins.jmh)
+}
+
 description = "doma-core"
 
 dependencies {
     testImplementation(project(":doma-mock"))
 }
+
+// JMH plugin configuration
+val jmhIncludes: String? = findProperty("jmh.includes") as String?
+val jmhProfile: String = findProperty("jmh.profile") as String? ?: "dev"
+
+jmh {
+    jmhVersion.set(libs.jmh.core.get().version) // Use JMH version from libs.versions.toml
+    timeUnit.set("ns") // Time unit for results
+    resultFormat.set("TEXT") // Result format
+    jvmArgs.set(listOf("-Xms2G", "-Xmx2G")) // JVM arguments
+
+    // Profile-based configuration
+    when (jmhProfile) {
+        "dev", "development" -> {
+            // Fast development profile
+            iterations.set(1) // Quick measurement
+            warmupIterations.set(1) // Minimal warmup
+            fork.set(1) // Single fork
+            timeOnIteration.set("1s") // 1 second per iteration
+        }
+        "ci" -> {
+            // CI profile - balanced speed vs accuracy
+            iterations.set(3) // Moderate measurement
+            warmupIterations.set(2) // Light warmup
+            fork.set(1) // Single fork for speed
+            timeOnIteration.set("3s") // 3 seconds per iteration
+        }
+        "production", "prod" -> {
+            // Production profile - high accuracy
+            iterations.set(10) // Thorough measurement
+            warmupIterations.set(5) // Proper warmup
+            fork.set(3) // Multiple forks for stability
+            timeOnIteration.set("10s") // 10 seconds per iteration
+        }
+        else -> {
+            // Default profile (moderate)
+            iterations.set(5)
+            warmupIterations.set(3)
+            fork.set(2)
+            timeOnIteration.set("5s")
+        }
+    }
+
+    // Dynamic filtering support
+    if (jmhIncludes != null) {
+        includes.set(listOf(jmhIncludes))
+    }
+}
+
+// Configure JMH task to disable caching and always run
+tasks.named("jmh") {
+    outputs.upToDateWhen { false }
+    doNotTrackState("Benchmarks should always run to get fresh results")
+}