Beehive Controls Tutorial
Introduction
Tutorial Goals
In this tutorial, you will learn:
- What Beehive Controls are for and what they do
- How to create a Beehive Control interface and implementation
- How to compile a Beehive Control
- How to use a Beehive Control as a component in a larger application
- How to use metadata annotations in Beehive Controls
- How to create custom metadata annotations
Step 1: Begin the Control Tutorial
To Set up the Development Environment
Complete all of the necessary and optional steps in the following topic: Beehive Installation and Setup
After completing the instructions, leave the command shell open to use throughout this tutorial.
Before proceding, confirm that you have the following variables set in your shell:
- BEEHIVE_HOME
- ANT_HOME
- JAVA_HOME
- CATALINA_HOME
Also ensure that the following elements are on your PATH:
- ANT_HOME/bin
- JAVA_HOME/bin
To Make a Control Project Folder
In this task you will make a control project folder.
On your C: drive, create a directory called beehive_projects.
Copy the folder BEEHIVE_HOME/samples/controls-blank into C:/beehive_projects.
Rename the folder C:/beehive_projects/controls-blank to the name C:/beehive_projects/controls_tutorial
Before proceeding, confirm that the following directory structure exists:
C: beehive_projects controls_tutorial src build.xml
To Create a Web Application Test Environment
In this step you create a web application that serves as the testing ground for your control. To test the control, you will import the control into the web application and invoke the control methods from the web application.
Copy the folder BEEHIVE_HOME/samples/netui-blank into C:/beehive_projects.
Rename the folder C:/beehive_projects/netui-blank to the name C:/beehive_projects/controls_tutorial_test
Before proceeding, confirm that the following directory structure exists:
C: beehive_projects controls_tutorial_test resources WEB-INF Controller.jpf error.jsp index.jsp
In this section you will edit the build.properties file--the file that sets the build-related properties for your test environment.
Open the file C:/beehive_projects/controls_tutorial_test/WEB-INF/src/build.properties in a text editor.
Edit the beehive.home property points to the top-level folder of your beehive installation.
Add the line contextPath=controls_tutorial_test (as shown below).
For example, if your beehive installation resides at C:/apache/apache-beehive-1.0, then your build.properties file would appear as follows.
beehive.home=C:/apache/apache-beehive-1.0 contextPath=controls_tutorial_test servlet-api.jar=${os.CATALINA_HOME}/common/lib/servlet-api.jar jsp-api.jar=${os.CATALINA_HOME}/common/lib/jsp-api.jar
To Start the Tomcat Server
At the command prompt, enter:
%CATALINA_HOME%\bin\startup.bat
Step 2: Compile the Template Control Implementation and Interface Files
Introduction
A Beehive Control consists of two files: an interface file (with the JAVA file extension) and an implementation file (with the JCS file extension). 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.
To Examine the Template Control Files
Open the file C:/beehive_projects/controls_tutorial/src/pkg/HelloImpl.jcs.
The implementation file appears as follows. (There is no need to edit the file at this point in the tutorial.)
package pkg; import org.apache.beehive.controls.api.bean.*; @ControlImplementation public class HelloImpl implements Hello { public String hello() { return "hello!"; } }
Open the file C:/beehive_projects/controls_tutorial/src/pkg/Hello.java.
The interface file appears as follows. (There is no need to edit the file at this point in the tutorial.)
package pkg; import org.apache.beehive.controls.api.bean.*; @ControlInterface public interface Hello { String hello(); }
To Edit the index.jspTest Page
To test the Hello control, you need to call the control from some other resource, such as a JAVA application, JSP page, or Page Flow web application. In this step you will call the control from a JSP page.
Edit the file C:/beehive_projects/controls_tutorial_test/index.jsp so it appears as follows. Code to edit appears in bold.
<%@ page language="java" contentType="text/html;charset=UTF-8"%> <%@ taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0" prefix="netui-data"%> <%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0" prefix="netui"%> <%@ taglib uri="http://beehive.apache.org/netui/tags-template-1.0" prefix="netui-template"%> <netui:html> <head> <title>Control Tutorial Test Page</title> <netui:base/> </head> <netui:body> <jsp:useBean class="pkg.HelloBean" id="helloBean" scope="session"/> <h3>Control Tutorial Test Page</h3> <p> Response from the hello() method on the Hello Control: <strong> <%= helloBean.hello() %> </strong> </p> </netui:body> </netui:html>
Save index.jsp.
To Compile and Deploy the Control
You are now ready to compile the control.
At the command prompt, enter the following Ant command.
ant -f C:\beehive_projects\controls_tutorial\build.xml build Copy and Paste version: ant -f C:\beehive_projects\controls_tutorial\build.xml build
Now copy the JAR file into the test web application.
copy C:\beehive_projects\controls_tutorial\build\mycontrols.jar C:\beehive_projects\controls_tutorial_test\WEB-INF\lib Copy and Paste version: copy C:\beehive_projects\controls_tutorial\build\mycontrols.jar C:\beehive_projects\controls_tutorial_test\WEB-INF\lib
You are now ready to compile the test environment and deploy it to Tomcat.
At the command prompt, enter:
ant -f C:\beehive_projects\controls_tutorial_test\WEB-INF\src\build.xml clean build war Copy and Paste version: ant -f C:\beehive_projects\controls_tutorial_test\WEB-INF\src\build.xml clean build war
To deploy the application, copy the WAR file into Tomcat's webapps directory.
copy C:\beehive_projects\controls_tutorial_test.war %CATALINA_HOME%\webapps
To Test the Control
Open a web browser and enter the following in the address bar:
http://localhost:8080/controls_tutorial_test/index.jsp
You will be directed to the index.jsp page.
Note the message on the page: "hello!"
This message is provided by the Hello control.
Step 3: Add a Parameterized Method to the Control
To edit the Interface and Implementation Files
Edit HelloImpl.jcs so it appears as follows. Code to add appears in bold.
package pkg; import org.apache.beehive.controls.api.bean.*; @ControlImplementation public class HelloImpl implements Hello { public String hello() { return "hello!"; } public String helloParam( String name ) { return "Hello, " + name + "!"; } }
Save and close HelloImpl.jcs
Edit Hello.java so it appears as follows. Code to add appears in bold.
package pkg; import org.apache.beehive.controls.api.bean.*; @ControlInterface public interface Hello { String hello(); String helloParam( String name ); }
To Edit the Test JSP Page
Edit index.jsp so it appears as follows. Code to add appears in bold.
<%@ page language="java" contentType="text/html;charset=UTF-8"%> <%@ taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0" prefix="netui-data"%> <%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0" prefix="netui"%> <%@ taglib uri="http://beehive.apache.org/netui/tags-template-1.0" prefix="netui-template"%> <netui:html> <head> <title>Control Tutorial Test Page</title> <netui:base/> </head> <netui:body> <jsp:useBean class="pkg.HelloBean" id="helloBean" scope="session"/> <h3>Control Tutorial Test Page</h3> <p> Response from the hello() method on the Hello Control: <strong> <%= helloBean.hello() %> </strong> </p> <p> Response from the helloParam() method on the Hello Control: <strong> <%= helloBean.helloParam("Moon") %> </strong> </p> </netui:body> </netui:html>
Save and close index.jsp
To Compile and Deploy the Control
You are now ready to compile the control.
At the command prompt, enter the following Ant command.
ant -f C:\beehive_projects\controls_tutorial\build.xml build Copy and Paste version: ant -f C:\beehive_projects\controls_tutorial\build.xml build
Now copy the JAR file into the test web application.
copy C:\beehive_projects\controls_tutorial\build\mycontrols.jar C:\beehive_projects\controls_tutorial_test\WEB-INF\lib Copy and Paste version: copy C:\beehive_projects\controls_tutorial\build\mycontrols.jar C:\beehive_projects\controls_tutorial_test\WEB-INF\lib
You are now ready to compile the test environment and deploy it to Tomcat.
At the command prompt, enter:
ant -f C:\beehive_projects\controls_tutorial_test\WEB-INF\src\build.xml clean build war Copy and Paste version: ant -f C:\beehive_projects\controls_tutorial_test\WEB-INF\src\build.xml clean build war
To deploy the application, copy the WAR file into Tomcat's webapps directory.
copy C:\beehive_projects\controls_tutorial_test.war %CATALINA_HOME%\webapps
To Test the Control
Open a web browser and enter the following in the address bar:
http://localhost:8080/controls_tutorial_test/index.jsp
You will be directed to the index.jsp page.
Note the messages on the page: "hello!" and "Hello, Moon!"
These messages are provided by the Hello control.