Bonus - Contribute Your Own Enricher

We've covered the basics of Nuxeo REST API. But there are some functionalities we left aside: Users / Groups management, and Directories. Feel free to take a look at their corresponding classes.

For now we will extend the REST API by contributing a custom content enricher. In order to contribute a content enricher, you need to:

• Create the content enricher
• Declare the content enricher
• Call the content enricher

Creating the Content Enricher

A content enricher is a Java class that:

• Extends the AbstractJsonEnricher class for a defined object (e.g.: AbstractJsonEnricher<DocumentModel> for a document)
• Contains a @Setup annotation before the class declaration in order to define:
  • How the class will be instantiated (usually as a singleton)
  • Which class will have the highest priority in case of naming conflict
• Uses the Jackson library to generate the JSON to be added in the response.

Here is a commented sample below:

package org.nuxeo.sample.enrichers;

import static org.nuxeo.ecm.core.io.registry.reflect.Instantiations.SINGLETON;
import static org.nuxeo.ecm.core.io.registry.reflect.Priorities.REFERENCE;

import java.io.IOException;

import org.codehaus.jackson.JsonGenerator;
import org.codehaus.jackson.map.ObjectMapper;
import org.codehaus.jackson.node.ObjectNode;
import org.nuxeo.ecm.core.api.CoreSession;
import org.nuxeo.ecm.core.api.DocumentModel;

// The class is instantiated as a singleton
// Priority defines which marshaller is used in case of conflict. Priority is an integer.
// The higher the number, the higher the priority: 10 > 1 for instance.

@Setup(mode = SINGLETON, priority = REFERENCE)
public class ParentDocEnricher extends AbstractJsonEnricher<DocumentModel> {

// The enricher is called using enrichers.document: parentDoc
    public static final String NAME = "parentDoc";

    public ParentDocEnricher() {
        super(NAME);
    }

// Method that is called when the enricher is called
    @Override
    public void write(JsonGenerator jg, DocumentModel doc) throws IOException {
      ObjectNode parentDocJsonObject = addParentDocAsJson(doc);
      jg.writeFieldName(NAME);
      jg.writeObject(parentDocJsonObject);
    }

    private ObjectNode addParentDocAsJson(DocumentModel doc) {
      ObjectMapper o = new ObjectMapper();

      // First create the parent document's JSON object content
      CoreSession session = doc.getCoreSession();
      DocumentModel parentDoc = session.getDocument(doc.getParentRef());

      ObjectNode parentObject = o.createObjectNode();
      parentObject.put("id", parentDoc.getRef().toString());
      parentObject.put("title", parentDoc.getTitle());
      parentObject.put("description", parentDoc.getPropertyValue("dc:description").toString());

      return parentObject;
    }
}

Now it's your turn!

Practice - Contribute a Content Enrichers

This exercise requires some familiarity with Java.

Create the content enricher

1. Download LastVersionEnricher.java or open in another tab to copy and add to your project.
2. In the Java class, retrieve the CoreSession from the DocumentModel object.
3. Retrieve the last document version from the CoreSession.
4. Use the JsonGenerator object to write a field with the enricher name.
5. Use the JsonGenerator object to write an object with the last document version.

• Solution

  package org.nuxeo.sample;
              import static org.nuxeo.ecm.core.io.registry.reflect.Instantiations.SINGLETON;
              import static org.nuxeo.ecm.core.io.registry.reflect.Priorities.REFERENCE;
              import java.io.IOException;
              import org.codehaus.jackson.JsonGenerator;
              import org.nuxeo.ecm.core.api.CoreSession;
              import org.nuxeo.ecm.core.api.DocumentModel;
              import org.nuxeo.ecm.core.io.marshallers.json.enrichers.AbstractJsonEnricher;
              import org.nuxeo.ecm.core.io.registry.reflect.Setup;
              @Setup(mode = SINGLETON, priority = REFERENCE)
              public class LastVersionEnricher extends AbstractJsonEnricher<DocumentModel> {
                  public static final String NAME = "lastVersion";
                  public SampleEnricher() {
                      super(NAME);
                  }
                  // Method that will be called when the enricher is asked for
                  @Override
                  public void write(JsonGenerator jg, DocumentModel doc) throws IOException {
                    // TODO: Retrieve the CoreSession from the DocumentModel object
                    CoreSession session = doc.getCoreSession();
                    // TODO: Retrieve the CoreSession from the DocumentModel object
                    DocumentModel lastVersion = session.getLastDocumentVersion(doc.getRef());
                    // TODO: Use the JsonGenerator object to write a field with the enricher name
                    jg.writeFieldName(NAME);
                    // TODO: Use the JsonGenerator object to write an object with the last document version
                    jg.writeObject(lastVersion);
                  }
              }
              

Declare the content enricher

1. Declare the content enricher through Nuxeo Studio, or by adding an XML file in your Java project's src/main/resources/OSGI-INF folder. Here is a sample.

2. If you declare it in your Java project, make sure to reference it in the project's manifest.mf file in the src/main/resources/META-INF folder, in the Nuxeo-Component list:

   Manifest.mf Extract

   Nuxeo-Component:OSGI-INF/org.nuxeo.sample.enrichers.parentDocEnricher.xml,OSGI-INF/org.nuxeo.sample.another-contribution.xml, ...
   

Now you can declare yours!

1. Declare the content enricher in your Java project.
2. Reference the component in the bundle's manifest file.

Call the content enricher

Now that the enricher is created, you need to package and deploy your application, then you can call it! Your enricher name is the one you put inside the NAME variable.