cloudstack-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From seb...@apache.org
Subject git commit: updated refs/heads/4.1 to c1bdaf4
Date Sat, 29 Jun 2013 19:53:20 GMT
Updated Branches:
  refs/heads/4.1 fa6fac4ad -> c1bdaf475


Add docs for plugin development


Project: http://git-wip-us.apache.org/repos/asf/cloudstack/repo
Commit: http://git-wip-us.apache.org/repos/asf/cloudstack/commit/c1bdaf47
Tree: http://git-wip-us.apache.org/repos/asf/cloudstack/tree/c1bdaf47
Diff: http://git-wip-us.apache.org/repos/asf/cloudstack/diff/c1bdaf47

Branch: refs/heads/4.1
Commit: c1bdaf475b2c5e85f83ee1d09e801c933a7982d6
Parents: fa6fac4
Author: Ian Duffy <ian@ianduffy.ie>
Authored: Fri Jun 28 13:33:20 2013 +0100
Committer: Sebastien Goasguen <runseb@gmail.com>
Committed: Sat Jun 29 15:53:09 2013 -0400

----------------------------------------------------------------------
 docs/en-US/creating-a-plugin.xml        |  29 ++++
 docs/en-US/creating-my-first-plugin.xml | 216 +++++++++++++++++++++++++++
 docs/en-US/plugin-development.xml       |  28 ++++
 3 files changed, 273 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cloudstack/blob/c1bdaf47/docs/en-US/creating-a-plugin.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/creating-a-plugin.xml b/docs/en-US/creating-a-plugin.xml
new file mode 100644
index 0000000..448d4e6
--- /dev/null
+++ b/docs/en-US/creating-a-plugin.xml
@@ -0,0 +1,29 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
[
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- 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.
+-->
+
+<chapter id="plugin-development">
+  <title>Plugin Development</title>
+  <para>This chapter will detail different elements related to the development of plugins
within Cloudstack</para>
+  <xi:include href="creating-my-first-plugin.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+</chapter>

http://git-wip-us.apache.org/repos/asf/cloudstack/blob/c1bdaf47/docs/en-US/creating-my-first-plugin.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/creating-my-first-plugin.xml b/docs/en-US/creating-my-first-plugin.xml
new file mode 100644
index 0000000..3809fd3
--- /dev/null
+++ b/docs/en-US/creating-my-first-plugin.xml
@@ -0,0 +1,216 @@
+<?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>

http://git-wip-us.apache.org/repos/asf/cloudstack/blob/c1bdaf47/docs/en-US/plugin-development.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/plugin-development.xml b/docs/en-US/plugin-development.xml
new file mode 100644
index 0000000..0492877
--- /dev/null
+++ b/docs/en-US/plugin-development.xml
@@ -0,0 +1,28 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
[
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- 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.
+-->
+
+<chapter id="plugin-development">
+  <title>Plugin Development</title>
+  <xi:include href="creating-my-first-plugin.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+</chapter>


Mime
View raw message