6.9 Java Extension

This article will guide you through the process of writing and compiling your own Java server side extensions for SmartFoxServer 1.4 or higher. All you need to start developing Java extensions is the Sun JDK, your favourite text editor and, of course, SmartFoxsServer installed on your machine. In this tutorial we will also see how to setup the Eclipse IDE to work with SmartFoxServer classes to boost your productivity.

» Extension template and provided examples

A server side extension is essentially a Java class that extends the AbstractExtension base class found in the it.gotoandplay.smartfoxserver.extensions package.

The following are the methods that your class should implement:

method signature description
init() called as soon as the extension is activated
destroy() called when shutting down the extensions
handleRequest(String cmd, ActionscriptObject ao, User u, int fromRoom) handles a request in XML format
handleRequest(String cmd, String params[], User u, int fromRoom) handles a request in Raw format
handleRequest(String cmd, JSONObject jso, User u, int fromRoom) handles a request in JSON format (only for SmartFoxServer 1.5.0 or higher)
handleInternalEvent(InternalEventObject ieo) handles an internal server event

All methods should be declared as public void.
For further reference you can check introductory articles, the extension template provided with the documentation and the examples found in the Server/javaExtensions/ folder in your SmartFoxServer installation directory.

» Compiling the extension using javac

In order to successfully compile your Java extensions you will need to include a few libraries to the classpath of the java compiler ("javac").

Depending on your server version these are the libraries to inlcude:

version 1.4.x: Server/smartfoxserver.jar
version 1.5.x: Server/lib/jysfs.jar and Server/lib/json.jar

Example: supposing that your extension source is located in the Server/javaExtensions/ folder and you're using version 1.5, this is what you should type in your shell/terminal window:

javac -classpath "../lib/jysfs.jar:../lib/json.jar" MyJavaExtension.java  

NB: the classpath separator ":" (colon) is valid for all Linux/Unix (including MacOS X) operating systems.
Under windows you should use ";" (semicolon)

» Using Eclipse

Using a Jave IDE like Eclipse can boost your productivity thanks to code completion, code templates, automated project building etc...
The following is a visual walkthrough that will guide you in the creation of a SmartFoxServer extension.

Assuming you already have installed Eclipse, let's go ahead and launche the IDE.
Click on File > New > Project in order to create a new Java project:

step01

Select Java Project and click Next

step20

Give a name to the project (e.g. "MyExtension") and in the "Project layout" make sure to select "Create separate source and output folder".
This will create two different directories for your source and compiled files.
Let's go ahead by clicking "Next"

step03

The Java Settings window contains a set of sub panels where you can configure all the details of your project. Click on the "Libraries" tab and on the "Add External JARs..." button. This will open a dialogue box where you can add additional libraries for your project.

step4

Navigate your file system and reach the SmartFoxServer installation folder. From there move to the Server/lib/ directory and select both jysfs.jar and json.jar by holding the CTRL key (Windows/Linux) or Command key (Mac) .

(NB: if you're using SmartFoxServer prior to version 1.5 you only need to select Server/lib/smartfoxserver.jar)

step5

Click Finish to create the project and make sure your Package Explorer is open.
(You can toggle it from Window > Open perspective > Java)
We can now create our first class in the project which will be the main extension class: right click the "src" folder and select New > Class

step6

In the "New Java Class" dialogue box we specify the package name ("test") and the class name ("MyExtension")
Go ahead and click "Finish"

step7

The class is now ready. You can write your code and take advantage of the powerful features of Eclipse.
By default your class will be auto-compiled in the bin/ folder of your project each time you save the source.

step8

» Deploying the extension

There are a few options that you can choose for deploying your Java extension:

» SIMPLE: use the javaExtensions/ folder:
You can simply copy your classes (including the packages folder structure) to the javaExtensions/ folder. This folder is already added to the standard server classpath so you don't need to add it yourself.
Your classes will be immediately available to the server, you just need to add an <extension/> definition to your Zone in the config.xml file.

» ADVANCED: Point the server classpath to your class/jar files:
Another option is to create a .jar archive of your class files and copy it in one of the server folders.
We suggest to always use the Server/javaExtensions/ folder for your custom Java extensions and the Server/lib/ folder for additional libraries.

Adding your .jar files to the classpath can be done in two different ways, depending on the way you're running the server:

Standalone:
just edit your start.bat (Windows) or start.sh (Linux / Unix / MacOS X)

Service / Deamon:
Open the wrapper.conf file inside the Server/conf/ folder and add a new classpath entry. (Windows / Linux / Unix)
(This doesn't apply to MacOS X. Just use the "standalone" method.)


doc index