Author: steveh Date: Tue Dec 7 11:10:11 2004 New Revision: 110142 URL: http://svn.apache.org/viewcvs?view=rev&rev=110142 Log: Content for the Forrest 0.6 site. Added: incubator/beehive/trunk/docs/ incubator/beehive/trunk/docs/build.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/ incubator/beehive/trunk/docs/forrest/build.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/forrest.properties (contents, props changed) incubator/beehive/trunk/docs/forrest/src/ incubator/beehive/trunk/docs/forrest/src/documentation/ incubator/beehive/trunk/docs/forrest/src/documentation/README.txt (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/classes/ incubator/beehive/trunk/docs/forrest/src/documentation/classes/CatalogManager.properties (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/ incubator/beehive/trunk/docs/forrest/src/documentation/content/dtd/ incubator/beehive/trunk/docs/forrest/src/documentation/content/dtd/gtlf/ incubator/beehive/trunk/docs/forrest/src/documentation/content/dtd/gtlf/gtlf-config-2.0.dtd (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/beehive/ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/beehive/guide.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/building.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/contributors.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsOverview.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/images/ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/index.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/sample_controls-blank.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/sample_controls-db.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/tutorial_controls.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/downloads.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/faq.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/glossary.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/index.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/jpetstore.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/license.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/mailinglists.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/config/ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/config/netui-config.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/guide.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/index.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_altering.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_building.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_controllers.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_jsp.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_overview.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/sample_netui-blank.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/tutorial_pageflow.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/reference.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/setup.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/tabs.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/webservices.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/datatypes.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/sample_AddressBook.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/sample_Dashboard.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/sample_wsm-blank.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/tutorial_wsm.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/ incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsOverview_1.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsOverview_2.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsOverview_3.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsOverview_4.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsProgramming_1.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsProgramming_2.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsProgramming_3.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/Logo_25wht.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsOverview_1.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsOverview_2.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsOverview_3.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsOverview_4.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsProgramming_1.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsProgramming_2.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsProgramming_3.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_Logo_25wht.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_apache-incubator-logo.png (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_beehive_logo_wide.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_incubator-logo.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_maven-button-1.png (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/apache-incubator-logo.png (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/beehive_logo_wide.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/controlsOverview1.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/controlsOverview2.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/controlsOverview3.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/controlsOverview4.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/controlsProg1.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/impl-flow-1.dia (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/impl-flow-1.png (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/impl-flow-2.dia (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/impl-flow-2.png (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/incubator-logo.gif (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/logical-flow-1.dia (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/logical-flow-1.png (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/logical-flow-2.dia (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/logical-flow-2.png (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/maven-button-1.png (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/skinconf.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/translations/ incubator/beehive/trunk/docs/forrest/src/documentation/translations/langcode.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/translations/languages_en.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/translations/languages_es.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_af.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_de.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_es.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_it.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_no.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_ru.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_sk.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/translations/tabs.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/translations/tabs_es.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/status.xml (contents, props changed)
Added: incubator/beehive/trunk/docs/build.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/build.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/build.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,15 @@ +<?xml version="1.0"?> + +<!-- + Beehive Docs build file. +--> +<project name="Beehive Docs Build" default="usage" basedir="."> + + <property environment="os"/> + <property file="beehive.properties"/> + + <target name="site"> + <ant dir="forrest" target="site"/> + </target> + +</project> Added: incubator/beehive/trunk/docs/forrest/build.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/build.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/build.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,6 @@ +<!-- 'site', the default target, is a target imported from forrest.build.xml --> +<project name="myproject" default="site"> + <property environment="os"/> + <property name="forrest.home" value="${os.FORREST_HOME}"/> + <import file="${os.FORREST_HOME}/forrest.build.xml"/> +</project> \ No newline at end of file Added: incubator/beehive/trunk/docs/forrest/forrest.properties Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/forrest.properties?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/forrest.properties Tue Dec 7 11:10:11 2004 @@ -0,0 +1,104 @@ +# Copyright 2002-2004 The Apache Software Foundation +# +# Licensed 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. + +############## +# Properties used by forrest.build.xml for building the website +# These are the defaults, un-comment them if you need to change them. +############## + +# Prints out a summary of Forrest settings for this project +#forrest.echo=true + +# Project name (used to name .war file) +#project.name=my-project + +# Specifies name of Forrest skin to use +#project.skin=tigris +#project.skin=pelt + +# comma separated list, file:// is supported +#forrest.skins.descriptors=http://forrest.apache.org/skins/skins.xml,file:///c:/myskins/skins.xml + +############## +# behavioural properties +#project.menu-scheme=tab_attributes +#project.menu-scheme=directories + +############## +# layout properties + +# Properties that can be set to override the default locations +# +# Parent properties must be set. This usually means uncommenting +# project.content-dir if any other property using it is uncommented + +#project.status=status.xml +#project.content-dir=src/documentation +#project.raw-content-dir=${project.content-dir}/content +#project.conf-dir=${project.content-dir}/conf +#project.sitemap-dir=${project.content-dir} +#project.xdocs-dir=${project.content-dir}/content/xdocs +#project.resources-dir=${project.content-dir}/resources +#project.stylesheets-dir=${project.resources-dir}/stylesheets +#project.images-dir=${project.resources-dir}/images +#project.schema-dir=${project.resources-dir}/schema +#project.skins-dir=${project.content-dir}/skins +#project.skinconf=${project.content-dir}/skinconf.xml +#project.lib-dir=${project.content-dir}/lib +#project.classes-dir=${project.content-dir}/classes +#project.translations-dir=${project.content-dir}/translations + +############## +# validation properties + +# This set of properties determine if validation is performed +# Values are inherited unless overridden. +# e.g. if forrest.validate=false then all others are false unless set to true. +#forrest.validate=true +#forrest.validate.xdocs=${forrest.validate} +#forrest.validate.skinconf=${forrest.validate} +#forrest.validate.sitemap=${forrest.validate} +#forrest.validate.stylesheets=${forrest.validate} +#forrest.validate.skins=${forrest.validate} +#forrest.validate.skins.stylesheets=${forrest.validate.skins} + +# *.failonerror=(true|false) - stop when an XML file is invalid +#forrest.validate.failonerror=true + +# *.excludes=(pattern) - comma-separated list of path patterns to not validate +# e.g. +#forrest.validate.xdocs.excludes=samples/subdir/**, samples/faq.xml +#forrest.validate.xdocs.excludes= + + +############## +# General Forrest properties + +# The URL to start crawling from +#project.start-uri=linkmap.html +# Set logging level for messages printed to the console +# (DEBUG, INFO, WARN, ERROR, FATAL_ERROR) +#project.debuglevel=ERROR +# Max memory to allocate to Java +#forrest.maxmemory=64m +# Any other arguments to pass to the JVM. For example, to run on an X-less +# server, set to -Djava.awt.headless=true +#forrest.jvmargs= +# The bugtracking URL - the issue number will be appended +#project.bugtracking-url=http://issues.apache.org/bugzilla/show_bug.cgi?id= +#project.bugtracking-url=http://issues.apache.org/jira/browse/ +# The issues list as rss +#project.issues-rss-url= +#I18n Property only works for the "forrest run" target. +#project.i18n=true Added: incubator/beehive/trunk/docs/forrest/src/documentation/README.txt Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/README.txt?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/README.txt Tue Dec 7 11:10:11 2004 @@ -0,0 +1,7 @@ +This is the base documentation directory. + +skinconf.xml # This file customizes Forrest for your project. In it, you + # tell forrest the project name, logo, copyright info, etc + +sitemap.xmap # Optional. This sitemap is consulted before all core sitemaps. + # See http://forrest.apache.org/docs/project-sitemap.html Added: incubator/beehive/trunk/docs/forrest/src/documentation/classes/CatalogManager.properties Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/classes/CatalogManager.properties?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/classes/CatalogManager.properties Tue Dec 7 11:10:11 2004 @@ -0,0 +1,37 @@ +# Copyright 2002-2004 The Apache Software Foundation +# +# Licensed 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. + +#======================================================================= +# CatalogManager.properties +# +# This is the default properties file for Apache Forrest. +# This facilitates local configuration of application-specific catalogs. +# +# See the Apache Forrest documentation: +# http://forrest.apache.org/docs/your-project.html +# http://forrest.apache.org/docs/validation.html + +# verbosity ... level of messages for status/debug +# See forrest/src/core/context/WEB-INF/cocoon.xconf + +# catalogs ... list of additional catalogs to load +# (Note that Apache Forrest will automatically load its own default catalog +# from src/core/context/resources/schema/catalog.xcat) +# use full pathnames +# pathname separator is always semi-colon (;) regardless of operating system +# directory separator is always slash (/) regardless of operating system +# +#catalogs=/home/me/forrest/my-site/src/documentation/resources/schema/catalog.xcat +catalogs= + Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/dtd/gtlf/gtlf-config-2.0.dtd Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/dtd/gtlf/gtlf-config-2.0.dtd?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/dtd/gtlf/gtlf-config-2.0.dtd Tue Dec 7 11:10:11 2004 @@ -0,0 +1,183 @@ +<!-- testlog.dtd --> + +<!ELEMENT description (#PCDATA)> + +<!-- Environment Section --> +<!ELEMENT env-attribute EMPTY> +<!ATTLIST env-attribute + name CDATA #REQUIRED + value CDATA #REQUIRED +> + +<!-- Don't worry about the attributes --> +<!ELEMENT environment (env-attribute+)> +<!ATTLIST environment + hosttype CDATA #IMPLIED + primary (TRUE|FALSE) "TRUE" +> + +<!-- Output Files --> +<!-- Don't worry about this element --> +<!ELEMENT output-files EMPTY> +<!ATTLIST output-files + filetype CDATA "OUTPUTLOG" + url CDATA #REQUIRED +> + + +<!-- Test Case Section --> + +<!-- + One per test result, this is the metadata about the test case + testcasename For javatest, this classname.methodname + testunit Grouping for test cases (one level only), not scoped by any other variable + testpath descriptive value, path to the testfile (if there is one) + qaowner If used, must map to a user within the system +--> +<!ELEMENT test-case (description?)> +<!ATTLIST test-case + testcasename CDATA #REQUIRED + testunit CDATA #IMPLIED + testpath CDATA #IMPLIED + qaowner CDATA #IMPLIED +> + + +<!-- Result Section --> + +<!-- Any kind of output about a test result, might include error info and stack trace --> +<!ELEMENT output-details (#PCDATA)> + +<!-- errorname Either a logical name for the error, or possibly just an exception name --> +<!ELEMENT execution-output (output-details?)> +<!ATTLIST execution-output + errorname CDATA #IMPLIED +> + +<!-- Ignore except for manual tests --> +<!ELEMENT reviewer-comments (#PCDATA)> + +<!-- Contains optional information about re-running failed tests --> +<!ELEMENT test-replication (info?,command-line)> + +<!-- + Newline delimited name=value pairs, used for test point + definition and comparison, therefore format should be consistent (e.g. sorted) +--> +<!ELEMENT test-parameters (#PCDATA)> + + +<!-- Test Replication section --> + +<!-- Any useful information about re-running this test --> +<!ELEMENT info (#PCDATA)> + +<!-- Optional command lines for re-running failed tests --> +<!ELEMENT command-line (unix,win?)> +<!ELEMENT unix (#PCDATA)> +<!ELEMENT win (#PCDATA)> + + +<!-- + Directly below the document element, this is the primary node for a given test in a run. + Note that it may include many elements + reviewstate Don't use non-default values except ANALYZED for manual tests + exectime Time at which the test started, java.sql.Timestamp.toString() escape format + duration In milliseconds + crlist comma separated WebClarify CR numbers + analyzer The user who should analyze this result, + If used, must map to a user within the system + + result These are the different types of outcomes for a test. + TIMEOUT = test timed out + ABORT = some sort of test initialization failed + FRAMEABORT = the test framework failed to do something required for this test + SKIP = test was skipped due to a framework decision (e.g. required test failed, require utility had problems) + FAILURE = test failed + SUCCESS = test passed + + isdone This should be removed, ignore for now + logicalname Name to easily identify an execution point within a test run + resultinfo Additional information provided about a test result (e.g. benchmark data, etc.) +--> +<!ELEMENT test-result (test-case, environment*, test-parameters?, execution-output?, reviewer-comments?, test-replication?, output-files*)> +<!ATTLIST test-result + reviewstate (ASSIGNED|EXECUTED|ANALYZED) "EXECUTED" + exectime CDATA #REQUIRED + duration CDATA #IMPLIED + crlist CDATA #IMPLIED + analyzer CDATA #IMPLIED + result (TIMEOUT|ABORT|FRAMEABORT|SKIP|FAILURE|SUCCESS|TEST_NOT_FOUND) #REQUIRED + isdone (TRUE|FALSE) "TRUE" + logicalname CDATA #IMPLIED + resultinfo CDATA #IMPLIED +> + + +<!-- + Header Information : Meta-Data about a Test Run + checksum Expected number of tests for a given import into Sapphire + resultcount Expected number of tests for this GTLF file + execaccount OS user who executed this run + execdate java.sql.Timestamp.toString() for when this test run began + harnesstype Descriptive field for the test harness / framework used to run the tests + importinfo Never used, supposed to have generic information about an import + testruntype This is used to classify a test run across the product + referencedPrimaryRunId This if present would signify that the run is secondary and value corresponds to the primary run; in case its null it means its a primary run +--> +<!ELEMENT header-info EMPTY> +<!ATTLIST header-info + checksum CDATA #IMPLIED + resultcount CDATA #IMPLIED + execaccount CDATA #REQUIRED + execdate CDATA #REQUIRED + harnesstype CDATA #REQUIRED + importinfo CDATA #IMPLIED + testruntype CDATA #IMPLIED + referencedPrimaryRunId CDATA #IMPLIED +> + +<!-- + Harness Specific Data : To be reused by the harness + processconfig The path to the file which is used for process management by some test frameworks +--> +<!ELEMENT harness-info EMPTY> +<!ATTLIST harness-info + processconfig CDATA #IMPLIED +> + +<!-- + Outermost Element : Defines a Test Run + runid Unique id for the run across Sapphire. Use the supplied utility. + testtype + release Must correspond to a release in the system. + load Must correspond to a load in the system, for this release. + branch Must correspond to a p4 branch in the system. + string A Sapphire semantic for frequency of execution. + Must be either 1, 2, 3, or 4. Roughly, + 1 = more than once per day, like a continuous build and test + 2 = nightly + 3 = weekly + 4 = once per load + changenumber p4 change number at which this this run occurred + analyzer Must correspond to a user in the system. + This can be overridden per test result + hostname + toptestfile The filename (not full path) of the top testfile. + This used to help distinguish between runs, along with testruntype +--> +<!ELEMENT test-log (environment?, output-files*, header-info, harness-info?, test-result+)> +<!ATTLIST test-log + runid CDATA #REQUIRED + testtype (AUTOMATED|MANUAL) #REQUIRED + release CDATA #REQUIRED + load CDATA #REQUIRED + branch CDATA #IMPLIED + string CDATA #REQUIRED + changenumber CDATA #IMPLIED + analyzer CDATA #IMPLIED + hostname CDATA #IMPLIED + toptestfile CDATA #IMPLIED + runmodifier CDATA #IMPLIED +> + Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/beehive/guide.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/beehive/guide.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/beehive/guide.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,52 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v13.dtd";> +<document> + <header> + <title>Putting the Pieces Together</title> + </header> + <body> + <section id="intro"> + <title>How Do Page Flows, Controls, and Web Services Fit Together?</title> + <p>Page Flows make building Java web applications easy and intuitive. When programming with Page Flows, the developer writes Java files and JSP pages--that's it. There is very little occasion to work with configuration files, or other components. Page Flow programming is not only simple, it is also excells at separating the presentation logic from the data processing logic. This results in uncluttered JSP code which is easy to understand and edit. Moreover, many of the most difficult programming tasks, such as security and validation, are handled with a simple declarative programming model using Java annotations.</p> + </section> + <section> + <title>How Do Page Flows Work?</title> + <p>A Page Flow consists of a single directory containing a Java class, called the "Controller", and any number of JSP pages. + The role of the JSP pages is to present a visual interface for users of the web application. The role of the Controller file is to coordinate all of the things that can happen when a user visits a web site. These duties include: handling user requests, fashioning responses to user requests, preserving session state, and coordinating back-end resources (such as databases and web services).</p> + <p>The JSP files use special tags (the "<netui>" tags) and databinding expressions which bind the user interface to objects and actions in the Controller file. + </p> + <p>tbd: need diagram here</p> + <p>The action methods in the controller file implement code that can result in site navigation, passing data, or invoking back-end business logic via controls. + Significantly, the business logic in the controller class is separate from the presentation code defined in the JSP files. + The overall purpose of a page flow is to provide you with an easy-to-use framework for building dynamic, sophisticated web applications. + While page flows give you access to advanced features of J2EE, you do not have to be a J2EE expert to quickly develop and deploy Java-based applications built on page flows.</p> + <p>The programming model: annotations, data binding expressions, <netui> tags, etc.</p> + </section> + <section id="nav"> + <title>Navigation</title> + </section> + <section id="submit"> + <title>Submitting Data: Form Beans, and Data Binding</title> + </section> + <section id="processing_data"> + <title>Processing Data</title> + </section> + <section id="displaying_data"> + <title>Displaying Data</title> + </section> + <section id="controls"> + <title>Accessing Back-End Resources with Controls</title> + </section> + <section id="validation"> + <title>Validation</title> + </section> + <section id="security"> + <title>Security</title> + </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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/building.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/building.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/building.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,95 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v13.dtd";> +<document> + <header> + <title>Building Beehive</title> + </header> + <body> + <section> + <title>Introduction</title> + <p>This topic explains how to download and build the Beehive source code on your local machine.</p> + </section> + <section id="setup"> + <title>Setting Up Beehive on Your Machine</title> + <p>To build Beehive, you need to have Java version 5 (or later) installed + with the JAVA_HOME environment variable defined to point to this JDK. + The JDK is available here: + </p> + <source> http://java.sun.com/j2se/1.5.0/download.jsp</source> + <p> + Set the BEEHIVE_HOME environment variable to point to the root of the branch in your + Beehive working copy that you want to work with. Typically you will be interested in + the trunk, where mainline work goes on. For example, if you ran + </p> + <source>svn checkout https://svn.apache.org/repos/asf/incubator/beehive/trunk</source> + <p> + from within "C:/MyProjects/beehive", BEEHIVE_HOME will be "C:/MyProjects/beehive/trunk", + since you explicitly only checked out the trunk. + </p> + <p>However, if you had run</p> + <source>svn checkout https://svn.apache.org/repos/asf/incubator/beehive</source> + <p>from within "C:/MyProjects/beehive", BEEHIVE_HOME will be "C:/MyProjects/beehive/beehive/trunk".</p> + <p>In addition, you'll need to install Ant in $BEEHIVE_HOME/installed/ from + the archive in $BEEHIVE_HOME/external/ant/apache-ant-1.6.2-bin.(zip|tar.gz). + The installed Ant distribution should end up here:</p> + <source> $BEEHIVE_HOME/installed/apache-ant-1.6.2/...</source> + </section> + <section> + <title>Building Beehive</title> + <p>In the following examples, '$>' is your propmpt at $BEEHIVE_HOME, so if + you see '$>ant', type 'ant' (without the quotes) and press [enter].</p> + <p>To initialize the Beehive build environment, run beehiveEnv for your platform:</p> + <p> + Windows: + </p> + <source> C:\MyProjects\beehive>beehiveEnv.cmd</source> + <p>UNIX:</p> + <source> $>source beehiveEnv.sh</source> + <p>Because Beehive depends on a set of external software, these dependencies need + to be installed before a build can be successful. You will need a network + connection for this step because jsr173_api.jar needs to be downloaded from a + website; if you need to use a proxy for this downolad, see the "Using Proxies" + instructions below. Once this has been downloaded, the build and tests can + be run successfully without a network connection. To install the external + dependnecies, run:</p> + <source> $>ant bootstrap</source> + <p>which will unzip Log4J and Tomcat installers. </p> + <p>To build Beehive, run:</p> + <source> $>ant clean deploy</source> + <p>To run Beehive tests, run:</p> + <source> $>ant drt</source> + </section> + <section> + <title>Using Proxies With a Beehive Build</title> + <p> + If you need to use proxies you can setup additional environment variables + so that the Ant "bootstrap" target is successful in downloading the + JSR 173 API JAR file. + </p> + <source><![CDATA[ +PROXYHOST=<name of proxy host> +PROXYPORT=<port used for proxying> +PROXYUSER=<username for proxy authentication> +PROXYPASSWORD=<password for proxy authentication> +NONPROXYHOSTS=<hosts that should not be proxied> +SOCKSPROXYHOST=<socks proxy host name> +SOCKSPROXYPORT=<socks proxy port> +]]></source> + <p>At a minimum, you will need to set PROXYHOST and PROXYPORT if your + network environment requires a proxy connection. To set these + environment variables in your shell, run:</p> + <source><![CDATA[ set PROXYHOST=<name of proxy host>]]></source> + <p>in a Windows shell and </p> + <source><![CDATA[ export PROXYHOST=<name of proxy host>]]></source> + <p>in a UNIX shell. + For information on proxy support using the <code><setproxy></code> task, please + visit http://ant.apache.org/manual/OptionalTasks/setproxy.html + </p> + </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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/contributors.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/contributors.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/contributors.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,57 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd"> + +<document> + +<header> + <title>Apache Beehive - </title> +</header> + +<body> + <section> + <title>Contributors</title> + <table> + <tr><td><strong>Username</strong></td><td><strong>Committers</strong></td><td><strong>Affiliation</strong></td></tr> + <tr><td>ias</td><td>Changshin Lee</td><td>Tmax Soft (Axis committer)</td></tr> + <tr><td>cjudson</td><td>Chris Judson</td><td>E2E Consulting</td></tr> + <tr><td>cliffs</td><td>Cliff Schmidt</td><td>BEA (XMLBeans committer)</td></tr> + <tr><td>craigc</td><td>Craig Crutcher</td><td /></tr> + <tr><td>dolander</td><td>Daryl Olander</td><td>BEA</td></tr> + <tr><td>dims</td><td>Davanum Srinivas</td><td>(Axis committer)</td></tr> + <tr><td>davidbau</td><td>David Bau</td><td>(XMLBeans committer)</td></tr> + <tr><td>dmkarr</td><td>David Karr</td><td>(Struts committer)</td></tr> + <tr><td>daveread</td><td>David Read</td><td>BEA</td></tr> + <tr><td>ekoneil</td><td>Eddie O'Neil</td><td>BEA</td></tr> + <tr><td>heathers</td><td>Heather Stephens</td><td>BEA</td></tr> + <tr><td>jsong</td><td>James Song</td><td>BEA</td></tr> + <tr><td>jongjinchoi</td><td>Jongjin Choi</td><td>Tmax Soft</td></tr> + <tr><td>kentam</td><td>Ken Tam</td><td>BEA</td></tr> + <tr><td>?</td><td>Kevin O'Connor</td><td>Documentum</td></tr> + <tr><td>kylem</td><td>Kyle Marvin</td><td>BEA</td></tr> + <tr><td>mclark</td><td>Michael Clark</td><td>SandCherry (need CLA)</td></tr> + <tr><td>mmerz</td><td>Mike Merz</td><td>BEA</td></tr> + <tr><td>rich</td><td>Rich Feit</td><td>BEA</td></tr> + <tr><td>rotan</td><td>Rotan Hanrahan</td><td>MobileAware</td></tr> + <tr><td>scottryan</td><td>Scott Ryan</td><td /></tr> + <tr><td>steveh</td><td>Steve Hanson</td><td>BEA</td></tr> + <tr><td>stocco</td><td>Steve Tocco</td><td>BEA</td></tr> + <tr><td>vsalvato</td><td>Vince Salvato</td><td>E2E Consulting</td></tr> + </table> + </section> + + <section> + <title>Sponsor</title> + <p>Craig McClanahan, Champion and Mentor for the project, (as defined in + <fork href="http://incubator.apache.org/incubation/Roles_and_Responsibilities.html";>http://incubator.apache.org/incubation/Roles_and_Responsibilities.html</fork>) + </p> + </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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsOverview.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsOverview.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsOverview.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,422 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v13.dtd";> +<document> + <header> + <title>Controls Overview</title> + </header> + <body> + <section> + <title>Overview</title> + <section> + <title>The Problem with J2EE: Complexity</title> + <p> +J2EE provides a rich set of component types, protocols, and system services that can be used to assemble an application or service</p> + <p> + <strong> +As the scope of the J2EE architectural design space has grown, the complexity of assembling solutions has also grown.</strong> + </p> + <p>Many of the basic building blocks provide their own set of mechanisms for how J2EE abstractions are accessed, how usage is parameterized, and how resources associated with them (connections, sessions, etc) are managed.</p> + <p> +An objective of the J2EE community is to expand beyond the Java system software developer that has traditionally built J2EE solutions to enfranchise a new type of developer: the corporate developer. The corporate developer is often a very strong programmer, but may have significantly less experience with object-oriented design, building distributed systems, and Java/J2EE.</p> + <p> + <strong>The goal is to enable a collaboration where the base J2EE distributed system architecture and back-end components can be designed and built by the J2EE system software developer, then assembled into exposed web user interfaces, web services, or applications by the corporate or application developer. +</strong> + </p> + <p>But the complexity and diversity of J2EE client access models stands in direct opposition to achieving this goal. Depending upon the system architecture and components constructed by the system developer, the application developer might have to learn a variety of new technologies and APIs to work within the architecture. +</p> + <p>Consider a simple example: A systems developer has built a distributed system where synchronous services are exposed as Enterprise JavaBeans and asynchronous services are exposed via JMS queues. A corporate developer new to J2EE is tasked with building a web user interface that integrates with these services. +</p> + <p>To accomplish his task, the corporate developer now has to learn how to:</p> + <ul> + <li>Create a JNDI context and lookup resources. If resources are app-scoped, then how to provide the appropriate deployment descriptor configuration.</li> + <li>How to use home/business interfaces of exposed EJBs to access business methods, including understanding differences in usage depending upon whether the exposed EJBs are Stateless Session Beans, Stateful Session Beans, or Entity Beans.</li> + <li>How to obtain JMS connections/sessions, and references to queues.</li> + <li>How to construct and enqueue a JMS message.</li> + <li>How to properly manage the resources associated with the above, such that vital system resources (such as connections) are used efficiently and correctly. The cost of a subtle mistake can be poor system performance or even system failure.</li> + </ul> + <p> +What initially appears to be a simple task in the abstract (call these EJBs or enqueue a message that looks like this) can devolve into hours or days or reading J2EE HowTo books and Javadoc API references, getting the right deployment descriptor values configured, and calling all the right APIs, at all of the right times, in the right order. In the resulting application or service, often the directly application-related code (i.e. calling the bean business method or building message contents) is a small fraction of the total code required to accomplish the task.</p> + <p> +Here is an example of the code required to invoke a single method on an exposed EJB using standard J2EE APIs: </p> + <source>Trader trader = null; +try +{ + InitialContext ic = new InitialContext(); + TraderHome home = (TraderHome)ic.lookup("MyTraderBean"); + Trader trader = home.create(); + TradeResult tradeResult = trader.buy(stock, shares); + return tradeResult; +} +catch (NamingException ne) +{ + ... +} +finally +{ + if (trader != null) + trader.remove(); +}</source> + <p>A common solution to this problem is often to task the J2EE professional developer with constructing facades or custom frameworks that hide some of the underlying complexity and resource access mechanisms and provides appropriate guarantees that system resources (connections, sessions, handles, etc) are utilized properly. But constructing these intermediate abstractions is an inefficient use of (an often scarce and expensive) systems development resources. Depending upon the "thickness" of the intermediate abstractions, this approach can also have performance or application deployment footprint implications. </p> + </section> + <section> + <title>Solution: Controls: A Unified Client Programming Model </title> + <p>Controls reduce the complexity and learning curve associated with acting as a client of J2EE resources by providing a unified client model that can provide access to diverse types of resources.</p> + <p> + <strong>To the client, Controls appear as JavaBeans that can be instantiated and used for resource access.</strong> + </p> + <p>Properties that parameterize resource access can be set using JSR-175 metadata attributes, as arguments to factory-based instantiation, or even bound using externalized configuration data. These configuration mechanisms are consistent across all resource types, and Controls provide the appropriate mapping to resource-type-specific APIs or deployment descriptor entries. </p> + <p> +Controls present operations on the resource as methods on the JavaBean interface. They also support a two-way communication style where resource events can be delivered to a registered listener.</p> + <p> + <strong> +Controls provide a consistent model for discovering the configuration options, operations, and events exposed by a resource. </strong> + </p> + <p> +Controls can also provide transparent (to the client) resource management of connections, sessions, or other resources to be obtained on behalf of the client, held for an appropriate resource scope to achieve best performance, and then released. This resource management mechanism frees the client from having to learn or understand the acquisition mechanisms, and from having to directly participate in guaranteeing their release. The Controls architecture provides this functionality by defining a simple resource management contract that can cooperate with an outer container to manage resources at the appropriate scope (for example, bounded to a transaction context or outer container operation or request scope).</p> + <p> +Using a Control that exposes the Trader EJB in the earlier example, the code to invoke the buy() method on this bean can become:</p> + <p>The TraderBean Control fully encapsulates the JNDI lookup as well as the home/bean interface operations needed to get an instance of the Trader EJB and invoke the buy() method on it, and exposes the JNDI name of the EJB as a property that can be set either programmatic, via metadata, or using an external deployment descriptor. </p> + <p> +Controls also provide an extensibility model that allows customized view of a resource to be constructed, with discrete operations defined as methods on the control. For example, it is possible to define a custom operation on a Control type representing a JMS queue resource, that uses metadata attributes to define the format of the message, with message contents set from message parameters. This enables the professional developer (or even the corporate developer) to construct new customized facades for resource access with a minimum of effort. </p> + <p>Weblogic Workshop Controls can be considered a "proof of concept" for the Controls architecture. Workshop Controls have used similar techniques to provide a base mechanism for unified access to:</p> + <ul> + <li>Enterprise JavaBeans</li> + <li>JMS Queues and Topics</li> + <li>Web Services</li> + <li>Database Access via JDBC</li> + <li>Enterprise Resources via JCA</li> + </ul> + <p> + <strong>The goal of the Controls architecture is not to define the standards for how specific resource types will be exposed; rather, it is to guarantee that when exposed they will have a commonality in mechanism that makes them easier to understand and use by developers.</strong> + </p> + </section> + <section> + <title>Another Problem: Tooling Challenges </title> + <p> +Beyond adding to overall complexity, the diversity of J2EE resource types and access mechanisms also makes it difficult for tools to offer assistance to developers who need to use them.</p> + <p> + <strong> + +For existing client models, the configuration of resource access is often some combination of resource-specific API usage and deployment descriptor entries. This generally requires custom IDE code that is knows how to generate the right (resource-specific) code or configuration entries.</strong> + </p> + <p>Specific resource types often need custom code in order to define wizards or property-driven user interface that aids in the process of defining a client of the resource. There is no common mechanism for discovering the potential set of configurable attributes for a resource type. This means that any graphical presentation of client attributes or wizards must be custom-authored based upon resource type. +</p> + <p> +Once configured, there is the secondary problem of how the IDE represents a configured client resource in source form. There are at least two potential options: save the attributes as generated source code and/or deployment descriptor entries that are resource-specific or define a canonical representation that is native to the IDE. Both are problematic. Two-way editing can be difficult, if the canonical format is generated source code or descriptors are visible to the end user and directly editable. Using some IDE-specific canonical representation (either based upon a closed framework or configuration data) means the configured client abstraction isn't portable to other development environments or editable outside of the IDE. </p> + <p> +Using the IDE to develop directly to native resource APIs or descriptor formats is also lacking in that it doesn't necessary have an associated constraint or extensibility model. If a resource should be consistently accessed with a particular configuration or expected semantics, there is no good way to describe resource constraints for clients or to enforce that they are followed. A concrete example is a JMS queue where it is expected that messages will always conform to a specific format or contain an expected set of properties. There is no good way of representing this constraint to the client, or of enforcing that it consistently following, short of runtime errors when it is not. </p> + <p> +The lack of a single canonical representation also makes it difficult for the systems developer to collaborate with the corporate developer, short of constructing and exposing custom facades for client access. But even then, there is the IDE problem of knowing what facades are available, and how they should be configured and used once selected.</p> + <p> + <strong> +Without any well-defined source format for representing client resource configuration, packaging models, or discovery mechanisms, there is no non-proprietary way for the IDE to present the notion of configured resources, nor to pre-configure client access to resources.</strong> + </p> + </section> + <section> + <title>Solution: A Unified Tooling Model </title> + <p>Controls, like the JavaBeans upon which they are built, are designed for tooling. Beyond the common programming model presented to developers, Controls also offer resource discovery and property introspection mechanisms that allow an IDE to locate available Controls and present and interactively configure their properties. + +</p> + <p> + <strong>Because Controls expose operations, events, and properties using common mechanisms, an IDE can support client use cases based upon these mechanisms as well as a common authoring model for defining new types of Controls, without the need for a large amount of resource-specific code. +</strong> + </p> + <p> +Using a common client model allows a single base of IDE code to allow the use of a variety of resource types, based upon introspection. Using a shared model (and code) for presenting and configuring client access also results in a consistent user experience when working with resources, both on the client and authoring side. While the developer might be using a diverse set of resources in the course of building a user interface, service, or application, the learning curve from a user interaction perspective can be reduced in the same way that it is reduced from an API perspective by having a common model. +</p> + <p> + <strong>Controls extend the base properties support of JavaBeans to add support for metadata-based (JSR-175) attributes, constraints, and an extensibility model, allowing an IDE to define new Control types that are pre-configured for specific resource access use cases. + +</strong> + </p> + <p>The earlier programming example showed a simple customized Control defined to access an Enterprise JavaBean advertised at a particular JNDI location. This example could easily have been constructed by an IDE using JMX to explore advertised EJBs on a J2EE server, and then generating the necessary Control definition that exposes the EJB with the specific home/business interfaces represented as operations on the bean and the correct JNDI location pre-configured as an attribute. +</p> + <p> + +The Controls architecture supports the definition of configuration options list for a particular Control type. This lists the base set of properties that are associated with the type and can be used to:</p> + <ul> + <li>Specify the attributes in the set that can be configured using JSR-175 metadata, and the syntax for doing so. This enables an IDE to present property-style selection of metadata-based attributes and values, as well as providing the ability to validate the annotations on any usage of the type and relationships between annotations. +</li> + <li>Specify the attributes in the set that should be settable dynamically using property getters/setters on instances of the type. This can be used to support auto-generation of Control types with property accessors based upon the attribute set. +</li> + <li> Derive a schema for representing the configuration of the attribute set using XML. These can be used in common tools for state management (to persist the representation of a Control instance and its attributes as XML) as well as in an externalized configuration mechanism that allows attributes to be bound externally using deployment descriptor-style configuration files. This makes the construction of instance introspectors and administrative tools much more straightforward, as compared to using ad-hoc deployment descriptor formats. + +</li> + </ul> + <p>Controls also provide a JAR-based packaging mechanism, for how Control types can be discovered within a jar. </p> + <p><strong> +The Controls architecture provides a well-defined packaging model that enables system vendors, 3rd party providers, or J2EE system developers (in the collaborative scenario) to distribute controls that offer client access to provided services or components. An IDE can then discover packaged controls to present them in a palette or list of available resource types for client use. +</strong></p> + + + + </section> + </section> + <section> + <title>The Controls Architecture</title> +<p>The following picture shows the basic runtime architecture and the relationships between a resource client, the associated Control, and the accessed J2EE resource:</p> +<p><img src="images/_ControlsOverview_1.gif" alt=""/></p> +<p>The Resource Client represents user code in a web application, service, or application that needs access to the J2EE resource. The Resource Client and supporting Control will always live in the same virtual machine and communicate directly using local Java method invocation. The accessed resource may or may not reside within the same virtual machine, depending upon the nature of the resource and the application server environment. </p> +<p> +Dynamic property accessors and resource operations are exposed on the Control and used by the client to initiate resource access. Data from the resource may be returned as return values from operations or fired as events on the bean event interface to registered listeners. </p> +<p> +Resource access may be parameterized by JSR-175 metadata declared directly on the Control instance, class, or method declarations, or by properties provided to the factory-based constructor. In addition to this, there is an external configuration model for how properties can be bound from external configuration (ex. deployment descriptors), enabling deploy-time binding of attributes. Examples of resource attributes that might be parameterized by metadata or external configuration or JNDI names associated with resources, resource or protocol configuration, message formats, etc. </p> +<p> +The Control itself will often hold a reference to a resource proxy associated with the accessed resource, and will use the proxy to enact operations requested by the client. Examples of resource proxies are EJB home or remote stubs, JMS connections or sessions, web service client proxies, etc. The Control manages the state and lifetime of this proxy reference, coordinated by a set of resource management notification events that are provided to it indicating how long the proxy resources can be held by an outer container that determines the resource scope. +</p> +<p> +The actual communication between the resource proxy and the resource itself is generally a function of the underlying resource. For EJBs, it might reflect communication via RMI or local Java invocation, for web services it might be service invocation based upon</p> +<p> +The following sections describes some of the key features and attributes of the Controls Architecture: +</p> + <section> + <title>Operations and Events</title> + <p> +Controls support a two-way interaction style with resource clients. The set of operations callable by the client are defined on the base public interface for the control, and the set of possible callbacks (events) that might be delivered back to the client from the resource are defined, by convention, on an optional inner Callback interface of the base public interface</p> +<p> +Here is a simple example that represents the client interface to a timer service resource: +</p> +<source> + +public interface TimerControl extends Control +{ + public void start() throws IllegalStateException; + public void stop(); + public interface Callback + { + public void onTimeout(long time); + } +} </source> +<p>In this example, TimerControl is the base public interface for timer Control. The TimerControl supports operations related to setting and using a timer (start, stop), as well as a single event (onTimeout) that will be delivered when the timer fires. +</p> + + + + </section> + <section> + <title> Public Interface / Private Implementation / ControlBean Wrapper </title> +<p>The definition of a new resource type in the Control architecture is composed of three distinct classes: +</p> +<ul> + <li>The public Control Public Interface defines the set of operations and events that are exposed for the resource type. In the earlier TimerControl example, TimerControl is the public resource interface for the timer service resource.</li> + + <li>The private Control Private Implementation class provides the implementation of resource operations as well as proxy resource management. In the TimerControl example, there would be a class (TimerControlImpl) that provides the implementation of the timer operations using the supporting resources of a J2EE timer service.</li> + + <li>The Control Bean Wrapper class is the JavaBean wrapper around the implementation class that provides the property accessor implementation, per-instance storage of dynamic properties, and property resolution services. It performs event listener routing and initialization of contextual services and nested Controls.</li> +</ul> +<p>The relationship and functions of these classes is summarized in the following diagram: </p> +<p><img src="images/_ControlsOverview_2.gif" alt=""/></p> +<p>The following picture shows how these 3 classes work together to fulfill the runtime responsibilities shown in the earlier architecture diagram: +</p> +<p><img src="images/controlsOverview3.gif" alt=""/></p> + + </section> + <section> + <title>A Flexible Property Model </title> +<p>A key aspect of the Controls architecture is a flexible configuration model for how resource access attributes will be resolved. Properties can be used to parameterize resource access, providing attributes such as JNDI names for local resources, web service URLs, connection attributes, etc. +</p> +<p> +It must be possible to introspect a bean and set the available set of properties. Additionally, Controls need to move beyond the traditional property setter/getter to provide some additional capabilities:</p> +<ul> + <li> Enables the assignment of Control properties using JSR-175 metadata attribute declarations on Control classes, instances, or methods. +</li> + + <li>Provides a consistent externalized property binding model, so resource attributes can be managed without requiring changes to source code. </li> +</ul> +<p>The three property configuration mechanisms (programmatic property accessors on the Control, JSR-175 metadata on Control declarations, and external deployment descriptor-style configuration) have a well-defined property resolution precedence that is implemented and enforced by the Control base implementation. The precedence (from highest to lowest) is: +</p> +<ul> + <li>Programmatically set property value</li> + + <li>Externally configured property value</li> + + <li>Metadata-defined property value</li> +</ul> +<p> +In other words, the resource client can override a value defined by either externalized configuration or metadata, and a value defined in externalized configuration can override a metadata-defined value. +</p> +<p> +To ensure that this flexibility is not misused where it is not desirable, it is also possible to declaratively specify the mechanisms that can be used to set attribute values. So an attribute could be marked as 'read-only' from a programmatic perspective, and would only have a getter and not a setter, or a metadata-based attribute could be marked as bound in a 'final' way that prevents override by either external configuration or programmatic mechanisms. This is useful in the previously described collaborative scenario, where the J2EE Systems Developer who is responsible for resource access definitions via Controls might want to constrain the flexibility that the consumer (the Corporate Developer) has in modifying those definitions upon use. +</p> +<p>In the earlier TimerControl example, an attribute might exist to set the timeout value of the timer. For this attribute, it should be possible to set the value programmatically, externally, or using declarative annotations.</p> +<p> +The declaration of the TimerControl JSR-175 attribute and member might look something like: +</p> +<source>Package com.myco; +public @interface Timer { + + /** @return timeout Duration as string */ + @AccessModes (property-style=true, external=true) String timeOut(); +... + }</source> + <p> +This defines a metadata attribute (com.myco.Timer) that has a String member value named 'timeOut'. The AccessModes meta-attribute specifies that the member can be set via JavaBean property-style accessors and external configuration, as well as using declarative metadata. +</p> +<p>An example of setting the timeOut member of the Timer metadata attribute inside of client code might look like: +</p> +<source>@Timer(timeout="3 seconds") +public TimerControlBean myTimerBean; +</source> +<p> +Because the AccessModes attribute indicates that a property-style accessors are enabled, the TimerControlBean will also advertise the following JavaBean property accessor methods: </p> +<source>Public String getTimeOut(); +public void setTimeOut(String timeout);</source> +<p> +This accessor could be used from client code, as in the following example: +</p> +<source>myTimerBean.setTimeout("3 seconds");</source> +<p> +Finally, there will also be a derived XML schema for external configuration of the Control based upon the set of properties that are defined as externally configurable. This schema is derived from the metadata attribute definition, not authored directly. +</p> +<p> +The configuration of the timeout member based upon external configuration would look something like: </p> +<source>â + <timer:timer xmlns:timer="http://openuri.org/com/myco/TimerControl";> + <timer:timeOut>3 seconds</timer:timeOut> + </timer:timer> +â</source> +<p></p> + + </section> + <section> + <title>Resource Views: Extensibility by Interface</title> + <p>Controls also support an extensibility model that allows operations on a resource to be defined using a customized interface that extends the base public resource interface, and defines metadata-annotated operations on the resource. This enables the construction of "views" or specific resource use cases, defining a more-specific set of resource operations or events. </p> + <p>As an example, imagine there is a basic DatabaseControl that provides simplified database access using JDBC, and hides and manages the details of how JDBC connections are acquired and released from the client programmer. +</p> + <p> +This Control could also define an extensibility model that allows the execution of JDBC PreparedStatements as operations on an extended interface, and marshals the returned ResultSet back to native Java types. When extended in this manner, the resulting extended control presents a view of the JDBC resource as a set of methods that result in the execution of predefined PreparedStatements. +</p> + <p> +An example of the customized interface for this Control might look like: +</p> + <source>public interface CustomerDatabase extends ControlExtension, DatabaseControl +{ + @sql statement="INSERT INTO CUSTOMERDB (ID, NAME) VALUES ({id}, {name})" + int newCustomer(int id, String name) throws SQLException; + + @sql statement="SELECT * FROM CUSTOMERDB WHERE ID = {id}" + Customer findCustomer(int id); +}</source> + <p> +In this simple example, each operation on the interface corresponds to a SQL prepared statement to be executed. Metadata attributes on the methods are used to define the additional semantics required, in this case the actual SQL statement to invoke. </p> + <p> +Support for Extensibility by Interface is optional. The Control author has full control of whether extensibility is or is not supported, as well as the ability to define and implement resource-specific semantics associated with extended operations on the control type. +</p> + </section> + <section> + <title>Contextual Services</title> +<p>Given their use case (resource access), it should be possible to use Controls from a variety of different runtime contexts: within web tier containers (servlets, JSP, JSF), within web services, standalone Java applications, even from within EJBs. Given this diverse set of contexts, Controls need to have a flexible model for how they integrate with any outer container or component model and for how services will be obtained from them. +</p> +<p> +Controls may need access to contextual services to support resources. One example of client-side contextual services might be security services to access a credential repository or to provide data encryption/decryption services. Services may be contextual, because the actual implementation might vary based upon the type of container in which the Control is running. As an example, a security contextual service might provide different implementations for Controls running in the EJB tier (by delegating to an enclosing EJBContext) vs. Controls running in the Servlet container vs. Controls running in a standalone Java application. +</p> +<p> +Contextual services can also define an event model, so contextual services can also declare and fire events on Controls that have registered in interest. As an example, a basic ControlContext contextual service is provided as part of the base Controls architecture. This contextual service provides common services for Controls, such as access to properties, as well as a set of lifecycle events for Controls. +</p> +<p> +The discovery and implementation model for Controls Contextual Services will be based upon the JavaBeans Runtime Containment and Services Protocol (Glasgow) (<link href="http://java.sun.com/products/javabeans/glasgow/#containment";>http://java.sun.com/products/javabeans/glasgow/#containment</link>) that is already shipping as part of J2SE. +</p> + </section> + <section> + <title>Resource Management</title> + <p>The Controls architecture defines a unique set of lifecycle events and a resource management contract between Controls and the execution container they are running within. There are three primary motivations for this:</p> +<ul> + <li>To enable the Control implementation to implicitly obtain supporting client-side resources (connections, sessions, etc) on behalf of the client.</li> + + <li>To enable the Control to hold these client-side resources for an appropriate resource scope (across multiple client invocations) to achieve optimal performance and utilization of resources +</li> + + <li>To ensure that client-side resources obtains on behalf of the client are consistently released at the end of the appropriate resource scope.</li> +</ul> +<p> +The key is that resource management should be transparent to the client. The Control resource management design makes the Control implementation class the responsible party, instead of the placing this burden upon the client of the resource, which is the common approach associated with most J2EE resource types. </p> +<p> +This is achieved by defining two basic lifecycle events that will be delivered to the Control Implementation Class: +</p> +<ul> + <li>onAcquire: the onAcquire event is delivered to a resource implementation on the first client invocation within a resource scope. This provides an opportunity to obtain any basic client-side resources necessary to support operations on the Control. For example, a Control that was providing access to a JMS queue might use the onAcquire event to obtain a JMS connection, session, and a reference to the target queue. +</li> +<li>onRelease: the onRelease event is guaranteed to be delivered to every control implementation instance that has received an onAcquire event during the current resource scope, at the end of that scope. This provides the opportunity to release any of the resources obtained during onAcquire event processing. In the previous example, the JMS connection and session could be appropriately closed and the queue reference reset to null.</li> +</ul> +<p> +The definition of resource scope is delegated to the outer container within which the Control is executing. For example, if the Control is executing within the web tier, the resource scope might be bounded by the duration of processing of the current http request. For a Control running in the EJB tier, the resource scope might be the current EJB method invocation or possibly even by the current transaction context. </p> +<p> +The following diagram shows the basic mechanics of this contract: +</p> +<p><img src="images/controlsOverview4.gif" alt=""/></p> +<p> +The Client Container has two basic responsibilities: to maintain an accumulated list of Controls that have acquired resources, and to invoke releaseResources API on each of them at the end of the appropriate resource scope. The Control Bean is responsible for delivering the onAcquire event to the Control Implementation instance, for notifying the Client Container that resources have been obtained, and for delivering the onRelease event to the implementation when notified by the Client Container. +</p> +<p>This diagram also demonstrates the transparency of resource management to client code itself; the client is only invoking operations, and all of the necessary underlying resource management is done by interactions between the Client Container, Control Bean, and Control Implementation. </p> + + </section> + <section> + <title>Composition Model</title> + <p> + +The Controls architecture also supports a composition model, so it is possible to define a Control type that nests another Control type. This makes it possible to extend a physical resource abstraction with a logical abstraction that lives entirely on the client side. Composition is useful for the construction of facades or to add additional client side operations, events, or state to the nested Control abstraction. </p> +<p> +Composition of Controls is supported using the mechanisms defined by the JavaBeans Runtime Containment and Services Protocol (Glasgow). +</p> + </section> + <section> + <title>Packaging Model</title> + <p>The Controls architecture provides a simple JAR-based packaging model that enables Controls to be packaged for distribution. The model defines a simple manifest file that describes the set of Controls within a jar. Tools can quickly introspect and build palettes of available controls based upon this packaging model.</p> +<p> +It should be possible to place Control jar files at a variety of classloader scopes (system, application, or module) for client use cases. +</p> + + </section> + </section> + <section> + <title>The Controls Client Model</title> + <p>The Controls architecture actually offers two related client models with slight different characteristics:</p> + <ul> + <li>A programmatic client model, where the client explicitly specifies Control instance attributes to factory-based constructors, and does direct registration of event listeners and event handling. +</li> + + <li>A declarative client model, where Control instance attributes are specified using JSR-175 metadata, and event routing is implicit based upon a set of basic naming conventions.</li> + </ul> + <p>The two offer the same basic functionality; but in the programmatic model the client takes explicit responsibility for construction of Control instances and event routing; in the declarative model, the Control container provides initialization and routing services on behalf of the client. The programmatic model directly exposes the details of how initialization and event handling takes place; it is likely a more comfortable environment for the professional developer or one who is already comfortable with constructing and handling events from JavaBeans. The declarative model hides many of these details, making it much easier for corporate developers (and development tools) to quickly declare and configure Control instances and create event handling code to service events. +</p> +<p></p> + <section> + <title>Programmatic Client Model Example</title> + <p> +The programmatic client model follows the basic pattern of JavaBeans construction and event handling: +</p> +<source>TimerControlBean myTimerBean = (TimerControlBean)ControlBean.instantiate( + classloader, "com.myco.TimerControlBean"); +myTimerBean.setTimeout("3 seconds"); +myTimerBeans.addTimerControlEventListener( + new TimerControlEventListener() // anonymous event handler class + { + public void onTimeout(long time) + { + // timer event handling code + } + } +);</source> +<p> +In the example above, a factory-based instantiation API (Controls.instantiate()) is used to construct a new instance of the TimerControlBean. It is programmatically initialized to the desired configuration, and then an event handler (based upon the declaration of an anonymous inner class) is used to service events from the bean. +</p> + + </section> + <section> + <title>Declarative Programming Model Example</title> +<p> +The following example is equivalent to the preceding example, but uses declarative style construction and event routing: +</p> +<source>@Timer(timeout="3 seconds") TimerControlBean myTimerBean; + +... + +public void myTimerBean_onTimeout(long time) +{ + // timer event handling code +}</source> +<p>In this example, the TimerControlBean instance is declared with attributes specified using JSR-175 metadata. There is no implicit construction of the bean instance; the client container for the ControlBean will recognize the presence of the Control declaration and will implicitly initialize the instance. Additionally, it (also implicitly) declares the necessary event listener class and routing code to deliver onTimeout events on the TimerControlBean instance to the declared event handler.</p> + </section> + </section> + </body> +</document> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsProgramming.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,1403 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v13.dtd";> +<document> + <header> + <title>Controls Programming</title> + </header> + <body> + <section> + <title>1. Overview</title> + <p>The Control architecture is a lightweight component framework based upon JavaBeans, which exposes a simple and consistent client model for accessing a variety of resource types. Controls take the base functionality of JavaBeans and add in the following unique new capabilities:</p> +<ul> + <li>Enhanced authoring model: uses a public interface contract and an associated implementation class to enable generation of a supporting JavaBean class for handling the details of property management and initialization. </li> + + <li>Extensibility model: enables the construction of views and custom operations (with implied semantics) on the Control using metadata-annotated interfaces. </li> + + <li>JSR-175 metadata attributes and external configuration data: provides an enhanced configuration model for resource access.</li> +</ul> +<p>This document focuses on the Controls programming and configuration model from two distinct perspectives:</p> +<ul> + <li> The authoring and extensibility model for defining a new type of Control</li> + + <li> The client access model for declaring and using Controls</li> +</ul> + + <p>An overview of the Control architecture and toolable access models can be found in the companion document entitled <link href="controlsOverview.html">Control Overview: Providing Simplified and Unified Access to J2EE Resources</link></p> + </section> + + <section> + <title>2. An Example</title> + <p>In the course of describing the programming model for Controls, this document builds upon an example Control that simplifies the enqueueing of JMS messages with a specific format and set of properties. Once completed, client code to accomplish this should be as straightforward as:</p> +<p><strong>Enqueueing using OrderQueueBean (<em>Client Code</em>)</strong></p> +<source>OrderQueueBean orderBean = (OrderQueueBean) + +java.beans.Beans.instantiate(âorg.apache.beehive.controls.examples.OrderQueueBeanâ); +Order order = new Order(myID, new String [ ] {âitem1â, âitem2â}; +OrderBean.submitOrder(order, â01-28-2004â); +</source> +<p>This document starts with a brief overview of the Control Authoring and Client Programming Models to establish some basic context, eventually building to enable the example above.</p> + </section> + + <section> + <title>3. The Control Authoring Model</title> + <p>This section describes the basic authoring model for Controls. This includes a description of the following elements:</p> + <ul> + <li><strong><em>Control Public Interface</em></strong>: source file that defines the set of operations, events, extensibility model, and properties associated with the Control type.</li> + + <li><strong><em>Control Implementation Class</em></strong>: source file that provides the implementation of the operations and extensibility model described by the Control Public Interface.</li> + + <li><strong><em>ControlBean Generated Class</em></strong>: code-generated JavaBean class that is derived from the Control Public Interface and the Control Implementation Class by a Control compiler.</li> + </ul> + <p>This authoring model is a departure from the traditional JavaBeans programming model, which is largely based upon a set of conventions that a bean author is expected to follow when constructing a new JavaBean type. In the Controls model, the author defines operations, events, and properties in an interface (Control Public Interface) and builds an underlying implementation (Control Implementation Class). A Control compiler takes these two elements and generates a specialized type of JavaBean (ControlBean Generated Class), which represents the full client programmerâs view of the Control.</p> +<p> There are two primary advantages of this model:</p> +<ul> + <li><strong>Simplicity.</strong> A key goal of any ease-of-use programming model is to free the developer from worrying about plumbing. Managing property values, event listener lists, and other basic JavaBean functions are fairly rote from implementation to implementation. The Controls architecture employs a unique variant of the Inversion of Control (IoC) design pattern based on JSR-175 metadata. This enables a Control Implementation Class to declaratively specify the events or services it requires to provide its semantics. The ControlBean Generated Class acts as a lightweight container to provide contextual hookup and implementation details.</li> + <li><strong>Consistency.</strong> Instead of trying to provide consistency through convention, the Control compiler provides both verification and code generation services to ensure that the resulting implementation provides consistent APIs and behaviors for clients, tools, and application deployers or administrators.</li> +</ul> +<p><strong>Diagram: Control Architecture Elements and Flow</strong></p> +<p><img src="images/_ControlsProgramming_1.gif" alt=""/></p> +<p>The client will interact with the Control by invoking operations defined on the Control Public Interface or dynamic property accessor methods on a ControlBean instance. The client can also express interest in any events the Control might generate by registering a listener to receive them.</p> +<p>The following diagram represents the relationship between the Control Public Interface, the Control Implementation Class, and the ControlBean Generated Class:</p> +<p><strong>Diagram: Relationships between Control Interface and Classes</strong></p> +<p><img src="images/_ControlsProgramming_2.gif" alt=""/></p> +<p>The Control Public Interface defines the operations on the Control and will be implemented by both the Control Implementation Class and the ControlBean Generated Class. The ControlBean Generated Class will also define property accessor methods and internally will maintain the state of property values. It will also maintain a reference to one (and only one) Control Implementation instance. The Control Implementation instance, wrapped by a bean instance, provides the actual implementation of resource semantics for the Control.</p> +<p>The subsequent sections will outline the various characteristics of Controls:</p> +<ul> + <li>Declaration / Instantiation</li> + <li>Operations</li> + <li>Events</li> + <li>Contextual Services</li> + <li>Properties</li> + <li>Extensibility</li> + <li>Composition</li> + <li>Context Events</li> +</ul> +<p>Where applicable, the aspects of each of these characteristics will be explored in two dimensions: from the perspective of a Control author who is defining a new type of Control, and from the perspective of a Control client that is using the services of an available Control type.</p> +<p>To make the descriptions more concrete, the characteristics will be presented within the context of a sample Control: the JmsMessageControl. This Control will provide a simplified client access model for enqueuing messages to a JMS queue or topic, freeing the client from having to learn the nuances of JMS client programming.</p> + </section> + + <section> + <title>4. The Control Client Models</title> + <p>There are actually two distinct programming models that may be available to clients of Controls:</p> + <ul> + <li><strong>Declarative Model.</strong> Uses a metadata-based variant of the Inversion of Control (IoC) design pattern to allow a component author to declare Control instances, contextual services, and event handlers using annotated fields and methods. The declarative model simplifies client programming, because many of the details of initialization and event routing are left to an external container supporting the model. A declarative programming style is also more toolable, since it is much easier for tools to manage and manipulate metadata rather than code.</li> + <li><strong>Programmatic Model.</strong> Uses the traditional JavaBean-style APIs for acting as a client of a bean, including factory-based constructor and event listeners. The programmatic model may be more comfortable to the traditional Java programmer, who wants to see and be in control of all the details. It also enables client use cases where there is no supporting container for the declarative model.</li> + </ul> + <p>The programmatic client model is generally available in all contexts where Controls might be used. It offers full generality, but leaves many of the details up to the client programmer, such as initialization, composition, and event handling wire-up.</p> +<p>The declarative model hides many of these details. Based upon its use of metadata it is also more tool friendly, allowing tools to present a view of the client code without code analysis. </p> +<p>The declarative model requires support of an outer container or construction-time code that fulfills the contract implied by annotations on a client class. </p> +<p>The ControlBean itself provides this support, so the Control Authoring Model is oriented towards using the declarative model, although programmatic equivalents are generally available.</p> + + </section> + + <section> + <title>5. Defining a New Control Type</title> +<p>Controls are designed to make it very easy for users (and tools) to define new types of Controls. Control authors might be:</p> +<ul> + <li> System vendors exposing specific types of resources</li> + + <li> Application developers defining new types of logical resources (possibly based upon physical ones)</li> + + <li>Third-party software vendors, using Controls as a mechanism to interface to components or subsystems they provide.</li> +</ul> +<p>In all instances, the goal of the Controls authoring model is to provide a basic set of conventions and supporting tools to make it easy to author a new Control type.</p> +<p>To get started, a Control author would define the two basic artifacts: </p> +<ul> + <li> the Control Public Interface</li> + + <li> the Control Implementation Class</li> +</ul> +<p>For the JmsMessageControl, the declaration of the public interface might look like:</p> +<p><strong>Interface Declaration (Control Public Interface)</strong></p> +<source>package org.apache.beehive.controls.examples; + +import org.apache.beehive.controls.api.bean.ControlInterface; + [EMAIL PROTECTED] +public interface JmsMessageControl +{ + â +}</source> + <p>The only basic rule for a Control Public Interface is that it must be annotated by the org.apache.beehive.controls.api.bean.ControlInterface marker interface.</p> + <p>The second source artifact a Control author would create to define a new type of Control is the Control Implementation Class. This declaration of the implementation class for our JmsMessageControl would look like:</p> +<p><strong>Class Declaration (Control Implementation Class)</strong></p> +<source>package org.apache.beehive.controls.examples; + +public class JmsMessageControlImpl implements JmsMessageControl +{ + â +}</source> +<p>The only basic rule for a Control Implementation Class is that it must always implement the associated Control Public Interface.</p> +<p>From these two source files, the Control compiler will create a third artifact, the ControlBean Generated Class. This class need not necessarily ever appear within an application in source code form; but for the purposes of explaining the overall architecture and client model, we will present source examples of the derived ControlBean Generated Class. </p> +<p>A Controls standard would focus only on the conventions for the external attributes of ControlBean Generated Classes, not upon the internal implementation. </p> +<p>The ControlBean Generated Class for the JmsMessageControl would look like:</p> +<p><strong>Class Declaration (ControlBean Generated Class)</strong></p> +<source>package org.apache.beehive.controls.examples; + +public class JmsMessageControIBean implements JmsMessageControl +{ + private JmsMessageControlImpl _impl; + + â +}</source> +<p>As shown above, the ControlBean Generated Class will also implement the Control Public Interface. The sample also shows that the bean will hold a private reference to an implementation instance used to support the bean.</p> + </section> + + <section> + <title>6. Instantiating a Control</title> + <p>This section covers the client mechanisms for creating a new instance of a Control. This can be done either programmatically or declarative, if running inside a container that support declarative initialization.</p> + <section> + <title>6.1 Declarative Instantiation</title> +<p>The client model for Controls supports a declarative model for instantiating a Control instance, when running in containers that support this model. In this model, the client class can annotate fields on the class using a special marker annotation (org.apache.beehive.controls.api.bean.Control) that indicates that the fields should be initialized to a ControlBean instance of the requested type.</p> +<p>Here is an example of declarative instantiation:</p> +<p><strong>Declarative Instantiation (Client Code)</strong></p> +<source>Import org.apache.beehive.controls.api.bean.Control; + +public class PublisherControlImpl extends PublisherControl +{ + <strong>@Control + public JmsMessageControlBean myJmsBean;</strong> + + â + + public void someOperation() + { + myJmsBean.sendTextMessage(âA Text Messageâ); + } +}</source> +<p>This example shows a second Control Implementation Class (PublisherControlImpl) that internally uses the services of JmsMessageControl to enqueue a JMS message. The child Control field is not explicitly initialized within the PublisherControl implementation class; by the time someOperation() is called, it is guaranteed that the myJmsBean reference has been initialized by the wrapping PublisherControlBean that contains the implementation.</p> +<p>It is also possible to parameterize the attributes of a Control at construction time, again using metadata attributes. These attributes can be placed on the field declaration (in addition to the @Control annotation) and will be used to do construction-time initialization.</p> +<p>The second example below shows initialization of the myJmsBean field again. In this case, an initial value of the @Destination ânameâ attribute is also provided using JSR-175 metadata:</p> +<p><strong>Declarative Instantiation with Properties (Client Code)</strong></p> +<source>public class PublisherControlImpl extends PublisherControl +{ + <strong>@Control @Destination(name=âInvoiceQueueâ) </strong> + public JmsMessageControlBean myJmsBean;</source> + <p>This example performs <strong>exactly</strong> the same initialization as the earlier declarative example, but does so using JSR-175 attribute syntax instead of passing parameters to a factory-based constructor.</p> +<p>The Controls architecture includes a mechanism for defining the expected set of annotations that might appear on a Control field. This mechanism is described in greater detail in the section on Properties.</p> + </section> + <section> + <title>6.2 Programmatic Instantiation</title> + <p>The client model for Controls supports instantiation of a new Control instance using the same factory-based model supported by JavaBeans. For example, the following code could be used to create a new instance of the JmsMessageControlBean generated class:</p> +<p><strong>Programmatic Instantiation (Client Code)</strong></p> +<source>JmsMessageControlBean myJmsBean = (JmsMessageControlBean) + <strong>java.beans.Beans.instantiate(cl, âorg.apache.beehive.controls.examples.JmsMessageControlBeanâ);</strong></source> + <p>The Control runtime also provides an extended factory model that allows metadata attributes to be passed into the factory constructor:</p> + <p><strong>Programmatic Instantiation with Properties (Client Code)</strong></p> + <source>import org.apache.beehive.controls.api.bean.Controls; +import org.apache.beehive.controls.api.properties.PropertyMap; + +PropertyMap jmsAttr = new (PropertyMap(JmsMessageControl.Destination.class); +jmsAttr.setProperty(ânameâ, âInvoiceQueueâ); +JmsMessageControlBean myJmsBean = (JmsMessageControlBean) + <strong>Controls.instantiate(cl, âorg.apache.beehive.controls.examples.JmsMessageControlBeanâ, jmsAttr);</strong> </source> + <p>In this example, the JmsMessageControlBean is being constructed with the Destination ânameâ property set to âInvoiceQueueâ. The AttributeMap class is a simple helper class that can hold a set of name-value pairs of a Controlâs properties, which are initialized by the factory-based constructor. More details on Controls properties are provided in a later section.</p> + </section> + </section> + + <section> + <title>7. Operations</title> + <p>Operations are actions that can be performed by a Control at the clientâs request. This section describes the authoring model for declaring and implementing a Control operation, as well as the client model for invoking operations on a ControlBean instance.</p> + <section> + <title>7.1 Declaring and Implementing Operations for a Control </title> + <p>All methods declared or inherited (via extension) by the Control Public Interface are considered to be Control operations. The following example shows the definition of two operations on the JmsMessageControl that will enqueue messages when invoked:</p> +<p><strong>Declaring Operations (Control Public Interface)</strong></p> +<source>package org.apache.beehive.controls.examples; + +import org.apache.beehive.controls.api.bean.ControlInterface + [EMAIL PROTECTED] +public interface JmsMessageControl +{ + <strong>public void sendTextMessage(String text); + public void sendObjectMessage(Serializable object);</strong> + + â +}</source> +<p>The Control Implementation Class implements the public interface for the Control, defining the operation methods, and the body of these methods.</p> +<p><strong>Implementing Operations (Control Implementation Class)</strong></p> +<source>package org.apache.beehive.controls.examples; + +public class JmsMessageControlImpl implements JmsMessageControl +{ + <strong>public void sendTextMessage(String text) + { + // Code to send a TextMessage to the destination + â. + } + + public void sendObjectMessage(Serializable object) + { + // Code to send an ObjectMessage to the destination + â. + }</strong> +} +</source> +<p>Finally, the ControlBean Generated Class will also implement all operations (since it also implements the Control Public Interface). It will always delegate to the implementation class for the actual implementation of the operation; it might also perform additional container-specific pre/post invocation processing.</p> +<p>Here is a skeleton of what the generated ControlBean code might look like for an operation:</p> +<p><strong>Implemented Operations (ControlBean Generated Class)</strong></p> +<source>package org.apache.beehive.controls.examples; + +public class JmsMessageControlBean implements JmsMessageControl +{ + private JmsMessageControlImpl _impl; + + <strong>public void sendTextMessage(String text) + { + â. + _impl.sendTextMessage(text); + â. + } + + public void sendObjectMessage(Serializable object) + { + â. + _impl.sendObjectMessage(object); + â. + }</strong> +</source> + + </section> + <section> + <title>7.2 Invoking Operations on a Control</title> +<p>The client model for invoking an operation on a Control is very straightforward: simply call the method on a held ControlBean instance as demonstrated by the following example:</p> +<p><strong>Invoking an Operation (Client Code)</strong></p> +<source> myJmsBean.sendTextMessage(âA Text Messageâ);</source> +<p>The invocation model for operations is the same, whether the Control instance was created using declarative or programmatic mechanisms.</p> + </section> + </section> + + <section> + <title>8. Events</title> + <p>Events are notifications sent by the Control back to its client whenever some condition has been met or internal event has taken place. A client can express interest in a Controlâs events by registering (either explicitly or implicitly) to receive them, and can write event handler code to be called when the event has taken place.</p> +<p>This section describes the declaration model for events, how an authored Control delivers them to a registered client, and the client code necessary to register and receive events.</p> + + <section> + <title>8.1 Declaring Events</title> +<p>Events are declared on an inner interface of the Control Public Interface, which is annotated with the org.apache.beehive.controls.api.events.EventSet annotation. The following example shows the declaration of an event interface for the JmsMessageControl, with a single event (onMessage):</p> +<p><strong>Declaring Events (Control Public Interface)</strong></p> +<source>package org.apache.beehive.controls.examples; + +import java.io.Serializable; +import javax.jms.Message; +import org.apache.beehive.controls.api.events.EventSet; +import org.apache.beehive.controls.api.bean.ControlInterface; + [EMAIL PROTECTED] +public interface JmsMessageControl +{ + public void sendTextMessage(String text); + public void sendObjectMessage(Serializable object); + + @EventSet + <strong>public interface Callback + { + void onMessage(Message m); + }</strong> + + â +}</source> +<p>If a Control Public Interface has defined an EventSet interface, then the associated ControlBean Generated Class will have two public methods supporting client listener management:</p> + +<p><strong>Event Listener Registration Methods (ControlBean Generated Class)</strong></p> +<source>package org.apache.beehive.controls.examples; + +import java.util.TooManyListenersException; + +public class JmsMessageControIBean implements JmsMessageControl +{ + â + + /** Registers a new client listener for this bean instance */ + <strong>public void addCallbackListener(Callback listener) throws TooManyListenersException</strong> + { + â. + } + + /** Deregisters a client listener for this bean instance */ + <strong>public void removeCallbackListener(Callback listener)</strong> + { + â. + } +}</source> +<p>The name of the listener registration methods are based upon the name of the associated EventSet interface. In the previous example, the EventSet interface was named Callback, so the associated listener registration method was addCallbackListener(), and the deregistration method was removeCallbackListener().</p> +<p>A Control Public Interface can have more than one inner interface that is annotated as an EventSet interface. Each declared EventSet will have its own independently managed list of registered listeners.</p> + </section> + <section> + <title>8.2 Firing Events</title> + <p>This section describes the mechanism available to a Control author to deliver events to any registered client listener. <strong>An initialized event proxy is created when the Control Implementation Class declares a field of an EventSet interface type, and annotates it with the org.apache.beehive.controls.events.Client annotation type.</strong> The containing ControlBean will initialize this reference to a valid proxy implementing the EventSet interface, and the Control Implementation Class can use this proxy to fire events back to any registered client.</p> +<p>This is demonstrated in the following sample code from the JmsControlBean implementation class, which will fire an onMessage event back to any registered client any time a message is enqueued:</p> + +<p><strong>Firing Events (Control Implementation Class)</strong></p> +<source>package org.apache.beehive.controls.examples; + +import org.apache.beehive.controls.api.events.Client; + +public class JmsMessageControlImpl implements JmsMessageControl +{ + <strong>@Client Callback client;</strong> + + public void sendTextMessage(String text) + { + // Code to construct and send a TextMessage to the destination + TextMessage m = â; + â. + <strong>client.onMessage(m);</strong> + } + â +}</source> + </section> + <section> + <title>8.3 Listening for Events</title> + <p>The client of a Control can express an interest in receiving events from a Control and write client event handlers to service them once delivered. Two basic event handling mechanisms are supported: Java event listeners or declarative event handlers (where supported by the client container).</p> + <section> + <title>8.3.1 Declarative Implementation of Event Handling</title> + <p>If the client code is implemented in a container that supports the declarative programming model for Controls (such as the Control Implementation Class itself), it can use a simplified convention for authoring event handlers for a declared Control instance.</p> +<p>If a Control is declared using the @Control marker interface, then <strong>the user can declare event handlers for the Control by using the EventHandler annotation type</strong>. These annotated methods will be considered an event handler for the Control event, and the container will automatically register for events and deliver them to this handler.</p> +<p>The previous example could be rewritten using the declarative event handling style as:</p> + +<p><strong>Declarative Handling of Events (Client Code)</strong></p> +<source> +import org.apache.beehive.controls.api.events.EventHandler + +public class PublisherControlImpl extends PublisherControl +{ + @Control + public JmsMessageControlBean myJmsBean; + + <strong>@EventHandler (field=âmyJmsBeanâ, evenSet= JmsMessageControl.Callback.class, + eventName=âonMessageâ) + public void myJmsBeanMessageHandler(Message m) + { + // Code implementing onMessage event handler + }</strong> + â +}</source> + + </section> + <section> + <title>8.3.2 Programmatic Implementation of Event Handling</title> + <p>The programmatic style follows the tradition Java event listener pattern. The client expresses its interest in receiving the event and also authors a (often anonymous inner) class that implements the event interface to receive events when delivered.</p> +<p>This is shown by the following sample code:</p> + +<p><strong>Programmatic Handling of Events (Client Code)</strong></p> +<source> myJmsBean.addCallbackListener( + new JmsMessageControl.Callback() + { + public void onMessage(Message m) + { + // Code implementing on Message event handler + } + });</source> +<p>There is no requirement that an anonymous inner class be used. One alternative would be to delegate to an instance of another class (as long as that class implements the Callback interface). In the preceding example, if event listening was implemented for the purposes of logging sent messages, and MessageLogger class could be declared (implementing the Callback interface), multiple beans could delegate to a single instance of this logging listener.</p> + </section> + </section> + </section> + + <section> + <title>9. Contextual Services</title> + <p>The Control authoring model makes use of contextual services to provide access to services from the current runtime environment of the ControlBean. The model for contextual services is based upon the existing standards for services in JavaBeans: The JavaBeans Runtime Containment and Services Protocol. This protocol provides a base mechanism for a JavaBean to locate and use services from the runtime environment, as well as an extensible service provider model to enable new (or environment-specific) types of services to be authored and made available to JavaBeans/Controls.</p> +<p>A key aspect of this service model is that it can be contextual; for example, it might be possible to write a basic security service interface that provides logical role-checking functionality. The actual implementation of this interface might vary for different runtime contexts: for example, the role check might be done differently for a Control running within the context of an EJB container (by delegating to the containing EJBContext) vs. a Control running within the Web tier (by delegating to ServletHttpRequest services).</p> +<p>Having an extensibility and service provider location model is important to enable the following scenarios:</p> +<ul> + <li> The Controlâs implementation is designed to run in a wide variety of environments. It uses the contextual service mechanism to declare its prerequisites and receive a provider implementation that is appropriate to the current runtime context.</li> + <li> The Controlâs implementation is designed to run in a very specific context (for example, only in the http servlet tier) and wants access to services that are very specific to that context (for example, session state or request query parameters). It should not be possible to instantiate this Control in other contexts (for example, from within an EJB).</li> +</ul> +<p><strong>One key contextual service for Controls that is guaranteed to be available in all contexts is the org.apache.beehive.controls.api.context.ControlBeanContext service interface. </strong>This service provides a common set of generic services that are available to Control authors, such as the ability to query property values on the current instance, or to receive a set of basic lifecycle or resource management events. The ControlBeanContext interface extends the java.beans.beancontext.BeanContextServices interface, so it also provides access to services provided by the JavaBeans bean context APIs. Later sections describe an overview of the internal architecture for contextual services, APIs to support property resolution, and lifecycle events.</p> + <section> + <title>9.1 Declarative Access to Contextual Services</title> + <p>To signal the desire to access a contextual service, a Control author only needs to declare a field of the desired context interface and annotate it with the org.apache.beehive.controls.api.context.Context marker annotation. The following example shows how the JmsMessageControlImpl class would use the declarative model to access its ControlBeanContext:</p> + +<p><strong>Declarative Access to Context Services (Control Implementation Class)</strong></p> +<source>package org.apache.beehive.controls.examples; + +import org.apache.beehive.controls.api.context.Context; +import org.apache.beehive.controls.api.context.ControlBeanContext; + +public class JmsMessageControlImpl implements JmsMessageControl +{ + <strong>@Context ControlBeanContext context;</strong> + + public void sendTextMessage(String text) + { + JmsMessageControl.Destination = + <strong>context.getControlPropertySet(JmsMessageControl.Destination.class);</strong> + + â + } +}</source> +<p>In this example, the JmsMessageControl implementation class expresses its desire to access ControlBeanContext services via the annotated declaration of the context field; when code in sendTextMessage operation is invoked, this contextual service has already been initialized by the containing ControlBean instance.</p> +<p>The ControlBeanContext for an authored Control is always accessed using the declarative mechanism. Other contextual services may be accessed declaratively, or using the programmatic mechanisms described in the following section.</p> + + </section> + <section> + <title>9.2 Programmatic Access to Contextual Services</title> +<p>The ControlBeanContext service also provides the base mechanism to discover and use other services programmatically. The following code fragment shows an example of how to use this API to obtain access to a service provider that provides the javax.servlet.ServletContext interface.</p> + +<p><strong>Programmatic Access to Context Services (Control Implementation Class)</strong></p> +<source>package org.apache.beehive.controls.examples; + +import javax.servlet.ServletContext; +import org.apache.beehive.controls.api.context.Context; +import org.apache.beehive.controls.api.context.ControlBeanContext; + +public class JmsMessageControlImpl implements JmsMessageControl +{ + <strong>@Context ControlBeanContext context;</strong> + + public void sendTextMessage(String text) + { + <strong>ServletContext servletContext = context.getService(ServletContext.class, null);</strong> + if (servletContext == null) + { + // no ServletContext provider is available + } + + â + } +}</source> +<p>The code in the sample uses the ControlBeanContext.getService API to request that it provide a ServletContext service. The parameters to this method are the Class of the requested service, and an (optional) service-specific selector that can be used to parameterize the service. </p> +<p>The ServletContext service is contextual because it is available only to controls running in the web tier. If the above sample control was running anywhere else, the call to ControlBeanContext.getService() would return null.</p> + + </section> + <section> + <title>9.3 Tradeoffs between Declarative and Programmatic Access</title> +<p>Declarative access to context services is always available to a Control Implementation Class, and generally results in less code associated with accessing services. Why then, would using programmatic access ever be useful? There is a key difference between the two:</p> + +<ul> + <li> When using the declarative model for accessing a contextual service, the Control is effectively saying that the service is required for it to function; if not available in a particular runtime environment, then construction of an instance of the Control will fail. Essentially, the annotated context acts as a notification to the runtime factory that this prerequisite must be satisfied.</li> + + <li> Use of the programmatic model allows a Control Implementation Class to implement conditional behavior based upon whether a contextual service is or is not available. The Control Implementation Class can use the programmatic accessor, and then make a decision how to proceed based upon whether the requested service is available.</li> +</ul> + </section> + </section> + + <section> + <title>10. Properties</title> + <p>This section describes Control properties. Properties provide the basic mechanism for parameterizing the behavior of a Control instance.</p> + <p>The Controls architecture takes the basic JavaBeans notion of properties and extends it to support two new capabilities:</p> + <ul> + <li> A declarative annotation model where properties can be preconfigured on a ControlBean using JSR-175 annotations</li> + + <li> An administrative model where the value of ControlBean properties can be externally defined or overridden.</li> + </ul> + <p>The external configuration and administrative model for Controls will be described in a separate document.</p> + <section> + <title>10.1 Declaring Properties for a Control Type</title> + <p>For Controls, the set of properties is explicitly declared on the Control Public Interface. This makes the available parameterization of a Control type readily visible to both code and tools.</p> +<p>Properties are grouped together into related groups called PropertySets. All Properties within a PropertySet will have a common set of attributes (such as where they can be declared, the access model for JavaBean accessors, etc) and will have property names based upon a common naming convention.</p> +<p>A PropertySet is declared as a JSR-175 attribute interface within the Control Public Interface, which is also decorated with the org.apache.beehive.controls.api.properties.PropertySet meta-attribute. Each of the members within a PropertySet will refer to a distinct property within the set, and the return value of the member defines the property type.</p> +<p>Here is a sample declaration of the Destination PropertySet for the JmsMessageControl, which can be used to configure the target JMS destination for the Control:</p> + +<p><strong>Declaring Properties (Control Public Interface)</strong></p> +<source>package org.apache.beehive.controls.examples; + +import org.apache.beehive.controls.api.bean.ControlInterface +import org.javacontrols.api.properties.PropertySet; +import java.lang.annotations.Retention; +import java.lang.annotations.RetentionPolicy; +import java.lang.annotations.Target; + [EMAIL PROTECTED] +public interface JmsMessageControl +{ + â + + public enum DestinationType { QUEUE, TOPIC } + + <strong>@PropertySet(prefix=âDestinationâ) + @Target({FIELD, TYPE}) + @Retention(RetentionPolicy.RUNTIME) + public @interface Destination + { + public DestinationType type() default QUEUE; + public String name(); + }</strong> + â +}</source> +<p>This declaration defines the PropertySet named âDestinationâ that includes two properties: type and name. The type property is based upon the DestinationType enumerated type, which is also defined in the public interface. The name attribute is a simple String property.</p> +<p>Meta-attributes on a PropertySet or property declaration can be used to provide additional details about the properties and how they may be used. In the above example, the standard java.lang.annotations.Target annotation is used to define the places where the @Destination property set can appear (in this case in either an extension class or field declaration). </p> +<p>The full set of meta-attributes that can decorate PropertySet or Property declarations are TBD. They can be used to define constraint models for property values, or relationships between properties (such as exclusive or, where one is set or the other, but never both). These meta-attributes can be read and used by development or administrative tools to aid in the selection of property values. They can also be used by the runtime for runtime validation of property values when set dynamically.</p> + + </section> + <section> + <title>10.2 Accessing Properties from Client Code</title> +<p>The properties defined in the Control Public Interface will be exposed to the client programmer using traditional JavaBean setter/getter methods on the ControlBean Generated Class. These methods will follow a simple naming pattern based upon the PropertySet interface name, and optional PropertySet prefix, and property member name. </p> +<p>The basic pattern for these accessors is:</p> + +<p><strong>Property Accessor Generation (Conventions)</strong></p> +<source> public void set<PropertySetPrefix><MemberName>(<MemberType>); + public <MemberType> get<PropertySetPrefix><MemberName>();</source> + <p>The PropertySetPrefix refers to the optional prefix attribute of the PropertySet annotation. If unspecified, it will default to an empty string (no prefix). The MemberName refers to the PropertySet method name that declares the property, with the first character converted to uppercase, and the MemberType refers to the return value type of this method declaration.</p> +<p>So for the Destination PropertySet interface shown in the example above, the resulting ControlBean Generated Class would expose the following accessors:</p> + +<p><strong>Property Accessors (ControlBean Generated Class)</strong></p> +<source>package org.apache.beehive.controls.examples; + +import java.util.TooManyListenersException; + +public class JmsMessageControIBean implements JmsMessageControl +{ + â + public void setDestinationType(DestinationType type) { â } + public DestinationType getDestinationType() { â} + public void setDestinationName(String name) { â} + public String getDestinationName(); +}</source> +<p>Client code to set the Destination properties on a JmsMessageControlBean instance would look like:</p> + +<p><strong>Using Property Accessors (Client Code)</strong></p> +<source>@Control JmsMessageControlBean jmsBean; + +â + + <strong>jmsBean.setDestinationType(Destination.QUEUE); + jmsBean.setDestinationName(âmyTargetQueueâ);</strong></source> + + </section> + <section> + <title>10.3 Accessing Properties from Control Implementation code</title> + <p>The Control Implementation class contains code that executes from within the context of the Control JavaBean that is generated to host the control. The generated bean will automatically manage the resolution of properties values from annotations, external configuration, or dynamic values set by the client.</p> +<p>Access to these properties is provided by the ControlBeanContext instance associated with the Control Implementation Class. This interface provides a set of property accessors that allow the implementation to query for property values:</p> + +<p><strong>ControlBeanContext APIs for Property Access</strong></p> +<source>package org.apache.beehive.controls.api.context; + +public interface ControlBeanContext extends java.beans.beancontext.BeanContextServices +{ + â. + public <T extends Annotation> T getControlPropertySet(Class<T> propertySet); + public <T extends Annotation> T getMethodPropertySet(Method m, Class<T> propertySet); + public <T extends Annotation> T getParameterPropertySet(Method m, index I, Class<T> propertySet); + â +}</source> + <p>The propertySet argument passed to these methods must be a valid PropertySet interface associated with the ControlInterface. The ControlBeanContext will return the current value for properties in the PropertySet, or will return null if no PropertySet value has been associated with this control instance.</p> +<p>Here is a simple example of using ControlBeanContext.getControlPropertySet() to query a property set:</p> + +<p><strong>Acccessing Control Properties (Client Implementation Class)</strong></p> +<source>package org.apache.beehive.controls.examples; + +import org.apache.beehive.controls.api.context.Context; +import org.apache.beehive.controls.api.context.ControlBeanContext; + +public class JmsMessageControlImpl implements JmsMessageControl +{ + <strong>@Context ControlBeanContext context;</strong> + + â + + @EventHandler(field=âcontextâ, eventSet=ControlBeanContext.Lifecycle.class, eventName=âonAcquireâ) + public void onBeanAcquire() + { + // + // Acquire the property values needed for initialization + // + <strong>Destination destProp = + (Destination)context.getControlPropertySet(JmsMessageControl.Destination.class);</strong> + if (destProp == null) + { + // No destination property set for the control + â + }</source> + <p>This code above queries for the value of the JmsMessageControl.Destination PropertySet on the current JmsMessageControl instance.</p> + <p>These query methods will return the value of resolved properties for the Control instance, method, or method argument, respectively. Control implementations should never use Java reflection metadata accessors directly on Control classes or methods; these accessors wonât reflect any property values that have been set dynamically by ControlBean client accessor methods or externally using administrative configuration mechanisms. The ControlBeanContext provides a consistent resolution of source annotation, client-provided, and external values.</p> +<p>A simple example of using the ControlBeanContext property accessor methods for accessing Method and Parameter properties is provided in the section on Extensibility.</p> + </section> + <section> + <title>10.4 External Configuration of Control Properties</title> + <p>Controls also support an administrative model that allows Control property values to be bound using external configuration syntax. The enables Control behavior to be parameterized externally to the code, and using a consistent mechanism that is well-defined and structured to enable tooling.</p> +<p>The specifics of this administrative model are not covered within this document.</p> + + </section> + </section> + + <section> + <title>11. Extensibility</title> +<p>The Controls architecture supports an extensibility model that enables the declarations of user-defined operations or events, based upon a predefined set of semantics defined by the author of the Control type. The extensibility mechanism enables the definition of an interface to the resource where operations (or events) have very specific context. </p> +<p>For example, in the JmsMessageControl sample, the extensibility mechanism will be used to raise the level of abstraction: instead of a low-level mechanism to enqueue messages to a topic or queue, the Control enables extensibility where operations can be defined that correspond to enqueuing messages with a very specific format and set of properties, and where message or property content is derived from method parameters. This creates a logical view of the resource (in this case a queue or topic) where the operations available on it have very specific (and constrained) semantics.</p> +<p>For this section, weâll start with the how an extension is defined, look at the authoring model for defining an extensible Control type, and finally show the client view of using an extended type.</p> + <section> + <title>11.1 Defining an Extended Interface for a Control Type</title> + <p>An extension to a base Control type that defines a specific resource use case is created by defining a new Control type that derives from the original type and is annotated with the ControlExtension annotation type:</p> + +<p><strong>Declaring a Control Extension (Control Extension Interface)</strong></p> +<source>package org.apache.beehive.controls.examples; + +import org.apache.beehive.controls.api.bean.ControlExtension; + +<strong>@ControlInterface</strong> [EMAIL PROTECTED](type=JmsMessageControl.QUEUE, name=âqueue.ordersâ) +<strong>public interface OrderQueue extends JmsMessageControl</strong> +{ + â +}</source> +<p>This example shows that this interface shows that property values can be configured on the extended interface to further parameterize the use case. In this case, the InvoiceQueue interface is being designed for a very specific use case: to enable orders to be enqueued to a JMS queue named âqueue.ordersâ.</p> +<p>Once defined, the Control extension author can now begin to define additional operations on it, in this case the ability to enqueue messages to the OrderQueue by calling methods on it.</p> + +<p><strong>Declaring Extended Operations with Properties (Control Extension Interface)</strong></p> +<source>package org.apache.beehive.controls.examples; + +import org.apache.beehive.controls.api.bean.ControlExtension; + [EMAIL PROTECTED] [EMAIL PROTECTED](type=JmsMessageControl.QUEUE, name=âqueue.ordersâ) +<strong>public interface OrderQueue extends JmsMessageControl</strong> +{ + public class Order implements java.io.Serializable + { + public Order(int buyer, String list) { buyerID = buyer; itemList list; } + int buyerID; + String [ ] itemList; + } + + <strong>@Message (OBJECT) + public void submitOrder( + @Body Order order, + @Property ( name=âDeliverByâ) String deliverBy);</strong> +}</source> +<p>This interface defines a single operation, submitOrder, that enqueues an ObjectMessage containing a new order. The body of the message will be a single instance of the Order class, and it will have a single StringProperty with the expected delivery date (enabling message selector-based queries for orders that are past due).</p> +<p>The message format (in this case an ObjectMessage) and the mapping of operation parameters to message content and/or properties are all defined using JSR-175 metadata on the method or its parameters. This format makes it very easy for tools to assist in the creation and presentation of extension interfaces.</p> +<p>How does the extension author (or tool) know about the set of annotations that can be used on the extension interface? This is the topic of the next section.</p> + </section> + <section> + <title>11.2 Defining Extension Semantics for a Control Type</title> + <p>A Control author is responsible for defining the extensibility semantics for a particular type, since ultimately they are responsible for providing the implementation that fulfills the semantics. </p> +<p>The extension semantics for a Control are part of the public contract for the Control, and thus are defined on the Control Public Interface as well. As with Control properties, these are defined in the form of JSR-175 annotation interfaces, as show in the following sample code from the JmsMessageControl Public Interface:</p> + +<p><strong>Declaring Extension Semantics (Control Public Interface)</strong></p> +<source>package org.apache.beehive.controls.examples; + +import java.io.Serializable; +import javax.jms.Message; +import org.apache.beehive.controls.api.bean.ControlInterface; + [EMAIL PROTECTED] +public interface JmsMessageControl +{ + â + + public enum MessageType { BYTES, MAP, OBJECT, STREAM, TEXT } + + <strong>@Target({METHOD}) + @Retention(RUNTIME) + public @interface Message + { + public MessageType value() default TEXT; + } + + @Target({PARAMETER} + @Retention(RUNTIME) + public interface Body {} + + @Target({PARAMETER}) + @Retention(RUNTIME) + public @interface Property + { + public String name(); + }</strong> +}</source> +<p>The JmsMessageMessageControl defines three annotation types: Message, Body, and Property. The @Target annotation on the Message declaration specifies that Message can be placed on the method declaration to indicate the type of JMS message that will be enqueued by the operation. The Body annotation is used to indicate the method parameter that contains the contents of the message (and must have a type that is compatible with the specified MessageType). The Property annotation on a method parameter indicates that the parameterâs value should be stored as a property on the enqueue message, with the property name coming from the value of the annotation and the property type derived from the type of the method parameter.</p> +<p>The key is that the Control Public Interface contains sufficient details about the expected annotations that a tool can support the construction. It also makes it possible for the Control compiler (that converts the extended interface to an associated bean implementation) to perform validation of interface and method annotations.</p> +<p>More details on how these extension semantics are implemented are described in the next section.</p> + </section> + <section> + <title>11.3 Authoring an Extensible Control Type</title> + <p>The author of a Control type is responsible for providing the code that implements the extension semantics for the Control. Support for extensibility is optional; so a Control author indicates extensibility of a type by declaring that that the Control Implementation Class implements the org.apache.beehive.controls.api.bean.Extensible interface. This interface has a single method named invoke(). </p> +<p>The skeleton of this code for the JmsMessageControlImpl class is shown below:</p> +<p><strong>Implementing Extended Operations (Control Implementation Class)</strong></p> +<source>package org.apache.beehive.controls.examples; + +import org.apache.beehive.controls.api.context/.Context; +import org.apache.beehive.controls.api.context.ControlBeanContext; +import org.apache.beehive.controls.api.bean.Extensible; + +public class JmsMessageControlImpl implements JmsMessageControl, Extensible +{ + @Context ControlBeanContext context; + + <strong>public Object invoke(Method m, Object [] args) throws Throwable + { + // Extensibility implementation + â + }</strong> +} +</source> +<p>The invoke() method on the Control Implementation Class will be called any time an operation defined on an extension interface is called on the Control by its client. The implementation of this method has responsibility for examining the current set of properties for the Control instance, methods, and parameters and using them to parameterize the behavior of the Control.</p> +<p>This is demonstrated by the code below, which shows a portion of the implementation of invoke() for the JmsMessageControlImpl class:</p> +<p><strong>Accessing Method Properties Using the Context (Control Implementation)</strong></p> +<source>Object invoke(Method m, Object [] args) throws Throwable +{ + â + + int bodyIndex = 1; + for (int i= 0; i < args.length; i++) + if (context.getArgumentPropertySet(m, i, JMMessageControl.Body.class) != null) + bodyIndex = i; + + // + // Create a message of the appropriate type + // + Message msg = null; + JMSMessageControl.Message msgProp = <strong>context.getMethodPropertySet(m, + JMSMessageControl.Message.class);</strong> + switch(msgProp.value()) + { + case MessageType.OBJECT: + msg = session.createObjectMessage(args[bodyIndex]); + break; + â + } + + // + // Decorate the message with properties defined by any arguments + // + for (int i= 0; i < args.length; i++) + { + JMSMessageControl.Property jmsProp = + <strong>context.getParameterPropertySet(m,i, JmsMessageControl.Property.class);</strong> + if (jmsgProp != null) + { + String name = jmsProp.value(); + if (args[I] instanceof String) + msg.setStringProperty(name, ((String)args[i]); + else if (args[I] instanceof Integer) + â + else + msg.setObjectProperty(name, args[I); + } +}</source> +<p>In the sample code above, the Control Implementation Class uses the ControlBeanContext getMethodProperty and getParameterProperty APIs to query properties of the invoked method and its argument. These query methods will return null if the property is not found and no default was defined for the attribute member.</p> + + </section> + <section> + <title>11.4 Client Model for Using an Extended Control Type</title> + <p>The client model for using an extended Control type is exactly the same as the model for using a base Control type. The same set of declarative and programmatic instantiation mechanisms (described in the previous section) will be used, and operations or events are handled the same way.</p> +<p>Below is sample code that uses the OrderQueue extended type (using declarative client model):</p> +<p><strong>Using a Control Extension (Client Code)</strong></p> +<source><strong>@Control org.apache.beehive.controls.examples.OrderQueueBean orderBean;</strong> + +â + Order order = new OrderQueue.Order(); + order.buyerID = myID; + order.itemList = new String [] {âitem1â, âitem2â}; + orderBean.submitOrder(order, â12-31-2004â); +</source> +<p>Looking closely at the example, youâll notice that a derived ControlBean type (OrderQueueBean) is generated by the Control compiler, just as it is for a base Control type. +The skeleton of this ControlBean Generated Class is shown below: +</p> +<p><strong>Implementation of Extended Operations (ControlBean Generated Class)</strong></p> +<source>Package org.apache.beehive.controls.examples; + +public class OrderQueueBean extends JmsMessageControlBean + implements OrderQueue +{ + JmsMessageControlImpl _impl; + â. + Public void submitOrder(Object order, String deliveryBy) + { + â + _impl.invoke(submitOrderMethod, new Object [] {order, deliveryBy}; + â + } + +}</source> + <p>There are several attributes worth noting about the extended ControlBean Generated Class:</p> + <ul> + <li> Its implementation will be a subclass of the base type ControlBean, so implementation of base type operations is inherited.</li> + + <li> The extended bean will implement the extended Control interface, meaning all extended operations will be implemented by the bean.</li> +</ul> +<p>The implementation of these extended operations will always delegate down to the base Control Implementation Class by calling the Extensible.invoke() method.</p> + </section> + </section> + + <section> + <title>12. Composition</title> + <p>The Controls architecture supports a composition model, based upon the JavaBeans Runtime Containment and Services Protocol. This means that it is possible for new types of ControlBeans to be defined that are built through composition of one or more other types.</p> + <section> + <title>12.1 Composition Using Declarative Instantiation</title> + <p>Additionally, the ControlBeans authoring model makes composition very simple based upon the declarative instantiation model. Within any ControlBean implementation, any @Control fields will automatically be initialized as children of the local beanâs context.</p> +<p>Hereâs a simple example based upon our previous OrderQueue example. Letâs say that we want to create a logical Control that can be used to submit orders. This Control will submit to one of two different queues, depending upon whether the order needs to ship in less than 30 days, or greater than 30 days.</p> +<p>The implementation of this Control could look like:</p> + <p><strong>Composition Using Declarative Instantiation (Control Implementation Class)</strong></p> +<source>package org.apache.beehive.controls.examples; + +public class OrderRouterImpl +{ + @Control @Destination(Name=âRushOrdersâ) + OrderQueueBean rushOrders; + + @Control @Destination(Name=âOrdersâ) + OrderQueueBean orders; + + â + + public void submitOrder(Order order, String deliverBy) + { + if (needsRushDelivery(deliveryBy)) + rushOrders.submitOrder(order, deliverBy); + else + orders.submitOrder(order, deliverBy); + } +} +</source> +<p>In this example, the OrderRouterImpl Control itself uses the services of two different OrderQueue Controls referencing two different queues, and uses a helper method (needsRushDelivery) to decide where to enqueue a particular order. The new Control has the same operations exposed as the original Controls; but now uses the services of one or the other of its children to satisfy the request.</p> +<p>The next section describes doing an equivalent composition using mechanisms to instantiate and build the Control hierarchy.</p> + <section> + <title>12.1.1 Composition using Programmatic Mechanisms</title> +<p>Because the ControlBeans architecture is built using the JavaBeans Runtime Containment protocol, which defines a base composition model for JavaBeans, it is also possible to manually instantiate and Controls using the APIs it defines. The ControlBeanContext API extends the java.beans.beancontext.BeanContext API, which provides support for adding children to the current beanâs context.</p> +<p>Hereâs the previous sample, rewritten to use programmatic composition:</p> +<p><strong>Composition Using Programmatic Instantiation (Control Implementation Class)</strong></p> +<source>package org.apache.beehive.controls.examples; + +public class OrderRouterImpl +{ + OrderQueueBean rushOrders; // no @Control annotation, so no auto-init + OrderQueueBean orders; // no @Control annotation, so no auto-init + <strong>@Context ControlBeanContext context;</strong> + â + + public void context_onCreate() + { + ClassLoader cl = Thread.currentThread().getContextClassLoader(); + rushOrders = (OrderQueueBean)Beans.instantiate(cl, âorg.apache.beehive.controls.examples.OrderQueueBeanâ); + rushOrders.setDestinationName(âRushOrdersâ); + <strong>context.add(rushOrders);</strong> + orders = (OrderQueueBean)Beans.instantiate(cl, âorg.apache.beehive.controls.examples.OrderQueueBeanâ); + orders.setDestinationName(âRushOrdersâ); + <strong>context.add(orders);</strong> + } + + public void submitOrder(Order order, String deliverBy) + { + â. + } +}</source> + + </section> + </section> + <section> + <title>12.2 Internal Architecture for Composition and Services</title> + <p>The JavaBeans Runtime Containment and Services Protocol provides the base composition model for Control composition and containment. In this model, JavaBeans are associated with a BeanContext that manages the composition hierarchy and also manages any contextual services requested by the contained beans.</p> +<p>In the Control architecture, a ControlBean will potentially be related to two different BeanContexts: a parent context that represents the outer container for the bean, and a peer context that provides containment and services to other beans nested within that Control.</p> +<p>These context relationships from the previous sample are shown in the following diagram:</p> +<p><img src="images/_ControlsProgramming_3.gif" alt=""/></p> +<p>In the diagram, the two OrderQueueBean instances created by OrderRouterBean are nested within the ControlBeanContext; while not shown, these two beans would also have a peer ControlBeanContext providing them with contextual services.</p> +<p>The peer ControlBeanContext provides localized generic services to the associated Control Implementation instance, such as ability to resolve property values from the local bean instance or externalized configuration, and the delivery of lifecycle events. The ControlBean architecture uses a delegation model for service discovery. If an implementation instance requests a service that is not implemented by the peer BeanContext, it will delegate up to the parent context to find a provider for the service.</p> +<p>At the root of the bean composition hierarchy is an instance of a ContainerBeanContext. This context represents the external runtime environment, within which the ControlBean is running. This might represent an EJB, servlet, web service, Java application, or any ControlBean-capable container. The ContainerBeanContext is responsible for the initialization and provisioning of service providers that are specific to runtime environment with which it is associated.</p> +<p>Whether ContainerBeanContext or ControlBeanContext, the BeanContext instances also provide the basic hierarchy of composition, as shown by the parent-child relationships above.</p> + </section> + </section> + + <section> + <title>13. Context Events</title> + <p>The Control programming model also exposes a basic set of lifecycle events to enable the Control to perform efficient initialization and resource management. These events are delivered by the peer ControlBeanContext associated with a ControlBean instance. A listener can register to receive these events using the addCallbackListener API on ControlBeanContext; the actual Callback event interface itself is defined there as well:</p> +<p><strong>Context Life Cycle Events</strong></p> +<source>import org.apache.beehive.controls.api.context; + +public interface ControlBeanContext extends java.beans.beancontext.BeanContextServices +{ + â + <strong>public interface Callback extends java.util.EventListener + { + public void onCreate(); + public void onAcquire(); + public void onRelease(); + } + + public void addCallbackListener(Callback lifecycleListener); + public void removeCallbackListener(Callback lifecycleListener); </strong> +}</source> +<p>The specific life cycle events are described in the following section:</p> + <section> + <title>13.1 Life Cycle Events</title> + <p>The ControlBeanContext life cycle events provide notification to the associated ControlBean derived class and Control Implementation Class (and potentially other interested listeners) of significant events related to the peer bean instance.</p> + <section> + <title>13.1.1 The onCreate Event</title> + <p>The onCreate event is delivered when the Control Implementation instance associated with the ControlBean has been constructed and all declarative initialization has been completed. This provides an opportunity for the implementation instance to perform any additional initialization required; implementation instances should generally use the onCreate event instead of writing constructor code.</p> + </section> + <section> + <title>13.1.2 The onAcquire Event</title> + <p>The onAcquire event is delivered to a registered listener the first time a ControlBean operation is invoked within a particular resource context. It provides an opportunity for the Control Implementation instance (or other related entities, such as a contextual service provider) to acquire any short-term resources (connections, sessions, etc) needed by the ControlBean.</p> +<p>The onAcquire event is guaranteed to be delivered once (and only once) prior to invocation of any operation within a resource context; it is also guaranteed that a paired onRelease event will be delivered when the resource context ends.</p> +<p>For more details on resource management, refer to the <link href="controlsOverview.html">Control Overview</link> document.</p> + </section> + <section> + <title>13.1.3 The onRelease Event</title> + <p>The onRelease event is the companion event to onAcquire. It is guaranteed to be called once (and only once) on any bean instance that has received an onAcquire event, when its associated resource context has ended. It acts as the signal that any short-term resources (connections, sessions, etc) acquired by the Control should be released.</p> + + </section> + </section> + <section> + <title>13.2 Receiving Life Cycle Events</title> +<p>For a Control Implementation Class, the model for receiving context life cycle events is consistent with the general client model for event registration and delivery. Both declarative and programmatic mechanisms are supported.</p> + <section> + <title>13.2.1 Declarative Access to Life Cycle Events</title> + <p>A Control Implementation Class can receive Life Cycle Events simply by declaring the annotated @Context ControlBeanContext and then defining event handlers that follow the <contextFieldName>_<eventName> convention.</p> +<p>The following sample code shows the JmsMessageControl registering to receive onAcquire and onRelease events:</p> +<p><strong>Declarative Handling of Life Cycle Events (Control Implementation Class)</strong></p> +<source>package org.apache.beehive.controls.examples; + +import org.apache.beehive.controls.api.context.Context; +import org.apache.beehive.controls.api.context.ControlBeanContext; +import org.apache.beehive.controls.api.events.EventHandler; + +Public class JmsMessageControlImpl implements JmsMessageControl +{ + <strong>@Context ControlBeanContext context; + + @EventHandler(field=âcontextâ, eventSet=ControlBeanContext.LifeCycle.class, + eventName=âonAcquireâ) + public void onAcquire() + { + // Code to acquire JMS connection/session/destination/writers + â + } + + @EventHandler(field=âcontextâ, eventSet=ControlBeanContext.LifeCycle.class, + eventName=âonReleaseâ) + public void onRelease() + { + // Code to release JMS connection/session/destination/writer + â + }</strong> +}</source> +<p>When using the declarative mechanism, a Control Implementation Class is free to implement only a subset of the life cycle listeners; it is not necessary that it provide a handler for all events.</p> + </section> + <section> + <title>13.2.2 Programmatic Access to Life Cycle Events</title> + <p>An external entity (such as contextual service provider or even a client) is also able to register for life cycle events on a ControlBean instance as well. This is done by obtaining a reference to the peer ControlBeanContext for the instance using the getPeerContext API, and then using the addCallbackListener API to register a lifecycle event listener.</p> +<p>This is shown by the following code:</p> +<p><strong>Programmatic Handling of Life Cycle Events (Control Implementation Class) </strong></p> +<source> JmsMessageControlBean myJmsBean = â; + + ControlBeanContext peerContext = myBean.getControlBeanContext(); + peerContext.addCallbackListener( + new ControlBeanContext.LifeCycle() + { + public void onCreate() { ... }; + public void onAcquire() { ... }; + public void onRelease() { ... }; + } + );</source> + </section> + </section> + <section> + <title>13.3 JavaBean Context Events</title> + <p>The org.apache.beehive.controls.api.context.ControlBeanContext API extends the following standard JavaBean context APIs:</p> + <ul> + <li> java.beans.BeanContextChild</li> + <li> java.beans.BeanContext</li> + <li> java.beans.BeanContextServices</li> + </ul> + <p>These APIs provide access to a standard set of JavaBean events that the Control Implementation Class can register an interest in. </p> + <p><em>[Issue: there is not a declarative mechanism for receiving these events, but probably should be.]</em></p> + <section> + <title>13.3.1 PropertyChange Events</title> + <p>The java.beans.BeanContextChild interface provides the addPropertyChangeListener() and addVetoableChangeListener() APIs to register for notification when a property is modified.</p> + </section> + <section> + <title>13.3.2 Membership Events</title> + <p>The java.beans.BeanContext interface provides the addMembershipChangeListener() API to register for notification whenever a child is added or removed from the BeanContext.</p> + </section> + <section> + <title>13.3.3 Context Services Events</title> + <p>The java.beans.BeanContextServices interface provides the addBeanContextServicesListener API to register for notification when new contextual services become available or are revoked.</p> + </section> + </section> + </section> + + <section> + <title>14. Appendix A: The JmsMessageControl Public Interface</title> + <source>package org.apache.beehive.controls.examples; + +import java.io.*; +import java.lang.annotation.*; +import javax.jms.*; + +import org.apache.beehive.controls.api.bean.ControlInterface; +import org.apache.beehive.controls.api.events.EventSet; +import org.apache.beehive.controls.api.properties.PropertySet; + +/** + * The JmsMessageControl defines a basic Control to enable messages to be enqueued to a JMS + * queue or topic. Using Control properties, you can configure the connection, session, and + * destination attributes that should be used to connect to the JMS provider. The Control + * will transparently connect to the JMS provider and obtain any necessary resources to + * enqueue the messages. The Control will also sure that the resources are properly released + * at the end of the current resource scope associated with the Controlâs runtime environment. + * + * The Control provides a basic set of operations that allow a simple text or object message to + * be written to the configured destination. It also provides an extensibility mechanism + * that allows new operations to be defined by extending this interface. Extended operations + * define the enqueueing of message with a specific type (TextMessage, ObjectMessage, ...) + * where operation parameters can be mapped to message properties or content. + */ [EMAIL PROTECTED] +public interface JmsMessageControl +{ + // OPERATIONS + + /** + * Sends a simple TextMessage to the Controlâs destination + * @param text the contents of the TextMessage + */ + public void sendTextMessage(String text); + + /** + * Sends a simple ObjectMessage to the Controlâs destination + * @param object the object to use as the contents of the message + */ + public void sendObjectMessage(java.io.Serializable object); + + + + // EVENTS + + /** + * The Callback interface defines the events for the JmsMessageControl. + */ + @EventSet + public interface Callback + { + /** + * The onSend event is delivered to a registered client listener whenever a + * a message has been sent by the Control. + * @param msg the message that was sent + */ + public void onMessage(javax.jms.Message msg); + } + + // PROPERTIES + + /** + * The Connection property defines the attributes of the connection and session used + * to enqueue the message. This annotation can appear on both class and Control + * field declarations. + */ + @PropertySet + @Target({FIELD, TYPE}) + public @interface Connection + { + public String factoryName(); + public boolean transacted() default true; + public int acknowledgeMode() default Session.CLIENT_ACKNOWLEDGE; + } + + /** An enumeration that defines the value set of destination types */ + public enum DestinationType { QUEUE, TOPIC } + + /** + * The Destination property defines the attributes of the JMS destination that should + * be the target of any enqueued messages. + */ + @PropertySet + @Target({FIELD, TYPE}) + public @interface Destination + { + public DestinationType type() default QUEUE; + public String name(); + } + + + + // EXTENSIBILITY ATTRIBUTES + + /** + * The set of supported message types for extended operations + */ + public enum MessageType { TEXT, OBJECT, BYTES } + + /** + * The Message attribute can be placed on an extended operation to describe the format of the + * message that should be enqueued when the operation is invoked. The method is expected to + * have a least parameter annotated with the Body attribute, and zero or more parameters with + * the Property attribute defining message properties. + */ + @Target({METHOD}) + public @interface Message + { + public MessageType value() default TEXT; + } + + /** The Body attribute indicates that the associated method parameter on an extended operation + * contains the message body. + */ + @Target({PARAMETER} + public interface Body {} + + /** + * The Property attribute can be used to define operation parameters that should be used to + * set properties on the message. The type of property to set will be inferred based upon + * the type of the parameter. + */ + @Target({PARAMETER}) + public @interface Property + { + public String name(); + } +}</source> + </section> + + <section> + <title>15. Appendix B: The JmsMessageControl Implementation Class</title> + <source>package org.apache.beehive.controls.examples; + +import org.apache.beehive.controls.api.bean.ControlImplementation; +import org.apache.beehive.controls.api.bean.Extensible; +import org.apache.beehive.controls.api.context.ControlBeanContext; +import org.apache.beehive.controls.api.events.Client; +import org.apache.beehive.controls.api.events.EventHandler; + +import javax.naming.InitialContext; +import javax.naming.NamingException; +import javax.jms.QueueConnectionFactory +import javax.jms.QueueConnection; +import javax.jms.QueueSession; +import javax.jms.QueueSender; +import javax.jms.TopicConnectionFactory +import javax.jms.TopicConnection; +import javax.jms.TopicSession; +import javax.jms.TopicPublisher; +import javax.jms.Message; + +/** + * The JmsMessageControlImpl class is the Control Implementation Class for the JmsMessageControl. + * It implements two basic operations (sendTextMessage and sendObjectMessage) as well as an + * extensibility model that enables custom message formats to be defined and associated with + * extended method signatures. + */ [EMAIL PROTECTED] +public class JmsMessageControlImpl implements JmsMessageControl, Extensible +{ + /** + * The peer BeanContext instance associated with the Control + */ + @Context ControlBeanContext context; + + /** + * The client callback event router for this Control + */ + @Client Callback client; + + /** + * The fields are used to hold transient JMS resources that are acquired and held for + * the resource scope associated with the Control + */ + transient javax.jms.Connection _connection; + transient javax.jms.Session _session; + transient javax.jms.MessageProduction _producer; + + + + /* + * The onAcquire event handler + * This method will be called prior to any operation with a given resource scope. It is + * responsible for obtaining the connection, session, destination, and appropriate + * writer instance, for use within the operation. + */ + @EventHandler(field=âcontextâ, eventSet=ControlBeanContext.Lifecycle.class, eventName=âonAcquireâ) + public void onBeanAcquire() + { + // + // Acquire the property values needed for initialization + // + Destination destProp = (Destination)context.getControlPropertySet(Destination.class); + Connection connProp = (Connection)context.getControlPropertySet(Connection.class); + + try + { + // + // Obtain the JMS Destination instance based upon the Destination property + // + InitialContext jndiContext = new InitialContext(); + _dest = (javax.jms.Destination)initContext.lookup(destProp.name()); + + // + // Obtain Connection, Session, and MessageProducer resources based upon the + // destination type and the values in the Connection PropertySet + // + if (destProp.type() = JmsControl.QUEUE) + { + javax.jms.QueueConnectionFactory connFactory = + (QueueConnectionFactory)jndiContext.lookup(connProp.factoryName()); + _connection = connFactory.createQueueConnection(); + _session = (QueueConnection)_connection).createQueueConnection( + connProp.transacted(), + connProp.acknowledgeMode()); + _producer = (QueueSession)_session).createSender((Queue)_dest); + } + else + { + javax.jms.TopicConnectionFactory connFactory = + (TopicConnectionFactory)jndiContext.lookup(connProp.factoryName()); + _connection = connFactory.createTopicConnection(); + _session = ((TopicConnection)_connection).createTopicConnection( + connProp.transacted(), + connProp.acknowledgeMode()); + _producer = ((TopicSession)_session).createPublisher((Topic)_dest); + + } + } + catch (javax.naming.NamingException ne) + { + throw new ControlException("Unable to locate JNDI object", ne); + } + catch (ClassCastException ce) + { + throw new ControlException("JNDI object did not match expected type", ce); + } + catch (JMSException jmse) + { + throw new ControlException("Unable to acquire JMS resources", jmse); + } + } + + /* + * The onRelease event handler for the associated context + * This method will release all resource acquired by onAcquire. + */ + @EventHandler (field=âcontextâ, eventSet=ControlBeanContext.Lifecycle.class , eventName=âonReleaseâ) + public void onRelease() + { + try + { + if (_producer != null) + { + _producer.close(); + _producer = null; + } + if (_session != null) + { + _session.close(); + _session = null; + } + if (_connection != null) + { + _connection.close(); + _connection = null; + } + } + catch (JMSException jmse) + { + throw new ControlException("Unable to release JMS resource", jmse); + } + } + + /** + * Helper method used to send a message once constructed + */ + private void sendMessage(Message msg) throws JMSException + { + client.onMessage(msg); + if (_producer instanceof java.jms.QueueSender) + ((QueueSender)_producer).send(msg); + else + ((TopicPublisher)_producer).publish(msg); + } + + + /** + * Sends a simple TextMessage to the Controlâs destination + * @param text the contents of the TextMessage + */ + public void sendTextMessage(String text) throws JMSException + { + javax.jms.TextMessage msg = _session.createTextMessage(text); + sendMessage(msg); + } + + /** + * Sends a simple ObjectMessage to the Controlâs destination + * @param object the object to use as the contents of the message + */ + public void sendObjectMessage(java.io.Serializable object) + { + javax.jms.ObjectMessage msg = _session.createObjectMessage(object); + sendMessage(msg); + } + + /** + * Implements the Extensible.invoke() interface for this Control + * This method uses the Message property to determine the type of message to construct, + * and then uses the Body and Property attributes of method parameters to supply message + * content and properties. + */ + public Object invoke(Method m, Object [] args) throws Throwable + { + int bodyIndex = -1; + for (int i= 0; i< args.length; i++) + { + if (context.getParametertPropertySet(m, I, JmsMessageControl.Body.class) != null) + { + bodyIndex = i; + break; + } + } + if (bodyIndex == -1) + throw new ControlException("No @Body argument defined for operation: " + m.getName()); + + // + // Create a message based upon the value of the Message property of the method + // + javax.jms.Message msg = null; + Message msgProp = context.getMethodPropertySet(m.JmsMessageControl.Message.class); + try + { + switch(msgProp.value()) + { + case MessageType.TEXT: + msg = session.createTextMessage((String)args[bodyIndex]); + break; + + case MessageType.OBJECT: + msg = session.createObjectMessage(args[bodyIndex]); + break; + case MessageType.BYTES: + msg = session.createBytesMessage() + msg.writeBytes((byte []) args[bodyIndex]); + break; + } + } + catch (ClassCastException) + { + throw new ControlException("Invalid type for Body parameter", cce); + } + + // + // Now decorate the message with any Property-annotated parameters + // + for (int i= 0; i< args.length; i++) + { + JMSMessageControl.Property prop = + context.getParameterPropertySet(m, i,.JmsMessageControl.Property.class); + if (prop != null) + { + String propName = prop.name(); + if (args[i] instanceof String) + msg.setStringProperty((String)args[i]); + else if (args[i] instanceof Integer) + msg.setStringProperty(((Integer)args[i])intValue()); + else if (args[i] instanceof Short) + msg.setStringProperty(((Short)args[i]).shortValue()); + else if (args[i] instanceof Boolean) + msg.setBooleanProperty(((Boolean)args[i]).booleanValue()); + else if (args[i] instanceof Float) + msg.setFloatProperty(((Float)args[i]).floatValue()); + else if (args[i] instanceof Double) + msg.setDoubleProperty(((Double)args[i]).doubleValue()); + else + msg.setObjectProperty(args[i]); + } + } + + // + // Send it + // + sendMessage(msg); + } +}</source> + </section> + + </body> +</document> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/index.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/index.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/index.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,328 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd";> +<document> + <header> + <title>Introduction to Beehive Page Flows</title> + </header> + <body> + <section id="advantages"> + <title>Why Use Page Flows?</title> + <p>By using page flows, you can avoid making the typical mistakes that often + happen during web application development, by separating presentation, business + logic implementation, and navigational control. In many web applications, + web developers using JSP (or any of the other dynamic web languages such + as ASP or CFM) combine presentation and business logic in their web pages. + </p> + <p>As these applications grow in complexity and are subject to continual change, + this practice leads to expensive, time-consuming maintenance problems, caused + by:</p> + <ul> + <li> + Limited reuse of business logic + </li> + <li> + Cluttered JSP source code + </li> + <li>Unintended exposure of business-logic code to team members who focus + on other aspects of web development, such as content writers and visual + designers</li> + </ul> + <p>Page flows allow you to separate the user interface code from navigational + control and other business logic. User interface code can be placed where + it belongs, in the JSP files. Navigational control can be implemented easily + in a page flow's single controller file, which is the nerve center of your + web application. A controller file is a special Java file that uses a JPF + file extension. Business logic can be implemented in the page controller + file, or in Java controls that you call from JPF files.</p> + <p>The separation of presentation and business logic offers a big advantage + to development teams. For example, you can make site navigation updates + in a single JPF file, instead of having to search through many JSP files + and make multiple updates. In WebLogic Workshop you can as easily navigate + between page flows as between individual JSP pages. This allows you to group + related web pages under one page flow, and create functionally modular web + components. This approach to organizing the entities that comprise web applications + makes it much easier to maintain and enhance web applications by minimizing + the number of files that have to be updated to implement changes, and lowers + the cost of maintaining and enhancing applications.</p> + <p>Another advantage of page flows is that an instance of the page flow controller + class is kept alive on a per-user-session basis while the user is navigating + within the scope of the page flow. This instance ends when the user exits + from the page flow. You can use instance member variables in page flow classes + to hold user session state.</p> + </section> + <section id="work"> + <title>How Does a Page Flow Work?</title> + <p>A page flow is a Java class, called the "controller" class, that + controls the behavior of a web application through the use of specially + designed annotations and methods. The directory that contains the controller + class also includes the JavaServer Pages (JSPs) used in the page flow. For + a JSP to be considered part of a page flow, it must reside within the page + flow directory. The JSP files use special tags which help bind to data and + business logic actions. The action methods in the controller file implement + code that can result in site navigation, passing data, or invoking back-end + business logic via controls. Significantly, the business logic in the controller + class is separate from the presentation code defined in the JSP files.</p> + <p>The overall purpose of a page flow is to provide you with an easy-to-use + framework for building dynamic, sophisticated web applications. WebLogic + Workshop provides graphical and code-level tools to simplify the development + cycle. While page flows give you access to advanced features of J2EE, you + do not have to be a J2EE expert to quickly develop and deploy Java-based + applications built on page flows. Wizards can be used to create different + types of page flows, generating the Java and JSP files that serve as a starting + point for your work. Graphical tools let you draw the relationships between + web components in a controller's Flow View. In Source View, syntax completion, + validation, and other programmer's aids reduce the amount of work required + to get your application running.</p> + <p> + <strong>Note</strong>: WebLogic Workshop's web application + functionality is built on Struts, which is an open-source framework for + building web applications in a J2EE environment.</p> + </section> + <section id="components"> + <title>Components of the Page Flow Programming Model</title> + <p>Page flows implement user interface control logic, and contain:</p> + <ul> + <li>Action Methods</li> + <li>Form Beans</li> + <li>Forward Objects</li> + <li>The <netui...> Tag Library</li> + </ul> + <section id="actionmethods"> + <title>Action Methods</title> + <p>In the controller class, action methods are methods that are annotated with a <code>@JpfAction</code> tag.</p> + <p> + <code> [EMAIL PROTECTED](forwards = { [EMAIL PROTECTED](name="success", path="page_A.jsp") + } + ) + protected Forward begin() + { + return new Forward( "success" ); + }</code> + </p> + <p> Action methods can perform several functions. They can (1) implement navigation + decisions, (2) move data into and out of JSP pages, and (3) invoke back-end + business logic via calls to controls.</p> + </section> + <section id="formbeans"> + <title>Form Beans</title> + <p>Form Beans are Java data structures that correspond to HTML forms. When a user submits data from an HTML form, the data is stored in a Form Bean instance. Once the data is stored in a Form Bean instance, the data is available for processing by the action methods in the controller file. Form Bean instances (containing submitted data) are typically passed as parameters to action methods. + +<code> @JpfAction() + + protected Forward ProcessData( MyFormBean form ) + { + + //Submitted data is processed here... + + }</code></p> +<p> +<code>Form Beans are simple Java classes contained within the controller file. They consist of some number of fields with setter and getter methods associated with those fields. Below is a Form Bean with one field, the String name, and setter and getter methods for that field. Form Bean must extend the class com.bea.wlw.netui.pageflow.FormData. + + public static class MyFormBean extends FormData + { + private String name; + + public void setName(String name) + { + this.name = name; + } + + public String getName() + { + return this.name; + }</code></p> + </section> + <section> + <title>Forward Objects</title> + <p>Forward objects are returned by action methods. They can be used to control navigation and pass data throughout the application.</p> + </section> + <section> + <title>The <netui> Tag Library</title> + <p>The <netui> tag library contains JSP tags specifically designed to work with the controller class. Tags in the library all begin with the prefixes "netui", "netui-databinding", and "netui-template". Some of these tags perform much like familiar HTML tags, while others perform function particular to page flow web applications. The most important feature of the tag library is its ability to "data bind" to data in the controller file. Data binding allows the JSP pages to both read from and write to Java code in the controller class. This is accomplished without placing any Java code on the JSP pages, greatly enhancing the separation of data presentation and data processing.</p> + </section> + </section> + <section> + <title>Example Code</title> + <section> + <title>Navigation</title> + <p>As shown in the Flow View diagram, the page flow class defines an action method named toPageB. This action can be invoked by a link on the JSP page page_A.jsp. + +page_A.jsp + +ÂÂÂÂ<%@ taglib uri="netui-tags-html.tld" prefix="netui"%> + ... + <netui:anchor action="toPageB">Link to page_B.jsp</netui:anchor></p> + +<p>A special JSP tag library named netui-tags-html.tld is referenced. WebLogic Workshop provides this tag library and several others to help you develop dynamic web applications. The <netui:anchor...> tag used here is simply invoking an action (toPageB) with a hyperlink. (For more information about the page flow tag library, see Designing User Interfaces in JSPs.)Â</p> + +<p>In the controller file SimpleNavigationController.jpf, the toPageB action method is defined as follows: + +SimpleNavigationController.jpf + + import com.bea.wlw.netui.pageflow.Forward; + + ... + + [EMAIL PROTECTED](forwards = { + @JpfForward(name="success", path="page_B.jsp") + }) + + public Forward toPageB() + { + return new Forward( "success" ); + }</p> + +<p>When the link on page_A.jsp is clicked, the page flow runtime detects the action and runs the toPageB action method. This action method is coded to return a Forward object which passes the parameter "success". (Notice that this name "success" matches the name on the corresponding action arrow in Flow View.)</p> + +<p>Look at the two @Jpf annotations that appear on the lines above this action method. These annotations are enclosed in Javadoc comments. The @JpfAction tag indicates that the toPageB method is an action method. The @JpfForward tag describes the behavior of that method.</p> + +<p>Putting it all together, a Forward object is returned by an action method. The Forward object passes the string "success", indicating that it should behave according to the directions encoded in the annotation @JpfForward name="success". That annotation's path attribute has the value "page_B.jsp", which causes the page flow controller to load page_B.jsp into the browser.</p> + +<p>The following diagram summarizes the flow in the example:</p> + + + +<p>To change the navigation target of this action method, simply change the value of the path attribute. For example, if you want this action method to navigate to page_C.jsp, you would make the following change to the controller file (no change to the JSP page is necessary). + + + [EMAIL PROTECTED](forwards = { + @JpfForward(name="success", path="page_C.jsp") + }) + + public Forward toPageB() + { + return new Forward( "success" ); + }</p> + +<p>As you will see in later sections, the WebLogic Workshop IDE generates this code for you when you create a new page flow or JSP file from the graphical view. This code generation and subsequent validation of your changes saves you considerable time.</p> + </section> + <section> + <title>Submitting Data</title> +<p>Suppose you want to your web application to collect data from users and then process that data in some way. The following example demonstrates how to set up a data submission process using page flows. The sample code referred to in this example can be found at: </p> + +<p><BEA_HOME>\weblogic90\samples\workshop\SamplesApp\WebApp\handlingData\simpleSubmit\ +</p> +<p>Submitting data is a two step process: (1) the data submitted from a JSP page is loaded into a Form Bean instance and (2) the Form Bean instance is passed to an action method for processing.</p> + + + +<p>Form Beans are simple Java classes with fields and setter and getter methods for accessing those fields. Form Beans classes are contained within the controller file. In most cases, Form Beans are designed to accept data submitted from JSP forms. For example, if a JSP page has input elements for name, eye_color, and height, then the Form Bean will have corresponding fields for name, eye_color, and height. The following example Form Bean can be found in the controller file SimpleSubmitController.jpf. It contains one field, name, and setter and getter methods for that field.</p> + +<p>SimpleSubmitController.jpf + + public class SimpleSubmitController extends PageFlowController + { + + ... + + public static class SubmitNameForm extends FormData + { + private String name; + + public void setName(String name) + { + this.name = name; + } + + public String getName() + { + return this.name; + } + } + }</p> + +<p>The input elements on the JSP page are said to be "data bound" to the fields in the Form Bean. Data binding allows the the data submitted from the JSP page to be loaded into the Form Bean instance. For example, the input element on index.jsp contains a data binding expression that refers to the name field of the Form Bean: {actionForm.name}. The expression "actionForm" refers to the Form Bean SubmitNameForm, the property ".name" refers to the name field of the Form Bean. For detailed information about data binding see Using Data Binding in Page Flows.</p> + +<p>index.jsp</p> + +<p> <netui:form action="SubmitName"> + Name: <netui:textBox dataSource="{actionForm.name}"/> + .... + </netui:form></p> + +<p>Finally the Form Bean instance (carrying the submitted data) is passed to the action method for processing.</p> + + + +<p>@JpfAction(forwards = { + @JpfForward(name="success", path="showName.jsp") + }) + + protected Forward SubmitName(SubmitNameForm form) + { + // + // The data is processed here + // + + return new Forward("success"); + }</p> + +<p>The submitted data can be accessed by calling the getter methods on the Form Bean.</p> + +<p>@JpfAction(forwards = { + @JpfForward(name="success", path="showName.jsp") + }) + protected Forward SubmitName(SubmitNameForm form) + { + if( form.getName() != null ) + // do something here + else + // do something else here + + return new Forward("success"); + }</p> + +<p>By default the Form Bean instance that is passed to the action method exists only as long as the HTTP request. This is called a "request-scoped Form Bean". When the HTTP request is destroyed, the Form Bean instance, along with the user submitted data, is destroyed. As an alternative, you can use a Page Flow-scoped Form Bean, which has a longer life cycle. For details see Form Bean Scopings.</p> + + </section> + <section> + <title>Displaying Data</title> +<p>Suppose that once you have collected data, you want to display it back to the user. The following example shows how to use data binding to display data to the user. The sample code referred to can be found at: </p> + +<p><BEA_HOME>\weblogic81\samples\workshop\SamplesApp\WebApp\handlingData\simpleSubmit\</p> + +<p>Displaying data using data binding requires that (1) the data is located somewhere where it can accessed by the JSP page and (2) the JSP page uses a data binding expression to retrieve the data from that location.</p> + + + +<p>Notice the syntax of data binding expression on the JSP page. (1) It is framed by curley braces, (2) it begins with a data binding context, in this case the request context, and (3) the context is followed by an attribute, in this case "name".</p> + +<p>In the following example, an action method places data on the name attribute of the request object.</p> + +<p>SimpleSubmitController.jpf + + [EMAIL PROTECTED](forwards = { + @JpfForward(name="success", path="showName.jsp") + }) + + protected Forward SubmitName(SubmitNameForm form) + { + getRequest().setAttribute("name", form.getName()); + return new Forward("success"); + }</p> + +<p>After the data has been located on the name attribute of the request object, it is displayed on a JSP page using a data binding expression.</p> + +<p>showName.jsp</p> + +<p> Here is the data you submitted: <netui:label value="{request.name}" /></p> + +<p>Note that the request object has a relatively short life-cycle. When the user makes a new request, by navigating to a new JSP page or invoking another action method, the current request object is destroyed along with the data it contains. If your application requires the data to be more persistent, then you could use a different data binding context, for example the session object or a Page Flow-scoped Form Bean, which both have longer life-cycles. For detailed information about the different data binding contexts available, see Using Data Binding in Page Flows. </p> + </section> + <section> + <title>Connecting to Resources with Controls</title> + <p>[tbd]</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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/sample_controls-blank.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/sample_controls-blank.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/sample_controls-blank.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,40 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v13.dtd";> +<document> + <header> + <title>Control Project Template</title> + </header> + <body> + <section id="intro"> + <title>Introduction</title> +<p>Use the "blank" Control sample (located at <code>BEEHIVE_HOME/samples/controls-blank</code>) as a template for building your own Control projects. + +</p> + +<p>The template contains a basic 'Hello World' control to get you started. Control projects can be archived in a JAR file and then imported into multiple applications. Simply import the JAR archive into the application's WEB-INF/lib directory. </p> + + </section> + <section> + <title>Using the Control Project Template</title> + <p>The following instruction assume that you have completed the basic Beehive set up procedure at <fork href="../setup.html">Set Up the Dev Environment</fork>.</p> + <p>To use the template, copy the contents of <code>BEEHIVE_HOME/samples/controls-blank</code> into your project folder (refered to as <code><Project-Folder></code> below). An Ant build file is included in the control application template, which will compile your control project into a distributable JAR file. +It is important to copy the <em>contents</em> of <code>controls-blank</code> into your project folder, not the <code>controls-blank</code> folder itself. After you have copied the contents of <code>controls-blank</code> into your project folder, the following directory structure should exist:</p> +<source><Project-Folder> + src + build.xml</source> + <p>The following Ant command will compile the control template. </p> +<source> ant + -f <Project-Folder>\build.xml build</source> + + + + <p>This will produce a distributable JAR file at: <code><Project-Folder>/build/mycontrols.jar</code>.</p> + <p>To use the JAR in your other projects (like a web app project or a web service project), copy <code>mycontrols.jar</code> into the project's <code>WEB-INF/lib</code> directory.</p> + </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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/sample_controls-db.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/sample_controls-db.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/sample_controls-db.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,113 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v13.dtd";> +<document> + <header> + <title>Database Control Sample</title> + </header> + <body> + <section> + <title>Control Programming: Simplifying Access to Resources</title> + + <p>A Database control makes it easy to access a relational database from your Java code using SQL commands. The Database control handles the work of connecting to the database, so you donât have to understand JDBC to work with a database.</p> + +<p>All Database controls are subclassed from the DatabaseControl interface. The interface defines methods that Database control instances can call from an application.</p> + +<p>The methods in the Database control execute SQL commands against the database. You can send any SQL command to the database via the Database control, so that you can retrieve data and perform operations like inserts and updates.</p> + +<p>A method on a Database control always has an associated SQL statement, which executes against the database when the method is called. The methodâs @SQL annotation describes the methodâs SQL statement. The methodâs SQL statement may include substitution parameters. These parameters are replaced at runtime with the values that were passed to the method. The names of the substitution parameters in the SQL statement must match those in the method signature, so that the Database control knows which parameter to replace with which value.</p> + +<p>The following example Database control method illustrates using parameter substitution in Database control methods:</p> + +<source> @SQL(statement="INSERT INTO EMPLOYEE " + + "(id, fName, lName, title) " + + "VALUES ({emp.id}, {emp.fName}, {emp.lName}, {emp.title})") + public void insertEmployee(Employee emp) throws SQLException;</source> + +<p>In the example above, the SQL statement includes the substitution {emp.id}, {emp.fName}, ... These map to the various class variables of the "emp" parameter in the insertEmployee method. When the method is invoked, the values of any referenced parameters are substituted in the SQL statement before it is executed. Note that parameter substitution is case sensitive, so parameters mentioned in substitutions must exactly match the spelling and case of the parameters to the method.</p> + +<p>The return type of the database operation is determined by the return type of the Java method. The Database control attempts to format the results in whatever type you have specified for the method to return. A method of a Database control can return a single value, a single row, or multiple rows. </p> + +<p>When your method returns a single value, its return type must be compatible with the value returned from the query. The following example looks up an employee's title.</p> + +<source> @SQL(statement="SELECT title FROM EMPLOYEE WHERE id={id}") + public String getEmployeeTitle(int id) throws SQLException;</source> + +<p>In this example, the title field is of type VARCHAR, so the return value is declared as String. </p> + +<p>When your method returns a single row with multiple fields, its return type can be a user-defined object or a java.util.HashMap object. When the return type is a user-defined object, it must contain members with names that match the names of the columns that will be returned by the query. Because database column names are case-insensitive, the matching names are case-insensitive. The class may also contain other members, members not matching any column names will not be set. The following example declares an Employee class with members corresponding to fields in the Employee table. The findEmployee method returns an object of type Employee:</p> + +<source> @SQL(statement="SELECT * FROM EMPLOYEE WHERE id={id}") + public Employee findEmployee(int id) throws SQLException; + + public class Employee + { + public int id; + public String fName; + public String lName; + public String title; + }</source> + +<p>When your method returns multiple rows from the database, its return type can be an array, a java.util.Iterator, or a java.sql.ResultSet. </p> +<p>When you want to return an Iterator object, you must specify the iteratorElementType element to the @SQL annotation to indicate the underlying type that the Iterator will contain. The following example returns a iterator of all employees sorted by their last names.</p> + +<source> @SQL(statement="SELECT * FROM EMPLOYEE ORDER BY lName", iteratorElementType=Employee.class, maxRows=500) + public Iterator getEmployeesSortedByLastName() throws SQLException;</source> + +<p>You can limit the number of rows returned by setting the maxRows element of the @SQL annotation. This element can protect you from very large resultsets that may be returned by very general queries. The default value of maxRow is 1024.</p> + +<p>The Database Control defines two annotations: SQL and ConnectionDataSource.</p> + +<p>The SQL Annotation specifies the SQL statement and associated attributes that correspond to a method in a Database control.</p> + +<source> public @interface SQL + { + String statement() default ""; + int maxRows() default MAXROWS_ALL; + @AnnotationMemberTypes.Optional + Class iteratorElementType() default UndefinedIteratorType.class; + }</source> + +<p>The "statement" element is required. It specifies the SQL (Structured Query Language) statement that will be executed when the associated Database control method is invoked. The statement may contain substitutions of the form {varName}, where paramName is a parameter of the Database control method (or a member accessible from the parameter).</p> + +<p>The "iteratorElementType" is required if Database control method return type is java.util.Iterator. It specifies the underlying class of the Iterator that will be returned by the Database control method. </p> + +<p>The "maxRows" element is optional. It sets the maximum number of records to be returned by the query. The maxRows element limits the size of all types of data sets, including Arrays, Iterator, ResultSet, etc. The default value of this element is 1024.</p> + +<p>The ConnectionDataSource annotation specifies the data source that the Database control will use to obtain connection. At the time of writing, this has not been fully implemented yet. The Database control currently uses the embedded Derby database driver to obtain connection, and it is expecting the value provided for the "jndiName" element to be a database URL.</p> + +<source> public @interface ConnectionDataSource + { + String jndiName(); // no default ... value is required + }</source> +</section> +<p>The Database control is currently included in the Beehive distribution as a sample control (\samples\controls-db). Building this control with the Ant script provided will create a <code>dbControl.jar</code> in \samples\controls-db\build\. You can start creating your own database control extension by simply including this JAR file in your classpath.</p> + +<section> + <title>The EmployeeWS Sample</title> +<p>Notice that the sample <link href="../wsm/sample_AddressBook.html">EmployeeWS</link> uses this same technique (subclassing DatabaseControl) for database access. The EmployeeWS sample is a database control exposed as a web service. The exposed database control, EmployeeDBControl, is a subclass of DatabaseControl (archived in <code>dbControl.jar</code>).</p> +<source>public interface EmployeeDBControl extends DatabaseControl +{ + ... +} +</source> +<p>The Java source for EmployeeDBControl is available at <code>BEEHIVE_HOME/samples/EmployeeWS/WEB-INF/src/org/apache/beehive/sample/EmployeeDBControl.jcx</code>.</p> +</section> + + + +<section> + <title>Building the Database Control</title> + <p>To build <code>dbControl.jar</code> run the following Ant command:</p> + <p>On Windows:</p> + <p><code>ant -f %BEEHIVE_HOME%\samples\controls-db\build.xml build</code>.</p> + <p>On Unix:</p> + <p><code>ant -f $BEEHIVE_HOME\samples\controls-db\build.xml build</code>.</p> + <p>This produces the file <code>dbControl.jar</code> in the directory <code>BEEHIVE_HOME/samples/controls-db/build</code>.</p> + <p></p> +</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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/tutorial_controls.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/tutorial_controls.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/tutorial_controls.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,264 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v13.dtd";> +<document> + <header> + <title>Beehive Controls Tutorial</title> + </header> + <body> + <section id="intro"> + <title>Introduction</title> + <section> + <title>Tutorial Goals</title> + <p>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 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> + <section> + <title>Assumptions Made in This Tutorial</title> + <p>The following tutorial assumes that you are working on a Windows machine. But, with a little common sense, it is easy to run through the tutorial on a Unix machine. For example, when the tutorial tells you to run the file beehiveUser.cmd, Unix users should run the file beehiveUser.sh.</p> + </section> + </section> + <section id="step1"> + <title>Step 1: Begin the Page Flow Tutorial</title> + <section> + <title>To Set up the Development Environment</title> + <p>Follow the setup directions at <fork href="../setup.html">Beehive Installation and Setup</fork></p> + <p>After completing the instructions, leave the command shell open to use throughout this tutorial.</p> + </section> + + <section> + <title>Add a Manager Role to Tomcat</title> + <p>Adding the manager role to Tomcat server allows you to run deploy related targets in the Ant file <code>runTomcat.xml</code>. This file is provided as a convenience for managing the Tomcat server.</p> + <p>Edit the file <code>CATALINA_HOME/conf/tomcat-users.xml</code> so it appears as follows. Code to add appears in bold type.</p> + <source><?xml version='1.0' encoding='utf-8'?> +<tomcat-users> + <role rolename="tomcat"/> + <role rolename="role1"/> + <strong><role rolename="manager"/></strong> + <user username="tomcat" password="tomcat" roles="tomcat"/> + <user username="role1" password="tomcat" roles="role1"/> + <user username="both" password="tomcat" roles="tomcat,role1"/> + <strong><user username="manager" password="manager" roles="manager"/></strong> +</tomcat-users></source> + </section> + <section> + <title>To Start the Tomcat Server</title> + <p>At the command prompt, enter:</p> + <source>%CATALINA_HOME%\bin\startup.bat</source> + </section> + </section> + <section id="step_2"> + <title>Step 2: Create Control Implementation and Interface Files</title> + <section> + <title>Introduction</title> + <p>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.</p> + </section> + <section> + <title>Make a Project Folder</title> + <p>On your C: drive, create a directory called <code>beehive_projects</code>.</p> + <p>In the <code>beehive_projects</code> directory, create a directory called control_tutorial.</p> + <p>Before proceeding, confirm that the following directory structure exists:</p> + <source>C: + beehive_projects + control_tutorial</source> + </section> + <section> + <title>To Add Beehive Runtime JARs to Your Application.</title> + <p>In this step you will assemble the runtime resources for your Control. Most of these files are included in the WEB-INF directory. It includes JAR files with the JSP tag handler classes, the Controls runtime JAR, etc. <!--[tbd: for a complete list see...]--></p> + <p>Using the command shell opened in the previous step, at the command prompt, enter: </p> + <source> ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=C:\beehive_projects\control_tutorial + deploy.beehive.webapp.runtime </source> + </section> + <section> + <title>To Create the Control's Implementation File</title> + <p>In this step you will create the implementation file for your Beehive Control. This is a Java class (although it has the JCS file extension) that contains the bulk of your Control's working code.</p> + <p>In the directory <code>C:/beehive_projects/control_tutorial/WEB-INF</code>, create a directory called <code>src</code>.</p> + <p>In the directory <code>C:/beehive_projects/webapps/control_tutorial/WEB-INF/src</code>, create a directory called <code>hellocontrol</code>.</p> + <p>In the directory <code>C:/beehive_projects/webapps/control_tutorial/WEB-INF/src/hellocontrol</code>, create a file called <code>HelloImpl.jcs</code>.</p> + <p>Before proceeding, confirm that the following directory structure exists:</p> + <source>C: + beehive_projects + control_tutorial + WEB-INF + src + hellocontrol + HelloImpl.jcs</source> + <p>In a text editor (or your IDE of choice), open the file HelloImpl.jcs.</p> + <p>Edit HelloImpl.jcs so it appears as follows.</p> + <source><![CDATA[package hellocontrol; + +import org.apache.beehive.controls.api.bean.*; + [EMAIL PROTECTED] +public class HelloImpl implements Hello +{ + public String hello() + { + return "Hello, World!"; + } +}]]></source> + <p>Save and close <code>HelloImpl.jcs</code>.</p> + </section> + <section> + <title>To Create the Control's Interface File</title> + <p>The interface file is a JAVA file that defines the public face of your control. <!--[tbd]--> + </p> + <p>In the directory <code>C:/beehive_projects/control_tutorial/WEB-INF/src/hellocontrol</code>, create a file named <code>Hello.java</code>.</p> + <p>Edit Hello.java so it looks like the following.</p> + <source><![CDATA[package hellocontrol; + +import org.apache.beehive.controls.api.bean.ControlInterface; + [EMAIL PROTECTED] +public interface Hello +{ + public String hello(); +}]]></source> + </section> + <section> + <title>To Create a JSP Page to Test the Control</title> + <p>To test your Beehive 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. + </p> + <p>In the directory <code>C:/beehive_projects/control_tutorial</code>, create a file named <code>hello.jsp</code>. + </p> + <p>Edit hello.jsp so it appears as follows.</p> + <source><![CDATA[<%@ page language="java" contentType="text/html;charset=UTF-8"%> +<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0"; prefix="netui"%> +<netui:html> + <head> + <title>Control Tutorial Test Page</title> + </head> + <netui:body> + <jsp:useBean class="hellocontrol.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>]]></source> + </section> + <section> + <title>To Compile and Deploy the Control</title> + <p>You are now ready to compile the control.</p> + <p>At the command prompt, enter:</p> + <source> ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=C:\beehive_projects\control_tutorial + -Dcontext.path=control_tutorial + build.webapp + deploy</source> + <p>If the application is already deployed on Tomcat (which may happen if this is your second time executing the tutorial), use the command below:</p> + <source> ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=C:\beehive_projects\control_tutorial + -Dcontext.path=control_tutorial + undeploy + build.webapp + deploy</source> + </section> + <section> + <title>To Test the Control</title> + <p>Open a web browser and enter the following in the address bar: <fork href="http://localhost:8080/control_tutorial/hello.jsp";>http://localhost:8080/control_tutorial/hello.jsp</fork> + </p> + <p>You will be directed to the index.jsp page.</p> + <p>Note the message on the page: "Hello, World!"</p> + <p>This message is provided by the Hello control.</p> + </section> + </section> + <section> + <title>Step 3: Add a Parameterized Method to the Control</title> + <section> + <title>To edit the Interface and Implementation Files</title> + <p>Edit <code>HelloImpl.jcs</code> so it appears as follows. Code to add appears in bold type.</p> +<source>package hellocontrol; + +import org.apache.beehive.controls.api.bean.*; + [EMAIL PROTECTED] +public class HelloImpl implements Hello +{ + public String hello() + { + return "Hello, World!"; + } + + <strong>public String helloParam( String name ) + { + return "Hello, " + name + "!"; + }</strong> +}</source> +<p>Save an close <code>HelloImpl.jcs</code></p> +<p>Edit <code>Hello.java</code> so it appears as follows. Code to add appears in bold type.</p> +<source>package hellocontrol; + +import org.apache.beehive.controls.api.bean.ControlInterface; + [EMAIL PROTECTED] +public interface Hello +{ + public String hello(); + + <strong>public String helloParam( String name );</strong> +}</source> + </section> + +<section> + <title>To Edit the Test JSP Page</title> + <p>Edit <code>hello.jsp</code> so it appears as follows. Code to add appears in bold type.</p> + <source><%@ page language="java" contentType="text/html;charset=UTF-8"%> +<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0"; prefix="netui"%> +<netui:html> + <head> + <title>Control Tutorial Test Page</title> + </head> + <netui:body> + <jsp:useBean class="hellocontrol.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> + <strong><p> + Response from the helloParam() method on the Hello Control: <strong> <%= helloBean.helloParam("Moon") %> </strong> + </p></strong> + </netui:body> +</netui:html></source> + <p>Save and close <code>hello.jsp</code></p> +</section> +<section> + <title>To Compile and Redeploy the Control</title> +<p>Compile and redeploy the control with the following And command:</p> + + <source> ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=C:\beehive_projects\control_tutorial + -Dcontext.path=control_tutorial + undeploy + build.webapp + deploy</source> +</section> + + <section> + <title>To Test the Control</title> + <p>Open a web browser and enter the following in the address bar: <fork href="http://localhost:8080/control_tutorial/hello.jsp";>http://localhost:8080/control_tutorial/hello.jsp</fork> + </p> + <p>You will be directed to the index.jsp page.</p> + <p>Note the messages on the page: "Hello, World!" and "Hello, Moon!"</p> + <p>These messages are provided by the Hello control.</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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/downloads.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/downloads.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/downloads.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,50 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd"> + +<document> + +<header> + <title>Apache Beehive - Downloads</title> +</header> + +<body> + +<section> + <title>Beehive V1 Alpha Binary Distribution</title> + <p>The Beehive 1.0 alpha binary distribution is available for download at + <fork href="http://cvs.apache.org/dist/incubator/beehive/v1.0-alpha/bin/";>http://cvs.apache.org/dist/incubator/beehive/v1.0-alpha/bin/</fork>. + This distribution is an <em>alpha</em> release and is not intended for creating production-level applications.</p> +</section> + +<section> + + +<title>Daily Drops</title> + <p>Beehive is still rather new, so we don't have daily drops yet. We are currently working + on getting some form of daily builds. When that happens, there will be a place to download both the source and binary distributions for + the most recent daily build.<br /> For now, if you want source, you can either download a recent snapshot + of source or get it from the Subversion repository (directions below). Once you've obtained a copy + of the source from an archive or from SVN, simply follow the instructions in BUILDING.txt. You can also roll your own distributions + using the build.dist target and then create archives using the build.dist.archives target. + <br /><br /></p> + </section> + +<section> + <title>Getting Source from SVN</title> + <ol> + <li>Download Subversion from <link href="http://subversion.tigris.org/";>http://subversion.tigris.org/ </link></li> + <li>In the specified directory say "beehive" run the svn client <br /> + <code>svn checkout http://svn.apache.org/repos/asf/incubator/beehive/trunk/</code><br /> + Note: If you're a user who has issues with proxies or firewalls, https can be used instead of http for Subversion checkout.</li> + </ol> +</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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/faq.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/faq.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/faq.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,60 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd"> + +<document> + +<header> + <title>Apache Beehive FAQ</title> +</header> + +<body> + +<section> + <title>Frequently_Asked_Questions</title> + <p><strong>General</strong></p> + <ol> + <li><link href="#what-is">What is Beehive?</link></li> + <li><link href="#annotations">What are annotations?</link></li> + <li><link href="#controls">What are controls? </link></li> + <li><link href="#commons_att">Does Beehive Support Commons Attributes? </link></li> + </ol> +</section> + +<section> + <title>General</title> + <dl> + <dt>What is Beehive?</dt> + <dd><anchor id="what-is" /> Beehive is a programming model built on J2EE that is meant to simplify + building Web Applications. See the <link href="index.html">overview</link> for more info.</dd> + </dl> + <dl> + <dt>What are annotations?</dt> + <dd><anchor id="annotations" /> Annotations are a new part of the Java language that are being introduced + in JDK 1.5. They allow you to add metadata to objects that live outside + of ordinary programmatic flow control. These are used for setting properties + on components that the container is then able to make sense of. For + more information on annotation in java see <fork href="http://jcp.org/en/jsr/detail?id=175";>JSR 175</fork></dd> + </dl> + <dl> + <dt>What are controls?</dt> + <dd><anchor id="controls" /> Controls are the new component model in Beehive. They are based on + regular JavaBeans, with an enhanced authoring model, an extensibility + model, and a configuration model using JSR 175 annotations. To find + out more about controls look at + <link href="controls/controlsOverview.html">Controls Overview</link>.</dd> + </dl> + <dl> + <dt>Does Beehive Support Commons Attributes?</dt> + <dd><anchor id="commons_att" />Since Beehive is depends on JDK1.5, which already contains support for JSR 175 annotations, support for commons-attributes is not a goal for Beehive.</dd> + </dl> + </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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/glossary.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/glossary.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/glossary.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,59 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v13.dtd";> +<document> + <header> + <title>Glossary of Terms</title> + </header> + <body> + <section> + <title>Terms</title> + <p id="bee_control">Beehive Control -- Beehive Controls are designed to make it easier to integrate complex resources into your Java application. For example, the A Beehive Control consists of two JAVA files: a Control implementation file, and a Control interface file. </p> + <p>Contoller file</p> + <p>Contoller implementation</p> + <p>Contoller interface</p> + <p>Contoller file</p> + <p>Data Binding</p> + <p>Form Bean -- Typically, a Form Bean is a server-side representation of a HTML <netui:form> tag. Form Beans follow ordinary Java Bean syntax: each Form Bean is a class consisting of any number of members, each member having a setter and a getter method + associated with it. Form Beans must extend the class org.apache.beehive.netui.pageflow.FormData. The Sample Form Bean below has two members, each member has a getter and setter method associated with it.</p> + <source><![CDATA[ + public static class ProfileFormBean extends FormData + { + private int age; + + private String name; + + public void setAge(int age) + { + this.age = age; + } + + public int getAge() + { + return this.age; + } + + public void setName(String name) + { + this.name = name; + } + + public String getName() + { + return this.name; + } + } + ]]></source> + <p>Form Beans are most often used to pick up data that is submitted from a <netui:form> tag, or incoming data from a back-end resource. Once the data has been picked up by a Form Bean instance, it is then passed to an Action method.</p> + <p>JWS</p> + <p>JPF</p> + <p>JCS</p> + <p><netui> tag library</p> + <p>Page Flow</p> + </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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/index.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/index.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/index.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,82 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd"> +<document> + <header> + <title>The Apache Beehive Project</title> + </header> + <body> + <!-- + Beehive + Welcome<should link to the HTML page created from Welcome.doc> + License<should link to http://www.apache.org/licenses/LICENSE-2.0> + + Documentation + FAQ<should link to the HTML page created from FAQ.doc> + Controls Overview<should link to Kyle's control Overview> + Controls Programming<should link to Kyle's Controls programming pdf> + Web Services (JSR 181)<should link to http://jcp.org/en/jsr/detail?id=181> + + Contributing + Mailing Lists<should link to HTML Page created from MailingLists.doc> + Contributers<should link to HTML Page created from Contributers.doc> + --> + <section> + <title>Beehive releases a V1 Alpha</title> + <p>Yes. That's right. The Beehive team released a V1 alpha. We'd love it if you'd <link href="downloads.html">give it a whirl</link>!</p> + </section> + <section> + <title>Introduction</title> + <anchor id="Introduction"/> + <p> Welcome to Beehive! Our goal is to make J2EE programming easier + by building a simple object model on J2EE and Struts. Using + the new JSR-175 and JSR-181 metadata annotations Beehive reduces the coding + necessary for J2EE. The initial Beehive project has three pieces.</p> + <ul> + <li>NetUI PageFlows – A web application framework built on top of Struts allowing easier + tooling as well as automatic updating of Struts configuration files with the + use of metadata.</li> + <li> Controls – Lightweight component framework that + helps programmers build components that incorporate metadata into their + programming model. This project comes with a few pre-made controls + as well, for example, see the <link href="controls/sample_controls-db.html">Database Control Sample</link>.</li> + <li>Web Services – An Implementation of JSR-181, + an annotation driven programming model for web services.</li> + </ul> + </section> + <section> + <title>Downloads</title> + <anchor id="Downloads"/> + <p> See <link href="downloads.html">downloads</link> + </p> + </section> + <section> + <title>News</title> + <anchor id="News"/> + <ul> + <li>Beehive now has a <fork href="http://wiki.apache.org/beehive";>wiki</fork>.</li> + <li>File bugs or feature requests in <fork href="http://nagoya.apache.org/jira/secure/BrowseProject.jspa?id=10570";>jira</fork> for Beehive.</li> + <li><fork href="http://www.eclipse.org/pollinate/";>Pollinate</fork> is an Eclipse technology project building an IDE + for the Beehive Framework. + <ul> + <li>Pollinate development is underway and some tools are available now.</li> + <li>pollinate-dev mailing list: [EMAIL PROTECTED], <fork href="http://dev.eclipse.org/mailman/listinfo/pollinate-dev";>http://dev.eclipse.org/mailman/listinfo/pollinate-dev</fork></li> + </ul> + </li> + <li>Would you like to contribute? Subscribe now to the -dev, -user or -commits mailing lists for Beehive. See the <link href="mailinglists.html">Mailing Lists</link> for subscription and archive infomation.</li> + </ul> + </section> + <section> + <title>Get Involved</title> + <p> + <link href="mailinglists.html">Mailing Lists</link> + <br/> + <link href="contributors.html">Contributors</link> + </p> + </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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/jpetstore.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/jpetstore.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/jpetstore.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,191 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v13.dtd";> +<document> + <header> + <title>Beehive Sample: Petstore</title> + </header> + <body> + <section> + <title>Introduction</title> + <p>The Petstore sample demonstrates how to integrate all three Beehive technologies (Page Flows, Controls and Web Services) in one application.</p> + <p>The Page Flows provide customers with web access to the Petstore. There are separate Page Flows for different customer activities: the 'shop' Page Flow (located at: <code>petstoreWeb/shop/</code>) lets users browse the catalog of pets, the 'checkout' Page Flow (petstoreWeb/checkout) lets users purchase selected items from a shopping cart, etc.</p> + <p>The Web Service provides employee access to the Petstore. Through the web service (located at <code>petstoreWeb/WEB-INF/src/PetstoreInventoryManager.jws</code>) employees can update the current inventory and prices displayed to customers through the web site. A Swing client for the web service is provided in the sample <link href="http://incubator.apache.org/beehive/wsm/sample_Dashboard.html";>Petstore Dashboard</link>. </p> + <p>Most of the Page Flows have associated Control files (located at: <code>petstoreWeb/WEB-INF/src/org/apache/beehive/samples/petstore/controls/</code>). The Controls handle the backend data traffic and encupsulate the operations of the web application, such as retrieving data from a database and handling user orders.</p> + </section> + <section> + <title>Petstore Directory Structure</title> + <p>The table below describes the functions of the most important files in the Petstore web application.</p> + <table> + <tr> + <th>Directory</th> + <th>Description</th> + </tr> + <tr> + <td>petstoreWeb</td> + <td/> + </tr> + <tr> + <td> account</td> + <td>Page Flow (=Controller.jpf + JSP files) user interface for managing user accounts.</td> + </tr> + <tr> + <td> auth</td> + <td>Page Flow user interface for managing login and logout.</td> + </tr> + <tr> + <td> checkout</td> + <td>Page Flow user interface for managing the shopping cart.</td> + </tr> + <tr> + <td> search</td> + <td>Page Flow user interface for searching the Petstore.</td> + </tr> + <tr> + <td> shop</td> + <td>Page Flow user interface for browsing the catalogue of pets.</td> + </tr> + <tr> + <td> site</td> + <td>Contains the Petstore "skin", including the CSS file, HTML frameset, and template file.</td> + </tr> + <tr> + <td> webappRoot</td> + <td><!--[todo]--></td> + </tr> + <tr> + <td> WEB-INF</td> + <td>Contains configuration files for deployment, validation, and security (web.xml).</td> + </tr> + <tr> + <td> lib</td> + <td>JAR resources</td> + </tr> + <tr> + <td> lib/PetstoreInventoryManager.jws</td> + <td>Web service for employee access to the store</td> + </tr> + <tr> + <td> src/.../controls</td> + <td>Beehive Controls encapsulating different functionalities, including handling user account data, catalogue data, and order processing.</td> + </tr> + <tr> + <td> src/.../forms</td> + <td>Form Beans: each form bean is a server-side representation of an HTML form appearing in the user interface.</td> + </tr> + <tr> + <td> src/.../model</td> + <td>Java object classes used by the Controls.</td> + </tr> + </table> + </section> + <section> + <title>Running the PetStore Sample on Tomcat 5</title> + <section> + <title>Requirements</title> + <p>Beehive requires the following software to build and deploy +the petstore: +</p> + <ul> + <li>J2SE 5.0</li> + <li>Ant 1.6.2</li> + <li>Tomcat 5.x</li> + </ul> + </section> + <section> + <title>Setup</title> + <p>In the descriptions below, <code>BEEHIVE_HOME</code> refers to the root of the +Beehive distribution. (The Beehive binary distribution can be downloaded from <fork href="http://cvs.apache.org/dist/incubator/beehive/v1.0-alpha/bin/";>http://cvs.apache.org/dist/incubator/beehive/v1.0-alpha/bin/</fork>.) For example, if Beehive is installed in: + +</p> + <source> c:\java\beehive-0.3alpha +</source> + <p>the value of BEEHIVE_HOME would be: +</p> + <source> %BEEHIVE_HOME%=c:\java\beehive-0.3alpha +</source> + <p>Now, modify and run <code>BEEHIVE_HOME/beehiveUser.cmd</code> to initialize your +shell with some required environment variables including: +</p> + <ul> + <li> + <code>BEEHIVE_HOME</code> + </li> + <li> + <code>JAVA_HOME</code> + </li> + <li> + <code>ANT_HOME</code> + </li> + <li> + <code>CATALINA_HOME</code> + </li> + </ul> + <p>Running <code>beehiveUser.cmd</code> will also add Java and Ant to your PATH. +</p> + <p> +</p> + </section> + <section> + <title>(Optional) Copy the Petstore Application to a Project Folder</title> + <p>If you want to keep your Beehive distribution directory pristine, you might consider copying the <code>petstoreWeb</code> folder to another location before proceeding. The following instructions assume that you have copied the <code>petstoreWeb</code> folder into the directory <code>C:/beehive_projects</code>.</p> + </section> + <section> + <title>Copy the Runtime Resources and Compile +</title> + <p>To copy the runtime JARs into the application source and compile, run the following target: +</p> + <source>ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=C:/beehive_projects/petstoreWeb + deploy.beehive.webapp.runtime + build.webapp</source> + <p>This will copy the Beehive webapp runtime JARs into </p> + <source> C:/beehive_projects/petstoreWeb/WEB-INF/lib</source> + <p>and run the Beehive webapp build process on the petstoreWeb application.</p> + </section> + <section> + <title>Start Tomcat</title> + <p>To start Tomcat, run the following command:</p> + <source>%CATALINA_HOME%\bin\startup.bat</source> + <p>You can also start Tomcat by running the following Ant command, provided in the buildWebapp.xml file:</p> + <source>ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml start</source> + <p><strong>Note:</strong> if you use the second of these methods for starting Tomcat, you will have to enter Ctrl+C into the command shell to enter any further commands.</p> + </section> + <section> + <title>Deploying to Tomcat and Running +</title> + <p>Petstore can be deployed to a running version of Tomcat in one +of two ways:</p> + <p>1) copy <code>BEEHIVE_HOME/samples/petstoreWeb/</code> to <code>CATALINA_HOME/webapps</code> + </p> + <p>This will cause Tomcat to automatically deploy the webapp. +</p> + <p>2) Use Beehive's deploy Ant target to deploy the Petstore to Tomcat. +</p> + <p>This requires that the "manager" role be defined in +<code>CATALINA_HOME/conf/tomcat-users.xml</code> with a username / password of +"manager" / "manager". +</p> + <p>Then, run the Ant command: +</p> + <source>ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml + deploy + -Dwebapp.dir=C:\beehive_projects\petstoreWeb + -Dcontext.path=petstoreWeb</source> + <p>If petstoreWeb is already deployed on the server, run the undeploy target first.</p> + <source>ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + undeploy + -Dwebapp.dir=C:\beehive_projects\petstoreWeb + -Dcontext.path=petstoreWeb</source> + <p>To see the running application, visit the URL: +</p> + <p> <link href=" http://localhost:8080/petstoreWeb/Controller.jpf";>http://localhost:8080/petstoreWeb/Controller.jpf</link></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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/license.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/license.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/license.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,20 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd"> + +<document> + +<header> + <title>The Apache License</title> +</header> + +<body> + <p> See the <fork href="http://www.apache.org/licenses/LICENSE-2.0";>License</fork> for license infomation.</p> +</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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/mailinglists.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/mailinglists.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/mailinglists.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,50 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd"> + +<document> + +<header> + <title>Apache Beehive Project</title> +</header> + +<body> + + <section> + <title>Mailing Lists</title> + <p>Use the links below to send mail to, subscribe, unsubscribe or check the archives of the Beehive mailing lists. + Subcribing and unsubscribing is performed by simply sending a blank email to applicable address (as linked below). + <br/><br/></p> + <table> + <tr> + <td><link href="mailto:[email protected]";> Beehive Users List</link></td> + <td><link href="mailto:[EMAIL PROTECTED]"> Subscribe</link></td> + <td><link href="mailto:[EMAIL PROTECTED]"> Unsubscribe</link></td> + <td><fork href="http://nagoya.apache.org/eyebrowse/[EMAIL PROTECTED]"> Archives</fork></td> + </tr> + <tr> + <td><link href="mailto:[email protected]";> Beehive Developer List</link></td> + <td><link href="mailto:[EMAIL PROTECTED]"> Subscribe</link></td> + <td><link href="mailto:[EMAIL PROTECTED]"> Unsubscribe</link></td> + <td><fork href="http://nagoya.apache.org/eyebrowse/[EMAIL PROTECTED]"> Archives</fork></td> + </tr> + <tr> + <td><link href="mailto:[email protected]";> Beehive SVN/Wiki Change List</link></td> + <td><link href="mailto:[EMAIL PROTECTED]"> Subscribe</link></td> + <td><link href="mailto:[EMAIL PROTECTED]"> Unsubscribe</link></td> + <td><fork href="http://nagoya.apache.org/eyebrowse/[EMAIL PROTECTED]"> Archives</fork></td> + </tr> + <tr> + <td><link href="mailto:[EMAIL PROTECTED]"> Beehive PPMC List</link></td> + </tr> + </table> + </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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/config/netui-config.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/config/netui-config.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/config/netui-config.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,30 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v13.dtd";> +<document> + <header> + <title>netui-config.xml</title> + </header> + <body> +<p>The netui-config.xml file, which resides in the web application's WEB-INF directory, contains webapp-wide configuration settings for all Page Flows in the web app. Descriptions for each element in the configuration file appear below.</p> +<section> + <title>Action interceptors</title> +<p><strong><pageflow-action-interceptors></strong></p> +<p>If you want to be notified before every action that's run in the webapp, you configure one of these. A simple example of this is monitoring infrastructure that keeps track of a count of actions raised -- you can register an interceptor that runs the counting code before going to any action. A more complex example is an interceptor that *redirects* you to another page flow before allowing you to go to the current one; for instance, it might take you to a nested page flow that asks you to fill out a "satisfaction survey" before sending you to the destination page flow.</p> +</section> +<section> + <title>Handlers</title> +<p><strong><pageflow-handlers></strong></p> +<p>These settings let you override base framework behavior. A good example is the LoginHandler. By default, we use standard Servlet APIs to see if you're logged in, and we use some server-specific APIs to actually log you in when login() is called inside a page flow. If you want to replace this behavior with your own login scheme (which may look at a User database table for login information), you can provide your own LoginHandler that defines methods like login() and isUserInRole().</p> +</section> +<section> + <title>PageFlow Config</title> + <p><strong><pageflow-config></strong></p> +<p>This is just the place for settings that configure the page flow runtime across the webapp. If you want to disable file-upload, for instance, you set the multipart-handler to "none". There will be more settings here soon.</p> +</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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/guide.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/guide.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/guide.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,248 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v13.dtd";> +<document> + <header> + <title>Page Flow Users Guide</title> + </header> + <body> + <section id="intro"> + <title>Advantages of Programming with Page Flows</title> + <p>Page Flows make building Java web applications easy and intuitive. When programming with Page Flows, the developer writes Java files and JSP pages--that's it. There is very little occasion to work with configuration files, or other components. Page Flow programming is not only simple, it is also excells at separating the presentation logic from the data processing logic. This results in uncluttered JSP code which is easy to understand and edit. Moreover, many of the most difficult programming tasks, such as security and validation, are handled with a simple declarative programming model using Java annotations.</p> + </section> + <section> + <title>How Do Page Flows Work?</title> + <p>A Page Flow consists of a single directory containing a Java class, called the "Controller", and any number of JSP pages. + The role of the JSP pages is to present a visual interface for users of the web application. The role of the Controller file is to coordinate all of the things that can happen when a user visits a web site. These duties include: handling user requests, fashioning responses to user requests, preserving session state, and coordinating back-end resources (such as databases and web services).</p> + <p>The JSP files use special tags (the "<netui>" tags) and databinding expressions which bind the user interface to objects and actions in the Controller file. + </p> + <p>tbd: need diagram here</p> + <p>The action methods in the controller file implement code that can result in site navigation, passing data, or invoking back-end business logic via controls. + Significantly, the business logic in the controller class is separate from the presentation code defined in the JSP files. + The overall purpose of a page flow is to provide you with an easy-to-use framework for building dynamic, sophisticated web applications. + While page flows give you access to advanced features of J2EE, you do not have to be a J2EE expert to quickly develop and deploy Java-based applications built on page flows.</p> + <p>The programming model: annotations, data binding expressions, <netui> tags, etc.</p> + </section> + <section id="nav"> + <title>Navigation</title> + <p> + <strong>Introduction</strong> + </p> + <p>Suppose you have two JSP pages, pageA.jsp and pageB.jsp. Also, suppose you want to place a link on pageA, that will navigate the user to pageB.</p> + <p>One solution would be to place an HTML anchor tag (<a>) on pageA that links to pageB. But what if you had dozens of pages that needed to link to pageB? You could repeat the anchor tag solution a dozen times, by placing an anchor tag on each page that required a link to pageB. But this solution becomes cumbersome if you ever need to edit those links. At some point in the future, you may want to change those links, so that they navigate to another page, say to pageC. But this would require sifting through all of your web site's JSP pages for anchor tags to edit.</p> + <p>Page Flows solve this problem by placing navigational control within a single file: the Controller file (=JPF file). Methods within the Controller file decide the target page, whether it is pageB, pageC, or somewhere else. The job of the JSP page is to invoke the method, not to directly link to another JSP page. The work of navigation in a Page Flow breaks down to a two step process: (1) The JSP page invokes a method in the Controller file, then (2) the method navigates the user to the target page.</p> + <p> + <strong>How the Code Works</strong> + </p> + <p>Methods in the Controller file are invoked through specially designed JSP tags, called "netui" tags. These tags appear with the prefix <strong><netui:></strong>. (Tags with the <netui:> reference the netui-tags-html.tld tag library.) Neuti tags like <neuti:anchor>, <netui:button>, and <netui:imageButton> are all capable of invoking methods in the Controller file. The method to invoke is specified by the tag's <code>action</code> attribute. For example, the following <netui:anchor> tag invokes the <code>toPageB</code> method by referencing the method in it's <code>action</code> attribute.</p> + <p> + <strong>pageA.jsp</strong> + </p> + <source> + <!-- Import the netui-tags-html.tld tag library --> + <%@ taglib uri="netui-tags-html.tld" prefix="netui"%> + ... + <!-- Render a link that invokes the toPageB method --> + <netui:anchor <strong>action="toPageB"</strong>>Link to page_B.jsp</netui:anchor> +</source> +<!-- <p>(When pageA.jsp is viewed in a broswer, the <netui:anchor> tag is rendered as ordinary HTML, with associated JavaScript which handles the invocation.... [todo] )</p>--> + <p>Suppose the link above is clicked. When clicked, the following method, <code>toPageB</code>, is invoked.</p> + <p>The method below, when invoked, navigates the user to pageB.jsp. The code within the method body is very simple: upon invocation, the method immediately returns a Forward object, with the String parameter "success". The code <em>above</em> the method does the real work of determining the navigational target. The code above the method consists of two metadata annotations. "Metadata" means that the annotation configures or sets a property on some part of the Java code. In the example below, the @Jpf.Action annotation makes the method available to invocation (by netui tags), while the @Jpf.Forward annotation configures the navigation information. In the this case the method it configured to navigate to pageB.jsp whenever it is invoked. </p> + <p> + <strong>Controller.jpf</strong> + </p> + <source> +import org.apache.beehive.netui.pageflow.Forward; +... + @Jpf.Action( + forwards = { + @Jpf.Forward(name = "<strong>success</strong>", path = "<strong>pageB.jsp</strong>") + } + ) + protected Forward navigate() + { + return new Forward("success"); + }</source> +<!-- <p>Metadata annotations are typically compiled into XML configuration files, or some other post-compilation artifact. Sometimes the artifacts are very complex, as in the case of the @WebService annotation. But in other case the post-compilation artifact is simple: for example, the @jpf:forward annotation compiles into an entry in the [todo] configuration file.</p> + <p>The first annotation, <code>@jpf:action</code>, declares that method is an Action method. Action methods are ...[todo]</p> + <p>The second annotation, <code>@jpf:forward</code>, configures the [todo]. As a result, at runtime, when the toPageB method is invoked (say by the clicking of a <netui:anchor> tag), the [todo] configuration file is consulted, and the user is navigated to pageB.jsp.</p> +--> + <p> + <strong>Changing the Navigation Target</strong> + </p> + <p>To change the navigation target of this action method, simply change the value of the path attribute. For example, if you want this action method to navigate to pageC.jsp, you would make the following change to the controller file (no change to the JSP page is necessary).</p> + <source> + @Jpf.Action( + forwards = { + @Jpf.Forward(name = "success", path = "<strong>pageC.jsp</strong>") + } + ) + protected Forward navigate() + { + return new Forward("success"); + }</source> + <p> + <strong>Conditional Navigation</strong> + </p> + <p>By placing navigational control in the Controller file, you can control conditional navigation.</p> + <p>The following example is from the Petstore sample. The <code>begin</code> method checks to see if the user is logged in or not, and navigates the user appropriately.</p> + <p> + <strong> + <code>beehive/trunk/samples/petstoreWeb/Controller.jpf</code> + </strong> + </p> + <source> + @Jpf.Action( + forwards = { + @Jpf.Forward(name = "shop", path = "/shop/Controller.jpf"), + @Jpf.Forward(name = "index", path = "/index.jsp") + } + ) + protected Forward begin() + { + if (_sharedFlow.isUserLoggedIn()) + return new Forward("shop"); + else return new Forward("index"); + } +</source> + <p> +Putting it all together, a Forward object is returned by an action method. The Forward object passes the string "success", indicating that it should behave according to the directions encoded in the annotation @jpf:forward name="success". That annotation's path attribute has the value "page_B.jsp", which causes the page flow controller to load page_B.jsp into the browser. + +</p> + </section> + <section id="submit"> + <title>Submitting Data: Form Beans and Data Binding</title> + <p> +<!-- +Suppose you want to your web application to collect data from users and then process that data in some way. The following example demonstrates how to set up a data submission process using page flows. The sample code referred to in this example can be found at: + +BEA_HOME>\weblogic81\samples\workshop\SamplesApp\WebApp\handlingData\simpleSubmit\ + +Submitting data is a two step process: (1) the data submitted from a JSP page is loaded into a Form Bean instance and (2) the Form Bean instance is passed to an action method for processing. + + + +Form Beans are simple Java classes with fields and setter and getter methods for accessing those fields. Form Beans classes are contained within the controller file. In most cases, Form Beans are designed to accept data submitted from JSP forms. For example, if a JSP page has input elements for name, eye_color, and height, then the Form Bean will have corresponding fields for name, eye_color, and height. The following example Form Bean can be found in the controller file SimpleSubmitController.jpf. It contains one field, name, and setter and getter methods for that field. + + SimpleSubmitController.jpf + + public class SimpleSubmitController extends PageFlowController + { + + ... + + public static class SubmitNameForm extends FormData + { + private String name; + + public void setName(String name) + { + this.name = name; + } + + public String getName() + { + return this.name; + } + } + } + +The input elements on the JSP page are said to be "data bound" to the fields in the Form Bean. Data binding allows the the data submitted from the JSP page to be loaded into the Form Bean instance. For example, the input element on index.jsp contains a data binding expression that refers to the name field of the Form Bean: {actionForm.name}. The expression "actionForm" refers to the Form Bean SubmitNameForm, the property ".name" refers to the name field of the Form Bean. For detailed information about data binding see Using Data Binding in Page Flows. + + index.jsp + <netui:form action="SubmitName"> + Name: <netui:textBox dataSource="{actionForm.name}"/> + .... + </netui:form> +Finally the Form Bean instance (carrying the submitted data) is passed to the action method for processing. + + /** + * @jpf:action + * @jpf:forward name="success" path="showName.jsp" + */ + protected Forward SubmitName(SubmitNameForm form) + { + // + // The data is processed here + // + + return new Forward("success"); + } + +The submitted data can be accessed by calling the getter methods on the Form Bean. + + /** + * @jpf:action + * @jpf:forward name="success" path="showName.jsp" + */ + protected Forward SubmitName(SubmitNameForm form) + { + if( form.getName() != null ) + // do something here + else + // do something else here + + return new Forward("success"); + } + +By default the Form Bean instance that is passed to the action method exists only as long as the HTTP request. This is called a "request-scoped Form Bean". When the HTTP request is destroyed, the Form Bean instance, along with the user submitted data, is destroyed. As an alternative, you can use a Page Flow-scoped Form Bean, which has a longer life cycle. For details see Form Bean Scopings. + +</p> + </section> + <section id="processing_data"> + <title>Processing Data</title> + </section> + <section id="displaying_data"> + <title>Displaying Data</title> + <p> +Displaying Data: A Simple Example + +Suppose that once you have collected data, you want to display it back to the user. The following example shows how to use data binding to display data to the user. The sample code referred to can be found at: + +<BEA_HOME>\weblogic81\samples\workshop\SamplesApp\WebApp\handlingData\simpleSubmit\ + +Displaying data using data binding requires that (1) the data is located somewhere where it can accessed by the JSP page and (2) the JSP page uses a data binding expression to retrieve the data from that location. + +Notice the syntax of data binding expression on the JSP page. (1) It is framed by curley braces, (2) it begins with a data binding context, in this case the request context, and (3) the context is followed by an attribute, in this case "name". + +In the following example, an action method places data on the name attribute of the request object. + + SimpleSubmitController.jpf + + /** + * @jpf:action + * @jpf:forward name="success" path="showName.jsp" + */ + protected Forward SubmitName(SubmitNameForm form) + { + getRequest().setAttribute("name", form.getName()); + return new Forward("success"); + } + +After the data has been located on the name attribute of the request object, it is displayed on a JSP page using a data binding expression. + + showName.jsp + + Here is the data you submitted: <netui:label value="{request.name}" /> + +Note that the request object has a relatively short life-cycle. When the user makes a new request, by navigating to a new JSP page or invoking another action method, the current request object is destroyed along with the data it contains. If your application requires the data to be more persistent, then you could use a different data binding context, for example the session object or a Page Flow-scoped Form Bean, which both have longer life-cycles. For detailed information about the different data binding contexts available, see Using Data Binding in Page Flows. + +--> +</p> + </section> +<!-- <section id="controls"> + <title>Accessing Back-End Resources with Controls</title> + </section> + <section id="validation"> + <title>Validation</title> + </section> + <section id="security"> + <title>Security</title> + </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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/index.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/index.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/index.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,328 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd";> +<document> + <header> + <title>Introduction to Beehive Page Flows</title> + </header> + <body> + <section id="advantages"> + <title>Why Use Page Flows?</title> + <p>By using page flows, you can avoid making the typical mistakes that often + happen during web application development, by separating presentation, business + logic implementation, and navigational control. In many web applications, + web developers using JSP (or any of the other dynamic web languages such + as ASP or CFM) combine presentation and business logic in their web pages. + </p> + <p>As these applications grow in complexity and are subject to continual change, + this practice leads to expensive, time-consuming maintenance problems, caused + by:</p> + <ul> + <li> + Limited reuse of business logic + </li> + <li> + Cluttered JSP source code + </li> + <li>Unintended exposure of business-logic code to team members who focus + on other aspects of web development, such as content writers and visual + designers</li> + </ul> + <p>Page flows allow you to separate the user interface code from navigational + control and other business logic. User interface code can be placed where + it belongs, in the JSP files. Navigational control can be implemented easily + in a page flow's single controller file, which is the nerve center of your + web application. A controller file is a special Java file that uses a JPF + file extension. Business logic can be implemented in the page controller + file, or in Java controls that you call from JPF files.</p> + <p>The separation of presentation and business logic offers a big advantage + to development teams. For example, you can make site navigation updates + in a single JPF file, instead of having to search through many JSP files + and make multiple updates. In WebLogic Workshop you can as easily navigate + between page flows as between individual JSP pages. This allows you to group + related web pages under one page flow, and create functionally modular web + components. This approach to organizing the entities that comprise web applications + makes it much easier to maintain and enhance web applications by minimizing + the number of files that have to be updated to implement changes, and lowers + the cost of maintaining and enhancing applications.</p> + <p>Another advantage of page flows is that an instance of the page flow controller + class is kept alive on a per-user-session basis while the user is navigating + within the scope of the page flow. This instance ends when the user exits + from the page flow. You can use instance member variables in page flow classes + to hold user session state.</p> + </section> + <section id="work"> + <title>How Does a Page Flow Work?</title> + <p>A page flow is a Java class, called the "controller" class, that + controls the behavior of a web application through the use of specially + designed annotations and methods. The directory that contains the controller + class also includes the JavaServer Pages (JSPs) used in the page flow. For + a JSP to be considered part of a page flow, it must reside within the page + flow directory. The JSP files use special tags which help bind to data and + business logic actions. The action methods in the controller file implement + code that can result in site navigation, passing data, or invoking back-end + business logic via controls. Significantly, the business logic in the controller + class is separate from the presentation code defined in the JSP files.</p> + <p>The overall purpose of a page flow is to provide you with an easy-to-use + framework for building dynamic, sophisticated web applications. WebLogic + Workshop provides graphical and code-level tools to simplify the development + cycle. While page flows give you access to advanced features of J2EE, you + do not have to be a J2EE expert to quickly develop and deploy Java-based + applications built on page flows. Wizards can be used to create different + types of page flows, generating the Java and JSP files that serve as a starting + point for your work. Graphical tools let you draw the relationships between + web components in a controller's Flow View. In Source View, syntax completion, + validation, and other programmer's aids reduce the amount of work required + to get your application running.</p> + <p> + <strong>Note</strong>: WebLogic Workshop's web application + functionality is built on Struts, which is an open-source framework for + building web applications in a J2EE environment.</p> + </section> + <section id="components"> + <title>Components of the Page Flow Programming Model</title> + <p>Page flows implement user interface control logic, and contain:</p> + <ul> + <li>Action Methods</li> + <li>Form Beans</li> + <li>Forward Objects</li> + <li>The <netui...> Tag Library</li> + </ul> + <section id="actionmethods"> + <title>Action Methods</title> + <p>In the controller class, action methods are methods that are annotated with a <code>@JpfAction</code> tag.</p> + <p> + <code> [EMAIL PROTECTED](forwards = { [EMAIL PROTECTED](name="success", path="page_A.jsp") + } + ) + protected Forward begin() + { + return new Forward( "success" ); + }</code> + </p> + <p> Action methods can perform several functions. They can (1) implement navigation + decisions, (2) move data into and out of JSP pages, and (3) invoke back-end + business logic via calls to controls.</p> + </section> + <section id="formbeans"> + <title>Form Beans</title> + <p>Form Beans are Java data structures that correspond to HTML forms. When a user submits data from an HTML form, the data is stored in a Form Bean instance. Once the data is stored in a Form Bean instance, the data is available for processing by the action methods in the controller file. Form Bean instances (containing submitted data) are typically passed as parameters to action methods. + +<code> @JpfAction() + + protected Forward ProcessData( MyFormBean form ) + { + + //Submitted data is processed here... + + }</code></p> +<p> +<code>Form Beans are simple Java classes contained within the controller file. They consist of some number of fields with setter and getter methods associated with those fields. Below is a Form Bean with one field, the String name, and setter and getter methods for that field. Form Bean must extend the class com.bea.wlw.netui.pageflow.FormData. + + public static class MyFormBean extends FormData + { + private String name; + + public void setName(String name) + { + this.name = name; + } + + public String getName() + { + return this.name; + }</code></p> + </section> + <section> + <title>Forward Objects</title> + <p>Forward objects are returned by action methods. They can be used to control navigation and pass data throughout the application.</p> + </section> + <section> + <title>The <netui> Tag Library</title> + <p>The <netui> tag library contains JSP tags specifically designed to work with the controller class. Tags in the library all begin with the prefixes "netui", "netui-databinding", and "netui-template". Some of these tags perform much like familiar HTML tags, while others perform function particular to page flow web applications. The most important feature of the tag library is its ability to "data bind" to data in the controller file. Data binding allows the JSP pages to both read from and write to Java code in the controller class. This is accomplished without placing any Java code on the JSP pages, greatly enhancing the separation of data presentation and data processing.</p> + </section> + </section> + <section> + <title>Example Code</title> + <section> + <title>Navigation</title> + <p>As shown in the Flow View diagram, the page flow class defines an action method named toPageB. This action can be invoked by a link on the JSP page page_A.jsp. + +page_A.jsp + +ÂÂÂÂ<%@ taglib uri="netui-tags-html.tld" prefix="netui"%> + ... + <netui:anchor action="toPageB">Link to page_B.jsp</netui:anchor></p> + +<p>A special JSP tag library named netui-tags-html.tld is referenced. WebLogic Workshop provides this tag library and several others to help you develop dynamic web applications. The <netui:anchor...> tag used here is simply invoking an action (toPageB) with a hyperlink. (For more information about the page flow tag library, see Designing User Interfaces in JSPs.)Â</p> + +<p>In the controller file SimpleNavigationController.jpf, the toPageB action method is defined as follows: + +SimpleNavigationController.jpf + + import com.bea.wlw.netui.pageflow.Forward; + + ... + + [EMAIL PROTECTED](forwards = { + @JpfForward(name="success", path="page_B.jsp") + }) + + public Forward toPageB() + { + return new Forward( "success" ); + }</p> + +<p>When the link on page_A.jsp is clicked, the page flow runtime detects the action and runs the toPageB action method. This action method is coded to return a Forward object which passes the parameter "success". (Notice that this name "success" matches the name on the corresponding action arrow in Flow View.)</p> + +<p>Look at the two @Jpf annotations that appear on the lines above this action method. These annotations are enclosed in Javadoc comments. The @JpfAction tag indicates that the toPageB method is an action method. The @JpfForward tag describes the behavior of that method.</p> + +<p>Putting it all together, a Forward object is returned by an action method. The Forward object passes the string "success", indicating that it should behave according to the directions encoded in the annotation @JpfForward name="success". That annotation's path attribute has the value "page_B.jsp", which causes the page flow controller to load page_B.jsp into the browser.</p> + +<p>The following diagram summarizes the flow in the example:</p> + + + +<p>To change the navigation target of this action method, simply change the value of the path attribute. For example, if you want this action method to navigate to page_C.jsp, you would make the following change to the controller file (no change to the JSP page is necessary). + + + [EMAIL PROTECTED](forwards = { + @JpfForward(name="success", path="page_C.jsp") + }) + + public Forward toPageB() + { + return new Forward( "success" ); + }</p> + +<p>As you will see in later sections, the WebLogic Workshop IDE generates this code for you when you create a new page flow or JSP file from the graphical view. This code generation and subsequent validation of your changes saves you considerable time.</p> + </section> + <section> + <title>Submitting Data</title> +<p>Suppose you want to your web application to collect data from users and then process that data in some way. The following example demonstrates how to set up a data submission process using page flows. The sample code referred to in this example can be found at: </p> + +<p><BEA_HOME>\weblogic90\samples\workshop\SamplesApp\WebApp\handlingData\simpleSubmit\ +</p> +<p>Submitting data is a two step process: (1) the data submitted from a JSP page is loaded into a Form Bean instance and (2) the Form Bean instance is passed to an action method for processing.</p> + + + +<p>Form Beans are simple Java classes with fields and setter and getter methods for accessing those fields. Form Beans classes are contained within the controller file. In most cases, Form Beans are designed to accept data submitted from JSP forms. For example, if a JSP page has input elements for name, eye_color, and height, then the Form Bean will have corresponding fields for name, eye_color, and height. The following example Form Bean can be found in the controller file SimpleSubmitController.jpf. It contains one field, name, and setter and getter methods for that field.</p> + +<p>SimpleSubmitController.jpf + + public class SimpleSubmitController extends PageFlowController + { + + ... + + public static class SubmitNameForm extends FormData + { + private String name; + + public void setName(String name) + { + this.name = name; + } + + public String getName() + { + return this.name; + } + } + }</p> + +<p>The input elements on the JSP page are said to be "data bound" to the fields in the Form Bean. Data binding allows the the data submitted from the JSP page to be loaded into the Form Bean instance. For example, the input element on index.jsp contains a data binding expression that refers to the name field of the Form Bean: {actionForm.name}. The expression "actionForm" refers to the Form Bean SubmitNameForm, the property ".name" refers to the name field of the Form Bean. For detailed information about data binding see Using Data Binding in Page Flows.</p> + +<p>index.jsp</p> + +<p> <netui:form action="SubmitName"> + Name: <netui:textBox dataSource="{actionForm.name}"/> + .... + </netui:form></p> + +<p>Finally the Form Bean instance (carrying the submitted data) is passed to the action method for processing.</p> + + + +<p>@JpfAction(forwards = { + @JpfForward(name="success", path="showName.jsp") + }) + + protected Forward SubmitName(SubmitNameForm form) + { + // + // The data is processed here + // + + return new Forward("success"); + }</p> + +<p>The submitted data can be accessed by calling the getter methods on the Form Bean.</p> + +<p>@JpfAction(forwards = { + @JpfForward(name="success", path="showName.jsp") + }) + protected Forward SubmitName(SubmitNameForm form) + { + if( form.getName() != null ) + // do something here + else + // do something else here + + return new Forward("success"); + }</p> + +<p>By default the Form Bean instance that is passed to the action method exists only as long as the HTTP request. This is called a "request-scoped Form Bean". When the HTTP request is destroyed, the Form Bean instance, along with the user submitted data, is destroyed. As an alternative, you can use a Page Flow-scoped Form Bean, which has a longer life cycle. For details see Form Bean Scopings.</p> + + </section> + <section> + <title>Displaying Data</title> +<p>Suppose that once you have collected data, you want to display it back to the user. The following example shows how to use data binding to display data to the user. The sample code referred to can be found at: </p> + +<p><BEA_HOME>\weblogic81\samples\workshop\SamplesApp\WebApp\handlingData\simpleSubmit\</p> + +<p>Displaying data using data binding requires that (1) the data is located somewhere where it can accessed by the JSP page and (2) the JSP page uses a data binding expression to retrieve the data from that location.</p> + + + +<p>Notice the syntax of data binding expression on the JSP page. (1) It is framed by curley braces, (2) it begins with a data binding context, in this case the request context, and (3) the context is followed by an attribute, in this case "name".</p> + +<p>In the following example, an action method places data on the name attribute of the request object.</p> + +<p>SimpleSubmitController.jpf + + [EMAIL PROTECTED](forwards = { + @JpfForward(name="success", path="showName.jsp") + }) + + protected Forward SubmitName(SubmitNameForm form) + { + getRequest().setAttribute("name", form.getName()); + return new Forward("success"); + }</p> + +<p>After the data has been located on the name attribute of the request object, it is displayed on a JSP page using a data binding expression.</p> + +<p>showName.jsp</p> + +<p> Here is the data you submitted: <netui:label value="{request.name}" /></p> + +<p>Note that the request object has a relatively short life-cycle. When the user makes a new request, by navigating to a new JSP page or invoking another action method, the current request object is destroyed along with the data it contains. If your application requires the data to be more persistent, then you could use a different data binding context, for example the session object or a Page Flow-scoped Form Bean, which both have longer life-cycles. For detailed information about the different data binding contexts available, see Using Data Binding in Page Flows. </p> + </section> + <section> + <title>Connecting to Resources with Controls</title> + <p>[tbd]</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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_altering.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_altering.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_altering.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,211 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd";> +<document> + <header> + <title>Altering a Page Flow</title> + </header> + <body> + + <section id="introduction"> + <title>Introduction</title> + + <p> + In the previous pages, you were shown how to stitch together a controller class + and a set of JSP pages. One of the most powerful features of the Beehive way + of building applications is being able to change the flow by editing only the + controller class file, without having to touch the JSP pages. + </p> + + </section> + + <section id="logical_flow_change"> + <title>Logical Flow Change</title> + + <p> + Sometime after deploying the application, it is decided that before allowing a + user to login, they must first be presented a page describing the terms of + service for using the application. Additionally, a decision is made to have + the "Sign Up" action automatically log-in the new user so they don't have + to traverse the login screen. + </p> + + <p> + The original logical flow looked like this: + </p> + + <p> + <img src="images/logical-flow-1.png" alt="logical flow, before alteration"/> + </p> + + <p> + After these changes, the logical flow now resembles: + </p> + + <p> + <img src="images/logical-flow-2.png" alt="logical flow, after alteration"/> + </p> + + </section> + + <section id="impl_flow_change"> + <title>Implementation Flow Change</title> + + <p> + To accomodate the new logical flow, the implementation flow model originally looked like this: + </p> + + <p> + <img src="images/impl-flow-1.png" alt="logical flow, after alteration"/> + </p> + + <p> + After removing <code>thanks.jsp</code>, adding <code>terms.jsp</code>, adding an + <code>acceptTerms()</code> method, and re-routing the post-signup flow, looks like: + </p> + + <p> + <img src="images/impl-flow-2.png" alt="logical flow, after alteration"/> + </p> + + </section> + + <section id="changes_to_jsp"> + <title>Changes Required in the JSPs</title> + + <p> + Strictly speaking, no changes to JSP content are required. Only deletion of the + unused <code>thanks.jsp</code> and creation of the <code>terms.jsp</code> is + all that is required. + </p> + + <p> + <strong>Note:</strong>, The <code>signup.jsp</code> page + that previously would direct a user to <code>thanks.jsp</code> but will now + send him to <code>mypage.jsp</code> requires <em>absolutely no changes</em>. + </p> + + <p> + The <code>terms.jsp</code> page would include a link through a new <code>acceptTerms()</code> + controller method, similar to: + </p> +<source> + <netui:anchor action="acceptTerms">Accept these Terms of Service</netui:anchor> +</source> + + </section> + + <section id="changes_to_controller"> + <title>Changes Required in the Controller Class</title> + + <p> + To change the flow, a few simple edits of the controller class are all that is required. + </p> + + <section id="redirecting_login"> + <title>Redirect <code>login()</code></title> + + <p> + Previous, the <code>login()</code> controller method was defined to statically + return the forward to <code>login.jsp</code>. + </p> + +<source> + @Jpf.Action( + forwards = { + @Jpf.Forward( name="success", path="<strong>login.jsp</strong>" ); + } + ) + public Forward login() + { + return new Forward( "success" ); + } +</source> + + <p> + By changing the <code>path</code> property of the <code>Jpf.Forward</code> associated + with this page, all links that previously took the user to <code>login.jsp</code> will + now direct him to <code>terms.jsp</code>. + </p> + +<source> + @Jpf.Action( + forwards = { + @Jpf.Forward( name="success", path="<strong>terms.jsp</strong>" ); + } + ) + public Forward login() + { + return new Forward( "success" ); + } +</source> + + <p> + The <code>terms.jsp</code> page links through a new <code>acceptTerms()</code> + controller method which simply is a static forward to <code>login.jsp</code>. + </p> + +<source> + @Jpf.Action( + forwards = { + @Jpf.Forward( name="success", path="login.jsp" ); + } + ) + public Forward acceptTerms() + { + return new Forward( "success" ); + } +</source> + + <p> + This biggest change in the controller class is in the <code>processSignUp()</code> + controller method. Instead of just recording the user's information, it now must + also perform the logic of logging in the user automatically. Additionally, the + forward returned by it will send the user directly to <code>mypage.jsp</code> + instead of the not-unused <code>thanks.jsp</code> page. + </p> + +<source> + @Jpf.Action( + forwards = { + @Jpf.Forward( name="success", path="<strong>mypage.jsp</strong>" ); + } + ) + public Forward processSignUp(SignUpForm form) + { + // record the user's sign-up information. + + ... + ... + + // perform automatic login for the user. + + HttpServletRequest request = getRequest(); + HttpSession session = request.getSession(); + + session.setAttribute( "authenticated_user", + form.getUsername() ); + + return new Forward( "success" ); + } +</source> + + <p> + The flow has successfully be altered to now include a jump through the site's + terms-of-service and automatically logging-in newly signed-up users. + </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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_building.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_building.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_building.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,325 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd";> +<document> + <header> + <title>Building a Page Flow Web App</title> + </header> + <body> + + <section id="introduction"> + <title>Introduction</title> + + <p> + Now that the theory of Java Page Flows has been explained, you need to know + how to concretely put together a web-app that uses JPFs. Beehive ships with + a set of Ant buildfiles to make the building of an application much easier. + </p> + + </section> + + <section id="source_tree_layout"> + <title>Source Tree Layout</title> + + <p> + The layout of your project may be anywhere on your local disk. We assume + that the environment variable $WEBAPP_DIR points to the top-level of your + application. + </p> + + <ul> + <li><code>$WEBAPP_DIR/</code> + <ul> + <li><code>Controller.jpf</code></li> + <li><code>index.jsp</code></li> + <li><code>login.jsp</code></li> + <li><code>signup.jsp</code></li> + <li><code>mypage.jsp</code></li> + <li><code>resources/</code></li> + <li><code>WEB-INF/</code> + <ul> + <li><code>src/</code></li> + <li><code>classes/</code></li> + <li><code>lib/</code></li> + </ul> + </li> + </ul> + </li> + </ul> + + <section id="top_level"> + <title><code>$WEBAPP_DIR/</code></title> + + <p> + The top-level of the web-app, at <code>$WEBAPP_DIR</code> should contain + your JSP pages and a <code>Controller.jpf</code>. When built, the + <code>Controller.jpf</code> will be compiled to <code>WEB-INF/classes/Controller.jpf</code>. + </p> + + + </section> + + <section id="web-inf"> + <title><code>$WEBAPP_DIR/WEB-INF/</code></title> + + <p> + The <code>$WEBAPP_DIR/WEB-INF/</code> directory is just as it is with any other servlet-based + application. + </p> + + </section> + + <section id="web-inf_src"> + <title><code>$WEBAPP_DIR/WEB-INF/src/</code></title> + + <p> + The <code>$WEBAPP_DIR/WEB-INF/src/</code> directory contains any other application + source files that need to be compiled into Java classes. They will be compiled + to <code>$WEBAPP_DIR/WEB-INF/classes/</code>. Additionally, any extra <code>.properties</code> + or <code>.xml</code> files that need to be deployed with your application will be copied + from the <code>src/</code> directory to the <code>classes/</code> directory during the build. + </p> + + </section> + + <section id="web-inf_lib"> + <title><code>$WEBAPP_DIR/WEB-INF/lib/</code></title> + + <p> + As with any other web application, the <code>$WEBAPP_DIR/WEB-INF/lib/</code> directory + should contain the jars for each dependency of your application, including those + required by Beehive itself. The jars required by Beehive are listed below. + </p> + + <table> + <tr> + <th>Project</th> + <th>Jar</th> + <th>Version</th> + </tr> + <tr> + <td>Beehive</td> + <td>beehive-controls.jar</td> + <td><em>distribution</em></td> + </tr> + <tr> + <td>Beehive</td> + <td>beehive-netui-compiler.jar</td> + <td><em>distribution</em></td> + </tr> + <tr> + <td>Beehive</td> + <td>beehive-netui-pageflow.jar</td> + <td><em>distribution</em></td> + </tr> + <tr> + <td>Beehive</td> + <td>beehive-netuid-scoping.jar</td> + <td><em>distribution</em></td> + </tr> + <tr> + <td>Beehive</td> + <td>beehive-netui-tags-databinding.jar</td> + <td><em>distribution</em></td> + </tr> + <tr> + <td>Beehive</td> + <td>beehive-netui-tags-html.jar</td> + <td><em>distribution</em></td> + </tr> + <tr> + <td>Beehive</td> + <td>beehive-netuid-template.jar</td> + <td><em>distribution</em></td> + </tr> + <tr> + <td>Beehive</td> + <td>beehive-tomcat-common-4x.jar</td> + <td><em>distribution</em></td> + </tr> + <tr> + <td>Beehive</td> + <td>beehive-tomcat-server-4x.jar</td> + <td><em>distribution</em></td> + </tr> + <tr> + <td>Beehive</td> + <td>beehive-tomcat-webapp-4x.jar</td> + <td><em>distribution</em></td> + </tr> + <tr> + <td>Beehive</td> + <td>beehive-netui-util.jar</td> + <td><em>distribution</em></td> + </tr> + <tr> + <td>CGLib</td> + <td>cglib-full.jar</td> + <td>2.0.1</td> + </tr> + <tr> + <td>Jakarta Commons</td> + <td>commons-beanutils</td> + <td>1.7.0</td> + </tr> + <tr> + <td>Jakarta Commons</td> + <td>commons-collections.jar</td> + <td>3.0</td> + </tr> + <tr> + <td>Jakarta Commons</td> + <td>commons-digester</td> + <td>1.6</td> + </tr> + <tr> + <td>Jakarta Commons</td> + <td>commons-lang.jar</td> + <td>1.0.1</td> + </tr> + <tr> + <td>Jakarta Commons</td> + <td>commons-logging.jar</td> + <td>1.0.3</td> + </tr> + <tr> + <td>EHCache</td> + <td>echache.jar</td> + <td>0.7</td> + </tr> + <tr> + <td>Geronimo</td> + <td>geronimo-spec-jta.jar</td> + <td>DEV</td> + </tr> + <tr> + <td>HSQLDB</td> + <td>hsqldb.jar</td> + <td>1.7.2.2</td> + </tr> + <tr> + <td>JSTL</td> + <td>jstl.jar</td> + <td>1.1.1</td> + </tr> + <tr> + <td>Log4J</td> + <td>log4j.jar</td> + <td>1.2.8</td> + </tr> + <tr> + <td>Servlet API</td> + <td>servletapi.jar</td> + <td>2.4</td> + </tr> + <tr> + <td>JSTL <strong>[todo: is this right? ]</strong></td> + <td>standard.jar</td> + <td>1.1.1</td> + </tr> + <tr> + <td>StAX</td> + <td>stax.jar</td> + <td>1.1.1-dev</td> + </tr> + <tr> + <td>StAX</td> + <td>stax-api.jar</td> + <td>1.0</td> + </tr> + <tr> + <td>Struts</td> + <td>struts.jar</td> + <td>1.1</td> + </tr> + <tr> + <td>XMLBeans</td> + <td>xmlbeans.jar</td> + <td>2.0-dev-2</td> + </tr> + </table> + + </section> + + </section> + + <section id="running_ant"> + <title>Running Ant</title> + + <p> + Before you can build the web-app using ant, you must ensure that the <code>BEEHIVE_HOME</code> + and <code>CATALINA_HOME</code> variables are set correctly, along with <code>WEBAPP_DIR</code>. + </p> + + <table> + <tr> + <th>Variable</th> + <th>Value</th> + </tr> + <tr> + <td>BEEHIVE_HOME</td> + <td>Top level of the Beehive distribution</td> + </tr> + <tr> + <td>CATALINE_HOME</td> + <td>Top level of the installed Tomcat server</td> + </tr> + <tr> + <td>WEBAPP_DIR</td> + <td>Top level of the web-app to be built</td> + </tr> + </table> + + <p> + Once these variables are set correctly, building the deployable web-app + requires a single ant invocation using the build file at <code>$BEEHIVE_HOME/ant/buildWebapp.xml</code>. + This build-file is invoked using ant's <code>-f <buildfile-path></code> option. + The directory of the web-app is passed on the commandline using the <code>-Dname=value</code> + functionality of ant. Finally, the <code>build.webapp</code> target is invoked. + </p> + +<source> +ant -f $BEEHIVE_HOME/ant/buildWebapp.xml -Dwebapp.dir=$WEBAPP_DIR build.webapp +</source> + + </section> + + <section id="deploying"> + <title>Deploying the Web-app</title> + + <p> + The easiest way to deploy the web-app is to create a symlink/shortcut from + $WEBAPP_DIR to $CATALINA_HOME/webapps. Another way would be to simply copy + $WEBAPP_DIR to $CATALINE_HOME/webapps. + </p> + +<source> +ln -s $WEBAPP_DIR $CATALINE_HOME/webapps +</source> + +<source> +cp -R $WEBAPP_DIR $CATALINE_HOME/webapps +</source> + + </section> + + <section id="next"> + <title>Next...</title> + + <p> + Now that you've built and deployed an application, you can see how easy it is to modify + the flow between pages, adding and removing pages. + </p> + + <ul> + <li><link href="pageflow_altering.html">Altering a Page Flow</link></li> + </ul> + </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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_controllers.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_controllers.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_controllers.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,505 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd";> +<document> + <header> + <title>Page Flow Controllers</title> + </header> + <body> + + <section id="introduction"> + <title>Introduction</title> + + <p> + As introduced in the <link href="pageflow_overview.html">Page Flow Overview</link>, the + following model will be used. + </p> + + <p> + <img src="images/impl-flow-1.png" alt="implementation page flow"/> + </p> + + </section> + + <section id="starting_the_controller"> + <title>Starting the Controller</title> + + <p> + The first step to writing a controller is to simply create a new basic class + named <code>Controller.jpf</code>. The <code>jpf</code> extension alerts the + build that this class is a special JPF controller class, instead of a typical + Java class. + </p> + +<source> +<strong>public class Controller +{ +}</strong> +</source> + + <p> + Just as the <code>.jpf</code> extension denotes a special Java class, controllers + also must subclass <code>org.apache.beehive.netui.pageflow.PageFlowController</code> + </p> + +<source> +<strong>import org.apache.beehive.netui.pageflow.PageFlowController;</strong> + +public class Controller + <strong>extends PageFlowController</strong> +{ +} +</source> + + <p> + Additionally, Beehive weaves magic into controller classes using annotations. + The <code>Jpf.Controller</code> annotation is a required marker on your + own controller class. + </p> + +<source> +import org.apache.beehive.netui.pageflow.PageFlowController; +<strong>import org.apache.beehive.netui.pageflow.annotations.Jpf;</strong> + +<strong>@Jpf.Controller</strong> +public class Controller + extends PageFlowController +{ +} +</source> + + <p> + Now we have the beginnings of a controller implementation. + </p> + + </section> + + <section id="fleshing_out_the_controller"> + <title>Fleshing Out the Controller</title> + + <p> + Now that the boilerplate <code>Controller.jpf</code> is in place, we can begin + to define the methods that intercept navigation and perform the necessary logic + to determine which JSP page should actually be displayed. In the above + model, these are: + </p> + + <ul> + <li><code>signUp()</code></li> + <li><code>login()</code></li> + <li><code>myPage()</code></li> + </ul> + + <p> + For the time being, we are going to ignore the methods that process form input. + </p> + + <p> + When a controller method completes, it must return an indication of what page to + display to the user. This is accomplished by returning a <code>org.apache.beehive.netui.pageflow.Forward</code> + object. + </p> + +<source> +import org.apache.beehive.netui.pageflow.Forward; +import org.apache.beehive.netui.pageflow.PageFlowController; +import org.apache.beehive.netui.pageflow.annotations.Jpf; + [EMAIL PROTECTED] +public class Controller + extends PageFlowController +{ + <strong> + public Forward signUp() + { + ... + } + + public Forward login() + { + ... + } + + public Forward myPage() + { + ... + } + </strong> +} +</source> + + <section id="constant_forwards"> + <title>Constant Forwards</title> + + <p> + For the two simple methods of <code>signUp()</code> and <code>login()</code>, + there is no special logic to be applied. They should simply return a constant + indication to arrive at <code>signup.jsp</code> and <code>login.jsp</code> + respectively. + </p> + + <p> + To help with configuration and to avoid having JSP page + names within the body of a controller method, Beehive once + again uses annotations. The <code>Jpf.Action</code> and + <code>Jpf.Forward</code> annotations are used on each method to + build an <strong>name to JSP page paths</strong> mapping. The method + then works only in terms of the <strong>id</strong>, and doesn't + directly refer to the JSP page path. + </p> + + <p> + The general form the of <code>Jpf.Action</code>/<code>Jpf.Forward</code> annotations are: + </p> + +<source> [EMAIL PROTECTED]( + forwards = { + @Jpf.Forward( <strong>name="...", path="..."</strong> ), + @Jpf.Forward( <strong>name="...", path="..."</strong> ), + @Jpf.Forward( <strong>name="...", path="..."</strong> ), + @Jpf.Forward( <strong>name="...", path="..."</strong> ) + } +) +</source> + + <p> + For simple methods that forward to a constant path, only a single <code>Jpf.Forward</code> + is needed. By convention, names such as <strong>success</strong> and <strong>failure</strong> + are used, but by no means are required. It is good practice, though, to avoid naming the + forward based upon the JSP page name since doing so would remove some of the decoupling that + Beehive applications attempt to achieve. + </p> + +<source> +import org.apache.beehive.netui.pageflow.Forward; +import org.apache.beehive.netui.pageflow.PageFlowController; +import org.apache.beehive.netui.pageflow.annotations.Jpf; + [EMAIL PROTECTED] +public class Controller + extends PageFlowController +{ + + <strong>@Jpf.Action( + forwards = { + @Jpf.Forward( name="success", path="signup.jsp") + } + )</strong> + public Forward signUp() + { + ... + } + + <strong>@Jpf.Action( + forwards = { + @Jpf.Forward( name="success", path="login.jsp" ) + } + )</strong> + public Forward login() + { + ... + } +} +</source> + + <p> + All that is left for these simple constant forward methods is a <code>return</code> + statement to return the appropriate <code>Forward</code> object. This is accomplished + simply by constructing a new <code>Forward</code> with the appropriate name. + </p> + +<source> +import org.apache.beehive.netui.pageflow.Forward; +import org.apache.beehive.netui.pageflow.PageFlowController; +import org.apache.beehive.netui.pageflow.annotations.Jpf; + [EMAIL PROTECTED] +public class Controller + extends PageFlowController +{ + + <strong>@Jpf.Action( + forwards = { + @Jpf.Forward( name="success", path="signup.jsp" ) + } + )</strong> + public Forward signUp() + { + <strong>return new Forward( "success" );</strong> + } + + <strong>@Jpf.Action( + forwards = { + @Jpf.Forward( name="success", path="login.jsp" ) + } + )</strong> + public Forward login() + { + <strong>return new Forward( "success" );</strong> + } +} +</source> +<p>The code above can be made even cleaner by defining "simple actions" at the class-level. Using the <code>@Jpf.SimpleAction</code> annotation at the class-level you can remove the controller methods and their annotations altogether. The code above can be replaced with the class-level annotations shown below:</p> +<source> + @Jpf.Controller( + <strong>simpleActions={ + @Jpf.SimpleAction(name="signUp", path="signup.jsp"), + @Jpf.SimpleAction(name="login", path="login.jsp") + }</strong> + ) +public class Controller + extends PageFlowController +{ +} +</source> + </section> + + <section id="conditional_forwards"> + <title>Conditional Forwards</title> + + <p> + The <code>myPage()</code> controller method, unlike <code>signUp()</code> and <code>login()</code> + contains logic to determine if the user has already authenicated himself. Unlike the previous two + methods, there will be two different <code>Jpf.Forward</code> annotations, and the job of the + <code>myPage()</code> method is to figure out which one is appropriate to return. + </p> + + <p> + We define two forwards named <strong>authenticated</strong> and <strong>not_authenticated</strong>, + which are linked to <code>mypage.jsp</code> and <code>login.jsp</code> respectively. + In this case, the determination of authentication is performed by checking a <strong>session attribute</strong> + to see if the <code>authenticated_user</code> attribute has been set. + Only the the <code>myPage()</code> method is displayed below in order to highlight condition forwards. + </p> + +<source> +import org.apache.beehive.netui.pageflow.Forward; +import org.apache.beehive.netui.pageflow.PageFlowController; +import org.apache.beehive.netui.pageflow.annotations.Jpf; + +import javax.servlet.http.HttpServletRequest; +import javax.servlet.http.HttpSession; + [EMAIL PROTECTED] +public class Controller + extends PageFlowController +{ + + ... + ... + + <strong>@Jpf.Action( + forwards = { + @Jpf.Forward( name="authenticated", path="mypage.jsp" ), + @Jpf.Forward( name="not_authenticated", path="login.jsp" ) + } + )</strong> + public Forward myPage() + { + HttpServletRequest request = getRequest(); + HttpSession session = request.getSession(); + + if ( session.getAttribute( "authenticated_user" ) != null ) + { + return new Forward( "authenticated" ); + } + + return new Forward( "not_authenticated" ); + } +} +</source> + + <p> + You may notice that the body of <code>myPage()</code> has no particular logic regarding + the user's "My Page" itself. It simply operates in terms of authentication and generically + named <code>Forward</code> objects. This presents a possibility of sharing this logic + with other controller methods that are concerned with authentication. For more ideas + along these lines, please see <!--<link href="controller_patterns.html">-->Controller Patterns [todo: forthcoming document]<!--</link>-->. + </p> + + </section> + + <section id="handling_forms"> + <title>Handling Forms</title> + + <p> + Handling form data works similar to other controller methods. By providing a parameter + to the controller method the HTML form data is made available to the controller method. In the above model, controller methods that process forms have been named + with the <code>processXXX(..)</code> convention. + <!--, a populated subclass of <code>org.apache.beehive.netui.pageflow.FormData</code>, --> + </p> + + <ul> + <li><code>processLogin(...)</code></li> + <li><code>processSignUp(...)</code></li> + </ul> + + <p> + First, define a JavaBean to represent the HTML form to be submitted. This JavaBean can be of any Java type. (In Struts applications the JavaBean must be a subclass of <code>org.apache.struts.action.ActionForm</code>. Similarly, in earlier incarnations of Page Flows the JavaBean had to be a subclass of <code>org.apache.beehive.netui.pageflow.FormData</code>. But this restriction has been loosened in the current incarnation: the JavaBean representation may be any JavaBean type.) + </p> + <p>The JavaBean may be defined (1) as a <code>static</code> inner class of the controller itself (see example below) or (2) as a stand-alone Java class in a separate file. The JavaBean class follows normal JavaBean conventions and require no special annotations. The JavaBean shown below is a subclass of <code>FormData</code>, but this is not a requirement. The JavaBean can be of any type. + </p> + +<source> +import org.apache.beehive.netui.pageflow.Forward; +import org.apache.beehive.netui.pageflow.FormData; +import org.apache.beehive.netui.pageflow.PageFlowController; +import org.apache.beehive.netui.pageflow.annotations.Jpf; + +import javax.servlet.http.HttpServletRequest; +import javax.servlet.http.HttpSession; + [EMAIL PROTECTED] +public class Controller + extends PageFlowController +{ + <strong>public static class LoginForm + extends FormData + { + private String username; + private String password; + + public void setUsername(String username) + { + this.username = username; + } + + public String getUsername() + { + return this.username; + } + + public void setPassword(String password) + { + this.password = password; + } + + public String getPassword() + { + return this.password; + } + }</strong> + + ... + ... + +} +</source> + + <p> + Defining the <code>processLogin(...)</code> method to take a <code>LoginForm</code> + parameter is all that is required to have a controller method that can + operate upon the submitted form. + </p> + +<source> +import org.apache.beehive.netui.pageflow.Forward; +import org.apache.beehive.netui.pageflow.FormData; +import org.apache.beehive.netui.pageflow.PageFlowController; +import org.apache.beehive.netui.pageflow.annotations.Jpf; + +import javax.servlet.http.HttpServletRequest; +import javax.servlet.http.HttpSession; + [EMAIL PROTECTED] +public class Controller + extends PageFlowController +{ + <strong>public static class LoginForm + extends FormData + { + ... + ... + }</strong> + + ... + ... + + <strong>public Forward processLogin(LoginForm form) + { + ... + }</strong> +} +</source> + + <p> + Once again, <code>processLogin(..)</code> is a conditional forward controller method. + If a user has entered a correct username and password, then they should be directed + to <code>mypage.jsp</code>, otherwise they will be returned back to the <code>login.jsp</code> + for another attempt. Checking username and password is outside of the scope of JPF, + and in this example, we rely upon a mythical <code>MyAppUtils</code> class to perform + this logic. + </p> + +<source> +import org.apache.beehive.netui.pageflow.Forward; +import org.apache.beehive.netui.pageflow.FormData; +import org.apache.beehive.netui.pageflow.PageFlowController; +import org.apache.beehive.netui.pageflow.annotations.Jpf; + +import javax.servlet.http.HttpServletRequest; +import javax.servlet.http.HttpSession; + [EMAIL PROTECTED] +public class Controller + extends PageFlowController +{ + ... + ... + + <strong>@Jpf.Action( + forwards = { + @Jpf.Forward( name="authenticated", path="mypage.jsp" ), + @Jpf.Forward( name="not_authenticated", path="login.jsp" ) + } + )</strong> + public Forward processLogin(LoginForm form) + { + if ( MyAppUtils.authenticate( form.getUsername(), + form.getPassword() ) ) + { + HttpServletRequest request = getRequest(); + HttpSession session = request.getSession(); + + session.setAttribute( "authenticated_user", + form.getUsername() ); + + return new Forward( "authenticated" ); + } + + return new Forward( "not_authenticated" ); + } +} +</source> + + <p> + Similar implementation would be done for <code>signUp(..)</code>, involving another + <code>FormData</code> subclass such as <code>SignUpForm</code>. + </p> + + </section> + + </section> + + <section id="next"> + <title>Next...</title> + + <p> + Next, learn about linking this controller class to the JSP pages to allow for + the interception to occur. + </p> + + <ul> + <li><link href="pageflow_jsp.html">Page Flow JSP</link></li> + </ul> + </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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_jsp.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_jsp.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_jsp.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,270 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd";> +<document> + <header> + <title>Page Flow JSP</title> + </header> + <body> + + <section id="introduction"> + <title>Introduction</title> + + <p> + Continuing with the same model used in previous pages of this documentation set, + examples will reference this: + </p> + + <p> + <img src="images/impl-flow-1.png" alt="implementation flow"/> + </p> + + <p> + Java Page Flow adds a handful of tag libraries to normal JSP usage to assist with the + binding of the JSP pages to the controller class. Of primary importance is the + <code>netui/tags-html</code> taglib. Other taglibs provide additional functionality + </p> + + </section> + + <section id="starting_a_jpf_jsp"> + <title>Starting a JPF JSP</title> + + <p> + As with <link href="pageflow_controllers.html">Page Flow Controller</link>, a certain amount + of common boilerplate text is required in each page. The first two lines should set + the content-type, the encoding, and import the base netui tag library. The <code>taglib</code> + binds the netui tags to the <code>netui</code> prefix. + </p> + +<source> +<strong><%@ page language="java" contentType="text/html;charset=UTF-8"%> +<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0"; prefix="netui"%></strong> +</source> + + <p> + After the common prolog, the JSP page can be written like most any other JSP page, + with some tag substitutions occurring: + </p> + + <table> + <tr> + <th>original tag</th><th>replace with</th> + </tr> + <tr> + <td>html</td><td>netui:html</td> + </tr> + <tr> + <td>body</td><td>netui:body</td> + </tr> + <tr> + <td>a</td><td>netui:anchor</td> + </tr> + <tr> + <td>form</td><td>netui:form</td> + </tr> + <tr> + <td><em>various form elements</em></td><td><em>various netui: elements</em> (see <link href="#handling_forms">Handling Forms</link>, below)</td> + </tr> + </table> + + <p> + In addition to the prolog and general tag substitutions, <code><netui:base></code> + should be present within the <code><head></code> element. The resulting general + form of a JPF-based JSP page is as follows: + </p> + +<source> +<strong><%@ page language="java" contentType="text/html;charset=UTF-8"%> +<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0"; prefix="netui"%> +<netui:html></strong> + <head> + <title>...</title> + <strong><netui:base/></strong> + </head> + <strong><netui:body></strong> + .. + .. + .. + <strong></netui:body> +</netui:html></strong> +</source> + + </section> + + <section id="simple_linking"> + <title>Simple Linking</title> + + <p> + Initially, we will examine simple linking through a controller to another JSP page. + The <code><netui:anchor></code> tag replaces the normal <code><a></code> + HTML anchor tag. A plain <code><a></code> links directly from one URL to + another, without providing the controller an opportunity to perform any conditional + logic. The <code><netui:anchor></code> tag will be substituted when the + page is display to render the correct HTML and Javascript to cause the link + to venture through the controller class. + </p> + + <p> + While it may seem silly to use JPF/netui functionality for simple + <em>constant forward methods</em>, the advantage is that if a page + gets renamed or you wish to change the flow through an application, + the destination only needs to be changed once, within the controller. + Otherwise, you may have to edit a handful of JSP pages manually + changing the URLs inside normal <code><a></code> tags. + </p> + + <p> + For example, if your application changes and you desire to show a + terms-of-service before allowing login, you can simply alter the <code>login()</code> + controller method to send a user to <code>terms_of_service.jsp</code> before + further sending him to the actual login screen. + </p> + + <p> + The <code><netui:anchor></code> tag parallels the <code><a></code> + tag but uses a <code>action</code> attribute instead of an <code>href</code>. + Instead of specifying the URL to another page, the name of the method + on the controller class is used, without parenthesis. + </p> + + <p> + Instead of using <code><a></code> + </p> + +<source> +<<strong>a href="login.jsp"</strong>>Login!</a> +</source> + + <p> + Use <code><netui:anchor></code> + </p> + +<source> +<<strong>netui:anchor action="login"</strong>>Login!</netui:anchor> +</source> + + <p> + When the link is displayed on-screen, clicking it will cause control to + go through the <code>Controller</code>'s <code>login()</code> method, + which will return the correct forward to select the actual next page to + display. + </p> + + </section> + + <section id="handling_forms"> + <title>Handling Forms</title> + + <p> + To connect an on-screen form to the underlying controller's form-handling + method, the <code><netui:form></code> container tag, along with + specialized tags that replace the normal form elements are used within + a JSP page. Similar to how <code><netui:anchor></code> replaces + normal HTML <code><a></code> tags, the <code><netui:form></code> + tag replaces the typical HTML <code><form></code> tag. Once again, + the tag will render the appropriate page so that submission of the form + will venture through the named form-handling method of the controller class. + </p> + + <p> + Instead of using <code><form></code> + </p> + +<source> +<<strong>form action="LoginServlet"</strong> method="POST"> +</source> + + <p> + Use <code><netui:form></code> + </p> + + +<source> +<<strong>netui:form action="processLogin"</strong> method="POST"> +</source> + + <p> + The other tags typically used with a <code><form></code> also have + replacements from the netui tag library. + </p> + + <table> + <tr> + <th>original tag</th><th>replace with</th><th><code>FormData</code> datatype</th> + </tr> + <tr> + <td>button</td><td>netui:button</td><td><em>optionally changing the controller form processing method</em></td> + </tr> + <tr> + <td>input type="checkbox"</td><td>netui:checkBox</td><td><code>boolean</code> or <code>java.lang.Boolean</code></td> + </tr> + <tr> + <td>input type="checkbox"</td><td>netui:checkBoxGroup</td><td><code>java.lang.String[]</code></td> + </tr> + <tr> + <td>input type="checkbox"</td><td>netui:checkBoxOption</td><td><em>see <code>netui:checkBoxGroup</code></em></td> + </tr> + <tr> + <td>hidden</td><td>netui:hidden</td><td><code>java.lang.String</code></td> + </tr> + <tr> + <td>input type="radio"</td><td>netui:radioButtonGroup</td><td><code>java.lang.String[]</code></td> + </tr> + <tr> + <td>input type="radio"</td><td>netui:radioButtonOption</td><td><em>see <code>netui:radioButtonGroup</code></em></td> + </tr> + <tr> + <td>input type="radio"</td><td>netui:select</td><td><code>java.lang.String[]</code></td> + </tr> + <tr> + <td>option</td><td>netui:option</td><td>see <code>netui:option</code></td> + </tr> + <tr> + <td>textarea</td><td>netui:textArea</td><td><code>java.lang.String</code></td> + </tr> + <tr> + <td>input (type="text")</td><td>netui:textBox</td><td><code>java.lang.String</code></td> + </tr> + </table> + + <p> + For the <code>processLogin(...)</code> form-processing method, the matching JSP form would be: + </p> + +<source> +<strong><netui:form action="processLogin" method="POST"> + <netui:textBox name="username" size="20"/> + <netui:textBox name="username" size="20" password="true"/> + <netui:button type="submit" value="Login"/> +</netui:form></strong> +</source> + + <p> + When the user submits the form by clicking upon the <code>Login</code> button, an instance of + the <code>LoginForm</code> subclass of <code>FormData</code> is created and passed to the + <code>processLogin(LoginForm form)</code> method of the controller class. + </p> + + </section> + + <section id="next"> + <title>Next...</title> + + <p> + Next, learn about how to compile and package up a complete web-app. + </p> + + <ul> + <li><link href="pageflow_building.html">Building a Page Flow Web-App</link></li> + </ul> + </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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_overview.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_overview.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/pageflow_overview.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,199 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd";> +<document> + <header> + <title>Page Flow Overview</title> + </header> + <body> + + <section id="introduction"> + <title>Introduction</title> + + <p> + A Java Page Flow (JPF) is a group of Java Server Pages (JSP) and a Java class that + controls the user experience flow through an application. In addition to allowing + complex logic to dictate which pages are displayed, JPF technology helps decouple + page authoring from application logic by preventing one JSP from directly referencing + another. It also allows for easy state management within a single Java class. + </p> + + </section> +<section> + <title>Page Flow Features</title> + <p>Page Flows make building Java web applications easy and intuitive. When programming with Page Flows, the developer writes JAVA classes and JSP pages--that's it. There is very little occasion to work with configuration files, or other components. Page Flow programming also excels at separating presentation logic from data processing logic, resulting in uncluttered JSP code which is easy to understand and edit. Data processing and the web application configurables are handled in a single Java class using a simple declarative programming model.</p> + <p><strong>Declarative Programming</strong></p> + <p>Many common web app programming tasks are accomplished through a declarative programming model using JSR 175 metadata annotations, a new feature in JKD5. JSR 175 metadata annotations, "annotations" for short, are property setters for Java classes and methods, aliviating the need for independent configuration files. Navigation, exception handling, validation, and other tasks become configurable properties of a single Java class, the "controller" class that drives the web application.</p> + + <p><strong>Page Flows are Stateful</strong></p> + <p>When a user enters a Page Flow (by calling an URL in the Page Flow's URL space), an instance of the Page Flow's controller class is created. While the user is in the Page Flow, the controller class stores the accumulated session and user state. The methods within the class have access to the accumulated state, making for easy state management within the web application. For example, suppose your web application calls for a multi-page registration, where the user moves from page to page filling out a user profile. The controller class stores the user data as the user progresses through the registration and has access to the profile data as session state. When the user leaves the Page Flow, the state is automatically cleaned up. </p> +<p><strong>Page Flows are Modular</strong></p> +<p>A single web application can have multiple Page Flows within it, allowing you to break up the application into separate, self-contained chunks of functionality. For an example, see the <link href="../jpetstore.html">Petstore Sample</link>, which has different Page Flows for browsing the Petstore, buying products, and handling user accounts.</p> +<p>Page Flow web applications also contain a global Page Flow, called the "shared flow", which is both a fallback handler for unhandled actions and exceptions and a place to store session state. An instance of the shared flow class is stored in the user session upon the first request to any Page Flow and remains until the session ends. When an action is raised in a Page Flow, and that action is not handled by the Page Flow, the shared flow gets a chance to handle it. The same is true for an exception raised within a Page Flow: if it is unhandled in the Page Flow, the shared flow gets a chance to handle it.</p> + <p><strong>Struts Integration</strong></p> + <p>Page Flows are built on top of Apache Struts 1.1. Each Page Flow is compiled into a Struts module. As a result, Page Flow and Struts applications can work closely together.</p> +<p>Struts and Page Flow apps can co-habitate and interact with one another inside a web app. To forward from a Page Flow to a (pure) Struts module, simply reference the desired action within the Struts module. The same goes for the reverse direction: from a Struts module, simply configure an action to point to the desired method in the Page Flow. <!--[todo: detailed doc based on R. Feit's: http://dev2dev.bea.com/products/wlworkshop81/articles/Feit.jsp]--></p> + +<p>You can use many advanced Struts features within a Page Flow, for example, the StrutsValidatorPlugIn, which allows you to declare validation rules inside an XML file. Page Flows do not directly support the plug-in, but you can refer your data to a Struts app that does support the plug-in by using the <strong>Struts merge</strong> feature of Page Flows. <!-- [todo: detailed doc based on R. Feit's: http://dev2dev.bea.com/products/wlworkshop81/articles/Feit.jsp] --> </p> +</section> + <section id="logical_flow"> + <title>The Logical Flow</title> + + <p> + Writing traditional web applications without JPFs requires a fair amount of + logic to be applied within the application's pages. For example, a site + that provides a "My Page" functionality for logged in users would have + to include logic on the home page to determine if the "My Page" link + should take the user to the login form or directly to their customized + page. + </p> + + <p> + Using JPF, the home page of the application would not link directly to + either the login page <strong>or</strong> the user's "My Page" location, but rather + would point back into Java code that makes the decision. + </p> + + <p> + For the rest of this overview, the following <strong>logical page flow</strong> wil + be used: + </p> + + <p> + <img src="images/logical-flow-1.png" alt="logical page flow" /> + </p> + + <p> + This flow supports several routes from the home page of the application + to the user's "My Page": + </p> + + <ol> + <li> + <p> + <code>index.jsp</code> directly to <code>mypage.jsp</code> if the user is already logged in. + </p> + </li> + <li> + <p> + <code>index.jsp</code> to <code>login.jsp</code> if the user explicitely selects the 'login' action. + After logging in, the user will be automatically taken to <code>mypage.jsp</code>. + </p> + + <p> + In the event of a login failure, <code>login.jsp</code> will be redisplayed to give them + another opportunity to authenticate themselves. + </p> + </li> + <li> + <p> + If the user desires to register with the site, he can select the action that will + take him to <code>signup.jsp</code>. One signed up, the <code>thanks.jsp</code> + will be displayed which also allows the user to follow the path outlined in #2 + above to login. + </p> + </li> + <li> + <p> + In the event a user has already authenticated himself, he will be allowed to + go directly to his "My Page" at <code>mypage.jsp</code>. + </p> + </li> + </ol> + + </section> + + <section id="implementation_of_flow"> + <title>The Implementation of the Flow</title> + + <p> + In the above <strong>logical flow</strong> there are several <em>if</em> statements + that cause the user flow to vary depending on their previous actions and other state. + </p> + + <ul> + <li> + <em>If the user is not logged in...</em> + </li> + <li> + <em>If the user is logged in...</em> + </li> + <li> + <em>If the user's login attempt fails...</em> + </li> + </ul> + + <p> + Java Page Flows moves this condition logic out of the JSP pages and into a + Java class that controls the movement through the application. This Java class + is the <strong>controller</strong> portion of the <strong>Model-View-Controller</strong> + (MVC) pattern. This allows a page to be written, for example, that appears + to link directly from the home page of the application to the user's "My Page". + The <strong>controller</strong> is given the opportunity to intercept the navigation + between the two and redirect the user to the login page, if required. + </p> + + <p> + Each of the interception points is simply a <strong>method</strong> of the + particular <strong>controller</strong> class. The method may perform any required + complex logic. The return-value of the method dictates which page is then + displayed. If a user clicks on the "My Page" link, the method may check if + the user is logged in, and if so, return an indication that the <code>mypage.jsp</code> + should be displayed, otherwise it will return an indication that + <code>login.jsp</code> should be presented to the user. + </p> + + <p> + With normal HTML pages, each page is linked directly to other pages. + </p> + + <ul> + <li><strong>page > page > page > page</strong></li> + </ul> + + <p> + When using JPFs, pages and controller methods are interleaved, transparently. + </p> + + <ul> + <li><strong>page > method > page > method > page > method > page</strong></li> + </ul> + + <p> + The above <strong>logical page flow</strong> can be redrawn with JPF controller methods + in mind, as: + </p> + + <p> + <img src="images/impl-flow-1.png" alt="implementation page flow"/> + </p> + + <p> + Now it is apparent that to navigation from <code>index.jsp</code> to <code>mypage.jsp</code>, + the user traverses across the <code>myPage()</code> method. This method performs the necessary + check to determine if the user has already been authenticated. If the user has logged in already, + it will direct the user straight to <code>mypage.jsp</code>, otherwise, it displays <code>login.jsp</code>. + </p> + + </section> + <section id="next"> + <title>Next...</title> + + <p> + Next, learn about writing a <strong>controller</strong> class with methods. + </p> + + <ul> + <li><link href="pageflow_controllers.html">Page Flow Controller</link></li> + </ul> + </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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/sample_netui-blank.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/sample_netui-blank.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/sample_netui-blank.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,57 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v13.dtd";> +<document> + <header> + <title>Page Flow Project Template</title> + </header> + <body> + <section id="intro"> + <title>Introduction</title> +<p>Use the "blank" Page Flow sample (located at <code>BEEHIVE_HOME/samples/netui-blank</code>) as a template for building your own Page Flow applications. +The sample contains everything needed in a basic Page Flow application, except for the runtime and <netui> tag library JAR files. +</p> + </section> + <section> + <title>Using the Page Flow Web App Template</title> + <p>The following instruction assume that you have completed the basic Beehive set up procedure at <fork href="../setup.html">Set Up the Dev Environment</fork>.</p> + <p>To use the template, (1) copy the contents of <code>BEEHIVE_HOME/samples/netui-blank</code> into your project folder (refered to as <code><Project-Folder></code> below), and (2) copy the runtime JARs to the project's WEB-INF/lib directory. +It is important to copy the <em>contents</em> of <code>netui-blank</code> into your project folder, not the <code>netui-blank</code> folder itself. After you have copied the contents of <code>netui-blank</code> into your project folder, the following directory structure should exist:</p> +<source><Project-Folder> + resources + WEB-INF + Controller.jpf + error.jsp + index.jsp</source> + <p>The following Ant command will copy the necessary runtime and tag library JARs to <code><Project-Folder>/WEB-INF/lib</code>.</p> +<source> ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=<Project-Folder> + deploy.beehive.webapp.runtime</source> + <p>To build and run the template web app, run the following Ant command. (Before running ensure that Tomcat is turned on: <code>%CATALINA_HOME%\bin\startup.bat</code>. Or use the Ant command provided in the distribution: <code>ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml start</code>. If you use the provided Ant command, you will have to press <code>Ctrl+C</code> to continue issuing commands in that command window.)</p> +<source> ant + -f ant\buildWebapp.xml + -Dwebapp.dir=<Project-Folder> + -Dcontext.path=WebApp-Blank + build.webapp + deploy</source> +<p>If the WebApp-Blank web app is already deployed, use the following target:</p> +<source> ant + -f ant\buildWebapp.xml + -Dwebapp.dir=<Project-Folder> + -Dcontext.path=WebApp-Blank + undeploy + build.webapp + deploy</source> +<p>You can now try out the web app by pointing your browser at the following links.</p> + <ul> + <li>Run the controller file's begin() method: <fork href="http://localhost:8080/WebApp-Blank/";>http://localhost:8080/WebApp-Blank/</fork></li> +</ul> + </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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/tutorial_pageflow.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/tutorial_pageflow.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/tutorial_pageflow.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,493 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd";> +<document> + <header> + <title>Beehive Page Flow Tutorial</title> + </header> + <body> + <section id="intro"> + <title>Introduction</title> + <section> + <title>Tutorial Goals</title> + <p>In this tutorial, you will learn:</p> + <ul> + <li>How to create a basic Page Flow web application</li> + <li>How to coordinate user navigation with Forward methods</li> + <li>How to handle data submission and processing with data binding and Form Beans</li> + <li>How to create a user interface with the <neuti> JSP tag library</li> + <li>How Page Flows help to separate data processing and data presentation</li> + </ul> + </section> + <section> + <title>Assumptions Made in This Tutorial</title> + <p>The following tutorial assumes that you are working on a Windows machine. But, with a little common sense, it is easy to run through the tutorial on a Unix machine. For example, when the tutorial tells you to run the file beehiveUser.cmd, Unix users should run the file beehiveUser.sh.</p> + </section> + </section> + <section id="step1"> + <title>Step 1: Begin the Page Flow Tutorial</title> + <section> + <title>To Set up the Development Environment</title> + <p>Follow the setup directions at <fork href="../setup.html">Beehive Installation and Setup</fork></p> + <p>After completing the instructions, leave the command shell open to use throughout this tutorial.</p> + </section> + <section> + <title>Add a Manager Role to Tomcat</title> + <p>Adding the manager role to Tomcat server allows you to run deploy related targets in the Ant file <code>runTomcat.xml</code>. This file is provided as a convenience for managing the Tomcat server.</p> + <p>Edit the file <code>CATALINA_HOME/conf/tomcat-users.xml</code> so it appears as follows. Code to add appears in bold type.</p> + <source><?xml version='1.0' encoding='utf-8'?> +<tomcat-users> + <role rolename="tomcat"/> + <role rolename="role1"/> + <strong><role rolename="manager"/></strong> + <user username="tomcat" password="tomcat" roles="tomcat"/> + <user username="role1" password="tomcat" roles="role1"/> + <user username="both" password="tomcat" roles="tomcat,role1"/> + <strong><user username="manager" password="manager" roles="manager"/></strong> +</tomcat-users></source> + </section> + <section> + <title>To Start the Tomcat Server</title> + <p>At the command prompt, enter:</p> + <source>%CATALINA_HOME%\bin\startup.bat</source> + </section> + </section> + <section id="step_2"> + <title>Step 2: Create a New Page Flow Application</title> + <section> + <title>Introduction</title> + <p> + In this step you will create a Controller file and a JSP page. These are the basic files in a Beehive Page Flow web application. Each Page Flow contains one Controller file and any number of JSP pages. A Controller file is a Java class (with the JPF file extension) that controls how your web application functions and what it does. The methods in the Controller file determines all of the major features of a web application: how users navigate from page to page, how user requests are handled, and how the web application accesses back-end resources. The JSP pages determine what a visitor to the web sees in the browser. (In terms of the Model-View-Controller paradigm for web applications: the Controller.jpf file is the Controller (naturally), and the JSP pages are the View. This web application's Model is very simple: it consists of two fields that represent the user's age and name. <!--[tbd: more, explain]-->) + </p> + <p> + Controller files contain Action methods. An Action method may do something simple, such as forward a user from one JSP page to another; or it may do a complex set of tasks, such as receive user input from a JSP page, calculate and/or retrieve other data based on the user input, and forward the user to a JSP page where the results are displayed. <!--[tbd: diagram, etc.]--> + </p> + <p> + The Controller file you create in this step contains one simple Action method. This simple navigational Action method forwards users to the index.jsp page. In the next step, you will create a more complex Action method. + </p> + </section> + <section> + <title>Make a Project Folder</title> + <p>On your C: drive, create a directory named <code>beehive_projects</code>.</p> + <p>In the <code>beehive_projects</code> directory, create a directory named <code>pageflow_tutorial</code></p> + <p>Before proceeding, confirm that the following directory structure exists:</p> + <source>C: + beehive_projects + pageflow_tutorial</source> + </section> + <section> + <title>To Copy Page Flow Resources into the Project Folder</title> + <p>In this step you will copy (most of) the Page Flow application template into your project folder. The application template gives the basic directory structure for a Page Flow web app, and it includes some common resources, for example: image files, supporting JavaScript files, and web app configuration files.</p> + <p>Copy the folder <code>BEEHIVE_HOME/samples/netui-blank/resources</code> into your project folder <code>C:\beehive_projects\pageflow_tutorial</code>.</p> + <p>Copy the folder <code>BEEHIVE_HOME/samples/netui-blank/WEB-INF</code> into your project folder <code>C:\beehive_projects\pageflow_tutorial</code>.</p> + <p>Before proceeding, confirm that the following directory structure exists:</p> +<source>C: + beehive_projects + pageflow_tutorial + resources + WEB-INF</source> + <p>Note: do <em>not</em> copy the files <code>Controller.jpf</code>, <code>index.jsp</code>, or <code>error.jsp</code>. For the sake of instruction, you will create these files from scratch in the steps below. </p> + <p>If you see the following directory structure you have made a mistake.</p> + <source>C: + beehive_projects + pageflow_tutorial + resource + WEB-INF + Controller.jpf - WRONG! + error.jsp - WRONG! + index.jsp - WRONG!</source> + <p>Note: do <em>not</em> copy the folder <code>netui-blank</code> into your project folder.</p> + <p>If you see the following directory structure you have made a mistake.</p> + <source>C: + beehive_projects + pageflow_tutorial + netui-blank - WRONG!</source> +<p></p> + </section> + <section> + <title>To Copy Runtime JARs to the Project Folder</title> + <p>In this step you will assemble the runtime resources for your Page Flow application. The runtime JARs include the Page Flow runtime, the <netui> tag library, etc. These resources are loaded into your project's <code>WEB-INF/lib</code> folder using the Ant command below.</p> + <p>At the command prompt, enter the following Ant command:</p> + <source> ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=C:\beehive_projects\pageflow_tutorial + deploy.beehive.webapp.runtime</source> + <p>Before proceeding, confirm that the following directory structure exists:</p> +<source>C: + beehive_projects + pageflow_tutorial + WEB-INF + lib + [many JAR files]</source> + </section> + <section> + <title>To Create a Controller File</title> + <p>In this step you will create the Controller file, the central file on any Page Flow.</p> + <p>In the directory <code>C:/beehive_projects/pageflow_tutorial</code>, create a file named <code>Controller.jpf</code>.</p> + <p>In a text editor (or your IDE of choice), open the file Controller.jpf.</p> + <p>Edit <code>Controller.jpf</code> so it appears as follows.</p> + <source><![CDATA[import org.apache.beehive.netui.pageflow.PageFlowController; +import org.apache.beehive.netui.pageflow.Forward; +import org.apache.beehive.netui.pageflow.annotations.Jpf; + [EMAIL PROTECTED] +public class Controller extends PageFlowController +{ + @Jpf.Action( + forwards={ + @Jpf.Forward(name="success", path="index.jsp") + } + ) + protected Forward begin() + { + return new Forward("success"); + } +}]]></source> + <!--<p>[todo: what is this code doing?]</p>--> + <p>Save and close the file Controller.jpf.</p> + </section> + <section> + <title>To Create a JSP File</title> + <p>In the directory <code>C:/beehive_projects/pageflow_tutorial</code>, create a file named <code>index.jsp</code>.</p> + <p>Edit <code>index.jsp</code> so it looks like the following.</p> + <source><![CDATA[<%@ page language="java" contentType="text/html;charset=UTF-8"%> +<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0"; prefix="netui"%> +<netui:html> + <head> + <title>index.jsp</title> + <netui:base/> + </head> + <netui:body> + <p> + index.jsp + </p> + </netui:body> +</netui:html>]]></source> + </section> + <section> + <title>To Compile and Deploy the Page Flow</title> + <p>You are now ready to compile the Page Flow and deploy it to Tomcat.</p> + <p>Using the command shell opened in the previous step, at the command prompt, enter:</p> +<source>ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=C:\beehive_projects\pageflow_tutorial + -Dcontext.path=pageflow_tutorial + build.webapp + deploy</source> +<p>Note: if you get an error stating that the <code>/pageflow_tutorial</code> context path already exists, then use the following Ant command to first undeploy the application from Tomcat. (You might be getting this error if this is your second time running through the tutorial.)</p> +<source>ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=C:\beehive_projects\pageflow_tutorial + -Dcontext.path=pageflow_tutorial + undeploy</source> + <p>When the undeploy is complete, then compile and deploy again.</p> + </section> + <section> + <title>To Test the Page Flow Web Application</title> + <p>Visit the following address:</p> + <p><fork href="http://localhost:8080/pageflow_tutorial";>http://localhost:8080/pageflow_tutorial</fork></p> + <p>You will be directed to the <code>index.jsp</code> page.</p> + </section> + </section> + <section id="step_3"> + <title>Step 3: Navigation</title> + <section> + <title>To Create a Destination JSP Page</title> + <p>In the directory <code>C:/beehive_projects/pageflow_tutorial</code>, create a file named <code>page2.jsp</code>.</p> + <p>Edit page2.jsp so it looks like the following.</p> + <source><![CDATA[<%@ page language="java" contentType="text/html;charset=UTF-8"%> +<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0"; prefix="netui"%> +<netui:html> + <head> + <title>page2.jsp</title> + <netui:base/> + </head> + <netui:body> + <p> + Welcome to page2.jsp! + </p> + </netui:body> +</netui:html>]]></source> + <p>Save and close <code>page2.jsp</code>.</p> + </section> + <section> + <title>To Create a Link to the Destination Page</title> + <p>Open the file <code>C:/beehive_projects/pageflow_tutorial/index.jsp</code>.</p> + <p>Edit <code>index.jsp</code> so it appears as follows. Code to add appears in bold type.</p> + <source> +<%@ page language="java" contentType="text/html;charset=UTF-8"%> +<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0"; prefix="netui"%> +<netui:html> + <head> + <title>index.jsp</title> + <netui:base/> + </head> + <netui:body> + <p> + index.jsp + </p> + <strong><p> + <netui:anchor action="toPage2">Link to page2.jsp</netui:anchor> + </p></strong> + </netui:body> +</netui:html> + </source> + </section> + <section> + <title>To Add an Action Method to Handle the Link</title> + <p>Open the file <code>C:/beehive_projects/pageflow_tutorial/Controller.jpf</code>.</p> + <p>Edit <code>Controller.jpf</code> so it appears as follows.</p> + <source>import org.apache.beehive.netui.pageflow.PageFlowController; +import org.apache.beehive.netui.pageflow.Forward; +import org.apache.beehive.netui.pageflow.annotations.Jpf; + [EMAIL PROTECTED] +public class Controller extends PageFlowController +{ + @Jpf.Action( + forwards={ + @Jpf.Forward(name="success", path="index.jsp") + } + ) + protected Forward begin() + { + return new Forward("success"); + } + + <strong>@Jpf.Action( + forwards={ + @Jpf.Forward(name="success", path="page2.jsp") + } + ) + public Forward toPage2() + { + return new Forward("success"); + }</strong> +}</source> + </section> + <section> + <title>To Compile and Redeploy the Page Flow</title> + <p>At the command prompt, enter:</p> +<source>ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=C:\beehive_projects\pageflow_tutorial + -Dcontext.path=pageflow_tutorial + undeploy + build.webapp + deploy</source> + </section> + <section> + <title>To Test the Page Flow Web Application</title> + <p>Visit the following link: + </p> + <p><fork href="http://localhost:8080/pageflow_tutorial";>http://localhost:8080/pageflow_tutorial</fork></p> + <p>You will be directed to the index.jsp page.</p> + <p>Click the link.</p> + <p>You will be directed to page2.jsp.</p> + </section> + </section> + <section id="step_4"> + <title>Step 4: Submitting Data</title> + <section> + <title>To Create a Submission Form</title> + <p>Edit the file <code>C:/beehive_projects/pageflow_tutorial/page2.jsp</code> so it appears as follows.</p> + <source><%@ page language="java" contentType="text/html;charset=UTF-8"%> +<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0"; prefix="netui"%> +<netui:html> + <head> + <title>page2.jsp</title> + <netui:base/> + </head> + <netui:body> + <p> + Welcome to page2.jsp! + </p> + <strong><p> + <netui:form action="processData"> + <p>Name:<netui:textBox dataSource="actionForm.name"/> + <p>Age:<netui:textBox dataSource="actionForm.age"/> + <p><netui:button type="submit">Submit</netui:button> + </netui:form> + </p></strong> + </netui:body> +</netui:html></source> +<p>Save and close <code>page2.jsp</code>.</p> + </section> + + <section> + <title>To Create a Server Side Representation of the Submission Form</title> + <p>In this step you will create a Java class that represents the submission form created in the previous task. When the form data is submitted, the Java class will be instantiated, and the form data will be loaded into the members of the Java class.</p> + <p>In the directory <code>C:/beehive_projects/pageflow_tutorial/WEB-INF/src</code> create a directory named <code>forms</code>.</p> + <p>In the directory <code>C:/beehive_projects/pageflow_tutorial/WEB-INF/src/forms</code> create a JAVA file named <code>ProfileForm.java</code>.</p> + <p>Edit <code>C:/beehive_projects/pageflow_tutorial/WEB-INF/src/forms/ProfileForm.java</code> so it appears as follows.</p> + <source>package forms; + +public class ProfileForm +{ + private int age; + private String name; + + public void setName(String name) + { + this.name = name; + } + + public String getName() + { + return this.name; + } + + public void setAge(int age) + { + this.age = age; + } + + public int getAge() + { + return this.age; + } +}</source> +<p>Save and close <code>ProfileForm.java</code>.</p> + </section> + <section> + <title>To Edit the Controller File to Handle the Submitted Data</title> + <p>Open the file <code>C:/beehive_projects/pageflow_tutorial/Controller.jpf</code> + </p> + <p>Edit <code>Controller.jpf</code> so it appears as follows. Code to add appears in bold type.</p> + <source>import org.apache.beehive.netui.pageflow.Forward; +import org.apache.beehive.netui.pageflow.PageFlowController; +import org.apache.beehive.netui.pageflow.annotations.Jpf; +<strong>import forms.ProfileForm;</strong> + [EMAIL PROTECTED] +public class Controller extends PageFlowController +{ + @Jpf.Action( + forwards={ + @Jpf.Forward(name="success", path="index.jsp") + } + ) + public Forward begin() + { + return new Forward("success"); + } + + @Jpf.Action( + forwards={ + @Jpf.Forward(name="success", path="page2.jsp") + } + ) + public Forward toPage2() + { + return new Forward("success"); + } + + <strong>@Jpf.Action( + forwards = { + @Jpf.Forward(name = "success", path = "page2.jsp") + } + ) + public Forward processData(ProfileForm form) + { + System.out.println("Name: " + form.getName()); + System.out.println("Age: " + form.getAge()); + return new Forward("success"); + }</strong> +}</source> + <!--<p>[TODO: what is this code doing?]</p>--> + <p>Save and close <code>Controller.jpf</code>.</p> + </section> + <section> + <title>To Compile and Redeploy the Page Flow</title> + <p>At the command prompt, enter:</p> +<source>ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=C:\beehive_projects\pageflow_tutorial + -Dcontext.path=pageflow_tutorial + undeploy + build.webapp + deploy</source> + </section> + <section> + <title>To Test the Page Flow Web Application</title> + <p>Visit the following link: + </p> + <p><fork href="http://localhost:8080/pageflow_tutorial";>http://localhost:8080/pageflow_tutorial</fork></p> + <p>You will be directed to the index.jsp page.</p> + <p>Click the link.</p> + <p>You will be directed to page2.jsp.</p> + <p>Enter values in the Name and Age fields, and click Submit.</p> + <p>Notice the name and age values you entered are displayed in the Tomcat console shell.</p> + </section> + </section> + <section id="step_5"> + <title>Step 5: Processing and Displaying Data</title> + <section> + <title>To Create a JSP Page to Display Submitted Data</title> + <p>In the directory <code>C:/pageflow_tutorial</code> Create a file named <code>displayData.jsp</code>. Edit <code>displayData.jsp</code> so it appears as follows.</p> + <source><![CDATA[<%@ page language="java" contentType="text/html;charset=UTF-8"%> +<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0"; prefix="netui"%> +<netui:html> + <head> + <title>displayData.jsp</title> + <netui:base/> + </head> + <netui:body> + <p>Name:<netui:span value="${requestScope.data.name}"/> + <p>Age:<netui:span value="${requestScope.data.age}"/> + </netui:body> +</netui:html>]]></source> + </section> + <section> + <title>To Process the Submitted Data</title> + <p>Edit the processData method in the Controller.jpf file so it appears as follows. Code to add appears in bold.</p> + <source> @Jpf.Action( + forwards = { + @Jpf.Forward(name = "success", path = "displayData.jsp") + } + ) + public Forward processData(ProfileForm form) + { + System.out.println("Name: " + form.getName()); + System.out.println("Age: " + form.getAge()); + <strong>getRequest().setAttribute("data", form);</strong> + return new Forward("success"); + }</source> + </section> + <section> + <title>To Compile and Redeploy the Page Flow</title> + <p>At the command prompt, enter:</p> +<source>ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=C:\beehive_projects\pageflow_tutorial + -Dcontext.path=pageflow_tutorial + undeploy + build.webapp + deploy</source> + </section> + <section> + <title>To Test the Page Flow Web Application</title> + <p>Visit the following link: + </p> + <p><fork href="http://localhost:8080/pageflow_tutorial";>http://localhost:8080/pageflow_tutorial</fork></p> + <p>You will be directed to the index.jsp page.</p> + <p>Click the link.</p> + <p>You will be directed to page2.jsp.</p> + <p>Enter values in the Name and Age fields. Click the Submit button.</p> + <p>You will be forwarded to the displayData.jsp page. Notice the values you entered are displayed.</p> + </section> + </section> +<!-- <section id="summary"> + <title>Summary: Page Flow Tutorial</title> + <p>This tutorial introduced you to the basics of building web applications with Beehive Page Flows.</p> + <p>Concepts and Tasks Introduced in This Tutorial</p> + <p> + [TODO: complete summary] + </p> + </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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/reference.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/reference.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/reference.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,35 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v13.dtd";> +<document> + <header> + <title>Beehive Reference Documentation</title> + </header> + <body> + <p>[todo: links to reference topics]</p> +<!-- These links temporarily turned off. Turning them on breaks the doc build, since these index.html pages +are javadoc-generated, but the javadoc portion of the doc build occurs after the forrest portion. + <ul> + <li> + <fork href="reference/taglib/index.html">Page Flow <netui> Tag Reference</fork> + </li> + <li> + <fork href="reference/classref_pageflows/index.html">Page Flow API Reference</fork> + </li> + <li> + <fork href="pageflow/config/netui-config.html">Configuration: netui-config.xml</fork> + </li> + <li> + <fork href="reference/classref_controls/index.html">Controls API Reference</fork> + </li> + <li> + <fork href="reference/classref_wsm/index.html">Web Services Metadata API Reference</fork> + </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/> + © 2004, Apache Software Foundation + </legal> + </footer> +</document> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/setup.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/setup.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/setup.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,103 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd"> +<document> + <header> + <title>Beehive Installation and Setup</title> + </header> + <body> + <p>This topic explains how to install and set up the Beehive development environment on your machine.</p> + <section> + <title>To Download and Install a Beehive Binary Distribution</title> + <p>Visit (<fork href="http://cvs.apache.org/dist/incubator/beehive/v1.0-alpha/bin/";>http://cvs.apache.org/dist/incubator/beehive/v1.0-alpha/bin/</fork>) and download the latest binary distribution of Beehive. Note that the current release of Beehive is an alpha: it is <em>not</em> for building production-level applcations.</p> + <p>Unzip the Beehive distribution file on your machine</p> + </section> + <section> + <title>To Download and Install J2SE5</title> + <p>If you do not have J2SE5 installed, visit <fork href="http://java.sun.com/j2se/1.5.0/download.jsp";>http://java.sun.com/j2se/1.5.0/download.jsp</fork>. + </p> + <p>Download and install the latest version of J2SE5.</p> + </section> + <section> + <title>To Install ANT 1.6.2</title> + <p>If you do not have Ant 1.6.2 installed, visit <fork href="http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/ant/apache-ant-1.6.2-bin.zip";>http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/ant/apache-ant-1.6.2-bin.zip</fork>. + </p> + <p>Download the ZIP file and unzip it on your machine.</p> + </section> + <section> + <title>To Download and Install Tomcat 5</title> + <p>If you do not have Tomcat 5 installed, visit <fork href="http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/tomcat/jakarta-tomcat-5.0.25.zip";>http://svn.apache.org/repos/asf/incubator/beehive/trunk/external/tomcat/jakarta-tomcat-5.0.25.zip</fork> + </p> + <p>Download the ZIP file and unzip it on your machine.</p> + </section> + <section> + <title>To Set up the Development Environment</title> + <p>Open the top level directory of the Beehive distribution (for example, <code>C:/apache-beehive-incubating-1.0-alpha-snapshot</code>). Open the file <code>beehiveUser.cmd</code> in a text editor and edit it to fit your local environment. The following environmental variables must be set to the appropriate paths on your machine: <code>BEEHIVE_HOME</code>, <code>JAVA_HOME</code>, <code>ANT_HOME</code>, and <code>CATALINA_HOME</code>. The following example shows how to edit <code>beehiveUser.cmd</code> for a typical environment.</p> + <source>REM the root of Beehive distribution +set BEEHIVE_HOME=C:\apache-beehive-incubating-1.0-alpha-snapshot + +REM location of a JDK +set JAVA_HOME=C:\jdk1.5.0 + +REM location of Ant +set ANT_HOME=C:\apache-ant-1.6.2 + +REM location of Tomcat +set CATALINA_HOME=C:\jakarta-tomcat-5.0.25</source> + <p>When you finished editing <code>beehiveUser.cmd</code>, save and close the file.</p> + <p>Open a command shell.</p> + <p>cd to the directory where <code>beehiveUser.cmd</code> resides (= the top level directory of the Beehive distribution).</p> + <p>At the command prompt, enter: <code>beehiveUser.cmd</code> + </p> + </section> + <section> + <title>Add a Manager Role to Tomcat (Optional)</title> + <p>Adding the manager role to Tomcat server allows you to run deployment-related targets in the Ant file <code>BEEEHIVE_HOME/ant/runTomcat.xml</code>. This file is provided as a convenience for managing the Tomcat server.</p> + <p>Edit the file <code>CATALINA_HOME/conf/tomcat-users.xml</code> so it appears as follows. Elements to add are shown in bold type.</p> + <source><?xml version='1.0' encoding='utf-8'?> +<tomcat-users> + <role rolename="tomcat"/> + <role rolename="role1"/> + <strong><role rolename="manager"/></strong> + <user username="tomcat" password="tomcat" roles="tomcat"/> + <user username="role1" password="tomcat" roles="role1"/> + <user username="both" password="tomcat" roles="tomcat,role1"/> + <strong><user username="manager" password="manager" roles="manager"/></strong> +</tomcat-users></source> + </section> + <section> + <title>Start Tomcat (Optional)</title> + <p>Before running the samples and tutorials ensure that Tomcat is turned on. Run the following Ant command to startup Tomcat:</p> + <source>%CATALINA_HOME%\bin\startup.bat</source> + <p>Or use the Ant command provided in the distribution: </p> + <source>ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml start</source> + <p>If you use the provided Ant command, you will have to press <code>Ctrl+C</code> to continue issuing commands in that command shell.</p> + </section> + <section> + <title>What Now?</title> + <p>You are now ready to begin developing Beehive applications. The following tutorials introduce the basic development cycle:</p> + <ul> + <li><link href="controls/tutorial_controls.html">Beehive Controls Tutorial</link></li> + <li><link href="pageflow/tutorial_pageflow.html">Beehive Page Flow Tutorial</link></li> + <li><link href="wsm/tutorial_wsm.html">Beehive Web Service Tutorial</link></li> + </ul> + <p>You can also begin running the following samples:</p> + <ul> + <li><link href="jpetstore.html">Beehive Sample: Petstore</link></li> + <li><link href="wsm/sample_Dashboard.html">Beehive Web Service Sample: Petstore Dashboard</link></li> + <li><link href="wsm/sample_AddressBook.html">Beehive AddressBookWS and EmployeeWS Samples</link></li> + <li><link href="controls/sample_controls-db.html">Database Control Sample</link></li> + </ul> + <p>The following application templates will help you get a project started:</p> + <ul> + <li><link href="pageflow/sample_netui-blank.html">Page Flow Project Template</link></li> + <li><link href="controls/sample_controls-blank.html">Control Project Template</link></li> + <li><link href="wsm/sample_wsm-blank.html">Web Service Project Template</link></li> + </ul> + </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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,55 @@ +<?xml version="1.0"?> +<site label="Beehive" href="" xmlns="http://apache.org/forrest/linkmap/1.0";> + <about label="Beehive"> + <index label="Welcome" href="index.html"/> + <license label="License" href="license.html"/> + <downloads label="Downloads" href="downloads.html"/> + <faq label="FAQ" href="faq.html"/> + </about> + <documentation label="Documentation"> + <setup label="Installation and Setup" href="setup.html" /> + <!--<beehive label="Beehive"> + <guide label="Putting the Pieces Together" href="beehive/guide.html"/> + </beehive>--> + <pageflow label="Page Flows"> + <pageflow_overview label="Page Flow Overview" href="pageflow/pageflow_overview.html"/> + <pageflow_controllers label="Page Flow Controllers" href="pageflow/pageflow_controllers.html"/> + <pageflow_jsp label="Page Flow JSP" href="pageflow/pageflow_jsp.html"/> + <pageflow_building label="Building a Page Flow Web-App" href="pageflow/pageflow_building.html"/> + <pageflow_altering label="Altering a Page Flow" href="pageflow/pageflow_altering.html"/> + <pageflow_programming label="Page Flow Programming" href="pageflow/guide.html"/> + <tutorial_pageflow label="Page Flow Tutorial" href="pageflow/tutorial_pageflow.html"/> + </pageflow> + <controls label="Controls"> + <control_overview label="Controls Overview" href="controls/controlsOverview.html"/> + <control_prog label="Control Programming" href="controls/controlsProgramming.html"/> + <tutorial_control label="Control Tutorial" href="controls/tutorial_controls.html"/> + </controls> + <wsm label="Web Services"> + <jsr181 label="Web Services (JSR 181)" href="webservices.html"/> + <supported_datatypes label="Supported Data Types" href="wsm/datatypes.html"/> + <tutorial_wsm label="Web Services Tutorial" href="wsm/tutorial_wsm.html"/> + </wsm> + <samples label="Samples"> + <jpetstore label="Petstore" href="jpetstore.html"/> + <dash label="Petstore Dashboard" href="wsm/sample_Dashboard.html"/> + <address label="AddressBook/Employee" href="wsm/sample_AddressBook.html"/> + <db label="Database Control" href="controls/sample_controls-db.html"/> + <control-blank label="Page Flow Project" href="pageflow/sample_netui-blank.html"/> + <control-blank label="Control Project" href="controls/sample_controls-blank.html"/> + <wsm-blank label="Web Service Project" href="wsm/sample_wsm-blank.html"/> + </samples> + <ref label="Reference Docs" href="reference.html"/> + <!--<gloss label="Glossary" href="glossary.html"/>--> + <!--<source label="Beehive Source"> + <building label="Building Beehive" href="building.html"/> + </source>--> + </documentation> + <community label="Community"> + <mailinglists label="Mailing Lists" href="mailinglists.html"/> + <contributors label="Contributors" href="contributors.html"/> + </community> + <external-refs> + <xml.apache.org href="http://xml.apache.org/"/> + </external-refs> +</site> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/tabs.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/tabs.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/tabs.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,10 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE tabs PUBLIC "-//APACHE//DTD Cocoon Documentation Tab V1.0//EN" "tab-cocoon-v10.dtd"> + +<tabs software="Apache Beehive" + title="Apache Beehive" + copyright="Apache Software Foundation" + xmlns:xlink="http://www.w3.org/1999/xlink";> + + <tab label="Home" dir=""/> +</tabs> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/webservices.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/webservices.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/webservices.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,25 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd"> + +<document> + +<header> + <title>Apache Beehive Web Services</title> +</header> + +<body> + +<p> +See the <fork href="http://wiki.apache.org/beehive/Web_20Services";>WSM on the Beehive wiki</fork> and the +<fork href="http://jcp.org/en/jsr/detail?id=181";>JSR 181 Spec</fork> for more information. +</p> + +</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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/datatypes.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/datatypes.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/datatypes.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,48 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd";> +<!--<!DOCTYPE document SYSTEM "C:\apache-forrest-0.5.1\context\resources\schema\dtd\document-v12.dtd">--> +<document> + <header> + <title>Supported Data Types</title> + </header> + <body> + <p>The following is a list of the types supported for use as parameters and return values in Beehive Web Services.</p> + <section id="standard"> + <title>Standard Java Types</title> + +<p>All standard Java types as specified in section 5.1 of the JAX-RPC spec (JSR-101) are supported. These types include some core Java classes that can easily convert to Strings (section 5.1.3), primitives, exceptions and arrays of types already deemed suitable.</p> + </section> + <section> + <title>JavaBeans</title> +<p>Java Value types (section 5.4 of JAX-RPC) are supported. These are standard JavaBeans with the requirements that (1) they have a default no argument constructor, (2) implement java.io.Serializable, but (3) do not implement java.rmi.Remote.</p> + + </section> + <section> + <title>Collections and Arrays</title> +<p>Collections are minimally supported: typed arrays are far superior. Support for JDK 5 typed Collections using Java Generics is being considered for the future. In the meantime use a typed array.</p> +</section> + +<section> + <title>XmlBeans</title> +<p>XmlBeans are supported as web service types.</p> +</section> + +<section> + <title>Attachments</title> +<p>DataHandler types provide attachment support in Apache Axis. If <code>activation.jar</code> and <code>mailapi.jar</code> are available, then developers can use java.awt.Image, javax.mail.internet.MimeMultipart as well as any classes extending javax.activation.DataHandler to transmit raw data as web service attachments. See the <link href="sample_Dashboard.html#Download+Required+JAR+Files">Petstore Dashboard Sample</link> for instructions on acquiring these JARs. If these types are used directly as return values or parameters, then the client must be an Axis client.</p> +</section> + +<section> + <title>Other Types</title> +<p>If you wish to use types not declared here, you can explicitly register your own serialization mechanism by adding code to register TypeMappings for custom type classes in a static block of those classes. See the Axis documentation for more information: <link href="http://ws.apache.org/axis/java/user-guide.html#DataMapping";>XML <-> Java Data Mapping in Axis</link> (see the section labeled "When Beans Are Not Enough - Custom Serialization").</p> +</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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/sample_AddressBook.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/sample_AddressBook.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/sample_AddressBook.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,107 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v13.dtd";> +<document> + <header> + <title>Beehive AddressBookWS and EmployeeWS Samples</title> + </header> + <body> + <section> + <title>The AddressBookWS and EmployeeWS Samples</title> + <p>The <strong>AddressBookWS</strong> sample is an annotation-aware web service based on the Apache Axis sample of the same name. AddressBookWS is organized as an application with POJO (Plain Old Java Objects) models, service interface, service implementation, and unit tests for the service. Apache Axis provides automatic client-generation and junit test cases for the sample. The directory structure and ant build file can be used as a template for building new standalone web services.</p> + <p><strong>EmployeeWS</strong> provides a web service interface for an Employee database. Using SOAP messages, the web service queries the backend database: selecting, updating and inserting employee data. A Beehive database control connects the web service and the database. The web service class is located at <code>EmployeeWS/WEB-INF/src/web/Service.jws</code>. The database control is located at <code>EmployeeWS/WEB-INF/src/org/apache/beehive/sample/EmployeeDBControl.jcx</code>. Note that EmployeeDBControl is a subclass of DatabaseControl, another Beehive sample. For more information see <link href="../controls/sample_controls-db.html">Database Control</link>. </p> +<p>Apache Derby supplies the database implementation. (Installing Derby requires a simple JAR file download, described below.) Apache Axis provides the automatic client-generation for the web service. Custom unit tests are provided to exercise the webservice methods. The unit tests creates the database table, inserts a new record, queries the database, and finally drops the table. Use the junit tests as a template for building automatic tests for your own controls.</p> + </section> + <section> + <title>Running the Samples</title> + <section> + <title>Requirements for Running the Sample</title> + <p>To run the Samples, you need:</p> + <ul> + <li>Beehive</li> + <li>Tomcat 5</li> + <li>J2SE 5</li> + <li>Ant 1.6.2</li> + <li>junit.jar (v3.8.1 or later)</li> + <li>derby_46005.jar (for EmployeeWS only)</li> + </ul> + </section> + <section> + <title>Setting up the Environment</title> + <p>Download a Beehive distribution archive (<fork href="http://cvs.apache.org/dist/incubator/beehive/v1.0-alpha/bin/";>http://cvs.apache.org/dist/incubator/beehive/v1.0-alpha/bin/</fork>), and explode it on your local machine. In the instructions below, the top level directory of the exploded Beehive archive is called '<code><dist-dir></code>'. For example if you explode the archive into </p> + <source>C:/beehive</source> + <p>then</p> + <source><dist-dir> = C:/apache-beehive-incubating-1.0-alpha-snapshot</source> + <p>Edit <code><dist-dir>/beehiveUser.cmd|sh</code> to match your local environment. The following four paths must resolve to paths on your machine.</p> + <source> + BEEHIVE_HOME + JAVA_HOME + CATALINA_HOME + ANT_HOME +</source> + <p> + <code>BEEHIVE_HOME</code> should refer to <dist-dir>:</p> + <source> +REM the root of Beehive distribution +set BEEHIVE_HOME=C:\beehive\apache-beehive-incubating-alpha-xxx +</source> + <p>After editing the file, open a command shell and run <code>beehiveUser.cmd|sh</code>.</p> + </section> + <p>Download junit.jar from <link href="http://prdownloads.sourceforge.net/junit/junit3.8.1.zip?download";>http://prdownloads.sourceforge.net/junit/junit3.8.1.zip?download</link> </p> + <p> Copy <code>junit.jar</code> to <code>ANT_HOME/lib</code>.</p> + <p> Download derby_46005.jar from <link href="http://incubator.apache.org/derby/binaries/derby_snapshot_svnversion_46005.ZIP";>http://incubator.apache.org/derby/binaries/derby_snapshot_svnversion_46005.ZIP</link>.</p> + <p> Copy <code>derby_46005.jar</code> to <code>BEEHIVE_HOME/samples/EmployeeWS/WEB-INF/lib</code>.</p> + <section> + <title>Setting up the Server</title> + <p> + <code>cd</code> to <dist-dir>. </p> + <p>Run the following Ant command:</p> + <source> ant -f ant\buildWebapp.xml start</source> + <p>This will start the Tomcat server located at <code>CATALINA_HOME</code>.</p> + <p>To build and deploy the web services, run the following Ant commands:</p> + <source> ant + -Dwebapp.dir=%BEEHIVE_HOME%\samples\AddressBookWS + -Dcontext.path=AddressBookWS + -f ant\buildWebapp.xml + deploy.wsm.webapp.runtime + build.webapp + deploy</source> + <source> ant + -Dwebapp.dir=%BEEHIVE_HOME%\samples\EmployeeWS + -Dcontext.path=EmployeeWS + -f ant\buildWebapp.xml + deploy.wsm.webapp.runtime + build.webapp + deploy</source> + <p>Verify that the web services are running by pointing your browser to:</p> + <p> + <fork href="http://localhost:8080/AddressBookWS/";>http://localhost:8080/AddressBookWS/</fork> + </p> + <p>and</p> + <p> + <fork href="http://localhost:8080/EmployeeWS/";>http://localhost:8080/EmployeeWS/</fork> + </p> + <p>Follow the validation links (<fork href="http://localhost:8080/AddressBookWS/happyaxis.jsp";>http://localhost:8080/AddressBookWS/happyaxis.jsp</fork> and <fork href="http://localhost:8080/EmployeeWS/happyaxis.jsp";>http://localhost:8080/EmployeeWS/happyaxis.jsp</fork>) to see the verification pages.</p> + <p>For the WSDLs visit</p> + <p><link href="http://localhost:8080/AddressBookWS/web/Service.jws?wsdl";> http://localhost:8080/AddressBookWS/web/Service.jws?wsdl</link></p> + <p><link href="http://localhost:8080/EmployeeWS/web/Service.jws?wsdl";> http://localhost:8080/EmployeeWS/web/Service.jws?wsdl</link></p> + </section> + <section> + <title>Setting up the Clients</title> + <p>To generate the clients run the following build files.</p> + <source> ant -f %BEEHIVE_HOME%/samples/AddressBookWS/WEB-INF/client-build.xml</source> + <p>and</p> + <source> ant -f %BEEHIVE_HOME%/samples/EmployeeWS/WEB-INF/client-build.xml</source> + <p>Note that you do not need to run a particular target within <code>client-build.xml</code>. Simply run the ant commands shown above and the client will be generated in <code>WEB-INF/build/generated</code>.</p> + <p>The clients consist of JUnit test cases that exercise the contract published in the WSDL. The final result shows the number of successfully passed JUnit tests.</p> + <p>The code generated in <code>/WEB-INF/build/generated/</code> can be used as a template to write your own client side applications.</p> + <p>Note that the client-build.xml scripts make certain assumptions about the context.path provided when the WS server is deployed. If the context.path differs from the name of the directory for a sample, the URLs in client-build.xml have to be adjusted accordingly. +</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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/sample_Dashboard.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/sample_Dashboard.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/sample_Dashboard.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,121 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v13.dtd";> +<document> + <header> + <title>Beehive Web Service Sample: Petstore Dashboard</title> + </header> + <body> + <section> + <title>The Petstore Dashboard Sample</title> + <p>Petstore has both a web site and a web service interface. The web site is designed for customer access; the web service is for employee access. Through the web service, employees update the prices and inventory seen on the customer web site. The Petstore Dashboard is a Swing client application for this web service. Updates made on the Dashboard are passed to the web service and ultimately the updates appear on the Petstore web site. +</p> +<!-- + <p>The Dashboard sample source code is located at <code>BEEHIVE_HOME/samples/PetStoreDashboard</code>. [todo: more about the code breakdown]</p> + <source><![CDATA[ + PetStoreDashboard + | - images + | - lib + | - src ]]></source> + --> + </section> + +<section> + <title>Running the Dashboard Sample</title> + <section> + <title>Requirements for Running the Sample</title> + <p>To run the Sample, you need:</p> + <ul> + <li>Beehive</li> + <li>Tomcat 5</li> + <li>J2SE 5</li> + <li>Ant 1.6.2</li> + <li>activation.jar (details below)</li> + <li>mailapi.jar (details below)</li> + </ul> + </section> + <section> + <title>Setting up the Environment</title> + <p>Download a Beehive distribution archive (<fork href="http://cvs.apache.org/dist/incubator/beehive/v1.0-alpha/bin/";>http://cvs.apache.org/dist/incubator/beehive/v1.0-alpha/bin/</fork>), and explode it on your local machine. In the instructions below, the top level directory of the exploded Beehive archive is called '<code><dist-dir></code>'. For example if you explode the archive into </p> + <source>C:/beehive</source> + <p>then</p> + <source><dist-dir> = C:/apache-beehive-incubating-1.0-alpha-snapshot</source> + <p>Edit <code><dist-dir>/beehiveUser.cmd|sh</code> to match your local environment. The following four paths must resolve to paths on your machine.</p> + <source> + BEEHIVE_HOME + JAVA_HOME + CATALINA_HOME + ANT_HOME +</source> + <p> + <code>BEEHIVE_HOME</code> should refer to <dist-dir>:</p> + <source> +REM the root of Beehive distribution +set BEEHIVE_HOME=C:\beehive\apache-beehive-incubating-alpha-xxx +</source> + <p>After editing the file, open a command shell and run <code>beehiveUser.cmd|sh</code>.</p> + </section> + <section> + <title>Start Tomcat</title> + <p>To start Tomcat, run the following command:</p> + <source>%CATALINA_HOME%\bin\startup.bat</source> + <p>You can also start Tomcat by running the following Ant command, provided in the buildWebapp.xml file:</p> + <source>ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml start</source> + <p><strong>Note:</strong> if you use the second of these methods for starting Tomcat, you will have to enter Ctrl+C into the command shell to enter any further commands.</p> + </section> + <section> + <title>Undeploy Petstore</title> + <p>If you have previously deployed Petstore, you must undeploy it now. (This allows you to recompile the Petstore source, which occurs in the next step.)</p> + <source> ant -Dwebapp.dir=BEEHIVE_HOME/samples/petstoreWeb -Dcontext.path=petstoreWeb -f ant/buildWebapp.xml undeploy</source> + </section> + <section> + <title>Download Required JAR Files</title> +<p> Before you can build Petstore Dashboard you must download 1) activation.jar and 2) mailapi.jar.</p> + +<p> 1) download activation.jar (<link href="http://java.sun.com/products/javabeans/glasgow/jaf.html";>http://java.sun.com/products/javabeans/glasgow/jaf.html</link>) </p> + + <p>Note that activation.jar is archived in the JAF 1.0.2 distribution ZIP file. Download the JAF 1.0.2 ZIP, extract activation.jar, and copy activation.jar into both </p> + +<source> BEEHIVE_HOME/samples/PetstoreDashboard/lib/ </source> + +<p>and</p> + +<source> BEEHIVE_HOME/samples/petstoreWeb/WEB-INF/lib</source> + +<p>2) mailapi.jar (<link href="http://java.sun.com/products/javamail/downloads/index.html";>http://java.sun.com/products/javamail/downloads/index.html</link>)</p> + +<p> mailapi.jar is archived in the JavaMail 1.3.2 distribution ZIP file. Download the JavaMail 1.3.2 ZIP, extract mailapi.jar, and copy mailapi.jar into both </p> + +<source> BEEHIVE_HOME/samples/PetstoreDashboard/lib/ </source> + +<p>and</p> + +<source> BEEHIVE_HOME/samples/petstoreWeb/WEB-INF/lib</source> + + </section> +<section> + <title>Initialize, Build and Deploy Petstore</title> +<p>To build and deploy Petstore, enter the following Ant command:</p> +<source>ant + -Dwebapp.dir=%BEEHIVE_HOME%/samples/petstoreWeb + -Dcontext.path=petstoreWeb + -f ant/buildWebapp.xml + deploy.beehive.webapp.runtime build.webapp deploy + </source> + <p>To launch the Dashboard:</p> + <p>cd to: <code>BEEHIVE_HOME/samples/PetstoreDashboard</code></p> + <p>At the command line, enter <code>ant</code></p> + <p></p> +<p>The Swing application comes up in its own window. Click on the different categories and modify price and quantity. The changes show up on the Petstore site (when the browser is refreshed). +</p> +<p> Note: If the petstoreWeb sample is deployed to Tomcat with a context.path different from "petstoreWeb", or if it is deployed to a different server than localhost:8080, then BEEHIVE_HOME/samples/PetstoreDashboard/build.xml needs to be modified accordingly. The client generator relies on these default values.</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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/sample_wsm-blank.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/sample_wsm-blank.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/sample_wsm-blank.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,76 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v13.dtd";> +<document> + <header> + <title>Web Service Project Sample Template</title> + </header> + <body> + <section id="intro"> + <title>Introduction</title> +<p>Use the "blank" web service sample (located at <code>BEEHIVE_HOME/samples/wsm-blank</code>) as a template for building your own web service applications. + +</p> + +<p>The sample contains everything needed in a basic web service application, except for the runtime JAR files. +</p> + </section> + <section> + <title>Using the Web Service Template</title> + <p>The following instruction assume that you have completed the basic Beehive set up procedure at <fork href="../setup.html">Set Up the Dev Environment</fork>.</p> + <p>To use the template, (1) copy the contents of <code>BEEHIVE_HOME/samples/wsm-blank</code> into your project folder, and (2) copy the runtime JARs to the project's WEB-INF/lib directory. +It is important to copy the <em>contents</em> of <code>wsm-blank</code> into your project folder, not the folder <code>wsm-blank</code> itself. After you have copied the contents of <code>wsm-blank</code> into your project folder, the following directory structure should exist:</p> +<source><Project-Folder> + WEB-INF + happyaxis.jsp + index.html</source> +<p> The following Ant command will copy the necessary runtime JARs to <code><Project-Folder>/WEB-INF/lib</code>, where <code><Project-Folder></code> is the path to your web service project folder: </p> +<source> ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=<Project-Folder> + deploy.wsm.webapp.runtime</source> + <p>To build and run the template, run the following Ant command. (Before running ensure that Tomcat is turned on: <code>%CATALINA_HOME%\bin\startup.bat</code>. Or use the Ant command provided in the distribution: <code>ant -f %BEEHIVE_HOME%\ant\buildWebapp.xml start</code>. If you use the provided Ant command, you will have to press <code>Ctrl+C</code> to continue issuing commands in that command window.)</p> +<source> ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=<Project-Folder> + -Dcontext.path=HelloWorldWS + build.webapp + deploy</source> +<p>If the HelloWorldWS web service is already deployed, use the redeploy target:</p> +<source> ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=<Project-Folder> + -Dcontext.path=HelloWorldWS + build.webapp + redeploy</source> +<p>You can now try out the HelloWorldWS web service by pointing your browser at the following links.</p> + <ul> + <li>Start Page: <fork href="http://localhost:8080/HelloWorldWS/";>http://localhost:8080/HelloWorldWS/</fork></li> + <li>WSDL: <fork href="http://localhost:8080/HelloWorldWS/template/Blank.jws?wsdl";>http://localhost:8080/HelloWorldWS/template/Blank.jws?wsdl</fork></li> + <li>Invoke the sayHelloWorld() method in Blank.java: <fork href="http://localhost:8080/HelloWorldWS/template/Blank.jws?method=sayHelloWorld";>http://localhost:8080/HelloWorldWS/template/Blank.jws?method=sayHelloWorld</fork></li> +</ul> + <!--<source> +netui-blank + resources + beehive + version + images + error-handling.jpg - header image for the error.jsp page + javascript + netui-tree.js - JavaScript file to support the <netui:tree> tag + WEB-INF + src + global + Global.app - a global Page Flow useful for common operations, error handling, etc. + log4j.xml - the log4j configuration file + netui-config.xml - + netui-validator-rules.xml + web.xml +</source>--> + </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> Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/tutorial_wsm.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/tutorial_wsm.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/wsm/tutorial_wsm.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,326 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd";> +<!--<!DOCTYPE document SYSTEM "C:\apache-forrest-0.5.1\context\resources\schema\dtd\document-v12.dtd">--> +<document> + <header> + <title>Beehive Web Service Tutorial</title> + </header> + <body> + <section id="intro"> + <title>Introduction</title> + <p>This tutorial introduces you to the basic development cycle for Beehive web services. The tutorial assumes that you are working on a Windows machine. But, with a little common sense, it is easy to execute the tutorial on a Unix machine. For example, when you are asked to run the file <code>beehiveUser.cmd</code>, run the file <code>beehiveUser.sh</code> instead.</p> + <p><strong>Tutorial Goals</strong></p> + <p>In this tutorial, you will learn:</p> + <ul> + <li>How to create a basic Beehive web service application.</li> + <li>How to use (JSR 175 and 181) metadata annotations.</li> + <li>How to deploy and test a web service to Tomcat</li> + </ul> + </section> + <section id="step1"> + <title>Step 1: Begin the Web Service Tutorial</title> +<section> + <title>To Set up the Development Environment</title> + <p>Follow the setup directions at <fork href="../setup.html">Beehive Installation and Setup</fork></p> + <p>After completing the instructions, leave the command shell open to use throughout this tutorial.</p> + </section> + <section> + <title>Add a Manager Role to Tomcat</title> + <p>Adding the manager role to Tomcat server allows you to run deploy related targets in the Ant file <code>runTomcat.xml</code>. This file is provided as a convenience for managing the Tomcat server.</p> +<p>Edit the file <code>CATALINA_HOME/conf/tomcat-users.xml</code> so it appears as follows:</p> + <source><![CDATA[<?xml version='1.0' encoding='utf-8'?> +<tomcat-users> + <role rolename="tomcat"/> + <role rolename="role1"/> + <role rolename="manager"/> + <user username="tomcat" password="tomcat" roles="tomcat"/> + <user username="role1" password="tomcat" roles="role1"/> + <user username="both" password="tomcat" roles="tomcat,role1"/> + <user username="manager" password="manager" roles="manager"/> +</tomcat-users>]]></source> + </section> + <section> + <title>To Start the Tomcat Server</title> + <p>At the command prompt, enter:</p> + <source>%CATALINA_HOME%\bin\startup.bat</source> + </section> + </section> + <section id="step_2"> + <title>Step 2: Install the Web Service Template</title> + <!--<section> + <title>Introduction</title> + <p>[todo]</p> + </section>--> + <section> + <title>Make a Project Folder</title> + <p>On your C: drive, create a directory called <code>beehive_projects</code>.</p> + <p>In the <code>beehive_projects</code> directory, create a directory called ws_tutorial.</p> + <p>Before proceeding, confirm that the following directory structure exists:</p> + <source>C: + beehive_projects + ws_tutorial</source> + </section> + <section> + <title>To Copy the Web Services Application Template</title> + <p>In this step you will copy the Web Services project template into your project folder. The project template contains a simple web service and a test JSP page.</p> + <p>Copy the contents of the folder</p> + <source>BEEHIVE_HOME/samples/wsm-blank</source> + <p>into your project folder</p> + <source>C:/beehive_projects/ws_tutorial</source> + <p>It is important that you copy the <em>contents</em> of <code>wsm-blank</code>; do not copy the folder <code>wsm-blank</code> itself.</p> + <p>Before proceeding, confirm that the following directory structure exists:</p> + <source>C: + beehive_projects + ws_tutorial + WEB-INF + happyaxis.jsp + index.html</source> + </section> + <section> + <title>Copy the Runtime JARs into the Project Folder</title> + <p>To copy the runtime JARs into your project, run the following Ant command:</p> +<source>ant + -Dwebapp.dir=C:\beehive_projects\ws_tutorial + -f ant\buildWebapp.xml + deploy.wsm.webapp.runtime</source> + <p>This will copy the JAR files from <code>BEEHIVE_HOME/lib/wsm</code> into <code>C:/beehive_projects/ws_tutorial/WEB-INF/lib</code>.</p> + </section> + <section> + <title>Examine the Blank.jws Web Service</title> + <p>You are now ready to compile and run your web service.</p> + <p>Before proceeding, lets examine the web service code. In a text editor of your choice, open the file <code>C:/beehive_projects/ws_tutorial/WEB-INF/src/template/Blank.jws</code>. The file extension 'JWS' stands for Java Web Service. Beehive web services do not require the JWS extension, but it is recommended that you use JWS, especially when working in conjunction Beehive Controls and Page Flows.</p> + <source><![CDATA[package template; +... +import javax.jws.WebMethod; +import javax.jws.WebService; + [EMAIL PROTECTED] +public class Blank +{ + @WebMethod + public String sayHelloWorld() + { + return "Hello world!"; + } +}]]></source> +<p>The web service looks like a familiar Java class, although these two elements may be new to you:</p> +<source> + @WebService + @WebMethod +</source> +<p><code>@WebService</code> and <code>@WebMethod</code> are "metadata annotations", a.k.a. "annotations". Annotations allow you to set properties on Java classes and methods. They can be used to generate compile-time artifacts such as configuration files or Java classes (this is how many Beehive Control annotations work) or to determine some runtime behavior (this is how Beehive Web Service annotations work). <code>@WebService</code> annotates (or "decorates") the class Blank: this tells the runtime that Blank is a web service that listens for SOAP messages and responds in kind. <code>@WebMethod</code> annotates the method sayHelloWorld(): this tells the runtime that the method can be invoked over the web.</p> + </section> + <section> + <title>Compile and Deploy the Web Service</title> + <p>In this step you will compile the web service and deploy it to Tomcat, all in one step.</p> + <p>Run the following Ant command:</p> + <source> ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=C:\beehive_projects\ws_tutorial + -Dcontext.path=ws_tutorial + build.webapp + deploy</source> + <p>If the application is already deployed on Tomcat (which may happen if this is your second time executing the tutorial), use the redeploy command below:</p> + <source> ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=C:\beehive_projects\ws_tutorial + -Dcontext.path=ws_tutorial + build.webapp + redeploy</source> + </section> + <section> + <title>To Run the Web Service Provided in the Template</title> + <p>Visit the index.jsp page: <fork href="http://localhost:8080/ws_tutorial/index.html";>http://localhost:8080/ws_tutorial/index.html</fork>.</p> + <p>Click the "Validate" link for an evaluation of the resources available to your web service. Note that you will need to download additional resources to take full advantage of Beehive web services. For example, for Axis to work properly with SOAP attachments, additional, external jars (activation.jar and mailapi.jar) are required. You will download those resources in later steps in the tutorial.</p> + <p>Click the "WSDL" link to see the web service's WSDL. </p> + <p>Click the "sayHelloWorld()" link to see a SOAP response from the web service's sayHelloWorld() method.</p> + </section> + </section> + <section id="step_3"> + <title>Step 3: Add a Parameterized Method to the Web Service</title> + <section> + <title>Edit the JWS File</title> + <p/> + <p>Edit the file <code>C:/beehive_projects/ws_tutorial/WEB-INF/src/template/Blank.jws</code> so it appears as follows. Code to add appears in bold type.</p> + <source>package template; +... +import javax.jws.WebMethod; +import javax.jws.WebService; +<strong>import javax.jws.WebParam;</strong> + [EMAIL PROTECTED] +public class Blank +{ + @WebMethod + public String sayHelloWorld() + { + return "Hello world!"; + } + + <strong>@WebMethod + public String sayHello( @WebParam String greetee ) + { + if( greetee.equals("") ) + { greetee = "World"; } + + return "Hello, " + greetee + "!"; + }</strong> +}</source> +<p>The <code>@WebParam</code> you just added lets you pass a String parameter to the method over the web.</p> + </section> + <section> + <title>Compile and Redeploy the Web Service</title> + <p>At the command prompt, enter the following Ant command:</p> + <source> ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=C:\beehive_projects\ws_tutorial + -Dcontext.path=ws_tutorial + build.webapp + redeploy</source> + <p>This Ant command compiles the app, undeploys it, and then deploys it. Calling <code>ant ... redeploy</code> is equivalent to calling <code>ant ... undeploy deploy</code>.</p> + </section> + <section> + <title>Test the Parameterized Method</title> + <p>Enter the following URL in the address bar of your browser. </p> + <p><fork href="http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayHello&greetee=Moon";>http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayHello&greetee=Moon</fork></p> + <p>The following SOAP response appears in the browser:</p> + <source><![CDATA[<soapenv:Envelope> + <soapenv:Body> + <sayHelloResponse> + <ns1:result>Hello, Moon!</ns1:result> + </sayHelloResponse> + </soapenv:Body> +</soapenv:Envelope> +]]></source> + </section> + </section> + <section> + <title>Step 4: Add a Non-Web Invokable Method</title> + <p>Edit the file <code>C:/beehive_projects/ws_tutorial/WEB-INF/src/template/Blank.jws</code> so it appears as follows. Code to add appears in bold type.</p> + <source>package template; +... +import javax.jws.WebMethod; +import javax.jws.WebService; +import javax.jws.WebParam; + [EMAIL PROTECTED] +public class Blank +{ + @WebMethod + public String sayHelloWorld() + { + return "Hello world!"; + } + + @WebMethod + public String sayHello( @WebParam String greetee ) + { + if( greetee.equals("") ) + { greetee = "World"; } + + return "Hello, " + greetee + "!"; + } + + <strong>public String sayNothingOverTheWeb() + { + return "Not for for Web consumption!"; + }</strong> +} +</source> + <p>Note that the method added, sayNothingOverTheWeb(), does not have the annotation @WebMethod, indicating that it cannot be invoked by SOAP messages over the web.</p> + <section> + <title>Compile and Redeploy the Web Service</title> + <p>At the command prompt, enter the following Ant command:</p> + <source> ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=C:\beehive_projects\ws_tutorial + -Dcontext.path=ws_tutorial + build.webapp + redeploy</source> + <p>This Ant command compiles the app, undeploys it, and then deploys it. Calling <code>ant ... redeploy</code> is equivalent to calling <code>ant ... undeploy deploy</code>.</p> + </section> + <section> + <title>To Test the Non-Web Invokable Method</title> + <p>Enter the following URL in the address bar of your browser. </p> + <p><fork href="http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayNothingOverTheWeb";>http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayNothingOverTheWeb</fork></p> + <p>The following SOAP response appears in the browser, indicating that the method sayNothingOverTheWeb() cannot be invoked through the web service (although it can be called by other methods within the web service).</p> + <source><![CDATA[<soapenv:Envelope> + <soapenv:Body> + <soapenv:Fault> + <faultcode>ns1:Client</faultcode> + <faultstring>No such operation 'sayNothingOverTheWeb'</faultstring> + <detail> + <ns2:hostname>[your machine name]</ns2:hostname> + </detail> + </soapenv:Fault> + </soapenv:Body> +</soapenv:Envelope> ]]></source> + </section> + <section> + <title>Step 5: Change the SOAP Style</title> + <p>The default SOAP style for JSR-181 web services is DOC-literal. In this step you will change the style to RPC-encoded.</p> + <p>Edit the file <code>C:/beehive_projects/ws_tutorial/WEB-INF/src/template/Blank.jws</code> so it appears as follows. Code to add appears in bold type.</p> + <source>package template; +... +import javax.jws.WebMethod; +import javax.jws.WebService; +import javax.jws.WebParam; +<strong>import javax.jws.soap.SOAPBinding;</strong> + [EMAIL PROTECTED] +<strong>@SOAPBinding(style = SOAPBinding.Style.RPC, use = SOAPBinding.Use.ENCODED)</strong> +public class Blank +{ + @WebMethod + public String sayHelloWorld() + { + return "Hello world!"; + } + + @WebMethod + public String sayHello( @WebParam String greetee ) + { + if( greetee.equals("") ) + { greetee = "World"; } + + return "Hello, " + greetee + "!"; + } + + public String sayNothingOverTheWeb() + { + return "Not for for Web consumption!"; + } +}</source> + <section> + <title>Compile and Redeploy the Web Service</title> + <p>At the command prompt, enter the following Ant command:</p> + <source> ant + -f %BEEHIVE_HOME%\ant\buildWebapp.xml + -Dwebapp.dir=C:\beehive_projects\ws_tutorial + -Dcontext.path=ws_tutorial + build.webapp + redeploy</source> + </section> + <section> + <title>To Test the Parameterized Method (with SOAP-encoded style)</title> + <p>Enter the following URL in the address bar of your browser. </p> + <p><fork href="http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayHello&greetee=Moon";>http://localhost:8080/ws_tutorial/template/Blank.jws?method=sayHello&greetee=Moon</fork></p> + <p>The following SOAP response appears in the browser. Compare the RPC style below with the DOC style above.</p> + <source><![CDATA[<soapenv:Envelope> + <soapenv:Body> + <sayHelloResponse soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/";> + <ns1:result xsi:type="xsd:string">Hello, Moon!</ns1:result> + </sayHelloResponse> + </soapenv:Body> +</soapenv:Envelope>]]></source> + </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/> + © 2004, Apache Software Foundation + </legal> + </footer> +</document> Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsOverview_1.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsOverview_1.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsOverview_2.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsOverview_2.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsOverview_3.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsOverview_3.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsOverview_4.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsOverview_4.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsProgramming_1.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsProgramming_1.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsProgramming_2.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsProgramming_2.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsProgramming_3.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/ControlsProgramming_3.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/Logo_25wht.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/Logo_25wht.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsOverview_1.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsOverview_1.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsOverview_2.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsOverview_2.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsOverview_3.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsOverview_3.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsOverview_4.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsOverview_4.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsProgramming_1.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsProgramming_1.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsProgramming_2.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsProgramming_2.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsProgramming_3.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_ControlsProgramming_3.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_Logo_25wht.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_Logo_25wht.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_apache-incubator-logo.png Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_apache-incubator-logo.png?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_beehive_logo_wide.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_beehive_logo_wide.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_incubator-logo.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_incubator-logo.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_maven-button-1.png Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/_maven-button-1.png?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/apache-incubator-logo.png Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/apache-incubator-logo.png?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/beehive_logo_wide.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/beehive_logo_wide.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/controlsOverview1.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/controlsOverview1.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/controlsOverview2.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/controlsOverview2.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/controlsOverview3.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/controlsOverview3.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/controlsOverview4.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/controlsOverview4.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/controlsProg1.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/controlsProg1.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/impl-flow-1.dia Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/impl-flow-1.dia?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/impl-flow-1.png Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/impl-flow-1.png?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/impl-flow-2.dia Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/impl-flow-2.dia?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/impl-flow-2.png Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/impl-flow-2.png?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/incubator-logo.gif Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/incubator-logo.gif?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/logical-flow-1.dia Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/logical-flow-1.dia?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/logical-flow-1.png Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/logical-flow-1.png?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/logical-flow-2.dia Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/logical-flow-2.dia?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/logical-flow-2.png Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/logical-flow-2.png?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/maven-button-1.png Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/resources/images/maven-button-1.png?view=auto&rev=110142 ============================================================================== Binary file. No diff available. Added: incubator/beehive/trunk/docs/forrest/src/documentation/skinconf.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/skinconf.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/skinconf.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,354 @@ +<?xml version="1.0"?> +<!-- + Copyright 2002-2004 The Apache Software Foundation + + Licensed 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. +--> + +<!-- +Skin configuration file. This file contains details of your project, +which will be used to configure the chosen Forrest skin. +--> + +<!DOCTYPE skinconfig PUBLIC "-//APACHE//DTD Skin Configuration V0.6-3//EN" "http://forrest.apache.org/dtd/skinconfig-v06-3.dtd";> +<skinconfig> + <!-- To enable lucene search add provider="lucene" (default is google). + Add box-location="alt" to move the search box to an alternate location + (if the skin supports it) and box-location="all" to show it in all + available locations on the page. Remove the <search> element to show + no search box. @domain will enable sitesearch for the specific domain with google. + In other words google will search the @domain for the query string. + --> + <search name="MyProject" domain="mydomain" provider="google"/> + + <!-- Disable the print link? If enabled, invalid HTML 4.0.1 --> + <disable-print-link>true</disable-print-link> + <!-- Disable the PDF link? --> + <disable-pdf-link>false</disable-pdf-link> + <!-- Disable the POD link? --> + <disable-pod-link>true</disable-pod-link> + <!-- Disable the Text link? FIXME: NOT YET IMPLEMENETED. --> + <disable-txt-link>true</disable-txt-link> + <!-- Disable the xml source link? --> + <!-- The xml source link makes it possible to access the xml rendition + of the source frim the html page, and to have it generated statically. + This can be used to enable other sites and services to reuse the + xml format for their uses. Keep this disabled if you don't want other + sites to easily reuse your pages.--> + <disable-xml-link>true</disable-xml-link> + + <!-- Disable navigation icons on all external links? --> + <disable-external-link-image>false</disable-external-link-image> + + <!-- Disable w3c compliance links? + Use e.g. align="center" to move the compliance links logos to + an alternate location default is left. + (if the skin supports it) --> + <disable-compliance-links>false</disable-compliance-links> + + <!-- Render mailto: links unrecognisable by spam harvesters? --> + <obfuscate-mail-links>true</obfuscate-mail-links> + <obfuscate-mail-value>.at.</obfuscate-mail-value> + + <!-- Disable the javascript facility to change the font size --> + <disable-font-script>true</disable-font-script> + + <!-- mandatory project logo + default skin: renders it at the top --> + <project-name>Apache Beehive</project-name> + <project-description>MyProject Description</project-description> + <project-url>http://incubator.apache.org/beehive</project-url> + <project-logo>images/_beehive_logo_wide.gif</project-logo> + <!-- Alternative static image: + <project-logo>images/project-logo.gif</project-logo> --> + + <!-- optional group logo + default skin: renders it at the top-left corner --> + <group-name>Apache Incubato</group-name> + <group-description>MyGroup Description</group-description> + <group-url>http://incubator.apache.org/</group-url> + <group-logo>images/_incubator-logo.gif</group-logo> + <!-- Alternative static image: + <group-logo>images/group-logo.gif</group-logo> --> + + <!-- optional host logo (e.g. sourceforge logo) + default skin: renders it at the bottom-left corner --> + <host-url></host-url> + <host-logo></host-logo> + + <!-- relative url of a favicon file, normally favicon.ico --> + <favicon-url></favicon-url> + + <!-- The following are used to construct a copyright statement --> + <year>2004</year> + <vendor>The Acme Software Foundation.</vendor> + <!-- The optional copyright-link URL will be used as a link in the + copyright statement + <copyright-link>http://www.apache.org/licenses/</copyright-link> + --> + + <!-- Some skins use this to form a 'breadcrumb trail' of links. + Use location="alt" to move the trail to an alternate location + (if the skin supports it). + Omit the location attribute to display the trail in the default location. + Use location="none" to not display the trail (if the skin supports it). + For some skins just set the attributes to blank. + --> + <trail> + <link1 name="myGroup" href="http://www.apache.org/"/> + <link2 name="myProject" href="http://forrest.apache.org/"/> + <link3 name="" href=""/> + </trail> + + <!-- Configure the TOC, i.e. the Table of Contents. + @max-depth + how many "section" levels need to be included in the + generated Table of Contents (TOC). + @min-sections + Minimum required to create a TOC. + @location ("page","menu","page,menu", "none") + Where to show the TOC. + --> + <toc max-depth="2" min-sections="1" location="page"/> + + <!-- Heading types can be clean|underlined|boxed --> + <headings type="boxed"/> + + <!-- The optional feedback element will be used to construct a + feedback link in the footer with the page pathname appended: + <a href="@href">[EMAIL PROTECTED]</a> + --> + <feedback to="[EMAIL PROTECTED]" + href="mailto:[EMAIL PROTECTED] " > + Send feedback about the website to: + </feedback> + <!-- + extra-css - here you can define custom css-elements that are + a. overriding the fallback elements or + b. adding the css definition from new elements that you may have + used in your documentation. + --> + <extra-css> + <!--Example of b. + To define the css definition of a new element that you may have used + in the class attribute of a <p> node. + e.g. <p class="quote"/> + --> + p.quote { + margin-left: 2em; + padding: .5em; + background-color: #f0f0f0; + font-family: monospace; + } + </extra-css> + + <colors> + <!-- These values are used for the generated CSS files. --> + + <!-- Krysalis --> +<!-- + <color name="header" value="#FFFFFF"/> + + <color name="tab-selected" value="#a5b6c6" link="#000000" vlink="#000000" hlink="#000000"/> + <color name="tab-unselected" value="#F7F7F7" link="#000000" vlink="#000000" hlink="#000000"/> + <color name="subtab-selected" value="#a5b6c6" link="#000000" vlink="#000000" hlink="#000000"/> + <color name="subtab-unselected" value="#a5b6c6" link="#000000" vlink="#000000" hlink="#000000"/> + + <color name="heading" value="#a5b6c6"/> + <color name="subheading" value="#CFDCED"/> + + <color name="navstrip" value="#CFDCED" font="#000000" link="#000000" vlink="#000000" hlink="#000000"/> + <color name="toolbox" value="#a5b6c6"/> + <color name="border" value="#a5b6c6"/> + + <color name="menu" value="#F7F7F7" link="#000000" vlink="#000000" hlink="#000000"/> + <color name="dialog" value="#F7F7F7"/> + + <color name="body" value="#ffffff" link="#0F3660" vlink="#009999" hlink="#000066"/> + + <color name="table" value="#a5b6c6"/> + <color name="table-cell" value="#ffffff"/> + <color name="highlight" value="#ffff00"/> + <color name="fixme" value="#cc6600"/> + <color name="note" value="#006699"/> + <color name="warning" value="#990000"/> + <color name="code" value="#a5b6c6"/> + + <color name="footer" value="#a5b6c6"/> +--> + + <!-- Forrest --> +<!-- + <color name="header" value="#294563"/> + + <color name="tab-selected" value="#4a6d8c" link="#0F3660" vlink="#0F3660" hlink="#000066"/> + <color name="tab-unselected" value="#b5c7e7" link="#0F3660" vlink="#0F3660" hlink="#000066"/> + <color name="subtab-selected" value="#4a6d8c" link="#0F3660" vlink="#0F3660" hlink="#000066"/> + <color name="subtab-unselected" value="#4a6d8c" link="#0F3660" vlink="#0F3660" hlink="#000066"/> + + <color name="heading" value="#294563"/> + <color name="subheading" value="#4a6d8c"/> + + <color name="navstrip" value="#cedfef" font="#0F3660" link="#0F3660" vlink="#0F3660" hlink="#000066"/> + <color name="toolbox" value="#4a6d8c"/> + <color name="border" value="#294563"/> + + <color name="menu" value="#4a6d8c" font="#cedfef" link="#ffffff" vlink="#ffffff" hlink="#ffcf00"/> + <color name="dialog" value="#4a6d8c"/> + + <color name="body" value="#ffffff" link="#0F3660" vlink="#009999" hlink="#000066"/> + + <color name="table" value="#7099C5"/> + <color name="table-cell" value="#f0f0ff"/> + <color name="highlight" value="#ffff00"/> + <color name="fixme" value="#cc6600"/> + <color name="note" value="#006699"/> + <color name="warning" value="#990000"/> + <color name="code" value="#CFDCED"/> + + <color name="footer" value="#cedfef"/> +--> + + <!-- Collabnet --> +<!-- + <color name="header" value="#003366"/> + + <color name="tab-selected" value="#dddddd" link="#555555" vlink="#555555" hlink="#555555"/> + <color name="tab-unselected" value="#999999" link="#ffffff" vlink="#ffffff" hlink="#ffffff"/> + <color name="subtab-selected" value="#cccccc" link="#000000" vlink="#000000" hlink="#000000"/> + <color name="subtab-unselected" value="#cccccc" link="#555555" vlink="#555555" hlink="#555555"/> + + <color name="heading" value="#003366"/> + <color name="subheading" value="#888888"/> + + <color name="navstrip" value="#dddddd" font="#555555"/> + <color name="toolbox" value="#dddddd" font="#555555"/> + <color name="border" value="#999999"/> + + <color name="menu" value="#ffffff"/> + <color name="dialog" value="#eeeeee"/> + + <color name="body" value="#ffffff"/> + + <color name="table" value="#ccc"/> + <color name="table-cell" value="#ffffff"/> + <color name="highlight" value="#ffff00"/> + <color name="fixme" value="#cc6600"/> + <color name="note" value="#006699"/> + <color name="warning" value="#990000"/> + <color name="code" value="#003366"/> + + <color name="footer" value="#ffffff"/> +--> + <!-- Lenya using pelt--> +<!-- + <color name="header" value="#ffffff"/> + + <color name="tab-selected" value="#4C6C8F" link="#ffffff" vlink="#ffffff" hlink="#ffffff"/> + <color name="tab-unselected" value="#E5E4D9" link="#000000" vlink="#000000" hlink="#000000"/> + <color name="subtab-selected" value="#000000" link="#000000" vlink="#000000" hlink="#000000"/> + <color name="subtab-unselected" value="#E5E4D9" link="#000000" vlink="#000000" hlink="#000000"/> + + <color name="heading" value="#E5E4D9"/> + <color name="subheading" value="#000000"/> + <color name="published" value="#4C6C8F" font="#FFFFFF"/> + <color name="feedback" value="#4C6C8F" font="#FFFFFF" align="center"/> + <color name="navstrip" value="#E5E4D9" font="#000000"/> + + <color name="toolbox" value="#CFDCED" font="#000000"/> + + <color name="border" value="#999999"/> + <color name="menu" value="#4C6C8F" font="#ffffff" link="#ffffff" vlink="#ffffff" hlink="#ffffff" current="#FFCC33" /> + <color name="menuheading" value="#cfdced" font="#000000" /> + <color name="searchbox" value="#E5E4D9" font="#000000"/> + + <color name="dialog" value="#CFDCED"/> + <color name="body" value="#ffffff" /> + + <color name="table" value="#ccc"/> + <color name="table-cell" value="#ffffff"/> + <color name="highlight" value="#ffff00"/> + <color name="fixme" value="#cc6600"/> + <color name="note" value="#006699"/> + <color name="warning" value="#990000"/> + <color name="code" value="#003366"/> + + <color name="footer" value="#E5E4D9"/> +--> + </colors> + + <!-- Settings specific to PDF output. --> + <pdf> + <!-- + Supported page sizes are a0, a1, a2, a3, a4, a5, executive, + folio, legal, ledger, letter, quarto, tabloid (default letter). + Supported page orientations are portrait, landscape (default + portrait). + Supported text alignments are left, right, justify (default left). + --> + <page size="letter" orientation="portrait" text-align="left"/> + + <!-- + Margins can be specified for top, bottom, inner, and outer + edges. If double-sided="false", the inner edge is always left + and the outer is always right. If double-sided="true", the + inner edge will be left on odd pages, right on even pages, + the outer edge vice versa. + Specified below are the default settings. + --> + <margins double-sided="false"> + <top>1in</top> + <bottom>1in</bottom> + <inner>1.25in</inner> + <outer>1in</outer> + </margins> + + <!-- + Print the URL text next to all links going outside the file + --> + <show-external-urls>false</show-external-urls> + + <!-- + Disable the copyright footer on each page of the PDF. + A footer is composed for each page. By default, a "credit" with role=pdf + will be used, as explained below. Otherwise a copyright statement + will be generated. This latter can be disabled. + --> + <disable-copyright-footer>false</disable-copyright-footer> + </pdf> + + <!-- Credits are typically rendered as a set of small clickable + images in the page footer. + Use box-location="alt" to move the credit to an alternate location + (if the skin supports it). + --> + <credits> + <credit box-location="alt"> + <name>Built with Apache Forrest</name> + <url>http://forrest.apache.org/</url> + <image>images/built-with-forrest-button.png</image> + <width>88</width> + <height>31</height> + </credit> + <!-- A credit with @role="pdf" will be used to compose a footer + for each page in the PDF, using either "name" or "url" or both. + --> + <!-- + <credit role="pdf"> + <name>Built with Apache Forrest</name> + <url>http://forrest.apache.org/</url> + </credit> + --> + </credits> + +</skinconfig> Added: incubator/beehive/trunk/docs/forrest/src/documentation/translations/langcode.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/translations/langcode.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/translations/langcode.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,25 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright 2002-2004 The Apache Software Foundation + + Licensed 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. +--> +<!-- + This catalog is used so displays how the language name + is named by their speakers. +--> +<catalogue > + <message key="en">English</message> + <message key="es">Espanol</message> + <message key="it">Italiano</message> +</catalogue> Added: incubator/beehive/trunk/docs/forrest/src/documentation/translations/languages_en.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/translations/languages_en.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/translations/languages_en.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,21 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright 2002-2004 The Apache Software Foundation + + Licensed 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. +--> +<catalogue xml:lang="en"> + <message key="en">English</message> + <message key="es">Spanish</message> + <message key="nl">Dutch</message> +</catalogue> Added: incubator/beehive/trunk/docs/forrest/src/documentation/translations/languages_es.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/translations/languages_es.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/translations/languages_es.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,21 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright 2002-2004 The Apache Software Foundation + + Licensed 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. +--> +<catalogue xml:lang="es"> + <message key="en">Ingles</message> + <message key="es">Espanol</message> + <message key="nl">Holandes</message> +</catalogue> Added: incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,32 @@ +<?xml version="1.0"?> +<!-- + Copyright 2002-2004 The Apache Software Foundation + + Licensed 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. +--> +<catalogue xml:lang="en"> + <message key="About">About</message> + <message key="Index">Index</message> + <message key="Changes">Changes</message> + <message key="Todo">Todo</message> + <message key="Samples">Samples</message> + <message key="Apache document">Apache document</message> + <message key="Static content">Static content</message> + <message key="Linking">Linking</message> + <message key="Wiki page">Wiki page</message> + <message key="ihtml page">Ihtml page</message> + <message key="ehtml page">Ehtml page</message> + <message key="FAQ">FAQ</message> + <message key="Simplifed Docbook">Simplifed Docbook</message> + <message key="XSP page">XSP page</message> +</catalogue> Added: incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_af.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_af.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_af.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,32 @@ +<?xml version="1.0"?> +<!-- + Copyright 2002-2004 The Apache Software Foundation + + Licensed 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. +--> +<catalogue xml:lang="af"> + <message key="About">Aangaande</message> + <message key="Index">Inhoud</message> + <message key="Changes">Veranderinge</message> + <message key="Todo">Om te doen</message> + <message key="Samples">Voorbeelde</message> + <message key="Apache document">Apache dokument</message> + <message key="Static content">Statise Inhoud</message> + <message key="Linking">Linking</message> + <message key="Wiki page">Wiki bladsy</message> + <message key="ihtml page">Ihtml bladsy</message> + <message key="ehtml page">Ehtml bladsy</message> + <message key="FAQ">FAQ</message> + <message key="Simplifed Docbook">Vereenvoudigde Docbook</message> + <message key="XSP page">XSP bladsy</message> +</catalogue> Added: incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_de.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_de.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_de.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,32 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright 2002-2004 The Apache Software Foundation + + Licensed 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. +--> +<catalogue xml:lang="de"> + <message key="About">Ãber</message> + <message key="Index">Index</message> + <message key="Changes">Ãnderungen </message> + <message key="Todo">Todo</message> + <message key="Samples">Beispiele</message> + <message key="Apache document">Apache Dokumentationsseite</message> + <message key="Static content">Statischer Inhalt</message> + <message key="Linking">Linking</message> + <message key="Wiki page">Wiki Seite</message> + <message key="ihtml page">ihtml Seite</message> + <message key="ehtml page">ehtml Seite</message> + <message key="FAQ">FAQ</message> + <message key="Simplifed Docbook">Vereinfachte Docbook</message> + <message key="XSP page">XSP Seite</message> +</catalogue> Added: incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_es.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_es.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_es.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,32 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright 2002-2004 The Apache Software Foundation + + Licensed 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. +--> +<catalogue xml:lang="es"> + <message key="About">Acerca de</message> + <message key="Index">Indice</message> + <message key="Changes">Cambios</message> + <message key="Todo">Tareas pendientes</message> + <message key="Samples">Ejemplos</message> + <message key="Apache document">Documento Apache</message> + <message key="Static content">Contenido EstÃtico</message> + <message key="Linking">Linking</message> + <message key="Wiki page">PÃgina Wiki</message> + <message key="ihtml page">PÃgina ihtml</message> + <message key="ehtml page">PÃgina ehtml</message> + <message key="FAQ">Preguntas Frecuentes</message> + <message key="Simplifed Docbook">PÃgina Simplifed Docbook</message> + <message key="XSP page">PÃgina XSP</message> +</catalogue> Added: incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_it.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_it.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_it.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,32 @@ +<?xml version="1.0"?> +<!-- + Copyright 2002-2004 The Apache Software Foundation + + Licensed 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. +--> +<catalogue xml:lang="it"> + <message key="About">Riguardo a</message> + <message key="Index">Indice</message> + <message key="Changes">Cambiamenti</message> + <message key="Todo">Cose da fare</message> + <message key="Samples">Esempi</message> + <message key="Apache document">Apache document</message> + <message key="Static content">Contenuto Statico</message> + <message key="Linking">Linking</message> + <message key="Wiki page">Pagina Wiki</message> + <message key="ihtml page">Pagina ihtml</message> + <message key="ehtml page">Pagina ehtml</message> + <message key="FAQ">Domande frequenti</message> + <message key="Simplifed Docbook">Simplifed Docbook</message> + <message key="XSP page">Pagina XSP</message> +</catalogue> Added: incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_no.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_no.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_no.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,32 @@ +<?xml version="1.0"?> +<!-- + Copyright 2002-2004 The Apache Software Foundation + + Licensed 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. +--> +<catalogue xml:lang="no"> + <message key="About">Om</message> + <message key="Index">Indeks</message> + <message key="Changes">Endringer</message> + <message key="Todo">Oppgave liste</message> + <message key="Samples">Eksempler</message> + <message key="Apache document">Apache Dokument</message> + <message key="Static content">Statisk innhold</message> + <message key="Linking">Linking</message> + <message key="Wiki page">Wiki side</message> + <message key="ihtml page">ihtml side</message> + <message key="ehtml page">ehtml side</message> + <message key="FAQ">FAQ</message> + <message key="Simplifed Docbook">Simplifed Docbook</message> + <message key="XSP page">XSP side</message> +</catalogue> Added: incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_ru.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_ru.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_ru.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,32 @@ +<?xml version="1.0"?> +<!-- + Copyright 2002-2004 The Apache Software Foundation + + Licensed 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. +--> +<catalogue xml:lang="ru"> + <message key="About">Ð ÐÑÐÐÐÑÐ</message> + <message key="Index">ÐÐÐÐÑÐÐÐÐÐ</message> + <message key="Changes">ÐÐÐÐÐÐÐÐÑ</message> + <message key="Todo">ÐÐÐÐ</message> + <message key="Samples">ÐÑÐÐÐÑÑ</message> + <message key="Apache document">ÐÑÑÐÐÐÑÐ ÐÐÐÑÐÐÐÑÐ Apache</message> + <message key="Static content">ÐÑÐÑÐÑÐÑÐÐÐ ÑÐÐÐÑÐÐÐÐÐ</message> + <message key="Linking">Linking</message> + <message key="Wiki page">ÐÑÑÐÐÐÑÐ Wiki</message> + <message key="ihtml page">ÐÑÑÐÐÐÑÐ ihtml</message> + <message key="ehtml page">ÐÑÑÐÐÐÑÐ ehtml</message> + <message key="FAQ">ÐÐÐÑÐÑÑ/ÐÑÐÐÑÑ</message> + <message key="Simplifed Docbook">Docbook ÑÑÑÐÐÐÑÐ</message> + <message key="XSP page">XSP ÑÑÑÐÐÐÑÐ</message> +</catalogue> Added: incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_sk.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_sk.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/translations/menu_sk.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,32 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright 2002-2004 The Apache Software Foundation + + Licensed 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. +--> +<catalogue xml:lang="sk"> + <message key="About">O programe</message> + <message key="Index">ZoznÃm</message> + <message key="Changes">Zmeny</message> + <message key="Todo">Ãlohy</message> + <message key="Samples">PrÃklady</message> + <message key="Apache document">Apache Document</message> + <message key="Static content">Statickà Obsah</message> + <message key="Linking">Linking</message> + <message key="Wiki page">Wiki strÃnka</message> + <message key="ihtml page">ihtml strÃnka</message> + <message key="ehtml page">ehtml strÃnka</message> + <message key="FAQ">Castà OtÃzky</message> + <message key="Simplifed Docbook">Simplifed Docbook strÃnka</message> + <message key="XSP page">XSP strÃnka</message> +</catalogue> Added: incubator/beehive/trunk/docs/forrest/src/documentation/translations/tabs.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/translations/tabs.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/translations/tabs.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,21 @@ +<?xml version="1.0"?> +<!-- + Copyright 2002-2004 The Apache Software Foundation + + Licensed 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. +--> +<catalogue xml:lang="en"> + <message key="Home">Home</message> + <message key="Samples">Samples</message> + <message key="Apache XML Projects">Apache XML Projects</message> +</catalogue> Added: incubator/beehive/trunk/docs/forrest/src/documentation/translations/tabs_es.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/translations/tabs_es.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/translations/tabs_es.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,21 @@ +<?xml version="1.0"?> +<!-- + Copyright 2002-2004 The Apache Software Foundation + + Licensed 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. +--> +<catalogue xml:lang="es"> + <message key="Home">Inicio</message> + <message key="Samples">Ejemplos</message> + <message key="Apache XML Projects">Projectos XML Apache</message> +</catalogue> Added: incubator/beehive/trunk/docs/forrest/status.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/status.xml?view=auto&rev=110142 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/status.xml Tue Dec 7 11:10:11 2004 @@ -0,0 +1,74 @@ +<?xml version="1.0"?> +<!-- + Copyright 2002-2004 The Apache Software Foundation + + Licensed 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. +--> +<status> + + <developers> + <person name="Joe Bloggs" email="[EMAIL PROTECTED]" id="JB" /> + <!-- Add more people here --> + </developers> + + <changes> + <!-- Add new releases here --> + <release version="0.1" date="unreleased"> + <!-- Some action types have associated images. By default, images are + defined for 'add', 'fix', 'remove', 'update' and 'hack'. If you add + src/documentation/resources/images/<foo>.jpg images, these will + automatically be used for entries of type <foo>. --> + + <action dev="JB" type="add" context="admin"> + Initial Import + </action> + <!-- Sample action: + <action dev="JB" type="fix" due-to="Joe Contributor" + due-to-email="[EMAIL PROTECTED]" fixes-bug="123"> + Fixed a bug in the Foo class. + </action> + --> + </release> + </changes> + + <todo> + <actions priority="high"> + <action context="docs" dev="JB"> + Customize this template project with your project's details. This + TODO list is generated from 'status.xml'. + </action> + <action context="docs" dev="JB"> + Add lots of content. XML content goes in + <code>src/documentation/content/xdocs</code>, or wherever the + <code>${project.xdocs-dir}</code> property (set in + <code>forrest.properties</code>) points. + </action> + <action context="feedback" dev="JB"> + Mail <link + href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</link> + with feedback. + </action> + </actions> + <!-- Add todo items. @context is an arbitrary string. Eg: + <actions priority="high"> + <action context="code" dev="SN"> + </action> + </actions> + <actions priority="medium"> + <action context="docs" dev="open"> + </action> + </actions> + --> + </todo> + +</status>
