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, for the JSONClientAPI. implementation the special path is \__JSONAPI__
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.

The JSONClientAPI implementation handles all of the ClientAPIInterface methods, and adds the following methods that must be implemented or can be overridden :-

Method	Description
public EnumSet<ApiRequest> getSupportedRequests()	Returns the set of API requests that this implementation supports. The APIRequest enum has the values GetAPIInfo, GetURLForPath, GetPathStatus and RunAction. This method must be implemented. The JSONClientAPI implements the GetAPIInfo request, so that must be included in the supported requests list. The RunAction API request should be included if you want to handle custom actions in your API implementation.
public ContextMenu getContextMenu()	Return the context menu details with the top level menu title and icon, plus the list of server actions that will be displayed on a sub-menu of the client context menu. This method must be implemented.
public String getClientAPIVersion()	Return the client API version in n.n.n.n format. This method must be implemented.
protected void preProcessRequest( ClientAPINetworkFile netFile, ClientAPIRequest req)	Optional method that can be overridden to handle a client request before the main request handler processes the request.
public ClientAPIResponse processGetURLForPath( GetURLForPathRequest req)	Optional method that should be overridden if the client API GetURLForPath API request is supported. The GetURLForPathRequest object contains the relative path of the file or folder that was selected on the client.
public ClientAPIResponse processGetPathStatus( GetPathStatusRequest req)	Optional method that should be overridden if the client API GetPathStatus API request is supported. The GetPathStatusRequest object contains a list of the relative paths that were selected on the client and a check type value for the path status to be checked.
public ClientAPIResponse processRunAction( RunActionRequest req, ClientAPINetworkFile netFile)	This method handles processes running a server side action associated with a context menu. The RunActionRequest object contains the action name, a list of one or more relative paths that were selected on the client and an optional list of parameter values.