Listeners: What are conversion listeners and how to work with them?

Conversion listeners provide users with hook for an additional logic when converting an entity to a document/metadata pair and backwards.

IDocumentConversionListener provides methods to inject custom actions before or after actual document/entity conversion.

public interface IDocumentConversionListener {
  /**
   * Called before converting an entity to a document and metadata
   * @param key
   * @param entity
   * @param metadata
   */
  void beforeConversionToDocument(String key, Object entity, RavenJObject metadata);

  /**
   * Called after having converted an entity to a document and metadata
   * @param key
   * @param entity
   * @param document
   * @param metadata
   */
  void afterConversionToDocument(String key, Object entity, RavenJObject document, RavenJObject metadata);

  /**
   * Called before converting a document and metadata to an entity
   * @param key
   * @param document
   * @param metadata
   */
  void beforeConversionToEntity(String key, RavenJObject document, RavenJObject metadata);

  /**
   * Called before converting a document and metadata to an entity
   * @param key
   * @param document
   * @param metadata
   * @param entity
   */
  void afterConversionToEntity(String key, RavenJObject document, RavenJObject metadata, Object entity);
}

Example

Let's consider a case that we want to convert a metadata value provided by RavenDB server to a property of our class. To achieve this we are going to ignore the property after the entity is converted to the document and set the value of this property after the entity is created from the document/metadata pair.

public static class Item {
  private String id;
  private String name;
  private String revision;
  public String getId() {
    return id;
  }
  public void setId(String id) {
    this.id = id;
  }
  public String getName() {
    return name;
  }
  public void setName(String name) {
    this.name = name;
  }
  public String getRevision() {
    return revision;
  }
  public void setRevision(String revision) {
    this.revision = revision;
  }
}

public static class MetadataToPropertyConversionListener implements IDocumentConversionListener {
  @Override
  public void beforeConversionToDocument(String key, Object entity, RavenJObject metadata) {
    //empty by design
  }

  @Override
  public void afterConversionToDocument(String key, Object entity, RavenJObject document, RavenJObject metadata) {
    if (!(entity instanceof Item)) {
      return ;
    }
    document.remove("Revision");
  }

  @Override
  public void beforeConversionToEntity(String key, RavenJObject document, RavenJObject metadata) {
    //empty by design
  }

  @Override
  public void afterConversionToEntity(String key, RavenJObject document, RavenJObject metadata, Object entity) {
    if (!(entity instanceof Item)) {
      return;
    }
    ((Item)entity).setRevision(metadata.value(String.class, "Raven-Document-Revision"));
  }

}