4.5 Using Java
4.5.1 Introduction
The Java API has been generated from the C++ API by using SWIG. That implies that their class hierarchy, their class names and their function names are almost identical. The Java API is currently composed of a set of about 25 classes having about 200 public functions located in the package called com.cyberbotics.webots.controller. The classes are either representations of a node of the scene tree (such as Robot, LED, etc.) or either utility classes (such as Motion, ImageRef, etc.). A complete description of these functions can be found in the reference guide while the instructions about the common way to program a Java controller can be found in the chapter 6.
4.5.2 Java and Java Compiler Installation
In order to develop and run Java controllers for Webots it is necessary to have the Java Development Kit (JDK), version 1.6 or later installed on your system.
Windows and Linux Instructions
On Windows or Linux the Java Development Kit (JDK) can be downloaded for free from the Sun Developer Network. Make sure you choose the most recent release and the Standard Edition (SE) of the JDK. For Windows, make also sure you have selected the 32 bit version since webots is incompatible with the 64 bit version. Then follow the installation instructions attending the package.
After installation you will need to set or change your PATH environment variable so that Webots is able to access the java or (javaw) and javac commands. The java command is the Java Virtual Machine (JVM); it is used for executing Java controllers in Webots. The javac command is the Java compiler; it is used for compiling Java controllers in Webots text editor.
On Linux, you can set the PATH by adding this line to your ~/.bashrc or equivalent file.
$ export PATH=/usr/lib/jvm/java-XXXXXX/bin:$PATH |
Where java-XXXXXX should correspond to the actual name of the installed JDK package.
On Windows, the PATH variable must be set using the Environment Variables dialog.
On Windows XP, this dialog can be opened like this: Choose Start > Settings > Control Panel, and double-click System. Select the Advanced tab and then Environment Variables.
On Windows Vista and Windows 7 the dialog can be opened like this: Choose Start > Computer > System Properties > Advanced system settings > Advanced tab and then Environment Variables.
In the dialog, in the User variables for ... section, look for a variable named PATH. Add the bin path of the installed SDK to the right end of PATH variables. If the PATH variable does not exist you should create it. A typical value for PATH is:
C:\Program Files\Java\jdk-XXXXXXX\bin |
Where jdk-XXXXXX stands for the actual name of the installed JDK package.
Then, you need to restart Webots so that the change is taken into account.
Note that the PATH can also be set globally for all users. On Linux this can be achieved by adding it in the /etc/profile file. On Windows this can be achieved by adding it to the Path variable in the System variables part of the Environment Variables dialog.
Mac OS X Instructions
Mac OS X comes with preinstalled and preconfigured Java Runtime Environment (JRE) and Java Development Kit (JDK). So you don't need to download or install it. However you will need to install the XCode Development Tools in order to be able to access the make command. You will also need the XCode Development Tools if you want to compile C or C++ controllers. The XCode tools can be found on your Mac OS X installation DVD, otherwise they can also be downloaded for free from the Apple Developer Connection.
Troubleshooting the Java installation
If a Java controller fails to execute or compile, check that the java, respectively the javac commands are reachable. You can verify this easily by opening a Terminal (Linux and Mac OS X) or a Command Prompt (Windows) and typing java or javac. If these commands are not reachable from the Terminal (or Command Prompt) they will not be reachable by Webots. In this case check that the JDK is installed and that your PATH variable is defined correctly as explained above.
If you run into an error message that looks approximately like this:
Native code library failed to load. See the chapter on Dynamic Linking |
4.5.3 Link with external jar files
When a Java controller is either compiled or executed, respectively the java and the javac commands are executed with the -classpath option. This option is filled internally with the location of the controller library, the location of the current controller directory, and the content of the CLASSPATH environment variable. In order to include third-party jar files, you should define (or modify) this environment variable before running Webots (see the previous section in order to know how to set an environment variable). Under windows, the CLASSPATH seems like this,
$ set CLASSPATH=C:\Program Files\java\jdk\bin;relative\mylib.jar |
while under Linux and Mac OS X, it seems like this:
$ export CLASSPATH=/usr/lib/jvm/java/bin:relative/mylib.jar |
An alternative to this is to define the CLASSPATH variable into the Makefile, and to put all the jar at the root of the controller directory.
4.5.4 Source Code of the Java API
The source code of the Java API is available in the Webots release. You may be interested in looking through the directory containing the Java files (projects/languages/java/src/SWIG_generated_files) in order to get the precise definition of every classes and functions although these files have been generated by SWIG and are difficult to read.
For users who want to use a third-party development environment, it can be useful to know that the package of the Java API (Controller.jar) is located in the lib directory.
For advanced users who want to modify the Java API, the SWIG script (controller.i), the java sources and the Makefile are located in the projects/languages/java/src directory.