Developing extensions

Developing extensions for CloudReports

CloudReports supports the development of extensions that can be "plugged in" on execution time using the Java Reflection API. However, there's a limited set of supported types of extensions that can be developed without making any modifications on CloudReports' source code.

##Supported types of extensions

The list below depicts all supported types with their respective base classes or interfaces to be implemented.

• Virtual machines allocation policies:
  Type: VmAllocationPolicy
  Base class: org.cloudbus.cloudsim.VmAllocationPolicy
  Must implement: cloudreports.extensions.vmallocationpolicies.VmAllocationPolicyExtensible
  Constructor signature: public ClassName(List<PowerHost> hostList, double upperUtilizationThreshold, double lowerUtilizationThreshold, double schedulingInterval);

• Broker policies:
  Type: Broker
  Base class: cloudreports.extensions.brokers.Broker
  Constructor signature: public ClassName(String customerName);

• Processing elements provisioners:
  Type: PeProvisioner
  Base class: org.cloudbus.cloudsim.provisioners.PeProvisioner
  Constructor signature: public ClassName(double mips);

• RAM provisioners:
  Type: RamProvisioner
  Base class: org.cloudbus.cloudsim.provisioners.RamProvisioner
  Constructor signature: public ClassName(int availableRam);

• Bandwidth provisioners:
  Type: BwProvisioner
  Base class: org.cloudbus.cloudsim.provisioners.BwProvisioner
  Constructor signature: public ClassName(long amount);

• Cloudlets schedulers:
  Type: CloudletScheduler
  Base class: org.cloudbus.cloudsim.CloudletScheduler
  Constructor signature: public ClassName(double mips, int numberOfPes);

• Power consumption models:
  Type: PowerModel
  Must implement: org.cloudbus.cloudsim.power.models.PowerModel
  Constructor signature: public ClassName(double maxPower, double staticPowerPercent);

• Resource utilization models:
  Type: UtilizationModel
  Must implement: org.cloudbus.cloudsim.UtilizationModel
  Constructor signature: public ClassName();

• Virtual machines schedulers:
  Type: VmScheduler
  Base class: org.cloudbus.cloudsim.VmScheduler
  Constructor signature: public ClassName(List<Pe> peList);

Important: Extensions must inherit from one of the base classes and/or implement one of the interfaces above. For instance, if you want to develop your own broker, it needs to be a subclass of cloudreports.extensions.brokers.Broker. Therefore, the statment below should be true:

instanceOfMyBroker instanceof cloudreports.extensions.brokers.Broker

This means your extension should belong to the base class' inheritance tree and need not to be an immediate subclass. Thus, you can freely make use of inheritance when developing your extensions.

Additionally, your new class must have a constructor that follows the signature of its type as described above.

A step-by-step guide using Eclipse

First of all, download the source code and build it to generate a .jar file.

Create a new Java project:

![newproject] (http://dl.dropbox.com/u/737234/CloudReports/wiki/createproject.png)

Choose any name you want (we'll call it MyExtensions) and click Next. On the Java Settings window, click on the Libraries tab, then click the button Add External JARs... and add CloudReports' .jar file:

![addjarfile] (http://dl.dropbox.com/u/737234/CloudReports/wiki/addjarfile.png)

Click on finish.

Now, let's create a new broker. First, create a new package named brokers:

![newpackage] (http://dl.dropbox.com/u/737234/CloudReports/wiki/createnewpackage.png)

Add a new class called MyBroker to the package :

![newclass] (http://dl.dropbox.com/u/737234/CloudReports/wiki/createnewclass.png)

The new class must inherit from cloudreports.extensions.brokers.Broker (see previous section). The code of our new broker is showed below:

package brokers;

import cloudreports.extensions.brokers.Broker;
import java.util.List;

public class MyBroker extends Broker {

  public MyBroker(String name) throws Exception {
    super(name);
  }

  @Override
  public List<Integer> getDatacenterIdList() {
    return super.getDatacenterIdsList();
  }

  @Override
  public int getDatacenterId() {
    return getId();
  }
}

Now export the project to a .jar file. First, click on Export on the file menu:

![exportproject] (http://dl.dropbox.com/u/737234/CloudReports/wiki/exportproject.png)

Select Java -> JAR file and click Next. Then, select the MyExtensions project, name the .jar file (we'll call it MyExtensions.jar) and click Finish.

That's it. The generated .jar file contains everything CloudReports needs to load the new broker. The same steps can be used for other types of extensions.

Tip: You can create as many extensions as you need in a single project and pack it in a single .jar file. CloudReports will automatically identify and load all your extensions as long as you have a valid classnames.xml file (see next section).

Loading extensions

The steps below describes how to make CloudReports identify extensions.

Inside the folder that contains the CloudReports' jar file (we'll call it cloudreports), create a new folder called extensions (beware, it's case sensitive):

mkdir extensions

This new folder must contain a file named classnames.xml that follows the template below:

<?xml version="1.0" encoding="UTF-8"?>
<classnames>
  <class name="value1" type="value2" alias="value3" filename="value4"/>
  <!-- Follows with one class node for each extension -->
</classnames>

This is a very important file, so pay attention to how it must be written. Every class node describes a specific extension. In this example, we will fill the values considering the broker created in the previous section.

The value1 must contain the full classname of the new class: name="brokers.MyBroker".

The value2 contains the type of the extension: type="Broker".

The value3 describes the name that will identify the extension and be displayed on CloudReports' GUI: alias="My broker".
Important: Every extension of a given type must have a unique alias. For instance, we can have a broker and a power model both called foo, but we cannot have two brokers with this same alias.

The value4 identifies the file that contains the extension: filename="MyExtensions.jar".

Therefore, in order to run the MyBroker extension, the classnames.xml file must look like this:

<?xml version="1.0" encoding="UTF-8"?>
<classnames>
  <class name="brokers.MyBroker" type="Broker" alias="My broker" filename="MyExtensions.jar"/>
</classnames>

Now, run cloudreports and see the new broker:

![newbroker] (http://dl.dropbox.com/u/737234/CloudReports/wiki/newbroker.png)