Serverside Plugins

Java Plugin Developement

Java plugins run at the server in the same Java VM as the NGClient itself runs. They are accessed by "plugins.xxx" the same as Service but such a service runs client side in the browser.

So a Java plugin can access everything on the server but nothing from the client machine.

Java Plugins can be created by any Java development tool like Eclipse and are then package it as a JAR that can then be installed in the {servoyinstall}/application_sever/plugins

There are 2 kinds of plugins:

ClientPlugin > This implements the IClientPlugin interface and 1 instance is created for every client

ServerPlugin > This implements the IServerPlugin interface and 1 instance is created on the whole server. This can expose Remote objects for the client part of the plugin, or register WebServices

This project needs to have at least 2 jars as the classpath, these can be taken from the {servoyinstall}/developer/plugins directory:

servoy_shared_VERSION.jar and the org.eclipse.dltk.javascript.rhino_VERSION.jar

Implementing the plugin (implementing the IClientPlugin interface)

public class WhoisPlugin implements IClientPlugin {
 public static final String PLUGIN_NAME = "whois";
 private WhoisPluginProvider provider;
 
 @Override
 public Properties getProperties() {
     Properties props = new Properties();
     props.put(DISPLAY_NAME, getName());
     return props;
 }
 
 /** 
  * Called when the plugin is loaded, can be used todo some initializations.
  */
 @Override
 public void load() throws PluginException {
     // ignore
 }
 
 /** 
  * Called when the plugin is unloaded (client closed), can be used todo some clean ups
  */
 @Override
 public void unload() throws PluginException {
     provider = null;
 }
 
 @Override
 public void propertyChange(PropertyChangeEvent arg0) {
     // ignore
 }
 
 /**
  * This will return the object that has the api this plugin where servoy developers code against
  */
 @Override
 public IScriptable getScriptObject() {
     if (provider == null) {
        provider = new WhoisPluginProvider();
     } 
     return provider;
 }
 
 @Override
 public Icon getImage() {
     URL iconUrl = getClass().getResource("images/whois.png"); //the image is added under a package 'com.servoy.plugins.whois.images' added to the WhoisPlugin project.
     if (iconUrl != null) {
         return new ImageIcon(iconUrl);
     } else {
         return null;
     }
 }
 
 @Override
 public String getName() {
    return PLUGIN_NAME;
 }
 
 @Override
 public void initialize(IClientPluginAccess pluginAccess) throws PluginException {
    // ignore
 }
}

Implement the Script Object

The method getScriptObject is inherited by IClientPlugin from IScriptableProvider interface, returns the object that will provide the plugin with scripting properties and methods. So, by convention, it is called a Provider.

A provider implements interfaces IScriptable and IReturnedTypesProvider. Do study them on api docs.

Create a class which implements the two interfaces. This class will provide methods representing the plugin behavior

Code the Plugin Main Behavior

In order to specify which methods are what, use the JavaDoc annotations system which identifies getter/setter methods for plugin properties, as well as function methods for the plugin functions. The JavaDoc annotation system is also used for documenting the plugin. For a proper understanding of how to use JavaDoc and how to build the documentation of a plugin, see Documenting the Plugin Api.

Example

This example shows the implementation of the WhoisPluginProvider - the scriptable object which provides the behavior for the 'whois' plugin. The plugin will expose an overloaded query method, as well as three other properties: port, server, and timeout. The main query method contains JavaDoc which provides a description of the function and a sample. The other overloaded methods will display the same description and sample, having them copied via @clonedesc and @sampleas annotations from the main method

@ServoyDocumented(publicName = WhoisPlugin.PLUGIN_NAME, scriptingName = "plugins." + WhoisPlugin.PLUGIN_NAME)
public class WhoisPluginProvider implements IScriptable, IReturnedTypesProvider {
 @Override
 public Class<?>[] getAllReturnedTypes() {
     return null; // this could return classes of the types that a plugin returns in one of its methods.
 }
 
 private String server = "whois.networksolutions.com";
 private int port = 43;
 private int timeout = 30 * 1000; // unit is milliseconds
 
 @JSGetter
 public String getServer() {
     return server;
 }
 
 @JSSetter
 public void setServer(String server) {
     this.server = server;
 }
 
 @JSGetter
 public int getPort() {
 return port;
 }
 
 @JSSetter
 public void setPort(int port) {
    this.port = port;
 }
 
 @JSGetter
 public int getTimeout() {
    return timeout;
 }
 
 @JSSetter
 public void setTimeout(int timeout) {
    this.timeout = timeout;
 }
 
 /**
 * @clonedesc query(String, String, int, int)
 * @sampleas query(String, String, int, int)
 * @param domainName
 */
 @JSFunction
 public String query(String domainName) {
    return query(domainName, this.server, this.port, this.timeout);
 }
 
 /**
 * @clonedesc query(String, String, int, int)
 * @sampleas query(String, String, int, int)
 * @param domainName
 * @param server
 */
 @JSFunction
 public String query(String domainName, String server) {
     return query(domainName, server, this.port, this.timeout);
 }
 
 /**
 * @clonedesc query(String, String, int, int)
 * @sampleas query(String, String, int, int)
 * @param domaninName
 * @param server
 * @param port
 */
 @JSFunction
 public String query(String domainName, String server, int port) {
    return query(domainName, server, port, this.timeout);
 }
 
 /**
 * Calls a whois server to retrieve information about the provided domain name
 * 
 * @sample
 * // call a whois server by providing a domain name and get info in return
 * var result = plugins.whois.query('servoy.com');
 * // alternatively, provide an alternate server (default is networksolutions.com)
 * var result = plugins.whois.query('servoy.com', 'whois.internic.net');
 * // provide a port, if not standard (43 by deafault)
 * var result = plugins.whois.query('servoy.com', 'whois.internic.net', 43);
 * // provide a timeout length (unit is milliseconds, default is 30 seconds)
 * var result = plugins.whois.query('servoy.com', 'whois.internic.net', 43, 50000);
 * 
 * @param domainName
 * @param server
 * @param port
 * @param timeout
 * @return
 */
 @JSFunction
 public String query(String domainName, String server, int port, int timeout) {
     try {
         // create the socket
         Socket socket = new Socket(server, port);
         socket.setSoTimeout(timeout);
         // create a reader to get the response from the server
         BufferedReader in = new BufferedReader(new InputStreamReader(socket.getInputStream()));
         // create an output stream to send our query to the server
         DataOutputStream out = new DataOutputStream(socket.getOutputStream());
         // call the service with the domainName supplied
         // and terminate with carriage return)
         out.writeBytes(domainName + " \r\n");
         // read the response from the server
         String str1 = null;
         StringBuffer buffer = new StringBuffer();
         while ((str1 = in.readLine()) != null) {
             buffer.append(str1);
             buffer.append("\r\n");
         }
         // close our stream and reader
         out.close();
         in.close();
         // close the socket
         socket.close();
         // return the result as String
         return buffer.toString();
         } catch (IOException ioEx) {
             return ioEx.getLocalizedMessage();
        } catch (Exception ex) {
            return ex.getLocalizedMessage();
        }
    }
}

Entry Points

Since the class which implements the IServerPlugin, IClientPlugin is one file among many inside the jar, it's mandatory indicate which file is the plugin entry point.

The plugin jar has to use Java Service Provider to expose Servoy Plugin classes. There should be a file inside the plugin jar at the path: META-INF/services/com.servoy.j2db.plugins.IPlugin which contains a line for each class in the jar that implements IPlugin (IClientPlugin or IServerPlugin).

The plugin should also have a default constructor (with no parameters).

An example of file (META-INF/services/com.servoy.j2db.plugins.IPlugin) content (for whois plugin) is:

com.servoy.plugins.whois.WhoisPlugin

Documenting the Plugin API

Servoy supplies a Java Eclipse Documentation Generator plugin to help with documenting the plugin API. This plugin allows to transform the plugin JavaDoc into a Servoy plugin xml api file. The generated XML file needs to be bundled with the plugin, which then will be used in Servoy Developer to provide the information (namely, the documentation) to the developer using the plugin. All the relevant API information can be supplied by JavaDoc directly on the public methods and properties of the plugin.

The IScriptable Interface

The IScriptable interface is an empty interface that classes that expose methods or properties to the JavaScript layer in Servoy have to implement. When plugins get loaded in Servoy Developer, all documentation provided in the classes implementing this interface will be loaded. For more information refer to the IScriptable API doc in the Servoy API.

IReturnedTypesProvider can be used to give return types to the plugin api (Like JSFile of the file plugin), which only needs to beimplemented on plugin classes that have actual returnTypes.

Documenting Method & Properties Using JavaDoc

When implementing the new documentation mechanism, the method sample code, tooltip, parameter names will have to be documented using JavaDoc. For more details on writing documentation in the Javadoc way, see the Javadoc reference pages. This type of code documentation is a standard way of documenting Java code. The supplied JavaDoc can be extracted in XML format using the Documentation Generator below and then be bundled with the plugin for Servoy Developer to use. A plugin must annotate itself so that the Document Generator Tool knows what to get. Servoy has a special annotation called @ServoyDocumented. The annotation can have additional attributes to specify the public and scripting names. Below, is a sample of the FilePlugin:

@ServoyDocumented(publicName = FilePlugin.PLUGIN_NAME, scriptingName = "plugins." + FilePlugin.PLUGIN_NAME)
public class FileProvider implements IReturnedTypesProvider, IScriptable

For returnTypes like JSFile the @ServoyDocumented annotation marks a class for documentation:

@ServoyDocumented
public class JSFile implements IScriptable, IJavaScriptType

Note that if a class is documented, documented methods/properties will be looked up in the class hierarchy. If a method is present multiple times in hierarchy, the first occurrence will be used by doc generator. Methods can be annotated in order to be marked as properties, functions or as deprecated. If a method is annotated with the special annotation @JSReadOnlyProperty, it will bee considered a readonly property of the plugin.

/**
 * This is a readonly property
 */
@JSReadOnlyProperty
public String myPropertyVersion()
{
 return "version 1.0";
}

Two methods using the @JSGetter and @JSSetter properties can be used to create a property of the plugin, as follows:

@JSGetter
public String getSomeProperty()
{
 //...
}
@JSSetter
public void setSomeProperty(String someProperty)
{
 //...
}

The code above will create a JavaScript property called 'someProperty' of the plugin. If a method is annotated with the @JSFunction property it will be considered a JavaScript function:

@JSFunction
public String myFunction(String myParameter)
{
 //...
}

Note that the method above does not have to start with the js_ prefix in order to be considered a JavaScript function of the plugin it belongs to. If a method should be marked as deprecated, the new documentation generator tool also takes into consideration the @Deprecated annotation:

@Deprecated
public void neverRetire()
{
 //...
}

The result is that such a method will not show up in the plugin's (Solution Explorer) list view. Methods can be documented according to the sample below:

/**
 * This is the method description.
 *
 * @sample
 * var message = someMethod('someParameter');
 *
 * @param simpleParameterName this is a simple parameter name
 *
 * @return what the method returns
 */
 @JSFunction
public String someMethod(String simpleParameterName)
{
 //...
}

Besides the standard JavaDoc tags like @param, @return and @since, Servoy introduces a few tags to provide sample code part or to clone parts of the JavaDoc of another method.

• @sample: doc below this section, until the next tag is seen as sample code. This should contain the text previously returned by getSample (String methodName)

• @sampleas: this will copy over the sample code from another method: @sampleas someMethod(String)

• @clonedesc: this will copy over the description from another method: @clonedesc someMethod(String)

• @sameas: this will copy the entire documentation from another method: @sameas someMethod(String)

The @param tag supports so-called rest parameters by using ... prefix. It also supports marking parameters as optional. The following example is the button a optional and variable arguments parameter.

@param ...button optional

To be able to type a specific variable, like /** @type {JSFile} */ , using a JSDoc annotation, the last slash must be escaped by using the ASCII notation:

/** @type {JSFile} *&#47

The Documentation Generator Tool

After annotating the source of the plugin using JavaDoc, the documentation needs to be exported to XML format and bundled with the plugin. Servoy provides an Eclipse plugin to generate the XML, called the Documentation Generator. In order to have the method documentation available in JavaScript, the documentation generation tool needs to be installed in the Eclipse in which the plugin is being developed. The documentation generation tool must be installed via Eclipse update sites. Go to Help > Install New Software..., add the https://download.servoy.com/documentbuilder URL and install the documentation generator (Servoy Documentation Generator Feature). It will show up under installed software as the Servoy Documentation Generator Feature.

Note Note that Group items by category has to be unchecked in the Install New Software first wizard page.

After the tool is installed, the documentation of the plugin can be generated by selecting the project/package corresponding to a Servoy plugin, ie. a class that implements IClientPlugin, and using the context menu Servoy > Generate Servoy Documentation XML in the Package Explorer view. Separate documentation XMLs are generated for each of the topmost package which contains a Servoy plugin, so one documentation file per plugin.

For instance, if the package structure is the following:

• com.mycompany.myplugin (this package contains a class implementing IClientPlugin)

• com.mycompany.myplugin.feature1

• com.mycompany.myplugin.feature2

A servoydoc.xml file will be generated in the com.mycompany.myplugin package.

In order to have this documentation available with the plugin, in the Servoy Developer, the plugin developer must include and bundle the documentation XML file along with the actual plugin, inside the plugin jar file. Then, once the plugin jar is copied to the Servoy installation's application_server/plugins directory, the documentation XML, corresponding to that plugin, will be automatically loaded and the documentation will be available. The documentation generator tool also has a corresponding preference page, which will show up in Eclipse under Windows > Preferences > Servoy Documentation Generator. There are currently two properties which can be set:

Show confirmation dialog before overwriting an existing file Show a final summary with an overview of the files that were generated