You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cloudstack.apache.org by ah...@apache.org on 2013/07/01 23:25:11 UTC
[27/50] [abbrv] git commit: updated refs/heads/vmsync to f737019
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/15a68447
Tree: http://git-wip-us.apache.org/repos/asf/cloudstack/tree/15a68447
Diff: http://git-wip-us.apache.org/repos/asf/cloudstack/diff/15a68447
Branch: refs/heads/vmsync
Commit: 15a6844784142141af22224489a57d7d748c6687
Parents: 676d874
Author: Ian Duffy <ia...@ianduffy.ie>
Authored: Fri Jun 28 13:33:20 2013 +0100
Committer: Sebastien Goasguen <ru...@gmail.com>
Committed: Sat Jun 29 15:52:36 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/15a68447/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/15a68447/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"><dependency>
+ <groupId>org.apache.cloudstack</groupId>
+ <artifactId>cloud-plugin-api-helloworld</artifactId>
+ <version>${project.version}</version>
+</dependency></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"><bean id="helloWorldImpl" class="org.apache.cloudstack.helloworld.HelloWorldImpl" /></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"><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">
+ <modelVersion>4.0.0</modelVersion>
+ <artifactId>cloud-plugin-api-helloworld</artifactId>
+ <name>Apache CloudStack Plugin - Hello World Plugin</name>
+ <parent>
+ <groupId>org.apache.cloudstack</groupId>
+ <artifactId>cloudstack-plugins</artifactId>
+ <version>4.2.0-SNAPSHOT</version>
+ <relativePath>../../pom.xml</relativePath>
+ </parent>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.cloudstack</groupId>
+ <artifactId>cloud-api</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.cloudstack</groupId>
+ <artifactId>cloud-utils</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ </dependencies>
+ <build>
+ <defaultGoal>install</defaultGoal>
+ <sourceDirectory>src</sourceDirectory>
+ <testSourceDirectory>test</testSourceDirectory>
+ </build>
+</project></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">......
+<module>api/helloworld</module>
+......</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<Class<?>> getCommands() {
+ List<Class<?>> cmdList = new ArrayList<Class<?>>();
+ 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/15a68447/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>