0
# Metamodel API
1

2
Complete reference for accessing entity metadata and type-safe queries using the Metamodel API.
3

4
## Imports
5

6
```java { .api }
7
import jakarta.persistence.metamodel.*;
8
```
9

10
## Capabilities
11

12
### Metamodel Interface
13

14
Access metadata for managed types, entities, and embeddables.
15

16
```java { .api }
17
/**
18
 * Provides access to the metamodel of persistent entities
19
 * @since 2.0
20
 */
21
public interface Metamodel {
22
    /**
23
     * Return the metamodel entity type representing the entity
24
     * @param cls the type of the represented entity
25
     * @return the metamodel entity type
26
     */
27
    <X> EntityType<X> entity(Class<X> cls);
28

29
    /**
30
     * Return the metamodel managed type representing the managed type
31
     * @param cls the type of the represented managed type
32
     * @return the metamodel managed type
33
     */
34
    <X> ManagedType<X> managedType(Class<X> cls);
35

36
    /**
37
     * Return the metamodel embeddable type representing the embeddable class
38
     * @param cls the type of the represented embeddable type
39
     * @return the metamodel embeddable type
40
     */
41
    <X> EmbeddableType<X> embeddable(Class<X> cls);
42

43
    /**
44
     * Return the metamodel managed types
45
     * @return the metamodel managed types
46
     */
47
    Set<ManagedType<?>> getManagedTypes();
48

49
    /**
50
     * Return the metamodel entity types
51
     * @return the metamodel entity types
52
     */
53
    Set<EntityType<?>> getEntities();
54

55
    /**
56
     * Return the metamodel embeddable types
57
     * @return the metamodel embeddable types
58
     */
59
    Set<EmbeddableType<?>> getEmbeddables();
60
}
61
```
62

63
**Usage Example:**
64

65
```java
66
EntityManagerFactory emf = Persistence.createEntityManagerFactory("myPU");
67
Metamodel metamodel = emf.getMetamodel();
68

69
// Get entity type
70
EntityType<Customer> customerType = metamodel.entity(Customer.class);
71
String entityName = customerType.getName();
72

73
// Get all entities
74
Set<EntityType<?>> entities = metamodel.getEntities();
75
for (EntityType<?> entity : entities) {
76
    System.out.println("Entity: " + entity.getName());
77
}
78
```
79

80
### Type Hierarchy
81

82
Base interfaces for representing type information.
83

84
```java { .api }
85
/**
86
 * Instances of the type Type represent persistent object or attribute types
87
 * @since 2.0
88
 */
89
public interface Type<X> {
90
    /**
91
     * Persistence type enumeration
92
     */
93
    public static enum PersistenceType {
94
        /** Entity */
95
        ENTITY,
96
        /** Embeddable class */
97
        EMBEDDABLE,
98
        /** Mapped superclass */
99
        MAPPED_SUPERCLASS,
100
        /** Basic type */
101
        BASIC
102
    }
103

104
    /**
105
     * Return the persistence type
106
     * @return persistence type
107
     */
108
    PersistenceType getPersistenceType();
109

110
    /**
111
     * Return the represented Java type
112
     * @return Java type
113
     */
114
    Class<X> getJavaType();
115
}
116

117
/**
118
 * Instances of BasicType represent basic types (including temporal and enumerated types)
119
 * @since 2.0
120
 */
121
public interface BasicType<X> extends Type<X> {
122
}
123

124
/**
125
 * Instances of Bindable represent object or attribute types that can be bound into a Path
126
 * @since 2.0
127
 */
128
public interface Bindable<T> {
129
    /**
130
     * Bindable type enumeration
131
     */
132
    public static enum BindableType {
133
        /** Single-valued attribute type */
134
        SINGULAR_ATTRIBUTE,
135
        /** Multi-valued attribute type */
136
        PLURAL_ATTRIBUTE,
137
        /** Entity type */
138
        ENTITY_TYPE
139
    }
140

141
    /**
142
     * Return the bindable type of the represented object
143
     * @return bindable type
144
     */
145
    BindableType getBindableType();
146

147
    /**
148
     * Return the Java type of the represented object
149
     * If the bindable type is PLURAL_ATTRIBUTE, the Java element type is returned
150
     * @return Java type
151
     */
152
    Class<T> getBindableJavaType();
153
}
154
```
155

156
### Managed Types
157

158
Interfaces for entity, embeddable, and mapped superclass types.
159

160
```java { .api }
161
/**
162
 * Instances represent managed types (entity, mapped superclass, or embeddable)
163
 * @since 2.0
164
 */
165
public interface ManagedType<X> extends Type<X> {
166
    /**
167
     * Return the attributes of the managed type
168
     * @return attributes
169
     */
170
    Set<Attribute<? super X, ?>> getAttributes();
171

172
    /**
173
     * Return the attributes declared by the managed type
174
     * @return declared attributes
175
     */
176
    Set<Attribute<X, ?>> getDeclaredAttributes();
177

178
    /**
179
     * Return the single-valued attribute of the given name and type
180
     * @param name the name of the represented attribute
181
     * @param type the type of the represented attribute
182
     * @return single-valued attribute
183
     */
184
    <Y> SingularAttribute<? super X, Y> getSingularAttribute(String name, Class<Y> type);
185

186
    /**
187
     * Return the declared single-valued attribute of the given name and type
188
     * @param name the name of the represented attribute
189
     * @param type the type of the represented attribute
190
     * @return declared single-valued attribute
191
     */
192
    <Y> SingularAttribute<X, Y> getDeclaredSingularAttribute(String name, Class<Y> type);
193

194
    /**
195
     * Return the single-valued attributes of the managed type
196
     * @return single-valued attributes
197
     */
198
    Set<SingularAttribute<? super X, ?>> getSingularAttributes();
199

200
    /**
201
     * Return the single-valued attributes declared by the managed type
202
     * @return declared single-valued attributes
203
     */
204
    Set<SingularAttribute<X, ?>> getDeclaredSingularAttributes();
205

206
    /**
207
     * Return the Collection-valued attribute of the given name and element type
208
     * @param name the name of the represented attribute
209
     * @param elementType the element type of the represented attribute
210
     * @return CollectionAttribute
211
     */
212
    <E> CollectionAttribute<? super X, E> getCollection(String name, Class<E> elementType);
213

214
    /**
215
     * Return the Collection-valued attribute declared by the managed type
216
     * @param name the name of the represented attribute
217
     * @param elementType the element type of the represented attribute
218
     * @return declared CollectionAttribute
219
     */
220
    <E> CollectionAttribute<X, E> getDeclaredCollection(String name, Class<E> elementType);
221

222
    /**
223
     * Return the Set-valued attribute of the given name and element type
224
     * @param name the name of the represented attribute
225
     * @param elementType the element type of the represented attribute
226
     * @return SetAttribute
227
     */
228
    <E> SetAttribute<? super X, E> getSet(String name, Class<E> elementType);
229

230
    /**
231
     * Return the Set-valued attribute declared by the managed type
232
     * @param name the name of the represented attribute
233
     * @param elementType the element type of the represented attribute
234
     * @return declared SetAttribute
235
     */
236
    <E> SetAttribute<X, E> getDeclaredSet(String name, Class<E> elementType);
237

238
    /**
239
     * Return the List-valued attribute of the given name and element type
240
     * @param name the name of the represented attribute
241
     * @param elementType the element type of the represented attribute
242
     * @return ListAttribute
243
     */
244
    <E> ListAttribute<? super X, E> getList(String name, Class<E> elementType);
245

246
    /**
247
     * Return the List-valued attribute declared by the managed type
248
     * @param name the name of the represented attribute
249
     * @param elementType the element type of the represented attribute
250
     * @return declared ListAttribute
251
     */
252
    <E> ListAttribute<X, E> getDeclaredList(String name, Class<E> elementType);
253

254
    /**
255
     * Return the Map-valued attribute of the given name, key type, and value type
256
     * @param name the name of the represented attribute
257
     * @param keyType the key type of the represented attribute
258
     * @param valueType the value type of the represented attribute
259
     * @return MapAttribute
260
     */
261
    <K, V> MapAttribute<? super X, K, V> getMap(String name, Class<K> keyType, Class<V> valueType);
262

263
    /**
264
     * Return the Map-valued attribute declared by the managed type
265
     * @param name the name of the represented attribute
266
     * @param keyType the key type of the represented attribute
267
     * @param valueType the value type of the represented attribute
268
     * @return declared MapAttribute
269
     */
270
    <K, V> MapAttribute<X, K, V> getDeclaredMap(String name, Class<K> keyType, Class<V> valueType);
271

272
    /**
273
     * Return the Collection-valued attributes of the managed type
274
     * @return Collection-valued attributes
275
     */
276
    Set<PluralAttribute<? super X, ?, ?>> getPluralAttributes();
277

278
    /**
279
     * Return the Collection-valued attributes declared by the managed type
280
     * @return declared Collection-valued attributes
281
     */
282
    Set<PluralAttribute<X, ?, ?>> getDeclaredPluralAttributes();
283

284
    /**
285
     * Return the attribute of the given name
286
     * @param name the name of the represented attribute
287
     * @return attribute
288
     */
289
    Attribute<? super X, ?> getAttribute(String name);
290

291
    /**
292
     * Return the declared attribute of the given name
293
     * @param name the name of the represented attribute
294
     * @return declared attribute
295
     */
296
    Attribute<X, ?> getDeclaredAttribute(String name);
297
}
298

299
/**
300
 * Instances represent entity types
301
 * @since 2.0
302
 */
303
public interface EntityType<X> extends IdentifiableType<X>, Bindable<X> {
304
    /**
305
     * Return the entity name
306
     * @return entity name
307
     */
308
    String getName();
309
}
310

311
/**
312
 * Instances represent embeddable types
313
 * @since 2.0
314
 */
315
public interface EmbeddableType<X> extends ManagedType<X> {
316
}
317

318
/**
319
 * Instances represent mapped superclass types
320
 * @since 2.0
321
 */
322
public interface MappedSuperclassType<X> extends IdentifiableType<X> {
323
}
324

325
/**
326
 * Instances represent identifiable types (entity or mapped superclass)
327
 * @since 2.0
328
 */
329
public interface IdentifiableType<X> extends ManagedType<X> {
330
    /**
331
     * Return the attribute that corresponds to the id attribute of the entity or mapped superclass
332
     * @param type the type of the represented id attribute
333
     * @return id attribute
334
     */
335
    <Y> SingularAttribute<? super X, Y> getId(Class<Y> type);
336

337
    /**
338
     * Return the attribute that corresponds to the id attribute declared by the entity or mapped superclass
339
     * @param type the type of the represented declared id attribute
340
     * @return declared id attribute
341
     */
342
    <Y> SingularAttribute<X, Y> getDeclaredId(Class<Y> type);
343

344
    /**
345
     * Return the attribute that corresponds to the version attribute of the entity or mapped superclass
346
     * @param type the type of the represented version attribute
347
     * @return version attribute
348
     */
349
    <Y> SingularAttribute<? super X, Y> getVersion(Class<Y> type);
350

351
    /**
352
     * Return the attribute that corresponds to the version attribute declared by the entity or mapped superclass
353
     * @param type the type of the represented declared version attribute
354
     * @return declared version attribute
355
     */
356
    <Y> SingularAttribute<X, Y> getDeclaredVersion(Class<Y> type);
357

358
    /**
359
     * Return the identifiable type that corresponds to the most specific mapped superclass or entity
360
     * @return supertype
361
     */
362
    IdentifiableType<? super X> getSupertype();
363

364
    /**
365
     * Whether the identifiable type has a single id attribute
366
     * @return boolean indicating whether the identifiable type has a single id attribute
367
     */
368
    boolean hasSingleIdAttribute();
369

370
    /**
371
     * Whether the identifiable type has a version attribute
372
     * @return boolean indicating whether the identifiable type has a version attribute
373
     */
374
    boolean hasVersionAttribute();
375

376
    /**
377
     * Return the attributes corresponding to the id class of the identifiable type
378
     * @return id class attributes
379
     */
380
    Set<SingularAttribute<? super X, ?>> getIdClassAttributes();
381

382
    /**
383
     * Return the type that represents the type of the id
384
     * @return type of id
385
     */
386
    Type<?> getIdType();
387
}
388
```
389

390
### Attribute Types
391

392
Interfaces for representing entity and embeddable attributes.
393

394
```java { .api }
395
/**
396
 * Represents an attribute of a Java type
397
 * @since 2.0
398
 */
399
public interface Attribute<X, Y> {
400
    /**
401
     * Persistent attribute type enumeration
402
     */
403
    public static enum PersistentAttributeType {
404
        /** Many-to-one association */
405
        MANY_TO_ONE,
406
        /** One-to-one association */
407
        ONE_TO_ONE,
408
        /** Basic attribute */
409
        BASIC,
410
        /** Embeddable class attribute */
411
        EMBEDDED,
412
        /** Many-to-many association */
413
        MANY_TO_MANY,
414
        /** One-to-many association */
415
        ONE_TO_MANY,
416
        /** Element collection */
417
        ELEMENT_COLLECTION
418
    }
419

420
    /**
421
     * Return the name of the attribute
422
     * @return name
423
     */
424
    String getName();
425

426
    /**
427
     * Return the persistent attribute type for the attribute
428
     * @return persistent attribute type
429
     */
430
    PersistentAttributeType getPersistentAttributeType();
431

432
    /**
433
     * Return the managed type representing the type in which the attribute was declared
434
     * @return declaring type
435
     */
436
    ManagedType<X> getDeclaringType();
437

438
    /**
439
     * Return the Java type of the represented attribute
440
     * @return Java type
441
     */
442
    Class<Y> getJavaType();
443

444
    /**
445
     * Return the java.lang.reflect.Member for the represented attribute
446
     * @return corresponding java.lang.reflect.Member
447
     */
448
    java.lang.reflect.Member getJavaMember();
449

450
    /**
451
     * Is the attribute an association
452
     * @return boolean indicating whether the attribute corresponds to an association
453
     */
454
    boolean isAssociation();
455

456
    /**
457
     * Is the attribute collection-valued (represents a Collection, Set, List, or Map)
458
     * @return boolean indicating whether the attribute is collection-valued
459
     */
460
    boolean isCollection();
461
}
462

463
/**
464
 * Instances represent singular attributes (basic, embedded, many-to-one, one-to-one)
465
 * @since 2.0
466
 */
467
public interface SingularAttribute<X, T> extends Attribute<X, T>, Bindable<T> {
468
    /**
469
     * Is the attribute an id attribute
470
     * @return boolean indicating whether the attribute is an id attribute
471
     */
472
    boolean isId();
473

474
    /**
475
     * Is the attribute a version attribute
476
     * @return boolean indicating whether the attribute is a version attribute
477
     */
478
    boolean isVersion();
479

480
    /**
481
     * Is the attribute optional
482
     * @return boolean indicating whether the attribute is optional
483
     */
484
    boolean isOptional();
485

486
    /**
487
     * Return the type that represents the type of the attribute
488
     * @return type of attribute
489
     */
490
    Type<T> getType();
491
}
492

493
/**
494
 * Instances represent plural attributes (one-to-many, many-to-many, element collections)
495
 * @since 2.0
496
 */
497
public interface PluralAttribute<X, C, E> extends Attribute<X, C>, Bindable<E> {
498
    /**
499
     * Collection type enumeration
500
     */
501
    public static enum CollectionType {
502
        /** Collection */
503
        COLLECTION,
504
        /** Set */
505
        SET,
506
        /** List */
507
        LIST,
508
        /** Map */
509
        MAP
510
    }
511

512
    /**
513
     * Return the collection type
514
     * @return collection type
515
     */
516
    CollectionType getCollectionType();
517

518
    /**
519
     * Return the type representing the element type of the collection
520
     * @return element type
521
     */
522
    Type<E> getElementType();
523
}
524

525
/**
526
 * Instances represent persistent java.util.Collection-valued attributes
527
 * @since 2.0
528
 */
529
public interface CollectionAttribute<X, E> extends PluralAttribute<X, java.util.Collection<E>, E> {
530
}
531

532
/**
533
 * Instances represent persistent java.util.Set-valued attributes
534
 * @since 2.0
535
 */
536
public interface SetAttribute<X, E> extends PluralAttribute<X, java.util.Set<E>, E> {
537
}
538

539
/**
540
 * Instances represent persistent java.util.List-valued attributes
541
 * @since 2.0
542
 */
543
public interface ListAttribute<X, E> extends PluralAttribute<X, java.util.List<E>, E> {
544
}
545

546
/**
547
 * Instances represent persistent java.util.Map-valued attributes
548
 * @since 2.0
549
 */
550
public interface MapAttribute<X, K, V> extends PluralAttribute<X, java.util.Map<K, V>, V> {
551
    /**
552
     * Return the Java type of the map key
553
     * @return Java key type
554
     */
555
    Class<K> getKeyJavaType();
556

557
    /**
558
     * Return the type representing the key type of the map
559
     * @return type representing key type
560
     */
561
    Type<K> getKeyType();
562
}
563
```
564

565
**Usage Example:**
566

567
```java
568
Metamodel metamodel = entityManager.getMetamodel();
569
EntityType<Customer> customerType = metamodel.entity(Customer.class);
570

571
// Access singular attributes
572
SingularAttribute<Customer, String> nameAttr =
573
    customerType.getSingularAttribute("name", String.class);
574
boolean isOptional = nameAttr.isOptional();
575

576
// Access collection attributes
577
SetAttribute<Customer, Order> ordersAttr =
578
    customerType.getSet("orders", Order.class);
579
Type<Order> elementType = ordersAttr.getElementType();
580

581
// Iterate all attributes
582
for (Attribute<? super Customer, ?> attr : customerType.getAttributes()) {
583
    System.out.println("Attribute: " + attr.getName() +
584
                       ", Type: " + attr.getPersistentAttributeType());
585
}
586
```
587

588
### Static Metamodel
589

590
Annotation for generating type-safe metamodel classes.
591

592
```java { .api }
593
/**
594
 * Designates a class as a static metamodel for an entity, mapped superclass, or embeddable class
595
 * @since 2.0
596
 */
597
@Target(TYPE)
598
@Retention(RUNTIME)
599
public @interface StaticMetamodel {
600
    /**
601
     * Class being modeled by the annotated class
602
     * @return class being modeled
603
     */
604
    Class<?> value();
605
}
606
```
607

608
**Usage Example:**
609

610
```java
611
@Entity
612
public class Customer {
613
    @Id
614
    private Long id;
615
    private String name;
616
    private String email;
617

618
    @OneToMany(mappedBy = "customer")
619
    private Set<Order> orders;
620
}
621

622
// Generated static metamodel class
623
@StaticMetamodel(Customer.class)
624
public class Customer_ {
625
    public static volatile SingularAttribute<Customer, Long> id;
626
    public static volatile SingularAttribute<Customer, String> name;
627
    public static volatile SingularAttribute<Customer, String> email;
628
    public static volatile SetAttribute<Customer, Order> orders;
629
}
630

631
// Usage in Criteria API
632
CriteriaBuilder cb = entityManager.getCriteriaBuilder();
633
CriteriaQuery<Customer> query = cb.createQuery(Customer.class);
634
Root<Customer> customer = query.from(Customer.class);
635

636
// Type-safe queries using static metamodel
637
query.select(customer)
638
     .where(cb.equal(customer.get(Customer_.name), "John"));
639
```
640