Incubator > Beehive
 

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.