Writing the first Extension
If you have followed our quick start article you are ready to start writing a simple server side Extension and play around with it.
The pre-requisites to follow this tutorial are:
- having a JDK installed (ver 21 or higher)
- basic familiarity with a Java IDE such as:
If you already have installed one of these editors, a JDK should also be installed locally, just make sure it is at least version 21. If not you can download and install a more up to date release from here.
Note:
In this tutorial we will be using Eclipse, however setting up a new project in another IDE should be a similar process. If you're more familiar with another Java IDE you should be able to follow along and translate the steps provided here. (If not, we recommend that you try Eclipse).
Setting up a new project
From Eclipse's File menu choose New > Java Project.
In the new window we give the project a name, for example MyJavaExtension, and choose a Java Runtime such as JRE 21.
Note:
SmartFoxServer 3 ships with Java 25, so any runtime version from 21 up to 25 can be used for your Extensions. If you plan to use a version > 25 please make sure to set the compiler compatibility level to 25.
Now it is time to add the libraries that are needed to compile our Extension. Click on Libraries tab, select Classpath, then on the Add External JARs... button and navigate your file system to your {sfs-install-dir}/server/lib/ folder.
Select two files: sfs3-core.jar and sfs3.jar and click Finish in the main window.
The new project will appear in the Package Explorer panel which by default is located at the top left column of your interface. Now you can create a new Java class by right-clicking on the src folder and selecting New > Class from the menu.
Here we proceed by entering the name of the class, for example MyExtension, and its package which in this case will be my.test. Please notice that using the Extension suffix in the class name is highly recommended, because it makes it easier to assign it to the server's Zone/Room in the AdminTool (see the additional note on the Type parameter of the Zone Extension tab or Room Extension tab in the Zone Configurator module documentation).
Finally we create our main Extension class adding some basic code, as shown below, and proceed to test it.
Deploying the Extension
The deployment follows a few simple rules. Every extension must reside in a folder under the server/extensions/ folder. The name you choose for this folder will determine the Extension name that is shown in the AdminTool when you activate the Extension.
Let's say we create a folder called MyJavaExtension under extensions/. Under this path we will deploy the jar file containing our classes.
IMPORTANT:
The name of the main Extension jar file must end with the word Extension, for example MyJavaExtension.jar. This is important because the AdminTool will only show the classes contained in the jar files which use this convention. For more information see the additional note on the Use naming convention setting of the Zone Extension tab or Room Extension tab in the Zone Configurator module documentation.
In Eclipse the compiled classes are usually stored in the bin/ folder, which sits next to the src/ folder in your project. You can export the compiled code in a jar file directly to the SmartFoxServer deployment folder by following the next steps.
In the Package Explorer right-click the project folder and choose Export... In the next dialogue box open the Java folder and choose JAR file, then click the Next button. A new window will open, click the Browse... button in the middle of it and navigate to the SmartFoxServer deployment folder (as we explained) specifying a name for the jar file to be created (remember the naming convention described above).
Click Next to advance to the next screen. Here you can store the export settings so that the next time you need to re-deploy your Extension it can be done by double clicking the export file in your project folder.
Activate the checkbox next to the Save the description... and click Browse... You will be presented with a list of all your Java projects: select the right one and provide a name for the export configuration; click Ok to close the panel and click Finish to complete the process.
At this point you will have deployed your jar file to the SFS Extension folder and saved the export configuration for future re-deployments.
SmartFoxServer actively monitors the Extension folders for changes and as soon as it detects an updated jar file it will restart your Extension. This is valid only for Zone-level Extensions, but not for Extensions at Room-level.
In order to toggle this feature you need to open the Server Configurator in the AdminTool and turn on the Extension file monitor option.
Assigning an Extension to a Zone or Room
The simplest way to plug our Extension to a Zone or Room is via the AdminTool. Launch the Zone Configurator, and select a Zone, then click the Zone Extension and select which Extension should be used.
Finally you can save, restart the server and the Extension will be activated. The same can be done for Room Extensions: simply access the Room Extension tab in the Room configuration panel of the Zone Configurator.