Crear su propio plugin Rest (ampliar la API REST)

Para crear su propio plugin REST debe crear una nueva clase que implemente la interfaz RestPlugin:

public interface RestPlugin extends Plugin {

    Object executePlugin(Map<String, String> parameters, InputStream is);

}

La nueva clase debe ubicarse en el paquete com.openkm.plugin.rest, porque el sistema de plugins de la aplicación intentará cargarla desde ahí. Consulte el ejemplo a continuación:

Descripción del método

Método	Tipo	Descripción
executePlugin	String	El método ejecuta un plugin REST y devuelve un objeto.

Ejemplo de implementación de un plugin REST

package com.openkm.plugin.rest;

import java.util.Map;

import net.xeoh.plugins.base.annotations.PluginImplementation;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

/**
 * Sample REST plugin
 *
 */
@PluginImplementation
public class TestRestPlugin implements RestPlugin {
    private static Logger log = LoggerFactory.getLogger(TestRestPlugin.class);

    @Override
    public Object executePlugin(Map<String, String> parameters, InputStream is) {
        log.debug("executePlugin({})", parameters);
        StringBuilder sb = new StringBuilder("{");
        sb.append("className=").append(this.getClass().getCanonicalName());
        for (String key : parameters.keySet()) {
            sb.append(", "+key+"=").append(parameters.get(key));
        }
        sb.append("}");
        return sb.toString();
    }
}

Ejemplo de implementación de un plugin REST que devuelve un archivo

package com.openkm.plugin.rest;

import com.openkm.bean.Document;
import com.openkm.integration.cifs.device.PathUtils;
import com.openkm.module.DocumentModule;
import com.openkm.module.ModuleManager;
import net.xeoh.plugins.base.annotations.PluginImplementation;
import org.apache.commons.io.IOUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import javax.ws.rs.WebApplicationException;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.StreamingOutput;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.Map;

/**
 * Sample rest plugin
 */
@PluginImplementation
public class TestGetDocumentRestPlugin implements RestPlugin {
  private static Logger log = LoggerFactory.getLogger(TestGetDocumentRestPlugin.class);

  @Override
  public Object executePlugin(Map<String, String> parameters, InputStream is) throws Exception {
    log.debug("executePlugin({})", parameters);
    DocumentModule dm = ModuleManager.getDocumentModule();
    String docId = parameters.get("docId");
    boolean inline = parameters.containsKey("inline");
    Document doc = dm.getProperties(null, docId);
    String mimeType = doc.getMimeType();
    String fileName = PathUtils.getFileNameFromPath(doc.getPath());
    final InputStream isContent = dm.getContent(null, docId, false);

    StreamingOutput stream = new StreamingOutput() {
      @Override
      public void write(OutputStream os) throws IOException, WebApplicationException {
        IOUtils.copy(isContent, os);
        IOUtils.closeQuietly(isContent);
        IOUtils.closeQuietly(os);
      }
    };

    Response.ResponseBuilder response = Response.ok(stream);
    response.type(mimeType); // because the method produces MediaType.APPLICATION_OCTET_STREAM can be set any document mime type

    // inline true when you want to embedded the content into
    if (inline) {
      response.header("Content-disposition", "inline; filename=\"" + fileName + "\"");
    } else {
      response.header("Content-Disposition", "attachment; filename=\"" + fileName + "\"");
    }

    return response;
  }
}

Declaración de objetos

El método executionPlugin devuelve un Object. Este objeto será procesado (marshall) por OpenKM. Los tipos básicos como String, Integer, etc. pueden utilizarse directamente, pero para objetos complejos necesita utilizar anotaciones en las clases.

Estrategias de marshall y unmarshall:

El resultado del método ejecutado es siempre un String. Internamente, el método convierte los objetos complejos a JSON.
El resultado del método ejecutado es un Object complejo.

Escenario String

Desde el lado del plugin (lado servidor) debe convertir el Object a JSON:

return new Gson().toJson(someObject)

Desde el lado cliente debe convertir el String JSON a Object:

// value contains the returned String value by the REST call
SomeObject someObject = new Gson().fromJson(value, SomeObject.class);

Escenario Object complejo

Puede utilizar clases existentes de OpenKM como Document, Folder, Record, Mail, entre otras, porque estas clases ya tienen la anotación.

Ejemplo de clases complejas:

Devolver una lista de String:

package com.openkm.ws.rest.util;

import java.util.ArrayList;
import java.util.List;

import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement(name = "languages")
public class LanguageList {
    @XmlElement(name = "language", required = true)
    List<String> languages = new ArrayList<String>();

    public List<String> getList() {
        return languages;
    }
}

Devolver una lista de Mail:

package com.openkm.ws.rest.util;

import com.openkm.bean.Mail;

import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;
import java.util.ArrayList;
import java.util.List;

@XmlRootElement(name = "mails")
public class MailList {
    @XmlElement(name = "mail", required = true)
    List<Mail> mails = new ArrayList<Mail>();

    public List<Mail> getList() {
        return mails;
    }
}

Objeto complejo:

package com.openkm.bean;

import javax.xml.bind.annotation.XmlRootElement;

/**
 * Record
 */
@XmlRootElement(name = "record")
public class Record {
    private static final long serialVersionUID = 1L;

    public static final String TYPE = "okm:record";
    public static final String NAME = "okm:name";

    private boolean locked;
    private LockInfo lockInfo;
    private String title;

    public boolean isLocked() {
        return locked;
    }

    public void setLocked(boolean locked) {
        this.locked = locked;
    }

    public LockInfo getLockInfo() {
        return lockInfo;
    }

    public void setLockInfo(LockInfo lockInfo) {
        this.lockInfo = lockInfo;
    }

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }

    public String toString() {
        StringBuilder sb = new StringBuilder();
        sb.append("{");
        sb.append("path=").append(path);
        sb.append(", permissions=").append(permissions);
        sb.append(", created=").append(created == null ? null : created.getTime());
        sb.append(", subscribed=").append(subscribed);
        sb.append(", subscriptors=").append(subscriptors);
        sb.append(", uuid=").append(uuid);
        sb.append(", keywords=").append(keywords);
        sb.append(", categories=").append(categories);
        sb.append(", notes=").append(notes);
        sb.append(", locked=").append(locked);
        sb.append(", lockInfo=").append(lockInfo);
        sb.append(", title=").append(title);
        sb.append("}");
        return sb.toString();
    }
}