Headless Jumpstart Application - Part 1

Overview

In this guide, we'll take a look at creating a minimal p2web application using the CORE CloudStack module. The application will be injected into the framework as a plug-in using an Eclipse extension and will use the CloudStack MVC model to define a simple page using a controller, action, and view.

Prerequisites

If you haven't already, you'll need to download CloudStack first.

Installing the headless jumpstart package

• Download the headless jumpstart zip file. Mac users might want to hold down the "option" while downloading to prevent automatic unarchiving of the zip file.
• Next we'll need to import this project into Eclipse. With Eclipse running, select File->Import and pick the "Existing Projects into Workspace" option under the General category. Click Next.
  
  


• Choose "Select archive file" and specify the path to the zip file. You will see org.cloudstack.jumpstart.headless under the list of projects. Click "Finish".
  
  

Running the headless jumpstart package

• Open the source file: org.cloudstack.jumpstart.headless.CloudStackApplication.java and replace the login placeholder strings with your Cloudstack username and password.
• Select the Plug-ins tab and click on the "Add Required Plug-ins" button. You should end up with 23 plug-ins selected.
  
  


• Click "Apply", then "Run" to launch the application.
• If everything worked, you should see a "Login successful" message in the console.
• Bring up a web browser window on the same or different machine and navigate to your CloudStack page.
• Login with your account information and you should see the CloudStack Welcome page.
• You can alternatively navigate to your CloudStack application using a localhost url from the same machine: http://localhost:57900
  
  

Extending the headless jumpstart package

Now that you have the jumpstart package installed and running, we'll start building a simple p2web application using the built-in MVC model:

• The persistence layer can be used to provide the Model or you can use your own.
• Velocity templates are used for the view technology.
• Controllers are defined using the org.cloudstack.p2webserver.controllers extension point

In order to create a p2web plug-in, we need to define a controller, one or more actions under that controller, and define a velocity template file (view) for each action. By default, the framework follows a REST approach to URL naming. The controller name is used to create a web application context and the action name is used to create the action servlet.

The Controller class must be derived from org.cloudstack.p2webserver.ApplicationController, which among other things sets the correct class loader for jetty. The controller class also adds the specified actions as servlets and is also responsible for setting up the default template directory.

The Action classes must be derived from org.cloudstack.p2webserver.ActionServlet, which reads the Velocity template from the default template directory. The action class is responsible for providing the Velocity Context that provides the variable definitions referenced in the template.

Create a new plug-in project and add CloudStack dependencies

P2Web applications are essentially a set of plug-ins so the first step is creating a new plug-in project.

• Select File->New->Project and create a new plug-in project named com.acme.p2webapp
• Select Next
• Make sure you unselect the checkbox: "This plug-in will make contributions to the UI" and click "Finish"
• Next, double click you plug-in's MANIFEST.MF file and select the Dependencies tab
• Click "Add", and add the javax.servlet, org.mortbay.jetty.cloudstack, org.cloudstack.core and org.cloudstack.p2webserver plug-ins

Define a controller extension point

• Double-click your plug-in's MANIFEST.MF file and select the Extensions tab
• Click "Add" and select the "org.cloudstack.p2webserver.controllers" extension point and click "Finish"

Let's finish defining the controller by switching to the plugin.xml tab and adding the following:

<extension point="org.cloudstack.p2webserver.controllers">
     <controller id="com.acme.p2webapp.dashboard"
     name="dashboard"
     class="com.acme.p2webapp.controllers.DashboardController">
    <action id="show"
      name="show"
      class="com.acme.p2webapp.controllers.ShowDashboardAction">
    </action>
  </controller>
</extension>

This snippet above defines a controller and a single action that resolves to the URL: /dashboard/show

Define DashboardController Class

Create the DashboardController Class under the com.acme.p2webapp.controllers package.

The DashboardController class is empty in this example:

package com.acme.p2webapp.controllers;

import org.cloudstack.p2webserver.ApplicationController;

public class DashboardController extends ApplicationController {

}

Define the ShowDashboardAction class

The ShowDashboardAction class creates the Velocity Context used for the Velocity template. The Velocity template is automatically loaded by the base class. It looks for the template in the default template directory (../views) using the servlet's request URI to generate a template name. In this example, the template is loaded from ../views/dashboard/show.vm.

package com.acme.p2webapp.controllers;

import java.util.Calendar;

import org.apache.velocity.VelocityContext;
import org.apache.velocity.context.Context;
import org.cloudstack.p2webserver.ActionServlet;

public class ShowDashboardAction extends ActionServlet {

	private static final long serialVersionUID = 1L;

	protected Context createContext(
			javax.servlet.http.HttpServletRequest request,
			javax.servlet.http.HttpServletResponse response) {

		VelocityContext context = new VelocityContext();

		context.put("product", "CloudStack");
		context.put("time", Calendar.getInstance().getTime().toString());
		return context;
	}
}

Create template file

Finally we need to create the template file show.vm under the /views/dashboard folder which you'll need to create.

The velocity template file is shown below:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>$product</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link href="/styles.css" rel="stylesheet" type="text/css"  media="screen">
</head>
<h2><span>Dashboard Page</span></h2>
<p>
Welcome to $product!<br />
It is currently $time.
</p>
</body>
</html>

Project files

You should end up with a project structure like the following:

Running your p2web app

We need to reopen the run configuration and add your plug-in:

• Select Run->Run from the Eclipse menu
• Select the Plug-ins tab and check the com.acme.p2webapp plug-in.
• Click "Apply", then "Run" to launch the application.
• If everything worked, you should see a "Login successful" message in the console.

Now open a web browser and navigate to [your_cloudstack_page]/dashboard/show or http://localhost:57900/dashboard/show.

Congrats! You've just deployed your first p2web application.