Author: steveh Date: Wed Jan 5 16:20:30 2005 New Revision: 124321 URL: http://svn.apache.org/viewcvs?view=rev&rev=124321 Log: Adding reference docs for JPF annotations. (Links to Javadoc are broken throughout. A separate bug has been opened on this.) Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/jpf-annotations/ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/jpf-annotations/pageflow_annotations.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/jpf-annotations/pageflow_class_annotations.xml (contents, props changed) incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/jpf-annotations/pageflow_method_annotations.xml (contents, props changed) Modified: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml
Added: incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/jpf-annotations/pageflow_annotations.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/jpf-annotations/pageflow_annotations.xml?view=auto&rev=124321 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/jpf-annotations/pageflow_annotations.xml Wed Jan 5 16:20:30 2005 @@ -0,0 +1,40 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd";> +<document> + <header> + <title>JPF Annotations</title> + </header> + <body> + + + <section id="overview"> + <title>Overview</title> + <p> + Pageflows use Java annotations to richly express the semantics of + a web-application entirely in Java sources. Annotations allow + configuration informatin to reside proximately near to the code + that uses it. + </p> + + <p> + All JPF annotations reside within the + <a href="../../apidocs/classref_pageflows/org/apache/beehive/netui/pageflow/annotations/Jpf.html">Jpf</a> + interface. + </p> + + <ul> + <li><a href="pageflow_class_annotations.html">Controller Class Annotations</a></li> + <li><a href="pageflow_method_annotations.html">Controller Method Annotations</a></li> + <li>Validation Annotations</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/jpf-annotations/pageflow_class_annotations.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/jpf-annotations/pageflow_class_annotations.xml?view=auto&rev=124321 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/jpf-annotations/pageflow_class_annotations.xml Wed Jan 5 16:20:30 2005 @@ -0,0 +1,240 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd";> +<document> + <header> + <title>JPF Class Annotations</title> + </header> + <body> + + <section id="toc"> + <title>Table of Contents</title> + <ul> + <li><a href="#jpf_controller">Jpf.Controller</a> + <ul> + <li><a href="#jpf_simpleaction">Jpf.Controller with Jpf.SimpleAction</a></li> + <li><a href="#jpf_forward">Jpf.Controller with Jpf.Forward</a></li> + <li><a href="#jpf_catch">Jpf.Controller with Jpf.Catch and Jpf.ExceptionHandler</a></li> + </ul> + </li> + </ul> + </section> + + + <section id="jpf_controller"> + <title><code>Jpf.Controller</code></title> + + <ul> + <li><a href="../../apidocs/classref_pageflows/org/apache/beehive/netui/pageflow/annotations/Jpf.Controller.html">Jpf.Controller Javadoc</a></li> + </ul> + + <p> + <code>Jpf.Controller</code> is the annotation used to both <strong>mark</strong> a class as a page-flow controller + and may additionally <strong>contain</strong> other annotations which participate in the configuration. + </p> + + <p> + When used simply as a marker, it must simply be placed directly in front of the class definition. + </p> + +<source> +<strong>@Jpf.Controller</strong> +public class Controller + extends PageFlowController +{ + ... + ... +} +</source> + + <p> + The <code>Jpf.Controller</code> annotation also has several configuration properties. + </p> + + <table> + <tr> + <th>Property</th> + <th>Type</th> + <th>Description</th> + </tr> + <tr> + <td><code>loginRequired</code></td> + <td><code>boolean</code></td> + <td>Checks user authentication and possibly throws <a href="../../apidocs/classref_pageflows/org/apache/beehive/netui/pageflow/NotLoggedInException.html">NotLoggedInException</a></td> + </tr> + <tr> + <td><code>readOnly</code></td> + <td><code>boolean</code></td> + <td>Flag to indicate this action does not modify state</td> + </tr> + <tr> + <td><code>rolesAllowed</code></td> + <td><code>String[]</code></td> + <td>List of roles allowed to invoke this action. Implies <code>loginRequired=true</code>.</td> + </tr> + <tr> + <td><code>nested</code></td> + <td><code>boolean</code></td> + <td>Flag the pageflow as nested</td> + </tr> + <tr> + <td><code>singleton</code></td> + <td><code>boolean</code></td> + <td>Flag the pageflow as singleton</td> + </tr> + </table> + +<source> +<strong>@Jpf.Controller { + rolesAllowed = { "admin" }; + nested = true; +}</strong> +public class AddNewUserController +{ + ... +} +</source> + + <p> + The above controller, notably not named <code>Controller</code>, is a nested pageflow + that requires the <code>admin</code> role to be invoked. + </p> + + <section id="jpf_simpleaction"> + <title>Jpf.Controller with Jpf.SimpleAction</title> + + <ul> + <li><a href="../../apidocs/classref_pageflows/org/apache/beehive/netui/pageflow/annotations/Jpf.SimpleAction.html">Jpf.SimpleAction Javadoc</a></li> + </ul> + + <p> + In addition to being a marker, simple configuration can occur using the <code>Jpf.SimpleAction</code> annotation. + </p> + +<source> [EMAIL PROTECTED] { + simpleActions = { + <strong>@Jpf.SimpleAction( name="mypage", path="mypage.jsp" )</strong>, + <strong>@Jpf.SimpleAction( name="terms", path="terms.jsp" )</strong> + } +} +public class Controller + extends PageFlowController +{ + ... + ... +} +</source> + + <p> + The combination of <code>Jpf.Controller</code> and <code>Jpf.SimpleAction</code> operates as short-hand + for the more verbose equivelent class using <code>Jpf.Controller</code> as a marker with explicitly + defined <em>controller methods</em> with <code>Jpf.Action</code> and <code>Jpf.Forward</code>. + </p> + +<source> [EMAIL PROTECTED] +public class Controller + extends PageFlowController +{ + <strong>@Jpf.Action { + forwards = { + @Jpf.Forward( name="success", path="mypage.jsp" ); + } + } + public Forward mypage() + { + return new Forward( "success" ); + }</strong> + + <strong>@Jpf.Action { + forwards = { + @Jpf.Forward( name="success", path="terms.jsp" ); + } + } + public Forward terms() + { + return new Forward( "success" ); + }</strong> +} +</source> + + </section> + + <section id="jpf_forward"> + <title>Jpf.Controller with Jpf.Forward</title> + + <ul> + <li><a href="../../apidocs/classref_pageflows/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html">Jpf.Forward Javadoc</a></li> + </ul> + + <p> + Global named forwards can be defined within the <code>Controller</code> class annotations. + </p> + +<source> [EMAIL PROTECTED] { + forwards = { + <strong>@Jpf.Forward( name="error", path="/error.jsp" )</strong> + } +} +public class Controller +{ + public Forward doSomething() + { + ... + if ( error ) + { + <strong>return new Forward( "error" );</strong> + } + } +} +</source> + </section> + + <section id="jpf_catch"> + <title>Jpf.Controller with Jpf.Catch and Jpf.ExceptionHandler</title> + + <ul> + <li><a href="../../apidocs/classref_pageflows/org/apache/beehive/netui/pageflow/annotations/Jpf.Catch.html">Jpf.Catch Javadoc</a></li> + <li><a href="../../apidocs/classref_pageflows/org/apache/beehive/netui/pageflow/annotations/Jpf.ExceptionHandler.html">Jpf.ExceptionHandler Javadoc</a></li> + </ul> + + <p> + Global exception-handlers can be configured within the <code>Controller</code> class annotations. + </p> +<source> [EMAIL PROTECTED] { + catches = { + <strong>@Jpf.Catch { type=com.myco.FailedLoginException.class, method="failedLoginHandler" }</strong> + } +} +public class Controller +{ + <strong>@Jpf.ExceptionHandler { + forwards = { + @Jpf.Forward { name="try_again", path="/try_again.jps" } + } + }</strong> + protected Forward failedLoginHandler(FailedLoginException e, + String actionName, + String message, + LoginForm form) + { + ... + return new Forward( "try_again" ); + } +} +</source> + + </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/jpf-annotations/pageflow_method_annotations.xml Url: http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/jpf-annotations/pageflow_method_annotations.xml?view=auto&rev=124321 ============================================================================== --- (empty file) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/jpf-annotations/pageflow_method_annotations.xml Wed Jan 5 16:20:30 2005 @@ -0,0 +1,168 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd";> +<document> + <header> + <title>JPF Annotations</title> + </header> + <body> + + <section id="toc"> + <title>Table of Contents</title> + <ul> + <li><a href="#jpf_action">Jpf.Action</a> + <ul> + <li><a href="#jpf_catch">Jpf.Action with Jpf.Forward</a></li> + <li><a href="#jpf_catch">Jpf.Action with Jpf.Catch and Jpf.ExceptionHandler</a></li> + </ul> + </li> + </ul> + </section> + + <section id="jpf_action"> + <title>Jpf.Action</title> + + <ul> + <li><a href="../../apidocs/classref_pageflows/org/apache/beehive/netui/pageflow/annotations/Jpf.Action.html">Jpf.Action Javadoc</a></li> + </ul> + + <p> + The <code>@Jpf.Action</code> annotation adorns action methods of the <code>Controller</code> + class. It serves as a container for further configuration annotations and properties. + </p> + + <table> + <tr> + <th>Property</th> + <th>Type</th> + <th>Description</th> + </tr> + <tr> + <td><code>loginRequired</code></td> + <td><code>boolean</code></td> + <td>Checks user authentication and possibly throws <a href="../../apidocs/classref_pageflows/org/apache/beehive/netui/pageflow/NotLoggedInException.html">NotLoggedInException</a></td> + </tr> + <tr> + <td><code>readOnly</code></td> + <td><code>boolean</code></td> + <td>Flag to indicate this action does not modify state</td> + </tr> + <tr> + <td><code>rolesAllowed</code></td> + <td><code>String[]</code></td> + <td>List of roles allowed to invoke this action. Implies <code>loginRequired=true</code>.</td> + </tr> + <tr> + <td><code>useFormBean</code></td> + <td><code>String</code></td> + <td>Name of a member to use as multi-page form</td> + </tr> + </table> + + <p> + In this example, the <code>collectBasicUserInformation</code> action is called + on one page of a multi-page form flow. For each form page submitted, the same + <code>NewUserForm</code> is used, to allow for collection of data across several + pages into a single usable form. The data is stored in the <code>NewUserForm</code> + member variable named <code>newUserForm</code>. + </p> + + <p> + The <code>rolesAllowed</code> property specifies that only users with the <code>admin</code> + role can invoke this action. + </p> + +<source> [EMAIL PROTECTED] +public class Controller +{ + <strong>private NewUserForm newUserForm;</strong> + + <strong>@Jpf.Action { + rolesAllowed = { "admin" }, + useFormBean = "newUserForm"; + }</strong> + public Forward collectBasicUserInformation(NewUserForm form) + { + .. + } +} +</source> + + <section id="jpf_forward"> + <title>Jpf.Action with Jpf.Forward</title> + + <ul> + <li><a href="../../apidocs/classref_pageflows/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html">Jpf.Forward Javadoc</a></li> + </ul> + +<source> [EMAIL PROTECTED] +public class Controller +{ + @Jpf.Action { + <strong>forwards = { + @Jpf.Forward{ name="success", path="/mypage.jsp" } + }</strong> + } + public Forward login(LoginForm form) + { + ... + return new Forward( "success" ); + } +} +</source> + + </section> + + <section id="jpf_catch"> + <title>Jpf.Action with Jpf.Catch and Jpf.ExceptionHandler</title> + + <ul> + <li><a href="../../apidocs/classref_pageflows/org/apache/beehive/netui/pageflow/annotations/Jpf.Catch.html">Jpf.Catch Javadoc</a></li> + <li><a href="../../apidocs/classref_pageflows/org/apache/beehive/netui/pageflow/annotations/Jpf.ExceptionHandler.html">Jpf.ExceptionHandler Javadoc</a></li> + </ul> + +<source> [EMAIL PROTECTED] +public class Controller +{ + @Jpf.Action { + <strong>catches = { + type=com.myco.FailedLoginException.class, method="failedLoginHandler" + }</strong> + } + public Forward login(LoginForm form) + throws FailedLoginException + { + ... + } + + <strong>@Jpf.ExceptionHandler { + forwards = @Jpf.Forward( name="try_again", path="/try_again.jps" } + }</strong> + protected Forward failedLoginHandler(FailedLoginException e, + String actionName, + String message, + LoginForm form) + { + ... + return new Forward( "try_again" ); + } +} +</source> + + + </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> Modified: 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=diff&rev=124321&p1=incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml&r1=124320&p2=incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml&r2=124321 ============================================================================== --- incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml (original) +++ incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml Wed Jan 5 16:20:30 2005 @@ -46,6 +46,7 @@ <netui label="Page Flows"> <netui label="Page Flow Javadoc" href="apidocs/classref_pageflows/index.html"/> <netui label="<netui> Tags" href="apidocs/taglib/index.html"/> + <netui label="Metadata Annotations" href="pageflow/jpf-annotations/pageflow_annotations.html"/> <netui label="netui-config.xml" href="pageflow/config/netui-config.html"/> </netui> <ws label="Web Services">
