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 a 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 source code for the client API interfaces and classes is available here.

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.
public String getClientAPIVersion()	Return the client API version in n.n.n.n format. This method must be implemented.
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.
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.

Implementing getSupportedRequests()

The JSONClientAPI implements a GetAPIInfo request that is used by the client to probe that the network drive supports the client API, and returns information about the API including the context menu title, description and icon details plus the sub-menu details that includes details of each server action.

Here is a sample context menu from the fileServersNG client API implementation :-

In the fileServersNG context menu example the context menu title is Alfresco Drive with a custom icon. The sub-menu contains the list of server actions such as Check In and Check Out.

Each server action on the sub-menu has an action name, description, details about the file and/or folder selections the action accepts, an optional user interface action to be run before the action request is sent to the server and an optional icon definition.

As the JSONClientAPI implements the GetAPIInfo request, 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. A sample implementation of the getSupportedRequests() method :-

public EnumSet<ApiRequest> getSupportedRequests() {
  return EnumSet.of ( ApiRequest.GetApiInfo, ApiRequest.RunAction);
}

Implementing getClientAPIVersion()

The getClientAPIVersion() method is called by the GetAPIInfo request processing when collecting details about the client API implementation. The method should return a version string with the format <major>.<minor>.<patch>.

A sample implementation of the getClientAPIVersion() method :-

public String getClientAPIVersion() {
  return "1.0.0";
}

Implementing getContextMenu()

The getContextMenu() method is called by the GetAPIInfo request processing when collecting details about the client API implementation. The method returns a ContextMenu object that defines the top level context menu and the server actions used for the sub-menu.

A ContextMenu object is created using the constructor ContextMenu(String title, String description, ActionIcon icon) where title is the menu title that will be shown on the File Explorer right click context menu, description may be used as a tooltip, and icon defines the icon to be displayed for the context menu.

The ContextMenu needs a list of ServerAction objects to be attached using the setActions( List<ServerAction>) method, this defines the items that will be shown on the sub-menu of the context menu.

ActionIcon

The ActionIcon class defines an icon on the client. The icon may be included in the client API context menu DLL, in the Windows shell32.dll system file or you can define a custom icon from another Windows system DLL.

There are convenience methods on the ActionIcon class for creating the different types of icon. To define an icon that is contained in the client API context menu DLL use the ActionIcon.createAppIcon(int) method, to define an icon that is contained in the Windows shell32.dll system file use the ActionIcon.createShellIcon(int) method, and to create a custom icon use the ActionIcon.createCustomIcon(int, String). For a custom icon the values are the index of the icon (should be a negative number) and the name of the Windows system file that contains the icon (without any path).

An ActionIcon can also be created using a name, using the ActionIcon.createByName(String) method, this is useful if the context menu is defined a configuration file.

The table below lists the available ActionIcon types, ids and names. Id types are ActionIcon.IconType enum values :-

Icon	Name	Type	Id	Description
	ShellScript	Shell	ActionIcon.SHELLICON_SCRIPT	Script icon
	ShellWebBrowser	Shell	ActionIcon.SHELLICON_WEBBROWSER	Web browser icon
	ShellFolder	Shell	ActionIcon.SHELLICON_FOLDER	Folder icon
	ShellPrinter	Shell	ActionIcon.SHELLICON_PRINTER	Printer icon
	ShellMagnify	Shell	ActionIcon.SHELLICON_MAGNIFY	Magnifying glass icon
	ShellStar	Shell	ActionIcon.SHELLICON_STAR	Star icon
	ShellLock	Shell	ActionIcon.SHELLICON_LOCK	Lock icon
	ShellMovie	Shell	ActionIcon.SHELLICON_MOVIE	Movie icon
	ShellAudio	Shell	ActionIcon.SHELLICON_AUDIO	Audio icon
	ShellCamera	Shell	ActionIcon.SHELLICON_CAMERA	Camera icon
	ShellInformation	Shell	ActionIcon.SHELLICON_INFORMATION	Information icon
	ShellHome	Shell	ActionIcon.SHELLICON_HOME	Home icon
	ShellGear	Shell	ActionIcon.SHELLICON_GEAR	Gear icon
	FileSysOrgAlfresco	App	ActionIcon.APPICON_FILESYSORG_ALFRESCO	Filesys.org Alfresco application icon
	FileSysOrg	App	ActionIcon.APPICON_FILESYSORG	Filesys.org application icon
	AlfrescoCheckIn	App	ActionIcon.APPICON_ALFRESCO_CHECKIN	Alfresco check in icon
	AlfrescoCheckOut	App	ActionIcon.APPICON_ALFRESCO_CHECKOUT	Alfresco check out icon

ServerAction

The ServerAction class defines a server-side action that will be displayed on the client context menu sub-menu, this includes details of the menu name, description and icon plus details of what type of file/folder selections the action accepts, and an optional user interface action for the client to run before sending the action request to the server, such as displaying an acknowledgement message dialog with Ok/Cancel buttons.

To create a server-side action you must extend the ServerAction class. The ServerAction class requires an action name, that will be used as the menu title, a description and a set of flags that define what combination of file/folder selections the action accepts. The ServerAction.Flags enum class defines the available flags, which are also defined below :-

Flag	Description
Files	Action accepts file selections
Folders	Action accepts folder selections
MultiSelect	Action accepts multiple file and/or folder selections

For example, a flags value of EnumSet.of( Flags.Files) would indicate the action only accepts a single file selection. If multiple files are selected on the client, or a folder is selected, the server action sub-menu will be greyed out and not selectable by the user. A flags value of EnumSet.of( Flags.Files, Flags.MultiSelect) would indicate the action accepts file selections with one or more files selected.

A ServerAction can have an optional icon defined, using the same ActionIcon class that the top level context menu uses. Set the icon using the appropriate ServerAction constructor, or using the setIcon(ActionIcon) method. If no icon is defined for a server action the sub-menu item will be shown with no icon.

A ServerAction can have an optional user interface action that will instruct the client application to display a user interface item such as a message box. If the user interface item has an option to cancel such as Ok/Cancel buttons then the action will not be triggered on the server if the cancel option is selected by the user.

A user interface action is configured for a server action using the setUIAction(ClientUIAction) method. The ClientUIAction has the type of user interface item to be displayed with an optional title, message text and the message severity for message box dialogs. The available ClientUIAction.UIAction types are shown below :-

UIAction	Description
MessageDialog	Display a message box dialog with an Ok button.
YesNoDialog	Display a message box dialog with Yes and No buttons. If the No button is selected by the user the action will not be run.
OkCancelDialog	Display a message box dialog with Ok and Cancel buttons. If the Cancel button is selected by the user the action will not be run.
CheckInDialog	Displays a custom dialog that lists the selected file(s) with a comment input field and buttons Check In, Cancel Checkout and Cancel. An example of the check in dialog :- If the Check In button is selected the action is run with the request parameters containing a value of checkin, if the Cancel Checkout button is selected the action is run with the request parameters containing a value of cancel. Selecting the Cancel button will not run the server action.

If the title is not set for a ClientUIAction the client application name will be used.