Help:Toolforge/Java
More information and discussion about changes to this draft on the talk page.
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.
Building and deploying code
To build and deploy your project you can use the build service, we don't have a toolforge-specific tutorial yet, but you can see the upstream tutorial for the buildpack that toolforge uses.
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 Help:Toolforge/Jobs_framework.
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 job for your tools. See the section of errors if you face any of them.
Web services
Play and similar JVM-based frameworks
toolforge webservice {toolforge latest image|jdk}} 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.
- 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="/"
- The application secret can be stored in a private file with 440 permissions.
- Build the project.
- After building the project, start your webservice:
toolforge webservice 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
jarfile. 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
jarfiles. 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.
See Also
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:
- Chat in real time in the IRC channel #wikimedia-cloud connect or the bridged Telegram group
- Discuss via email after you have subscribed to the cloud@ mailing list
- Subscribe to the cloud-announce@ mailing list (all messages are also mirrored to the cloud@ list)
- Read the News wiki page
Use a subproject of the #Cloud-Services Phabricator project to track confirmed bug reports and feature requests about the Cloud Services infrastructure itself
Read the Cloud Services Blog (for the broader Wikimedia movement, see the Wikimedia Technical Blog)