You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beehive.apache.org by ek...@apache.org on 2006/01/09 21:11:51 UTC
svn commit: r367381 - in
/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs:
controls/gettingStarted.xml controls/tutorial_controls.xml tabs.xml
Author: ekoneil
Date: Mon Jan 9 12:11:46 2006
New Revision: 367381
URL: http://svn.apache.org/viewcvs?rev=367381&view=rev
Log:
Updates to the Controls tutorial. Reworking some of the content around JUnit testing to have more explanation, split the tests into a separate sub-directory, different use of JUnit, etc.
More updates to come...
BB: self
Test: docs build pass
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/gettingStarted.xml
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/tutorial_controls.xml
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/tabs.xml
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/gettingStarted.xml
URL: http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/gettingStarted.xml?rev=367381&r1=367380&r2=367381&view=diff
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/gettingStarted.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/gettingStarted.xml Mon Jan 9 12:11:46 2006
@@ -5,25 +5,31 @@
<title>Controls: Getting Started</title>
</header>
<body>
- <p>For an introduction to the basic concepts of Java Controls, see the <strong>users guide</strong> topics:
+ <p>
+ To get started developing and using controls, see the <strong>user's guide</strong> topics:
</p>
<ul>
<li><a href="site:control_overview">Controls Overview</a></li>
<li><a href="site:control_programming">Control Programming</a></li>
<li><a href="site:control_containment">Control Containment</a></li>
</ul>
- <p>The following <strong>tutorial</strong> will familiarize with the basic development cycle for Java Controls:</p>
+ <p>
+ The following <strong>project template</strong> will help you get a Control project started:
+ </p>
<ul>
- <li><a href="site:tutorial_control">Controls Tutorial</a></li>
+ <li><a href="site:control-blank">Project: Control</a></li>
</ul>
- <p>The following <strong>project template</strong> will help you get a
- Control project started:</p>
+ <p>
+ The following <strong>tutorial</strong> will familiarize you with the steps for building and testing a Control:
+ </p>
<ul>
- <li><a href="site:control-blank">Project: Control</a></li>
+ <li><a href="site:tutorial_control">Controls Tutorial</a></li>
</ul>
</body>
<footer>
- <legal>Java, J2EE, and JCP are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.<br/>
+ <legal>
+ Java, J2EE, and JCP are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.
+ <br/>
© 2004, Apache Software Foundation
</legal>
</footer>
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/tutorial_controls.xml
URL: http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/tutorial_controls.xml?rev=367381&r1=367380&r2=367381&view=diff
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/tutorial_controls.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/tutorial_controls.xml Mon Jan 9 12:11:46 2006
@@ -5,90 +5,84 @@
<title>Beehive Controls Tutorial</title>
</header>
<body>
- <section id="intro">
+ <section id="introduction">
<title>Introduction</title>
- <section id="goals">
- <title>Tutorial Goals</title>
- <p>
- The Controls tutorial is provided as a way to become familiar with the concepts of Controls in Beehive. The tutorial
- walks through creating, building, and packaging and testing a simple Hello World control. In this tutorial, you will learn:
- </p>
- <ul>
- <li>What Beehive Controls are for and what they do.</li>
- <li>How to create a Beehive Control interface and implementation.</li>
- <li>How to compile a Beehive Control.</li>
- <li>How to package a Control as a distributable JAR file.</li>
- <li>How to test a Control using JUnit.</li>
- <li>How to use a Beehive Control as a component in a larger application.</li>
- <li>How to use metadata annotations in Beehive Controls.</li>
- <li>How to create custom metadata annotations.</li>
- </ul>
- </section>
+ <p>
+ The Controls Tutorial is a good way to become familiar with the concepts of Beehive Controls. This describes
+ how to write, build, package, and test a simple Hello Control. The following concepts will be convered here:
+ </p>
+ <ul>
+ <li>How to create a standalone Beehive Control project</li>
+ <li>How to create a Control interface and implementation</li>
+ <li>How to compile a Control</li>
+ <li>How to package a Control into a JAR file</li>
+ <li>How to test a Control using JUnit</li>
+ </ul>
+ <p>
+ For a technical description of Controls, see the <a href="site:control_programming">Controls programming guide</a>.
+ </p>
</section>
<section id="setup">
<title>Step 1: Setup Control Development</title>
- <section id="setup_shell">
- <title>Set Shell Variables</title>
+ <section id="setup-beehive">
+ <title>Install Beehive</title>
<p>
- Complete all of the necessary and optional steps in the following topic: <a class="fork" href="site:setup">Beehive
- Installation and Setup</a>
- </p>
+ Complete all of the required and optional steps to install and setup Beehive <a class="fork" href="site:setup">here</a>.
+ </p>
</section>
- <section id="install_junit">
+ <section id="setup-junit">
<title>Install JUnit</title>
<p>
- <a href="http://sourceforge.net/project/showfiles.php?group_id=15278">Download</a> the latest version of JUnit.
- </p>
- <p>
- Unzip the junit.zip file into a directory of your choice.
+ In this tutorial, JUnit is the test framework used. In order to use JUnit, download a JUnit release
+ <a href="http://sourceforge.net/project/showfiles.php?group_id=15278">here</a> and unzip it into a local
+ directory.
</p>
</section>
- <section id="create_control_proj">
+ <section id="setup-control-project">
<title>Create a Control Project</title>
<p>
- Copy the directory <code><BeehiveRoot>/samples/controls-blank</code> to a location of your choice. For example, you might copy
- to the following location: <code>/beehive_projects/controls-blank</code>.
+ Copy the directory <code><BeehiveRoot>/samples/controls-blank</code> to a location of your choice. For example, you might copy
+ to the following location: <code>/beehive-projects/controls-blank</code>.
</p>
<p>
- Rename <code>controls-blank</code> to <code>controls_tutorial</code>.
+ Rename <code>controls-blank</code> to <code>controls_tutorial</code>.
</p>
<p>
- Edit the file <code>controls_tutorial/build.properties</code> so that the property <code>beehive.home</code> points to the top level folder of your
- beehive distribution.
+ Edit the file <code>controls_tutorial/build.properties</code> so that the property <code>beehive.home</code> points
+ to the top level folder of your Beehive distribution.
</p>
<p>
- Add the property <code>junit.home</code> to the file and ensure that it points to your junit installation.
+ Add the property <code>junit.home</code> to the file and ensure that it points to your JUnit installation.
</p>
<p>
- For example, if your Beehive distribution is located at <code>/apache/apache-beehive-1.0</code>
- and junit is located at /test-tools/junit,
- then your <code>build.properties</code> file would appear as follows.
+ For example, if Beehive distribution is located in <code>/apache/apache-beehive-1.0</code>
+ and JUnit is located in <code>/test-tools/junit</code>, then your <code>build.properties</code> file
+ would appear as follows:
</p>
<source>
beehive.home=<strong>/apache/apache-beehive-1.0</strong>
-junit.home=<strong>/test-tools/junit</strong>
- </source>
+junit.home=<strong>/test-tools/junit</strong></source>
<note>
- Properties files should use the '/' character to separate drive, directory, and file names.
+ Properties files should use the '/' character to separate drive, directory, and file names.
</note>
</section>
</section>
<section id="compile">
- <title>Step 2: Compile the Control Implementation and Interface Files</title>
- <section id="compile_introduction">
+ <title>Step 2: Compile Control Interface and Implementation Source Files</title>
+ <section id="compile-introduction">
<title>Introduction</title>
- <p>A Beehive Control consists of two files: an interface file and an implementation file. The interface file is the
- public face of your control. It lists all of the methods which can be invoked by
- users. The implementation file contains the implementation code for the methods
- listed in the interface file.</p>
+ <p>
+ A Beehive Control consists of two source files -- an interface file and an implementation file. The interface
+ file is the public API of a control and provides all of the methods that can be invoked by a Control user (or client).
+ The implementation file contains the implementation code for the methods listed in the interface file.
+ </p>
</section>
- <section id="compile_examine"><title>Examine the Control Files</title>
+ <section id="compile-examine">
+ <title>A Control's Source Files</title>
<p>Open the file <code>/controls_tutorial/src/pkg/HelloImpl.java</code>.</p>
- <p>The implementation file appears as follows. (There is no need to edit the file at
- this point in the tutorial.)</p>
- <source>
-package pkg;
+ <p>The implementation file appears as follows. (There is no need to edit the file at this point in the tutorial.)</p>
+ <source>package pkg;
import org.apache.beehive.controls.api.bean.ControlImplementation;
@@ -97,10 +91,9 @@
implements Hello {
public String hello() {
- return "hello!";
+ return "Hello!";
}
-}
- </source>
+}</source>
<p>
Open the file <code>controls_tutorial/src/pkg/Hello.java</code>. The interface file should appear appears as follows.
</p>
@@ -109,239 +102,184 @@
import org.apache.beehive.controls.api.bean.ControlInterface;
@ControlInterface
-public interface Hello
-{
+public interface Hello {
String hello();
-}
- </source>
+}</source>
</section>
- <section id="set_jar_name">
- <title>Set the Name of the Built Control JAR File</title>
+ <section id="name-control-jar">
+ <title>Set a Name for the Hello Control JAR</title>
<p>
- In this task you will set the name of the built JAR file.
+ This step sets the name of the JAR file created when compiling the <code>Hello</code> and <code>HelloImpl</code> interface
+ and implementation.
</p>
<p>
- Edit the file <code>controls_tutorial/build.xml</code> so it appears as follows. Code to edit appears in bold.
+ Edit the file <code>controls_tutorial/build.xml</code> to set the <code>build.jar</code> property to the name
+ <code>helloControl.jar</code>. The property should appear as:
</p>
<source>
<project name="<strong>controls_tutorial</strong>" default="usage" basedir=".">
-
...
-
<property name="build.jar" value="<strong>helloControl.jar</strong>"/>
-
...
- </source>
+<project></source>
</section>
<section id="build">
- <title> Compile the Control </title>
- <p> You are now ready to compile the control. </p>
- <p> The following Ant command assumes that you are in the
- <code>controls_tutorial</code> directory. At the command prompt, enter: </p>
+ <title>Build and Package the Control</title>
+ <p>
+ Now, compile the control and build the Control's JAR file. The following Ant command should be run from the
+ <code>controls_tutorial</code> project directory; at the command prompt, enter:
+ </p>
<source>ant clean build</source>
- <p> A JAR file is created and saved at
- <code>controls_tutorial/build/helloControl.jar</code> </p>
+ <p>
+ The Control's classes are generated in <code>build/classes</code>, and the Control's JAR file is created in <code>build/helloControl.jar</code>.
+ </p>
</section>
</section>
- <section id="test_setup">
+ <section id="test-setup">
<title>Step 3: Create a JUnit Test for the Control</title>
- <section id="add_test_class">
- <title>Add a Test Class</title>
- <p>In the directory <code>/controls_tutorial/src</code> create a directory named <code>tests</code>.</p>
- <p>In the directory <code>/controls_tutorial/src/tests</code> create a file named <code>Tests.java</code>.</p>
- <p>Edit the file <code>Tests.java</code> so appears as follows</p>
- <source>
-package tests;
+ <section id="add-test-class">
+ <title>Create a JUnit Test Class</title>
+ <p>
+ Now that the control builds successfully, it's time to write a JUnit test case to ensure that the
+ Control operates as it is intended. To do this, create a <code>tests</code> directory to contain
+ the JUnit test cases for the control. The directory should be created under <code>controls_tutorial/tests</code>
+ with the command:
+ </p>
+ <source>mkdir tests</source>
+ <p>
+ In this directory, create a Java package to contain the source of a JUnit test with:
+ </p>
+ <source>mkdir tests/testpackage</source>
+ <p>
+ Now, create a JUnit test case called <code>HelloControlTest.java</code>. This class wil declare an instance of the
+ Hello control and unit test its API. This class should appear as follows:
+ </p>
+ <source>package testpackage;
import org.apache.beehive.controls.api.bean.Control;
+import org.apache.beehive.controls.test.junit.ControlTestCase;
+
import pkg.Hello;
-import org.apache.beehive.controls.test.junit.ControlTestCase;
+public class Tests
+ extends ControlTestCase {
-public class Tests extends ControlTestCase
-{
@Control
private Hello _helloControl;
- public void testHello() throws Exception
- {
- String message = _helloControl.hello();
- if(!message.equalsIgnoreCase("hello!"))
- fail("Method hello() failed to return message 'hello!'.");
- }
-}
- </source>
- </section>
- <section id="add_test_to_build">
- <title>Edit the build.xml File</title>
- <p>
- Edit the file build.xml so it appears as follows. Code to edit and add appears in bold:
- </p>
- <source>
-<?xml version="1.0" ?>
-
-<project name="controls_tutorial" default="usage" basedir=".">
-
- <property environment="os"/>
- <property file="build.properties"/>
- <import file="${beehive.home}/beehive-imports.xml"/>
- <import file="${beehive.home}/ant/beehive-tools.xml"/>
-
- <property name="source.dir" location="${basedir}/src"/>
- <property name="build.dir" location="${basedir}/build"/>
- <property name="build.classes" location="${build.dir}/classes"/>
- <property name="build.beansrc" location="${build.dir}/beansrc"/>
- <property name="build.jar" value="helloControl.jar"/>
- <strong><property name="junit.jar" value="${junit.home}/junit.jar"/>
- <property name="commons.disc.jar" value="${beehive.home}/lib/common/commons-discovery-0.2.jar"/>
- <property name="commons.log.jar" value="${beehive.home}/lib/common/commons-logging-1.0.4.jar"/></strong>
-
-
- <path id="build.classpath">
- <pathelement path="${build.classes}"/>
- <path refid="controls.dependency.path"/>
- </path>
-
- <strong><path id="test.classpath">
- <pathelement path="${junit.jar}"/>
- <pathelement path="${commons.disc.jar}"/>
- <pathelement path="${commons.log.jar}"/>
- <pathelement path="${build.classes}"/>
- <path refid="controls.dependency.path"/>
- </path></strong>
-
- <target name="clean" description="Delete all generated files">
- <delete dir="${build.dir}"/>
- <delete file="velocity.log"/>
- </target>
-
- <target name="build" description="Build control sources">
- <mkdir dir="${build.classes}"/>
- <mkdir dir="${build.beansrc}"/>
-
- <build-controls srcdir="${source.dir}"
- destdir="${build.classes}"
- tempdir="${build.beansrc}"
- classpathref="build.classpath"/>
+ public void testHello()
+ throws Exception {
+ String message = _helloControl.hello();
- <control-jar destfile="${build.dir}/${build.jar}" basedir="${build.classes}" />
- </target>
-
- <strong><target name="test" description="Run the JUnit Tests">
- <java
- classname="junit.textui.TestRunner"
- classpathref="test.classpath">
- <arg line="tests.Tests"/>
- </java>
- </target></strong>
-
- <target name="usage" description="Print the usage for this build.xml">
- <echo message=""/>
- <echo message=""/>
- <echo message="Controls Project Template Build file"/>
- <echo message=""/>
- <echo message=""/>
- <echo message="----------------------------------------------------------------"/>
- <echo message="| Standard Targets |"/>
- <echo message="----------------------------------------------------------------"/>
- <echo message="clean - Delete all generated files"/>
- <echo message="build - Build control sources"/>
- <strong><echo message="test - Test the control"/></strong>
- <echo message="----------------------------------------------------------------"/>
- </target>
-
-</project>
-
- </source>
- </section>
- <section id="run_test">
- <title>Run the Test</title>
- <p>In your command shell, ensure that you are in the directory <code>controls_tutorial/</code></p>
- <p>Run the following Ant command to test the control.</p>
- <source>
+ assertEquals("Hello!", message, "Failed to receive message 'Hello!'.");
+ }
+}</source>
+ </section>
+ <section id="add-test-to-build">
+ <title>Edit build.xml to Compile and Run the JUnit Test</title>
+ <p>
+ Now that the test has been written, the Ant build.xml file still needs to change to support building
+ and running JUnit tests. To do this, add the following target to build the JUnit tests; this target
+ would appear as follows:
+ </p>
+ <source>
+todo
+ </source>
+ <p>
+ Now, add a target to run the JUnit tests. This can be done in several different ways; here, Ant's
+ JUnit targets are used.
+ </p>
+ <source>
+todo
+ </source>
+ </section>
+ <section id="run-test">
+ <title>Run the Test</title>
+ <p>In your command shell, ensure that you are in the directory <code>controls_tutorial/</code></p>
+ <p>Run the following Ant command to test the control.</p>
+ <source>
ant clean build test
- </source>
- </section>
+ </source>
</section>
- <section id="add_parameter_method">
- <title>Step 4: Add a Parameterized Method to the Control</title>
+ </section>
+ <section id="add-parameter-method">
+ <title>Step 4: Edit the Control and Re-test</title>
<section>
<title>Edit the Control Source Files</title>
<p>Edit the file <code>HelloImpl.java</code> so it appears as follows. Code to add appears in bold</p>
<source>package pkg;
- import org.apache.beehive.controls.api.bean.ControlImplementation;
-
- @ControlImplementation(isTransient=true)
- public class HelloImpl implements Hello
- {
- public String hello()
- {
- return "hello!";
- }
+import org.apache.beehive.controls.api.bean.ControlImplementation;
- <strong> public String helloParam(String name)
- {
- return "Hello, " + name + "!";
- }</strong>
+@ControlImplementation(isTransient=true)
+public class HelloImpl
+ implements Hello {
+
+ public String hello() {
+ return "Hello!";
}
- </source>
+
+<strong>public String hello(String name) {
+ return "Hello, " + name + "!";
+ }</strong>
+}</source>
<p>Edit the file <code>Hello.java</code> so it appears as follows. Code to add appears in bold</p>
<source>package pkg;
- import org.apache.beehive.controls.api.bean.ControlInterface;
+import org.apache.beehive.controls.api.bean.ControlInterface;
- @ControlInterface
- public interface Hello
- {
- String hello();
+@ControlInterface
+public interface Hello {
+ String hello();
- <strong>String helloParam(String name);</strong>
- }
- </source>
+ <strong>String hello(String name);</strong>
+}</source>
</section>
<section>
<title>
Add a Test Case for the New Control Method
</title>
<p>Edit the file <code>Tests.java</code> so it appears as follows. Code to add appears in bold.</p>
- <source>
-package tests;
+ <source>package testpackage;
import org.apache.beehive.controls.api.bean.Control;
+import org.apache.beehive.controls.test.junit.ControlTestCase;
+
import pkg.Hello;
-import org.apache.beehive.controls.test.junit.ControlTestCase;
+public class Tests
+ extends ControlTestCase {
-public class Tests extends ControlTestCase
-{
@Control
private Hello _helloControl;
- public void testHello() throws Exception
- {
- String message = _helloControl.hello();
- if(!message.equalsIgnoreCase("hello!"))
- fail("Method hello() failed to return message 'hello!'.");
+ public void testHello()
+ throws Exception {
+
+ String message = _helloControl.hello();
+ assertEquals("Hello!", message, "Failed to receive message 'Hello!'.");
}
- <strong>public void testParam() throws Exception
- {
- String message = _helloControl.helloParam("World");
- if(!message.equalsIgnoreCase("Hello, World!"))
- fail("Method helloParam() failed to return message 'Hello, World!'.");
+ <strong>public void testParam()
+ throws Exception {
+ String message = _helloControl.hello("World");
+
+ assertEquals("Hello, World!", message, "Failed to receive message 'Hello, World!'.");
}</strong>
-}
- </source>
+}</source>
</section>
- <section id="run_test2">
+ <section id="run-test2">
<title>Run the Test</title>
- <p>Test the control according to the previous instructions <a href="#run_test">here</a>.</p>
+ <p>
+ Test the control according to the previous instructions <a href="#run_test">here</a>.
+ </p>
</section>
- </section>
+ </section>
</body>
<footer>
- <legal>Java, J2EE, and JCP are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.<br/>© 2005, Apache Software Foundation
+ <legal>
+ Java, J2EE, and JCP are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.
+ <br/>© 2005, Apache Software Foundation
</legal>
</footer>
</document>
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/tabs.xml
URL: http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/tabs.xml?rev=367381&r1=367380&r2=367381&view=diff
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/tabs.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/tabs.xml Mon Jan 9 12:11:46 2006
@@ -17,6 +17,6 @@
be displayed when their parent tab is selected.
-->
- <tab id="home" label="Home" dir="" href="http://beehive.apache.org"/>
+ <tab id="welcome" label="Home" dir="" href="http://beehive.apache.org"/>
<tab id="release-svn" label="Beehive SVN" dir="" indexfile="index.html"/>
</tabs>