How to use Hibernate @Any-related annotations?

Question

Could someone explain to me how Any-related annotations (@Any, @AnyMetaDef, @AnyMetaDefs and @ManyToAny) work in practice. I have a hard time finding any useful documentation (JavaDoc alone isn't very helpful) about these.

I have thus far gathered that they somehow enable referencing to abstract and extended classes. If this is the case, why is there not an @OneToAny annotation? And is this 'any' referring to a single 'any', or multiple 'any'?

A short, practical and illustrating example would be very much appreciated (doesn't have to compile).

Edit: as much as I would like to accept replies as answers and give credit where due, I found both Smink's and Sakana's answers informative. Because I can't accept several replies as the answer, I will unfortunately mark neither as the answer.

Answer 1

Hope this article brings some light to the subject:

Sometimes we need to map an association property to different types of entities that don't have a common ancestor entity - so a plain polymorphic association doesn't do the work.

For example let's assume three different applications which manage a media library - the first application manages books borrowing, the second one DVDs, and the third VHSs. The applications have nothing in common. Now we want to develop a new application that manages all three media types and reuses the exiting Book, DVD, and VHS entities. Since Book, DVD, and VHS classes came from different applications they don't have any ancestor entity - the common ancestor is java.lang.Object. Still we would like to have one Borrow entity which can refer to any of the possible media type.

To solve this type of references we can use the any mapping. this mapping always includes more than one column: one column includes the type of the entity the current mapped property refers to and the other includes the identity of the entity, for example if we refer to a book it the first column will include a marker for the Book entity type and the second one will include the id of the specific book.

@Entity @Table(name = "BORROW") public class Borrow{      @Id     @GeneratedValue     private Long id;      @Any(metaColumn = @Column(name = "ITEM_TYPE"))     @AnyMetaDef(idType = "long", metaType = "string",              metaValues = {               @MetaValue(targetEntity = Book.class, value = "B"),              @MetaValue(targetEntity = VHS.class, value = "V"),              @MetaValue(targetEntity = DVD.class, value = "D")        })     @JoinColumn(name="ITEM_ID")     private Object item;       .......     public Object getItem() {         return item;     }      public void setItem(Object item) {         this.item = item;     }  }