Creating your own Rest Plugin ( extending REST API )

To create your own REST plugin you must create a new class that implements RestPlugin interface: 

public interface RestPlugin extends Plugin {
    
    Object executePlugin(Map<String, String> parameters, InputStream is);
    
}

The new class must be located into the package com.openkm.plugin.rest because the application plugins system will try to load it from there. See the sample below: 

Method description

Example of REST plugin implementation

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();
    }
}

Example of REST plugin implementation what returns file

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;
	}
} 

Objects declaration

The method executionPlugin returns an Object. This object will be processed - marshall - by OpenKM. Basic types like String, Integer, etc. can be directly used, but for complex objects you need to use annotation on classes.

Marshall and unmarshall strategies:

• The result of the executed method is always an String. Internally the method converts the complex objects to JSON.
• The result of the executed mehod is a complex Object.

String scenario

From the plugin side - server side - you must convert the Object to JSON:

return new Gson().toJson(someObject)

From the cliend side you must convert JSON String to Object:

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

Complex Object scenario

You can use existing OpenKM classes like Document, Folder, Record, Mail among others, because theses clases have already the annotation.

Example of complex classes:

Return a list of Strings:

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;
    }
}

Return a list of Mails:

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;
    }
}

Complex object:

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();
    }
}