Short version: it's in the spec so you have to allow and implement it. Long version:

Say you have a LOCATION table as follows ("*" = PK;"+" = required):

• id*
• name+
  ...

Since a Location can have multiple "parent" locations, you have a relation table LOCATION_PARENT:

• location_id*
• parent_location_id*

Your entity class would start out as this:

@Entity
public class Location ... {

private String name;

@ManyToMany
@JoinTable(
name = "LOCATION_PARENT",
joinColumns = { @JoinColumn(name = "LOCATION_ID") },
inverseJoinColumns = { @JoinColumn(name = "PARENT_LOCATION_ID") }
)
private Set<Location> parentLocations;

...
}

So far so good. But what if you also want to include a Set of child Locations? You obviously don't need another join table--you can reuse the old one. Your class becomes this:

@Entity
public class Location ... {

private String name;

@ManyToMany
@JoinTable(
name = "LOCATION_PARENT",
joinColumns = { @JoinColumn(name = "LOCATION_ID") },
inverseJoinColumns = { @JoinColumn(name = "PARENT_LOCATION_ID") }
)
private Set<Location> parentLocations;

@ManyToMany
@JoinTable(
name = "LOCATION_PARENT",
joinColumns = { @JoinColumn(name = "PARENT_LOCATION_ID") },
inverseJoinColumns = { @JoinColumn(name = "LOCATION_ID") }
)
private Set<Location> childLocations;

...
}

This is perfectly valid and works, but there is one problem: when you insert new entities, hibernate/eclipselink/everyone attempts (correctly) to insert two entries into the LOCATION_PARENT table (one for each field). The insert fails because of this. The way you tell the persistence manager NOT to add an entry for one of the fields is by delegating responsibility to the other field with the "mappedBy" attribute:

@ManyToMany(mappedBy = "parentLocations")
@JoinTable(
name = "LOCATION_PARENT",
joinColumns = { @JoinColumn(name = "PARENT_LOCATION_ID") },
inverseJoinColumns = { @JoinColumn(name = "LOCATION_ID") }
)
private Set<Location> childLocations;

This works everywhere but in Hibernate. Hibernate gives this "I know better than you what you're doing" error:

org.hibernate.AnnotationException: Associations marked as mappedBy must not define database mappings like @JoinTable or @JoinColumn: com.ijet.cwt.domain.Location.childLocations

Thank you.