Синтаксис Java EE SqlResultSetMapping

Документы по аннотациям Hibernate (http://www.hibernate.org/hib_docs/annotations/reference/en/html_single/) предполагают, что это должна быть аннотация уровня класса, а не встроенная в ваш код. И действительно, когда я вставляю этот код в свою среду IDE и перемещаю его, ошибки компиляции присутствуют, когда аннотация встроена, но исчезают, когда я помещаю ее над объявлением класса:

@SqlResultSetMapping( name = "TripResults",
        entities = {
            @EntityResult( entityClass=TripEntity.class ),
            @EntityResult( entityClass=CommercialTripEntity.class )
        }
    )
public class Foo {
   public void bogus() {
      Query q = em.createNativeQuery( 
        "select T.* " +
        "from Trip T join Itinerary I on (T.itinerary_id=I.id) " +
        "where I.launchDate between :start and :end " +
        "or ADDDATE(I.launchDate, I.equipmentPullDayOfTrip) between :start and :end",
        "TripResults" );

      q.setParameter( "start", range.getStart(), TemporalType.DATE );
      q.setParameter( "end", range.getEnd(), TemporalType.DATE );
   }
}

... очевидно, у меня нет доказательств того, что приведенный выше код действительно будет работать. Я только убедился, что это не вызывает ошибок компиляции.

Ваш пример взят прямо из документации API, которая, к сожалению, плохо представлена.

Ваша аннотация должна быть размещена в каком-то классе, вероятно, в том, в котором вы будете создавать запрос для использования сопоставления набора результатов. Однако на самом деле не имеет значения, где размещена эта аннотация. Ваш провайдер JPA фактически будет поддерживать глобальный список всех этих сопоставлений, поэтому независимо от того, где вы его определяете, вы сможете использовать его где угодно.

Это недостаток метода аннотации (в отличие от указания вещей в XML). Многие другие вещи в JPA (то есть именованные запросы) определяются таким же образом. Создается впечатление, что существует какая-то связь между определяемой вещью и классом, для которого она аннотирована, когда это не так.