What is envers @AuditMappedBy() supposed to do?

Question

I am using Hibernate-Envers 4.3.11 Final

I see that the documentation says:

To properly audit such relations with Envers, you can use the @AuditMappedBy annotation. It enables you to specify the reverse property (using the mappedBy element). In case of indexed collections, the index column must also be mapped in the referenced entity (using @Column( insertable=false, updatable=false ), and specified using positionMappedBy. This annotation will affect only the way Envers works. Please note that the annotation is experimental and may change in the future.

What does the docs mean when it says "specify the reverse property"?

I have several entities that have collections with ManyToOne and ManyToMany links and I want to audit the entities and their relations and be able to retrieve revisions. But I can't seem to be able to traverse through the data down to the collections of the child entities that I'm retrieving, so I am guessing I am not auditing the relation between entities correctly?

So I think I need to use @AuditMappedBy().

But I am confused because whether I use @AuditMappedBy(MappedBy = "NAME") on the columns that are the collections or @audited at the top of my entities, I see the same results in the audit tables and in the data when I retrieve my entities. I have yet to see why I would use @AuditMappedBy().

Can someone help me understand a use case for @AuditMappedBy()?

Example of the hierarchy of table and how I need to traverse to collections in child tables:

**TABLE A:**

@Entity()
@Audited
@Table(name = "TABLE_A")

@Column(name = "ID")
private Long id;
@Column(name = "NAME", length = 50)
private String name;

@OneToMany(
            mappedBy = "table_a",
            cascade = {CascadeType.MERGE, CascadeType.PERSIST}
    )
    @org.hibernate.annotations.Cascade(
            {org.hibernate.annotations.CascadeType.SAVE_UPDATE, org.hibernate.annotations.CascadeType.DELETE_ORPHAN}
    )
    private Collection<TABLE_B> table_b = new ArrayList<TABLE_B>();




**TABLE B:**


@Entity()
@Audited
@Table(name = "TABLE_B")

@Column(name = "ID")
private Long id;
@Column(name = "NAME", length = 50)
private String name;

@XmlTransient
@ManyToOne()
@JoinColumn(name = "ID_TABLE_B", nullable = false)
private TABLE_A table_a;

@ManyToOne(
        cascade = {CascadeType.MERGE, CascadeType.PERSIST})
@org.hibernate.annotations.Cascade(
        {org.hibernate.annotations.CascadeType.SAVE_UPDATE}
)
@JoinColumn(name = "ID_TABLE_C")
private TABLE_C table_c;

@ManyToOne(
        cascade = {CascadeType.MERGE, CascadeType.PERSIST})
@org.hibernate.annotations.Cascade(
        {org.hibernate.annotations.CascadeType.SAVE_UPDATE}
)
@JoinColumn(name = "ID_TABLE_D", nullable = true)
private TABLE_D table_d;



**TABLE C:**

@Entity()
@Audited
@Table(name = "TABLE_C")

@Column(name = "ID")
private Long id;
@Column(name = "NAME", length = 50)
private String name;


@OneToMany(
        mappedBy = "table_c",
        cascade = {
                CascadeType.REMOVE})
@org.hibernate.annotations.Cascade(
        {org.hibernate.annotations.CascadeType.SAVE_UPDATE,
                org.hibernate.annotations.CascadeType.MERGE,
                org.hibernate.annotations.CascadeType.DELETE_ORPHAN}
)
@XmlTransient
private Collection<TABLE_B> table_b = new HashSet<TABLE_B>();



**TABLE D:**

@Entity()
@Audited
@Table(name = "TABLE_D")

@Column(name = "ID")
private Long id;
@Column(name = "NAME", length = 50)
private String name;

@XmlTransient
@OneToMany(
        mappedBy = "table_d",
        cascade = {CascadeType.MERGE, CascadeType.PERSIST}
)
private Collection<TABLE_B> table_b = new ArrayList<TABLE_B>();