Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

finish updating javadoc of query package

This commit is contained in:
Gavin 2022-12-28 00:09:20 +01:00
parent 6c3131b981
commit 3569efcf7a
10 changed files with 166 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
hibernate-core/src/main/java/org/hibernate/Session.java
View File

@ -1360,9 +1360,8 @@ public interface Session extends SharedSessionContract, EntityManager {
boolean getScope();
/**
* Check if locking extends to owned collections and associated entities.
*
* @return true if locking will be extended to owned collections and associated entities
* Obtain the {@link PessimisticLockScope}, which determines if locking
* extends to owned collections and associated entities.
*/
default PessimisticLockScope getLockScope() {
return getScope() ? PessimisticLockScope.EXTENDED : PessimisticLockScope.NORMAL;
@ -1383,6 +1382,10 @@ public interface Session extends SharedSessionContract, EntityManager {
@Deprecated(since = "6.2")
LockRequest setScope(boolean scope);
/**
* Set the {@link PessimisticLockScope}, which determines if locking
* extends to owned collections and associated entities.
*/
default LockRequest setLockScope(PessimisticLockScope scope) {
return setScope( scope == PessimisticLockScope.EXTENDED );
}
@ -1444,7 +1447,7 @@ public interface Session extends SharedSessionContract, EntityManager {
<R> Query<R> createQuery(CriteriaQuery<R> criteriaQuery);
/**
* Create a {@link Query} for the given JPA {@link CriteriaDelete}
* Create a {@link Query} for the given JPA {@link CriteriaDelete}.
*
* @deprecated use {@link #createMutationQuery(CriteriaDelete)}
*/
@ -1452,7 +1455,7 @@ public interface Session extends SharedSessionContract, EntityManager {
Query createQuery(CriteriaDelete deleteQuery);
/**
* Create a {@link Query} for the given JPA {@link CriteriaUpdate}
* Create a {@link Query} for the given JPA {@link CriteriaUpdate}.
*
* @deprecated use {@link #createMutationQuery(CriteriaUpdate)}
*/

6
hibernate-core/src/main/java/org/hibernate/query/CommonQueryContract.java
View File

@ -21,9 +21,9 @@ import jakarta.persistence.TemporalType;
/**
* Defines the aspects of query execution and parameter binding that apply to all
* forms of querying - HQL, {@linkplain jakarta.persistence.criteria.CriteriaBuilder
* criteria queries}, and {@link org.hibernate.procedure.ProcedureCall stored
* procedure calls}.
* forms of querying: HQL/JPQL queries, native SQL queries,
* {@linkplain jakarta.persistence.criteria.CriteriaBuilder criteria queries}, and
* {@linkplain org.hibernate.procedure.ProcedureCall stored procedure calls}.
*
* @author Steve Ebersole
* @author Gavin King

31
hibernate-core/src/main/java/org/hibernate/query/MutationQuery.java
View File

@ -19,9 +19,34 @@ import jakarta.persistence.Parameter;
import jakarta.persistence.TemporalType;
/**
* Models a mutation (insert, update, or delete) query. It is a slimmed
* down version of {@link Query}, but providing only methods relevant to
* mutation queries.
* Within the context of an active {@linkplain org.hibernate.Session session},
* an instance of this type represents an executable mutation query, that is,
* an {@code insert}, {@code update}, or {@code delete}. It is a slimmed-down
* version of {@link Query}, providing only methods relevant to mutation queries.
* <p>
* A {@code MutationQuery} may be obtained from the {@link org.hibernate.Session}
* by calling:
* <ul>
* <li>{@link QueryProducer#createMutationQuery(String)}, passing the HQL as a
* string,
* <li>{@link QueryProducer#createNativeMutationQuery(String)}, passing native
* SQL as a string,
* <li>{@link QueryProducer#createMutationQuery(jakarta.persistence.criteria.CriteriaUpdate)} or
* {@link QueryProducer#createMutationQuery(jakarta.persistence.criteria.CriteriaDelete)},
* passing a criteria update or delete object, or
* <li>{@link QueryProducer#createNamedMutationQuery(String)}, passing the
* name of a query defined using {@link jakarta.persistence.NamedQuery} or
* {@link jakarta.persistence.NamedNativeQuery}.
* </ul>
* <p>
* A {@code MutationQuery} controls how the mutation query is executed, and
* allows arguments to be bound to its parameters.
* <ul>
* <li>Mutation queries must be executed using {@link #executeUpdate()}.
* <li>The various overloads of {@link #setParameter(String, Object)} and
* {@link #setParameter(int, Object)} allow arguments to be bound to named
* and ordinal parameters defined by the query.
* </ul>
*
* @author Steve Ebersole
*/

11
hibernate-core/src/main/java/org/hibernate/query/NativeQuery.java
View File

@ -49,9 +49,14 @@ import org.hibernate.type.BasicTypeReference;
* </ul>
* <p>
* A {@code NativeQuery} may be obtained from the {@link org.hibernate.Session}
* by calling {@link QueryProducer#createNativeQuery(String, Class)},
* {@link QueryProducer#createNativeQuery(String, String, Class)}, or
* {@link QueryProducer#createNativeMutationQuery(String)}.
* by calling:
* <ul>
* <li>{@link QueryProducer#createNativeQuery(String, Class)}, passing
* native SQL as a string, or
* <li>{@link QueryProducer#createNativeQuery(String, String, Class)}
* passing the native SQL string and the name of a result set mapping
* defined using {@link jakarta.persistence.SqlResultSetMapping}.
* </ul>
* <p>
* A result set mapping may be specified by:
* <ul>

22
hibernate-core/src/main/java/org/hibernate/query/Query.java
View File

@ -58,28 +58,30 @@ import jakarta.persistence.TypedQuery;
* A {@code Query} may be obtained from the {@link org.hibernate.Session} by
* calling:
* <ul>
* <li>{@link QueryProducer#createQuery(String, Class)},
* {@link QueryProducer#createQuery(jakarta.persistence.criteria.CriteriaQuery)},
* or {@link QueryProducer#createNamedQuery(String, Class)} for
* selection queries, or
* <li>{@link QueryProducer#createMutationQuery(String)},
* {@link QueryProducer#createMutationQuery(jakarta.persistence.criteria.CriteriaUpdate)},
* or {@link QueryProducer#createNamedMutationQuery(String)} for
* mutation queries.
* <li>{@link QueryProducer#createQuery(String, Class)}, passing the HQL as a
* string,
* <li>{@link QueryProducer#createQuery(jakarta.persistence.criteria.CriteriaQuery)},
* passing a {@linkplain jakarta.persistence.criteria.CriteriaQuery criteria
* object}, or
* <li>{@link QueryProducer#createNamedQuery(String, Class)} passing the name
* of a query defined using {@link jakarta.persistence.NamedQuery} or
* {@link jakarta.persistence.NamedNativeQuery}.
* </ul>
* <p>
* A {@code Query} controls how a query is executed, and allows arguments to be
* bound to its parameters.
* <ul>
* <li>Selection queries are usually executed using {@link #getResultList()} or
* {@link #getSingleResult()}, and mutation queries must be executed using
* {@link #executeUpdate()}.
* {@link #getSingleResult()}.
* <li>The methods {@link #setMaxResults(int)} and {@link #setFirstResult(int)}
* control limits and pagination.
* <li>The various overloads of {@link #setParameter(String, Object)} and
* {@link #setParameter(int, Object)} allow arguments to be bound to named
* and ordinal parameters defined by the query.
* </ul>
* <p>
* Note that this interface offers no real advantages over {@link SelectionQuery}
* except for compatibility with the JPA-defined {@link TypedQuery} interface.
*
* @author Gavin King
* @author Steve Ebersole

7
hibernate-core/src/main/java/org/hibernate/query/QueryProducer.java
View File

@ -62,7 +62,7 @@ public interface QueryProducer {
<R> Query<R> createQuery(String queryString, Class<R> resultClass);
/**
* Create a {@link Query} for the given JPA {@link CriteriaQuery}
* Create a {@link Query} for the given JPA {@link CriteriaQuery}.
*/
<R> Query<R> createQuery(CriteriaQuery<R> criteriaQuery);
@ -222,7 +222,7 @@ public interface QueryProducer {
MutationQuery createMutationQuery(@SuppressWarnings("rawtypes") JpaCriteriaInsertSelect insertSelect);
/**
* Create a {@link NativeQuery} instance for the given native (SQL) statement
* Create a {@link NativeQuery} instance for the given native SQL statement.
*
* @param sqlString a native SQL statement string
*
@ -298,9 +298,6 @@ public interface QueryProducer {
*/
MutationQuery createNamedMutationQuery(String name);
/**
* Create a {@link Query} instance for the named query.
*

31
hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java
View File

@ -36,8 +36,35 @@ import jakarta.persistence.Parameter;
import jakarta.persistence.TemporalType;
/**
* Models a selection query returning results. It is a slimmed down version
* of {@link Query}, but providing only methods relevant to selection queries.
* Within the context of an active {@linkplain org.hibernate.Session session},
* an instance of this type represents an executable selection query, that is,
* a {@code select}. It is a slimmed-down version of {@link Query}, providing
* only methods relevant to selection queries.
* <p>
* A {@code SelectionQuery} may be obtained from the {@link org.hibernate.Session}
* by calling:
* <ul>
* <li>{@link QueryProducer#createSelectionQuery(String, Class)}, passing the
* HQL as a string,
* <li>{@link QueryProducer#createSelectionQuery(jakarta.persistence.criteria.CriteriaQuery)},
* passing a {@linkplain jakarta.persistence.criteria.CriteriaQuery criteria
* query object}, or
* <li>{@link QueryProducer#createNamedSelectionQuery(String, Class)} passing
* the name of a query defined using {@link jakarta.persistence.NamedQuery}
* or {@link jakarta.persistence.NamedNativeQuery}.
* </ul>
* <p>
* A {@code SelectionQuery} controls how a query is executed, and allows arguments
* to be bound to its parameters.
* <ul>
* <li>Selection queries are usually executed using {@link #getResultList()} or
* {@link #getSingleResult()}.
* <li>The methods {@link #setMaxResults(int)} and {@link #setFirstResult(int)}
* control limits and pagination.
* <li>The various overloads of {@link #setParameter(String, Object)} and
* {@link #setParameter(int, Object)} allow arguments to be bound to named
* and ordinal parameters defined by the query.
* </ul>
*
* @author Steve Ebersole
*/

15
hibernate-core/src/main/java/org/hibernate/query/package-info.java
View File

@ -7,5 +7,20 @@
/**
* Everything related to HQL/JPQL, native SQL, and criteria queries.
* <p>
* The important interfaces {@link org.hibernate.query.SelectionQuery},
* {@link org.hibernate.query.MutationQuery}, {@link org.hibernate.query.Query},
* and {@link org.hibernate.query.NativeQuery} provide an API for executing
* queries. Instances of these interfaces may be obtained from a
* {@link org.hibernate.query.QueryProducer}, that is, from any
* {@link org.hibernate.Session} or {@link org.hibernate.StatelessSession}.
* <p>
* Hibernate's extensions to the JPA criteria query API are defined in the
* subpackage {@link org.hibernate.query.criteria}, with
* {@link org.hibernate.query.criteria.HibernateCriteriaBuilder} as the
* entry point.
* <p>
* Other subpackages contain SPIs and internal implementation details,
* including the HQL parser and translator.
*/
package org.hibernate.query;

43
hibernate-core/src/test/java/org/hibernate/BugTest.java Normal file
View File

@ -0,0 +1,43 @@
package org.hibernate;
import jakarta.persistence.Column;
import jakarta.persistence.Convert;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;
import jakarta.persistence.MappedSuperclass;
import org.hibernate.testing.orm.junit.DomainModel;
import org.hibernate.testing.orm.junit.SessionFactory;
import org.hibernate.testing.orm.junit.SessionFactoryScope;
import org.junit.jupiter.api.Test;
import java.util.List;
@SessionFactory
@DomainModel (annotatedClasses = {BugTest.MyInstance.class, BugTest.My.class})
public class BugTest {
@Test void test(SessionFactoryScope scope) {
scope.inTransaction( s -> s.persist( new My() ) );
scope.inTransaction(
s -> s.createMutationQuery("update My m set m.smallintCol = cast(1 as Short)")
.executeUpdate()
);
}
@MappedSuperclass
static abstract class MyInstance {
@Column(name = "iface_ids", columnDefinition = "TEXT")
@Convert(converter = StringListToStringConverter.class)
List<String> interfaceIds = List.of("a", "b", "c");
}
@Entity(name="My")
static class My extends MyInstance {
@Id @GeneratedValue
Long id;
@Column(name = "smallint_col", nullable = false)
private short smallintCol;
}
}

18
hibernate-core/src/test/java/org/hibernate/StringListToStringConverter.java Normal file
View File

@ -0,0 +1,18 @@
package org.hibernate;
import jakarta.persistence.AttributeConverter;
import java.util.Arrays;
import java.util.List;
public class StringListToStringConverter implements AttributeConverter<List<String>, String> {
@Override
public String convertToDatabaseColumn(List<String> attribute) {
return attribute.toString();
}
@Override
public List<String> convertToEntityAttribute(String dbData) {
return Arrays.asList( dbData.split(",") );
}
}