This is an automated email from the ASF dual-hosted git repository.
robertlazarski pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/axis-axis2-java-core.git
The following commit(s) were added to refs/heads/master by this push:
new 726808dae0 docs: Clarify that annotation mode requires compiled classes
726808dae0 is described below
commit 726808dae02c2ba09c566866309b8b1d65852a04
Author: Robert Lazarski <[email protected]>
AuthorDate: Tue May 12 05:59:27 2026 -1000
docs: Clarify that annotation mode requires compiled classes
The JPA annotation section didn't explain that AnnotationIntrospector
uses Java reflection and needs compiled @Entity classes on the
classpath — unlike HBM XML mode which reads raw files and has a
standalone CLI tool. Added integration point guidance (startup,
build time, unit tests) so users understand when each mode applies.
Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
---
src/site/xdoc/docs/openapi-jpa-schema.xml | 19 +++++++++++++++++--
1 file changed, 17 insertions(+), 2 deletions(-)
diff --git a/src/site/xdoc/docs/openapi-jpa-schema.xml
b/src/site/xdoc/docs/openapi-jpa-schema.xml
index 54a773c5a6..bc317d232b 100644
--- a/src/site/xdoc/docs/openapi-jpa-schema.xml
+++ b/src/site/xdoc/docs/openapi-jpa-schema.xml
@@ -35,8 +35,23 @@ request/response bodies that map directly to database
entities.</p>
<h2 id="annotation_mode">JPA Annotation Mode</h2>
-<p>The <code>AnnotationIntrospector</code> reads standard Jakarta Persistence
-annotations (<code>@Entity</code>, <code>@Column</code>, <code>@Id</code>,
+<p>The <code>AnnotationIntrospector</code> uses Java reflection to read
+Jakarta Persistence annotations from compiled <code>@Entity</code> classes.
+Unlike the <a href="#hbm_xml_mode">HBM XML mode</a> (which reads raw XML
+files and has a standalone CLI tool), annotation mode requires the entity
+classes to be compiled and on the classpath. Typical integration points:</p>
+
+<ul>
+ <li><strong>At startup</strong> — a Spring bean or context listener scans
+ entity classes and generates schemas on first request</li>
+ <li><strong>At build time</strong> — a Maven/Gradle task that runs after
+ compilation (e.g., in the <code>process-classes</code> phase)</li>
+ <li><strong>In unit tests</strong> — call
+ <code>introspector.introspect(Product.class)</code> directly</li>
+</ul>
+
+<p>The introspector reads standard Jakarta Persistence annotations
+(<code>@Entity</code>, <code>@Column</code>, <code>@Id</code>,
<code>@ManyToOne</code>, <code>@OneToMany</code>, etc.) and produces an
<code>EntitySchemaModel</code> that the <code>JpaSchemaGenerator</code>
converts to JSON Schema.</p>
