Adding Client API Support To A Filesystem

The client API feature was added in the JFileServer 1.4.0/JFileServer Enterprise 1.3.0 release, as an optional interface a filesystem can implement. The client API interface allows a client to send requests to the file server over existing protocols, currently SMB2 and SMB3 protocols are supported. A filesystem must implement the core DiskInterface, and can then add other functionality using optional interfaces such as to implement file locking, or in this case the client API interface.

The client API uses a special path on the server that the client can write a request into, and receives the response from the server. The special path is not visible in folder listings. The main implementation uses JSON format to send request and for the response, but you can implement your own format of request and response by implementing the lower level ClientAPIInterface, rather than extending the JSONClientAPI implementation.

The JSON client API has a client side application, currently for Windows 10 and 11, that provides a right click context menu into the Windows File Explorer application, with a configurable set of sub-menus that trigger server side actions. The client side application is also able to display message boxes and other user interface items before and after an action has run, show notifications, run applications and open URLs all under control of the server side actions.

The fileServersNG Alfresco add-on module contains a reference implementation of a client API, extending the JSONClientAPI. There is a Wiki document that describes the fileServersNG client API implementation here, and the source code for the fileServersNG implementation is here.

This document describes how to implement a client API by extending the JSONClientAPI implementation.

Filesystem Requirements

To enable client API support a filesystem must implement the optional org.filesys.server.filesys.clientapi.ClientAPI interface, with a client API implementation class that either implements the base org.filesys.server.filesys.clientapi.ClientAPIInterface interface or extends the org.filesys.server.filesys.clientapi.json.JSONClientAPI abstract class.

The ClientAPI interface has two methods :-

Method	Description
public boolean isClientAPIEnabled()	Returns true is the client API is enabled for this filesystem, else false
public ClientAPIInterface getClientAPI(SrvSession<?> sess, TreeConnection tree)	Returns the ClientAPI implementation that handles the requests from the client

The base ClientAPIInterface interface has the following methods :-

Method	Description
public String getClientAPIPath()	Returns the special path that the client will write requests and receive responses via. The path should be a path that is relative to the root of the filesystem, eg. \__CLIENT_API__
public ClientAPINetworkFile openClientAPIFile(SrvSession<?> sess, TreeConnection tree, FileOpenParams params)	Returns a special in-memory file that represents a file open to the special client API path. The in-memory file is created per file open, it is not shared between users or sessions
public void processRequest( ClientAPINetworkFile netFile)	Process a client request received via the specified client API file. The request data can be retrieved using the byte[] netFile.getRequestData() method. The response is written to the client API file using the setResponseData( byte[]) method.