This page needs to be checked for accuracy and content. Please help improve this page: https://phabricator.wikimedia.org/T245314

This page contains information about developing tools in Java.

Java frameworks

You can choose from a number of Java frameworks to work with. A list can be found at List of Java frameworks.

jar files

Your completed Java project should be built to result in a jar file. You can upload the jar file to your tool account in Toolforge, along with any other libraries dependencies.

Execute your jar file with command line java

For example, if your jar file name is fixLink.jar, then you can execute it by following these steps:

  • Change directory to the folder that jar file exist in. e.g. cd fixLink/dist
  • Prompt the following command line: java -jar fixlink.jar
  • Type enter, and the program should run.

Follow this method each time you need to manually run the jar file.

Schedule tasks

When you need to schedule the Java tool you should use crontab.

Crontab is a file you can append some commands into that lets you schedule your tools for any interval of time, (every 5 min, 1 hour, 24 hours...etc).

We recommend that you use the jsub command when writing cron for your java tool.

Schedule a java tool:

Following is an example for scheduling your Java tool with crontab:

  • Choose the folder in your tool you want to run.
    • For example, you have a folder in your tool called test, and it contains your jar file (test.jar).
  • Type crontab -e.
  • Choose the interval of time you want to use and write the Cron syntax.
    • For example, if you want the tool to run every 5 minutes write: */5 * * * *.
  • After that, append your tool execution command, so you write: jsub -mem 9000m -once /usr/bin/java -jar /data/project/YourToolName/test/dist/test.jar
  • Your final cron code is */5 * * * * jsub -mem 9000m -once /usr/bin/java -jar /data/project/YourToolName/test/dist/test.jar
  • Save the file, and your cron job is now scheduled.

Note: Java consumes a lot of RAM memory, and it's very sensitive about paths. You may face some common errors when you try to write cron for your tools. See the section of errors if you face any of them.

Web services

Play and similar JVM-based frameworks

  • webservice --backend=kubernetes jdk17 start|stop|restart|shell BINARY

Play Framework projects (and other JVM-based projects that have one executable to start the application) can be run on Toolforge.

  1. In order to work on Toolforge, the following Play configuration changes need to be made:
    # Secret key
    # ~~~~~
    # The secret key is used to secure cryptographics functions.
    # If you deploy your application to several instances be sure to use the same key!
    # On Toolforge, we will make a startup script that specifies play.crypto.secret
    # using a command line option reading from a private file.
    play.crypto.secret="changeme"
    
    # Port
    # ~~~~~
    # On WMF Toolforge, the port used by kubernetes webservice is 8000/TCP
    http.port=8000
    
    # HTTP context
    # ~~~~~
    # Your tool will be available at https://$TOOLNAME.toolforge.org/.
    # Play usually expects to be operating at the root of a domain, so this setting is
    # required for routes to work properly.
    play.http.context="/"
    
  2. The application secret can be stored in a private file with 440 permissions.
  3. Build the project.
  4. After building the project, start your webservice:
    webservice --backend=kubernetes jdk17 start -- /usr/bin/java -Dplay.crypto.secret="$(cat /data/project/$TOOLNAME/app_secret)" -jar /data/project/TOOL/path/to/file.jar.

For more details, see User:Sn1per/Play on Tool Labs.

Tomcat

Tomcat is no longer supported on Toolforge.


Common errors

Java versions

The common error may face you when running your Java tool in Toolforge is the difference between Java versions. The Java version installed in Toolforge is 1.7 (also known as Java 7). If you write your code in higher versions of Java; you'd have to change the version of your project; so it can be equal or lower than Toolforge Java version. If you use Netbeans IDE, you can change the Java version of the project by:

  • Right click on project, and select proporties.
  • In sources category; change source/Binary Format to JDK 7.
  • In libraries category; change java platform to JDK 1.7.
  • Click Ok.

Crontab errors

There are some errors that may face you when trying to write crons:

  • Error: Error occurred during initialization of VM, Could not allocate metaspace, Could not reserve enough space for code cache: make sure you used this phrase when creating your cron job: -mem 9000m. It allocates memory to the JVM, so it can be run successfully without any errors.
  • Error: Unable to access jarfile: This error happens when you don't point to the exact path of the jar file. Cron works only if you give it the absolute path.

For example, you have a Java tool folder in you tool account, which named is "test", inside test folder there is a dist folder; which contains the jar file, and the lib folder, which contains any dependent libraries. Now, if you write cron like this:

java -jar /test/dist/test.jar
You need to rewrite the cron with absolute paths, like:
usr/bin/java -jar /data/projects/YourToolName/test/dist/test.jar
  • Error: Could not create the Java Virtual Machine. Error: A fatal exception has occurred. Program will exit.: This error means that Java needs more memory to run your tool. Java consumes a lot of memory, and it needs large memory space to run jar files. So, refer to the previous example:
usr/bin/java -jar /data/projects/YourToolName/test/dist/test.jar
You have to add -mem command to the cron line:
jsub -mem 9000m -once java -jar /data/project/YourToolName/test/dist/test.jar
  • Error occurred during initialization of VM Could not reserve enough space for object heap Error occurred during initialization of VM Could not reserve enough space for object heap: This error tells you that the value of memory you have specified is too low for Java. You can fix this error by raising the value.

Communication and support

Support and administration of the WMCS resources is provided by the Wikimedia Foundation Cloud Services team and Wikimedia movement volunteers. Please reach out with questions and join the conversation:

Discuss and receive general support
Stay aware of critical changes and plans
Track work tasks and report bugs

Use a subproject of the #Cloud-Services Phabricator project to track confirmed bug reports and feature requests about the Cloud Services infrastructure itself

Read stories and WMCS blog posts

Read the Cloud Services Blog (for the broader Wikimedia movement, see the Wikimedia Technical Blog)

See Also