<?xml version='1.0' encoding='utf-8'?>
<!-- Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at
 
   http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
-->
<section id="creating-my-first-plugin">
    <title>Creating my first plugin</title>
    <para>This is a brief walk through of creating a simple plugin that adds an additional command to the API to return the message "Hello World".</para>
    <section id="letting-cloudstack-know-about-the-plugin">
        <title>Letting Cloudstack know about the plugin</title>
        <para>Before we can being we need to tell Cloudstack about the existance of our plugin. In order to do this we are required to edit some files related to the cloud-client-ui module</para>
        <orderedlist>
            <listitem>
                <para>Navigate to the folder called client</para>
            </listitem>
            <listitem>
                <para>Open pom.xml and add a dependency, this will look something like the following: </para>
                <example>
                    <title>client/pom.xml</title>
                    <programlisting language="XML">&lt;dependency&gt;
  &lt;groupId&gt;org.apache.cloudstack&lt;/groupId&gt;
  &lt;artifactId&gt;cloud-plugin-api-helloworld&lt;/artifactId&gt;
  &lt;version&gt;${project.version}&lt;/version&gt;
&lt;/dependency&gt;</programlisting>
                </example>
            </listitem>
            <listitem>
                <para>Continuing with client as your working directory open up tomcatconf/applicationContext.xml.in</para>
            </listitem>
            <listitem>
                <para>Within this file we must insert a bean to load our class:</para>
                <example>
                    <title>client/tomcatconf/applicationContext.xml.in</title>
                    <programlisting language="XML">&lt;bean id="helloWorldImpl" class="org.apache.cloudstack.helloworld.HelloWorldImpl" /&gt;</programlisting>
                </example>
            </listitem>
            <listitem>
                <para>Finally we need to register the additional API commands we add. Again with client as your working directory this is done by modifying tomcatconf/commands.properties.in</para>
            </listitem>
            <listitem>
                <para>Within the file we simply add the names of the API commands we want to create followed by a permission number. 1 = admin, 2 = resource domain admin, 4 = domain admin, 8 = user.</para>
                <example>
                    <title>tomcatconf/commands.properties.in</title>
                    <programlisting>helloWorld=8</programlisting>
                </example>
            </listitem>
        </orderedlist>
    </section>
    <section id="creating-the-plugin">
        <title>Creating the plugin</title>
        <para>Within the Cloudstack filing structure all plugins live under the plugins folder. Since the sample plugin for this document is going to be API related it will live in plugins/api/helloworld. Along with this we will need a standard maven package layout, so lets create all the required folders:</para>
        <programlisting language="Bash">$ mkdir -p plugins/api/helloworld/{src,target,test}
$ mkdir -p plugins/api/helloworld/src/org/apache/cloudstack/{api,helloworld}
$ mkdir -p plugins/api/helloworld/src/org/apache/cloudstack/api/{command,response}
$ mkdir -p plugins/api/helloworld/src/org/apache/cloudstack/api/command/user/helloworld</programlisting>
        <para>With helloworld as our working directory we should have a tree layout like the following:</para>
        <programlisting language="Bash">$ cd plugins/api/helloworld
$ tree
.
|-- src
|   `-- org
|       `-- apache
|           `-- cloudstack
|               |-- api
|               |   |-- command
|               |   |   `-- user
|               |   |       `-- helloworld
|               |   |-- response
|               `-- helloworld
|-- target
`-- test
 
12 directories, 0 files</programlisting>
        <para>First we will create a pom.xml for our plugin:</para>
        <example>
            <title>plugins/api/helloworld/pom.xml</title>
            <programlisting language="XML">&lt;project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"&gt;
  &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
  &lt;artifactId&gt;cloud-plugin-api-helloworld&lt;/artifactId&gt;
  &lt;name&gt;Apache CloudStack Plugin - Hello World Plugin&lt;/name&gt;
  &lt;parent&gt;
    &lt;groupId&gt;org.apache.cloudstack&lt;/groupId&gt;
    &lt;artifactId&gt;cloudstack-plugins&lt;/artifactId&gt;
    &lt;version&gt;4.2.0-SNAPSHOT&lt;/version&gt;
    &lt;relativePath&gt;../../pom.xml&lt;/relativePath&gt;
  &lt;/parent&gt;
  &lt;dependencies&gt;
    &lt;dependency&gt;
      &lt;groupId&gt;org.apache.cloudstack&lt;/groupId&gt;
      &lt;artifactId&gt;cloud-api&lt;/artifactId&gt;
      &lt;version&gt;${project.version}&lt;/version&gt;
    &lt;/dependency&gt;
    &lt;dependency&gt;
      &lt;groupId&gt;org.apache.cloudstack&lt;/groupId&gt;
      &lt;artifactId&gt;cloud-utils&lt;/artifactId&gt;
      &lt;version&gt;${project.version}&lt;/version&gt;
    &lt;/dependency&gt;
  &lt;/dependencies&gt;
  &lt;build&gt;
    &lt;defaultGoal&gt;install&lt;/defaultGoal&gt;
    &lt;sourceDirectory&gt;src&lt;/sourceDirectory&gt;
    &lt;testSourceDirectory&gt;test&lt;/testSourceDirectory&gt;
  &lt;/build&gt;
&lt;/project&gt;</programlisting>
        </example>
        <para>Next we need to make the root plugin pom aware of our plugin to do this simply edit plugins/pom.xml inserting a line like the following:</para>
        <programlisting language="XML">......
&lt;module&gt;api/helloworld&lt;/module&gt;
......</programlisting>
        <para>Finally we will being to create code for your plugin. Create an interface called HelloWorld that will extend PluggableService within src/org/apache/cloudstack/hellowold</para>
        <programlisting language="Java">package org.apache.cloudstack.helloworld;
  
import com.cloud.utils.component.PluggableService;
  
public interface HelloWorld extends PluggableService { }</programlisting>
        <para>Create an implementation of HelloWorld called HelloWorldImpl:</para>
        <programlisting language="Java">package org.apache.cloudstack.helloworld;
 
import org.apache.cloudstack.api.command.user.helloworld.HelloWorldCmd;
import org.apache.log4j.Logger;
import org.springframework.stereotype.Component;
 
import javax.ejb.Local;
import java.util.*;
 
@Component
@Local(value = HelloWorld.class)
public class HelloWorldImpl implements HelloWorld {
    private static final Logger s_logger = Logger.getLogger(HelloWorldImpl.class);
     
    public HelloWorldImpl() {
        super();
    }
    /**
     * This informs cloudstack of the API commands you are creating.
     */
    @Override
    public List&lt;Class&lt;?&gt;&gt; getCommands() {
        List&lt;Class&lt;?&gt;&gt; cmdList = new ArrayList&lt;Class&lt;?&gt;&gt;();
        cmdList.add(HelloWorldCmd.class);
        return cmdList;
    }
}</programlisting>
        <para>Next we will create our API command navigate to src/org/apache/cloudstack/api/command/user/helloworld and open up HelloWorldCmd.java, create it as follows</para>
        <programlisting language="Java">package org.apache.cloudstack.api.command.user.helloworld;
 
import org.apache.cloudstack.api.APICommand;
import org.apache.cloudstack.api.BaseCmd;
import org.apache.cloudstack.api.response.HelloWorldResponse;
import org.apache.log4j.Logger;
 
// Note this name matches the name you inserted into client/tomcatconf/commands.properties.in
@APICommand(name = "helloWorld", responseObject = HelloWorldResponse.class, description = "Returns a hello world message", since = "4.2.0")
public class HelloWorldCmd extends BaseCmd {
    public static final Logger s_logger = Logger.getLogger(HelloWorldCmd.class.getName());
    private static final String s_name = "helloworldresponse";
  
    @Override
    public void execute()
    {
        HelloWorldResponse response = new HelloWorldResponse();
        response.setObjectName("helloworld");
        response.setResponseName(getCommandName());
        this.setResponseObject(response);
    }
  
    @Override
    public String getCommandName() {
        return s_name;
    }
  
    @Override
    public long getEntityOwnerId() {
        return 0;
    }
}</programlisting>
        <para>Finally we need to create our HelloWorldResponse class, this will exist within src/org/apache/cloudstack/api/response/</para>
        <programlisting language="Java">package org.apache.cloudstack.api.response;
 
import com.google.gson.annotations.SerializedName;
import org.apache.cloudstack.api.BaseResponse;
import com.cloud.serializer.Param;
 
@SuppressWarnings("unused")
public class HelloWorldResponse extends BaseResponse {
    @SerializedName("HelloWorld") @Param(description="HelloWorld Response")
    private String  HelloWorld;
  
    public HelloWorldResponse(){
        this.HelloWorld = "Hello World";
    }
}</programlisting>
    </section>
    <section id="compiling-your-plugin">
        <title>Compiling your plugin:</title>
        <para>Within the directory of your plugin i.e. plugins/api/helloworld run mvn clean install.</para>
        <para>After this we need to recompile the client-cloud-ui to do this come back to the cloudstack base directory and execute mvn -pl client clean install</para>
    </section>
    <section id="starting-cloudstack-and-testing">
        <title>Starting Cloudstack and Testing:</title>
        <para>Start up cloudstack with the normal mvn pl :client-cloud-ui jetty:run, wait a few moments for it to start up then head over to: localhost:8096/client/api?command=helloWorld and you should see your HelloWorld message.</para>
    </section>
</section>