You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beehive.apache.org by cs...@apache.org on 2007/02/27 23:39:59 UTC
svn commit: r512463 - in
/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs: ./
controls/samples/ netui/samples/ samples/ system-controls/jdbc/samples/
Author: cschoett
Date: Tue Feb 27 14:39:58 2007
New Revision: 512463
URL: http://svn.apache.org/viewvc?view=rev&rev=512463
Log:
Updated doc for the new jdbc and controls samples.
Added:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/samples/controlsLifecycle.xml (with props)
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/system-controls/jdbc/samples/
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/system-controls/jdbc/samples/jdbcSample.xml (with props)
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/samples/index.xml
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/samples/index.xml
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml
Added: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/samples/controlsLifecycle.xml
URL: http://svn.apache.org/viewvc/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/samples/controlsLifecycle.xml?view=auto&rev=512463
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/samples/controlsLifecycle.xml (added)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/samples/controlsLifecycle.xml Tue Feb 27 14:39:58 2007
@@ -0,0 +1,250 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Beehive Sample: Controls Life Cycle and Resource Events</title>
+ </header>
+ <body>
+ <section>
+ <title>Introduction</title>
+ <p>
+ This sample demonstrates several Beehive controls framework features:
+ </p>
+
+ <ul>
+ <li>Control life cycle and resource events</li>
+ <li>Adding a service to a control container context</li>
+ </ul>
+
+ <p>
+ The custom service provider can be found in the <code>service</code> package
+ of this sample. A custom service provider must implement the
+ <code>java.beans.beancontext.BeanContextServiceProvider</code> provider interface. The
+ <code>service.EventRecorderServiceProvider</code> class is the service provider for this sample
+ and gets added to the <code>ControlContainerContext</code> in the page flow controller's
+ <code>onCreate()</code> method.
+ </p>
+ <p>
+ The service returned by the <code>EventRecorderServiceProvider</code> is the
+ <code>EventRecorderService</code>. This service provides a mechanism for all controls within
+ the <code>ControlContainerContext</code> to log events with the service. Controls may access
+ the service by using the @Context annotation in their implementation.
+ </p>
+
+ <source>
+ .
+ .
+ @Context
+ private EventRecorderService myService;
+ .
+ .
+ </source>
+
+ <p>
+ See the <code>controls.OuterControlImpl</code> and <code>controls.InnerControlImpl</code> classes
+ for examples of how to access the EventRecorderService.
+ </p>
+
+ <p>
+ This sample uses the EventRecorderService to record controls life cycle and resource events
+ generated by the controls framework. Two scenarios are included:
+ </p>
+
+ <ul>
+ <li>page flow -> invoke outer control method</li>
+ <li>page flow -> invoked outer control method -> invoke inner control method</li>
+ </ul>
+
+ <p>
+ This is an interactive sample. A page flow is used to allow the user to invoke either
+ of these scenarios in any order and any number of times. After a scenario is invoked
+ the list of events is displayed by the page flow. To reset the state of the page flow and
+ the event list use the <code>Reset</code> link.
+ </p>
+
+ </section>
+
+ <section id="running">
+ <title>Running the Samples on Tomcat 5</title>
+ <p>
+ The following explains how to run this sample on Tomcat 5. The sample
+ will run on other web containers, but we have chosen Tomcat 5 for convenience.
+ </p>
+
+ <section id="set_up">
+ <title>To Set up the Environment</title>
+ <p>
+ Before proceeding, complete all of the necessary and optional steps in the
+ following topic:
+ <a class="fork" href="site:installation">Beehive Installation and Setup</a>
+ </p>
+
+ <p>
+ Open a command shell and confirm that you have set following variables:
+ </p>
+ <ul>
+ <li><code>ANT_HOME</code></li>
+ <li><code>JAVA_HOME</code></li>
+ <li><code>CATALINA_HOME</code></li>
+ </ul>
+ <p>
+ Also ensure that the following elements are on your <code>PATH</code>:
+ </p>
+ <ul>
+ <li><code>ANT_HOME/bin</code></li>
+ <li><code>JAVA_HOME/bin</code></li>
+ </ul>
+ </section>
+
+ <section id="copy_app">
+
+ <title>To Copy the Application to a Project Folder (Optional Step)</title>
+
+ <p>
+ To keep your Beehive distribution directory pristine, you should copy the
+ <code><BeehiveRoot>/samples/control-lifecycle</code> folder to another location before
+ proceeding.
+ </p>
+
+ <note>
+ <BeehiveRoot> refers to the top-level directory of your Beehive installation.
+ A typical value for <BeehiveRoot> would be <code>/apache/apache-beehive-1.0.2</code>.
+ </note>
+
+ <p>
+ The following instructions assume that you have copied the folder <code>controls-lifecycle</code>
+ into the directory <code>/beehive_projects</code>, resulting in the following directory structure.
+ </p>
+
+ <source>/
+ beehive_projects
+ controls-lifecycle
+ </source>
+
+ <note>
+ Strictly speaking, you do not need to copy the <code>controls-lifecycle</code>
+ directory to another location. If you wish to leave the <code>controls-lifecycle</code>
+ directory in place, in the instructions below you must replace occurrences of the path
+ element <code>/beehive_projects</code> with this path element: <code><BeehiveRoot>/samples</code>.
+ <br/><br/>
+ For example, to build the sample, run the following Ant command:
+ <br/><br/>
+ <code>ant -f <BeehiveRoot>/samples/controls-lifecycle/build.xml clean build war</code>
+ <br/><br/>
+ To delete the sample's build directory, run the <code>clean</code> target:
+ <br/><br/>
+ <code>ant -f <BeehiveRoot>/samples/controls-lifecycle/src/WEB-INF/build.xml clean</code>
+ </note>
+ </section>
+
+ <section id="edit_properties_file">
+ <title>Edit the <code>build.properties</code> File</title>
+ <p>
+ In this section you will edit the <code>build.properties</code> file--the file
+ that sets the build-related properties for your web application.
+ </p>
+ <p>
+ Open the file <code>/beehive_projects/netui-samples/WEB-INF/src/build.properties</code>
+ in a text editor.
+ </p>
+ <p>
+ Edit the file so that the <code>beehive.home</code> property points to the
+ top-level folder of your beehive installation. For example, if your beehive installation
+ resides at <code>/apache/apache-beehive-1.0.2</code>, then your <code>build.properties</code> file
+ would appear as follows.
+ </p>
+ <source>beehive.home=<strong>/apache/apache-beehive-1.0.2</strong>
+
+servlet-api.jar=${os.CATALINA_HOME}/common/lib/servlet-api.jar
+jsp-api.jar=${os.CATALINA_HOME}/common/lib/jsp-api.jar
+
+context.path=controls-lifecycle
+ </source>
+
+ <note>Windows users must use forwardslashes (/) not backslashes (\) in the
+ <code>build.properties</code> file.
+ </note>
+ </section>
+
+ <section id="compile">
+ <title>To Compile the Controls Life Cycle Sample</title>
+ <p>To compile the controls-lifecycle sample, enter the following Ant command:</p>
+<source>ant
+ -f /beehive_projects/controls-lifecycle/build.xml
+ clean
+ build
+ war
+
+<strong>Copy and Paste version:</strong>
+ant -f /beehive_projects/controls-lifecycle/build.xml clean build war</source>
+
+ </section>
+
+ <section id="start_tomcat">
+ <title>To Start Tomcat</title>
+
+ <p>
+ To start Tomcat, run the following command:
+ </p>
+
+ <source>%CATALINA_HOME%\bin\startup.bat</source>
+ <p>
+ Or, on non-Windows systems,
+ </p>
+ <source>$CATALINA_HOME/bin/startup.sh</source>
+ </section>
+
+ <section id="deploy">
+ <title>To Deploy to Tomcat</title>
+
+ <p>
+ To deploy the samples, copy the WAR file to Tomcat's <code>webapps</code> directory.
+ </p>
+ <p>
+ On Windows:
+ </p>
+
+ <source>copy C:\beehive_projects\netui-samples.war %CATALINA_HOME%\webapps /Y</source>
+
+ <note>
+ On Windows, there are file-locking issues that Tomcat versions 5.5.x and above are sensitive to.
+ In particular, any web application that uses Struts will <strong>fail to redeploy</strong> if you
+ copy in a new .war file as described here. The Commons Digester team is adding a workaround for the
+ issue (see
+ <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=37034">this bug</a>), but in the meantime,
+ you can work around it with the <code>antiResourceLocking</code> option in Tomcat. Just add a file
+ called <code>context.xml</code> in a directory called <code>META-INF</code> inside the
+ web application directory before building (so it will end up as <code>META-INF/context.xml</code>
+ in your <code>controls_tutorial.war</code>):
+ <br/>
+ <br/>
+ <code> <?xml version="1.0" encoding="UTF-8"?></code><br/>
+ <code> <Context antiResourceLocking="true"></code><br/>
+ <code> </Context></code>
+ </note>
+
+ <p>
+ Everywhere else:
+ </p>
+ <source>cp /beehive_projects/controls-lifecycle.war $CATALINA_HOME/webapps</source>
+ </section>
+
+ <section id="test">
+ <title>Running</title>
+
+ <p>
+ To start the sample visit the following link in a browser:
+ </p>
+ <p>
+ <a class="fork" href="http://localhost:8080/controls-lifecycle">http://localhost:8080/controls-lifecycle</a>
+ </p>
+ </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/>
+ © 2004, Apache Software Foundation
+ </legal>
+ </footer>
+</document>
Propchange: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/samples/controlsLifecycle.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/samples/index.xml
URL: http://svn.apache.org/viewvc/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/samples/index.xml?view=diff&rev=512463&r1=512462&r2=512463
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/samples/index.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/samples/index.xml Tue Feb 27 14:39:58 2007
@@ -85,7 +85,7 @@
<title>To Set up the Environment</title>
<p>Before proceeding, complete all of the necessary and optional steps in the
following topic:
- <a class="fork" href="#setup">Beehive Installation and Setup</a></p>
+ <a class="fork" href="site:installation">Beehive Installation and Setup</a></p>
<p>Open a command shell and confirm that you have set following variables:</p>
<ul>
<li><code>ANT_HOME</code></li>
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/samples/index.xml
URL: http://svn.apache.org/viewvc/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/samples/index.xml?view=diff&rev=512463&r1=512462&r2=512463
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/samples/index.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/samples/index.xml Tue Feb 27 14:39:58 2007
@@ -20,6 +20,12 @@
<li>
<a href="site:netui-jsf">NetUI: JSF Integration</a>
</li>
+ <li>
+ <a href="site:controls-lifecycle">Controls: Life Cycle Events</a>
+ </li>
+ <li>
+ <a href="site:system-controls-jdbc">System Controls: JDBC Control Sample</a>
+ </li>
</ul>
<p>
<strong>Project Templates</strong>
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml
URL: http://svn.apache.org/viewvc/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml?view=diff&rev=512463&r1=512462&r2=512463
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml Tue Feb 27 14:39:58 2007
@@ -134,7 +134,9 @@
<jdbc_control_annotations label="Annotations" href="system-controls/jdbc/jdbc-annot-guide.html"/>
<jdbc_control_paramsub label="Parameter Substitution" href="system-controls/jdbc/jdbc-paramsub-guide.html"/>
<jdbc_control_storedproc label="Stored Procedures" href="system-controls/jdbc/jdbc-storedprocs-guide.html"/>
- <jdbc_control_storedfunc label="Return Type Mapping" href="system-controls/jdbc/jdbc-typemapping-guide.html"/>
+ <jdbc_control_typemapping label="Return Type Mapping" href="system-controls/jdbc/jdbc-typemapping-guide.html">
+ <custom_typemapping href="#Creating+Customer+Result+Set+Mappers"/>
+ </jdbc_control_typemapping>
<jdbc_control_conmgmt label="Connection Management" href="system-controls/jdbc/jdbc-connectionmgmt-guide.html"/>
<jdbc_tutorial label="Tutorial" href="/system-controls/jdbc/tutorial.html"/>
</jdbc>
@@ -145,6 +147,8 @@
<petstore label="Petstore" href="samples/petstore.html"/>
<netui-samples label="NetUI Samples" href="netui/samples/index.html"/>
<netui-jsf label="NetUI + JSF Integration" href="netui/samples/jsfIntegration.html"/>
+ <controls-lifecycle label="Controls Life Cycle" href="controls/samples/controlsLifecycle.html"/>
+ <system-controls-jdbc label="JDBC Control" href="system-controls/jdbc/samples/jdbcSample.html"/>
<netui-blank label="Project: NetUI" href="netui/samples/netuiBlank.html"/>
<control-blank label="Project: Control" href="controls/samples/controlsBlank.html"/>
</samples>
Added: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/system-controls/jdbc/samples/jdbcSample.xml
URL: http://svn.apache.org/viewvc/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/system-controls/jdbc/samples/jdbcSample.xml?view=auto&rev=512463
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/system-controls/jdbc/samples/jdbcSample.xml (added)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/system-controls/jdbc/samples/jdbcSample.xml Tue Feb 27 14:39:58 2007
@@ -0,0 +1,118 @@
+<?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.
+
+ $Header:$
+ -->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Beehive Sample: Jdbc Control</title>
+ </header>
+ <body>
+ <section>
+ <title>Introduction</title>
+
+ <p>
+ This sample demonstrates JDBC system control features as well as how to test a Beehive control
+ out-of-container using JUnit. Features demonstrated include:
+ </p>
+ <ul>
+ <li>Using the JDBC control to invoke stored procedures</li>
+ <li>Using a custom result set mapper with the JDBC control</li>
+ <li>Use of the setConnection API</li>
+ </ul>
+ </section>
+
+ <section>
+ <title>Running the Sample</title>
+ <p>
+ This sample requires the Apache Derby jar to run. See <a href="http://db.apache.org/derby/quick_start.html">
+ http://db.apache.org/derby/quick_start.html</a> for more information about Derby and how to download the
+ Derby distribtion.
+ </p>
+ <p>
+ Once Derby has been downloaded update the sample's build.properties file to include the fully qualified
+ name of the Derby jar file. To build and run the JUnit tests, from the command line:
+ </p>
+ <source>
+ant build test
+ </source>
+ </section>
+
+ <section>
+ <title>The JUnit Tests</title>
+ <p>
+ The JUnit tests are located in the <code>EmployeeJdbcControlTest</code> class. Instead of extending
+ <code>junit.framework.TestCase</code> the <code>EmployeeJdbcControlTest</code> test case extends
+ <code>org.apache.controls.test.junit.ControlTestCase</code>. This is necessary in order to have
+ a control environment correctly setup when running out of container. For detailed information
+ about the <code>ControlTestCase</code> class see <a href="site:testing">Testing Controls</a>.
+ </p>
+ <section>
+ <title>Test Setup</title>
+ <p>
+ The JUnit setup() method configures the Derby database for each test. For this particular
+ set of tests, a database connection is established, a new database table is created and
+ a stored procedure is created. All tests are run against the Jdbc control defined by the
+ <code>org.apache.beehive.samples.jdbc.control.EmployeeJdbcControl</code> class.
+ </p>
+ </section>
+ <section>
+ <title>testEmployeeInsert</title>
+ <p>
+ This test inserts a row of data into the database table. Note that since the
+ <code>@ConnectionOptions.useExternalConnection</code> annotation value has been set to true,
+ the Jdbc control's <code>setConnection()</code> API must be used to provide the JDBC control
+ with a connection to the database.
+ </p>
+ </section>
+ <section>
+ <title>testGetEmployee</title>
+ <p>
+ Tests the retrieval of an employee record from the database. The
+ ResultSet resulting from the SQL query is mapped into an Employee java bean.
+ </p>
+ </section>
+ <section>
+ <title>testIsIdAssignedPositive</title>
+ <p>
+ This test invokes a JDBC control method which uses a Derby stored procedure to
+ determine if a given employee ID has a record associated with it in the database. Derby
+ stored procedures are static Java methods, however they are invoked in the same manner
+ as stored procedures supported by other DBMS's. The stored procedure code for this sample
+ can be found in the <code>org.apache.beehive.samples.jdbc.control.StoredProcedures</code> class.
+ </p>
+ </section>
+ <section>
+ <title>testIsIdAssignedNegative</title>
+ <p>
+ Tests the negative case of the previous test.
+ </p>
+ </section>
+ <section>
+ <title>testEmployeeAddressLabel</title>
+ <p>
+ The Jdbc control method invoked by this test uses a custom result set mapper.
+ The mapper transforms a row of data into an AddressLabel bean. The mapper implementation
+ can be found in the <code>org.apache.beehive.samples.jdbc.control.CustomEmployeeMapper</code> class.
+ For more information on custom result set mappers see <a href="site:jdbc_control_typemapping/custom_typemapping">
+ Jdbc Control Type Mapping Guide</a>.
+ </p>
+ </section>
+ </section>
+ </body>
+</document>
Propchange: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/system-controls/jdbc/samples/jdbcSample.xml
------------------------------------------------------------------------------
svn:eol-style = native