RUN@cloud » JVM Runtime Container

JVM Runtime Container

Last modified by Michael Neale on 2013/11/11 01:03

JVM Runtime Container

The Java runtime container supports all JVM applications that can be started with a Java main method (public static void main(String[] args) ). This makes the Java runtime container a very powerful tool to launch virtually any Java application or JVM-language-based app on CloudBees. We re-use the Java runtime container within CloudBees to support a variety of tools and frameworks. In this article, we cover the usage of the Java runtime container itself, and show you how to use it to launch a Play2 application. For more information on Play2 on CloudBees, refer to our community page.

Usage

When using the bees CLI - you can select it when you deploy, or using config:set command (eg for 1.7 - as is default)

bees app:deploy -t java -R class=your.main.Class -R java_version=1.7 PATH_TO_APP_PACKAGE

You only need to set these settings once - they will be remembered for subsequent deploys.

The container type is specified at deployment time with the CloudBees SDK app:deploy command and the "-t java" option flag. The system property "app.port" tells you which port can be used if you need to listen for http connections.

Port for Web Applications

If the java application needs to start an embedded server, it can retrieve its designated internal network port via the built-in system property "app.port" :System.getProperty("app.port")

Run-time Parameters

In order to run an application with the Java container, you may need to supply several arguments. At least one runtime argument is mandatory: it specifies the Java class containing the main method. Other arguments can be used to specify the classpath to jars used by the application, main method arguments, JVM arguments and Java version. These are passed to the command line with the "-RargName" parameter pattern.

Runtime parameter Description
 classThe java class containing the main method (e.g., com.acme.Hello)
 classpathThe list of jars, part of the deployment packaged and used by the application. Each jar path is relative to the deployment package root and separated by ":"
 argsThe main method arguments
 JAVA_OPTSJVM properties that will be added to the command line. Be careful of escaping. For example, if you want to add [-XX:OnOutOfMemoryError="kill -9 %p"] here, you will need to do [-R JAVA_OPTS="-XX:OnOutOfMemoryError=\"kill -9 %p\" "] - note spaces and escaped double quotes.
 java_versionThe Java version to be used (1.6, 1.7 or 1.8 for Java 6,7 and 8 respectively)

Runtime parameters can reference some built-in environment variables, for example -RJAVA_OPTS='-Dhttp.port=$app_port' (eg if you need to use a different system property to set the port)

Environment variable Description 
 $app_dir The root deployment directory in the cloud. The application package directory is $app_dir/app/
 $app_port The application network port allocated to the application (inside your app this will be JVM system property of app.port)

Dealing with OutOfMemoryExceptions

Ideally no apps would leak memory - but for everything else - you can have the container shut itself down when any kind of OOME in the JVM is encountered - this is useful even in the case where naughty code or libraries have swallowed the exception (and even for Perm Gen) - this means your app will stop, and restart. To see the cause - you will need to look in your logs (it could be a heap exception, stack or perm gen). 

The following shows an example of how this is done when deploying an app using a runtime parameter:

bees app:deploy -a app_id -R JAVA_OPTS="-XX:OnOutOfMemoryError=\"kill -9 %p\" " ~/sample.war 

(note the escaped quotes).

Service Resources

Applications can be bound to various resources from the eco-system (see Resource Management). Those resources might have configuration parameters such as connection url and credentials for databases.  Those configurations parameters are available to the application via system properties.

For example when a MySQL database is bound to an application, the connectivity information is available as:

  • DATABASE_URL_alias_name
  • DATABASE_USERNAME_alias_name
  • DATABASE_PASSWORD_alias_name

The alias_name is the resource alias used to bind the resource to the application.

Deployment

Package

The deployment package is a zip file containing the various classes, jars and resources comprising the application.

Examples

Hello Application

This example Hello Application is a non-Web application that just loops every 5 seconds and prints the time. It is not using any network port, so cannot be accessed via a URL.

package com.cloudbees.test;
import java.util.Date;

public class Hello {
    public Hello(String[] args) {
       if (args.length > 0) {
           for (int i=0; i<args.length; i++)
                System.out.println(String.format("Arg[%d] %s", i, args[i]));
        }
    }

    public static void main(String[] args) {
        String hello = System.getProperty("message","Hi");
        System.out.println("RUN v0.1: " + hello);
        new Hello(args).run();
    }

    private void run() {
       while (true) {
           try {
                System.out.println(new Date());
                Thread.sleep(5000);
            } catch (InterruptedException e) {
                e.printStackTrace();
            }
        }
    }
}

Create the hello.zip, and then deploy from the command line:

(bees app:deploy -a  YOUR_APPLICATION_NAME  -t java   -R class=com.cloudbees.test.Hello   -R classpath=hello.jar   -R args=Works   target\hello.zip   waitForApplicationStart=false)

Since the application is not a web application (it does not have an accessible URL), the last argument (waitForApplicationStart=false) instructs the deployment system to not wait for the application URL to be accessible. This makes the deployment a little faster.

Tags:
Created by Fabian Donze on 2012/09/24 15:07