example config files in javadoc, and squash some warnings from jdoc tool

This commit is contained in:
Gavin 2023-01-05 22:52:31 +01:00
parent 5c6127848f
commit ccff90b211
9 changed files with 125 additions and 11 deletions

View File

@ -118,7 +118,7 @@ import jakarta.persistence.criteria.CriteriaUpdate;
* An easy way to be sure that session and transaction management is being done correctly
* is to {@linkplain SessionFactory#inTransaction(Consumer) let the factory do it}:
* <pre>
* sessionFactory.inTransaction(session -> {
* sessionFactory.inTransaction(session -&gt; {
* //do the work
* ...
* });
@ -127,7 +127,7 @@ import jakarta.persistence.criteria.CriteriaUpdate;
* A session may be used to {@linkplain #doWork(Work) execute JDBC work} using its JDBC
* connection and transaction:
* <pre>
* session.doWork(connection -> {
* session.doWork(connection -&gt; {
* try ( PreparedStatement ps = connection.prepareStatement( " ... " ) ) {
* ps.execute();
* }

View File

@ -44,6 +44,11 @@ import jakarta.persistence.criteria.CriteriaUpdate;
* <li>via {@link Configuration#setProperty(String, String)}, or
* <li>via {@link org.hibernate.boot.registry.StandardServiceRegistryBuilder#applySetting(String, Object)}.
* </ul>
* <p>
* Note that Hibernate does not distinguish between JPA-defined configuration
* properties and "native" configuration properties. Any property listed here
* may be used to configure Hibernate no matter what configuration mechanism
* or bootstrap API is used.
*
* @author Steve Ebersole
*/

View File

@ -17,5 +17,114 @@
* <p>
* Note that all the real meat behind these APIs is defined in the package
* {@link org.hibernate.boot}.
* <p>
* Configuration properties may be specified:
* <ul>
* <li>in Java code that {@linkplain org.hibernate.cfg.Configuration#setProperty
* configures} Hibernate,
* <li>in a JPA configuration file named {@code persistence.xml},
* <li>in a native configuration file named {@code hibernate.cfg.xml},
* <li>in a file named {@code hibernate.properties}, or
* <li>using some container-specific configuration facility, for example,
* Quarkus configuration properties.
* </ul>
* <p>
* We now present a couple of example configuration files.
*
* <h3>Example JPA configuration file</h3>
*
* The following JPA configuration may be specified in a file named {@code persistence.xml}:
*
* <pre>{@code <persistence xmlns="http://java.sun.com/xml/ns/persistence"
* xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
* xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
* version="2.0">
*
* <persistence-unit name="postgresql-example" transaction-type="RESOURCE_LOCAL">
*
* <class>org.hibernate.orm.example.Author</class>
* <class>org.hibernate.orm.example.Book</class>
*
* <properties>
*
* <!-- PostgreSQL -->
* <property name="javax.persistence.jdbc.url"
* value="jdbc:postgresql://localhost/library"/>
*
* <!-- Credentials -->
* <property name="javax.persistence.jdbc.user"
* value="hibernate"/>
* <property name="javax.persistence.jdbc.password"
* value="hibernate"/>
*
* <!-- Agroal connection pool config -->
* <property name="hibernate.agroal.maxSize"
* value="10"/>
* <property name="hibernate.agroal.acquisitionTimeout"
* value="PT1s"/>
* <property name="hibernate.agroal.reapTimeout"
* value="PT10s"/>
*
* <!-- Automatic schema export -->
* <property name="javax.persistence.schema-generation.database.action"
* value="drop-and-create"/>
*
* <!-- SQL statement logging -->
* <property name="hibernate.show_sql" value="true"/>
* <property name="hibernate.format_sql" value="true"/>
* <property name="hibernate.highlight_sql" value="true"/>
*
* </properties>
* </persistence-unit>
*
* </persistence>}</pre>
*
* The JPA configuration file is necessary when bootstrapping Hibernate via
* {@link jakarta.persistence.Persistence#createEntityManagerFactory(java.lang.String)}.
*
* <h3>Example native configuration file</h3>
*
* The following configuration may be specified in a file named {@code hibernate.cfg.xml}:
*
* <pre>{@code <?xml version='1.0' encoding='utf-8'?>
* <!DOCTYPE hibernate-configuration PUBLIC
* "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
* "http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd">
*
* <hibernate-configuration>
* <session-factory>
* <!-- PostgreSQL -->
* <property name="javax.persistence.jdbc.url">jdbc:postgresql://localhost/library</property>
*
* <!-- Credentials -->
* <property name="hibernate.connection.username">hibernate</property>
* <property name="hibernate.connection.password">hibernate</property>
*
* <!-- Agroal connection pool config -->
* <property name="hibernate.agroal.maxSize">10</property>
* <property name="hibernate.agroal.acquisitionTimeout">PT1s</property>
* <property name="hibernate.agroal.reapTimeout">PT10s</property>
*
* <!-- Automatic schema export -->
* <property name="hibernate.hbm2ddl.auto">create</property>
*
* <!-- SQL statement logging -->
* <property name="hibernate.show_sql">true</property>
* <property name="hibernate.format_sql">true</property>
* <property name="hibernate.highlight_sql">true</property>
*
* <!-- Maximum JDBC batch size -->
* <property name="hibernate.jdbc.batch_size">10</property>
*
* <!-- Entity classes -->
* <mapping class="org.hibernate.orm.example.Author"/>
* <mapping class="org.hibernate.orm.example.Book"/>
*
* </session-factory>
* </hibernate-configuration>}</pre>
*
* The native configuration file is used when configuring Hibernate via
* {@link org.hibernate.cfg.Configuration#configure()} or
* {@link org.hibernate.boot.registry.StandardServiceRegistryBuilder#configure()}.
*/
package org.hibernate.cfg;

View File

@ -2145,8 +2145,6 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
* @param lockOptions The lock options to apply
* @param tableName The name of the table to which to apply the lock hint.
* @return The table with any required lock hints.
*
* @author Helge Schulz
*/
public String appendLockHint(LockOptions lockOptions, String tableName){
return tableName;

View File

@ -104,7 +104,7 @@ public abstract class AbstractSqmFrom<O,T> extends AbstractSqmPath<T> implements
}
/**
* Intended for use with {@link SqmTreatedRoot} -> {@link SqmRoot}
* Intended for use with {@link SqmTreatedRoot} to {@link SqmRoot}
*/
protected AbstractSqmFrom(
NavigablePath navigablePath,

View File

@ -15,7 +15,7 @@ import org.hibernate.query.sqm.SqmExpressible;
import org.hibernate.query.sqm.tree.SqmCopyContext;
/**
* Effectively a query-literal but we want to handle it specially in the SQM -> SQL AST conversion
* Effectively a query-literal but we want to handle it specially in the SQM to SQL AST conversion
*
* @author Gavin King
*/

View File

@ -96,7 +96,7 @@ public class SqmJpaCriteriaParameterWrapper<T>
* as part of {@link SemanticQueryWalker#visitJpaCriteriaParameter}. This wrapper
* is intended just for representing unique SqmParameter references for each
* JpaCriteriaParameter occurrence in the SQM true as part of the {@link org.hibernate.query.QueryParameter}
* -> {@link SqmParameter} -> {@link JdbcParameter} transformation.
* to {@link SqmParameter} to {@link JdbcParameter} transformation.
* Each occurrence requires a unique SqmParameter to make sure we ultimately get the complete
* set of JdbcParameter references
*/

View File

@ -126,8 +126,9 @@ mappings as an alternative.
container-managed transactions.
</p>
<p>
A comprehensive list of configuration properties understood by Hibernate may be found in the
class {@link org.hibernate.cfg.AvailableSettings}. Most sensible programs will only ever need
Example configuration files for JPA and native usage may be found {@linkplain org.hibernate.cfg
here}. A comprehensive list of configuration properties understood by Hibernate may be found in
the class {@link org.hibernate.cfg.AvailableSettings}. Most sensible programs will only ever need
to use a tiny handful of them.
</p>

View File

@ -126,8 +126,9 @@ mappings as an alternative.
container-managed transactions.
</p>
<p>
A comprehensive list of configuration properties understood by Hibernate may be found in the
class {@link org.hibernate.cfg.AvailableSettings}. Most sensible programs will only ever need
Example configuration files for JPA and native usage may be found {@linkplain org.hibernate.cfg
here}. A comprehensive list of configuration properties understood by Hibernate may be found in
the class {@link org.hibernate.cfg.AvailableSettings}. Most sensible programs will only ever need
to use a tiny handful of them.
</p>