Annotation Interface EntityResult

@Target(METHOD)
@Retention(RUNTIME)
@Repeatable(EntityResult.EntityResults.class)
public @interface EntityResult

Used in conjunction with the SqlResultSetMapping or NamedNativeQuery annotation to map the SELECT clause of a SQL query to an entity result.

The SQL SELECT statement should select every column mapped by the entity class, including foreign key columns of related entities. If a mapped column is missing from the SQL result set, the behavior is undefined.

If the names of the columns of the result set of the SQL statement exactly match the column names mapped by the entity class, then it is not necessary to explicitly specify mappings for the fields() or discriminator column of the entity. Otherwise, if a column name of the SQL result set does not exactly match the column name mapped by the entity class, the FieldResult annotation must be used to explicitly specify the mapping.

Consider the following SQL query:

Query ordersWithItems =
        em.createNativeQuery(
            """
               SELECT o.id, o.quantity, o.item,
                      i.id, i.name, i.description
               FROM Order o
               JOIN Item i ON o.item = i.id
               WHERE o.quantity > 25
            """,
            ResultMappings_.MAPPING_ORDERS_WITH_ITEMS
        );

The result set mapping might be defined as follows:

@SqlResultSetMapping(
    name = "OrdersWithItems",
    entities = {
        @EntityResult(entityClass = Order.class),
        @EntityResult(entityClass = Item.class)
    }
)
interface ResultMappings {}

At runtime, an EntityResult annotation is represented by an instance of EntityMapping in the ResultSetMapping returned by EntityManagerFactory.getResultSetMappings(Class).

This annotation may be placed directly on a method annotated NativeQuery.

@NativeQuery("SELECT * FROM orders WHERE order_total > ?")
@EntityResult(
    entityClass = Order.class,
    fields = {@FieldResult(name = Order_.ID, column = "order_id"),
              @FieldResult(name = Order_.TOTAL, column = "order_total"),
              @FieldResult(name = Order_.ITEM, column = "order_item")}
)
List<Order> largeOrders(int threshold) {
    return entityManager.createQuery(Shop_.largeOrders(threshold))
            .getResultList();
}

Since:

1.0

See Also:

• SqlResultSetMapping
• NamedNativeQuery
• EntityMapping

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static @interface	EntityResult.EntityResults

Required Element Summary

Required Elements

Modifier and Type	Required Element	Description
Class<?>	entityClass	The class of the result.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String	discriminatorColumn	Specifies the column name (or alias) of the column in the SELECT list that is used to determine the type of the entity instance.
FieldResult[]	fields	Maps the columns specified in the SELECT list of the query to the properties or fields of the entity class.
LockModeType	lockMode	The lock mode obtained by the SQL query.

Element Details

entityClass

Class<?> entityClass

The class of the result.

lockMode

LockModeType lockMode

The lock mode obtained by the SQL query.

Since:

3.2

Default:

NONE

fields

FieldResult[] fields

Maps the columns specified in the SELECT list of the query to the properties or fields of the entity class.

Default:

{}

discriminatorColumn

String discriminatorColumn

Specifies the column name (or alias) of the column in the SELECT list that is used to determine the type of the entity instance. An empty string indicates that there is no discriminator column.

Default:

""