You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by sk...@apache.org on 2008/02/01 21:02:52 UTC
svn commit: r617625 [3/3] - in /myfaces/orchestra/trunk/core/src/site/xdoc:
component-bindings.xml conversation.xml faqs.xml glossary.xml
installation.xml introduction.xml persistence.xml todo.xml usage.xml
viewController.xml
Modified: myfaces/orchestra/trunk/core/src/site/xdoc/usage.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/usage.xml?rev=617625&r1=617624&r2=617625&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/usage.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/usage.xml Fri Feb 1 12:02:48 2008
@@ -1,267 +1,267 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
- "http://www.apache.org/dtd/xdoc.dtd">
-<!--
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
- -->
-
-<document>
- <properties>
- <title>Usage</title>
- </properties>
-
- <body>
- <section name="Usage">
- <p>
- Once you have configured the system as described in
- the installation document you can start using the new scope.
- </p>
-
- <p>
- One more prerequisite: instead of configuring your beans in the faces-config.xml
- configuration you have to do this in your spring configuration now. You can
- take over all your beans into the Spring configuration, Spring also provides
- a session and a request scope.
- </p>
-
- <p>
- With this in place, we'll start evaluating the Orchestra-relevant use-cases now - so we'll
- together look at what you will want to do with Orchestra.
- </p>
-
- <subsection name="Starting a conversation">
- In the beginning, we'll want to start a conversation. Doing that is a no-brainer in Orchestra - if
- you've declared the relevant managed beans as in the following example:
- <code><pre>
-<bean name="userInfo"
- class="my.app.pck.backings.UserInfo"
- scope="conversation.access"
- autowire="byName">
- <aop:scoped-proxy />
-</bean>
- </pre></code>
- <p>
- We've learned about this syntax in the small example in the introduction - a short repetition:
- <br/>
- The scope-attribute of the bean-element will be defining the name of the scope; the
- names can be whatever you like but we recommend "conversation.access" and "conversation.manual".
- </p>
- <p>The
- <code>autowire="byName"</code>
- Setting this property is fully optional. However, it
- lowers the amount of configuration required. With this property set, Spring will scan your
- bean configuration. Whenever it finds a bean with the same name as the property, it
- will inject an instance of this bean configuration into this property.
- </p>
- <p>For example, if you configure a bean named
- <code>userInfoDao</code>
- and your bean has a
- <code>setUserInfoDao()</code>
- method Spring will inject an instance of this DAO into your bean.
- </p>
- <p>
- Alternatively you could provide a custom conversation name:
- </p>
- <code><pre>
-<bean name="bean1"
- class="my.app.pck.backings.bean1"
- scope="conversation.manual"
- orchestra:conversationName="multibean"
- autowire="byName">
- <aop:scoped-proxy />
-</bean>
-<bean name="bean2"
- class="my.app.pck.backings.bean2"
- scope="conversation.manual"
- orchestra:conversationName="multibean"
- autowire="byName">
- <aop:scoped-proxy />
-</bean>
- </pre></code>
- <p>
- As you can see in the above example we put two beans into the same conversation, which
- means they share the same persistence context.<br />
- This opens the possibility to keep the "one class per page" paradigm and still
- allows you to pass entities between these two pages (e.g. Master/Detail scenarios).
- </p>
- </subsection>
-
- <subsection name="Closing a conversation">
- <p>
- Closing a conversation is straightforward as well. If the bean is in a scope
- that has been marked with lifetime=access then the conversation terminates
- when a request is processed without referring to anything in that conversation.
- If you've using a "manual" conversation instead, then you need to call:
- <pre>
- <code>Conversation.getCurrentInstance().invalidate()</code>
- </pre>
- from within the conversation-scoped bean. With this call, the conversation will cease to exist
- and the bean will be cleared from the conversation.
- </p>
- </subsection>
-
- <subsection name="Restart a conversation">
- <p>
- At times, you do not only want to close a conversation, but you also want to restart it
- immediately. For this, use the following call:
- <pre>
-public void invalidateAndRestart()
-{
- YouBean bean = (YourBean)
- ConversationUtils.invalidateAndRestart(Conversation.getCurrentInstance());
- bean.setUser(createdUser.getId());
-}
- </pre>
-
- With the returned object, you can do configuration and initialization work.
- </p>
- </subsection>
-
- <subsection name="Ensure a conversation is running">
- <p>
- If you have a conversation running over a multitude of pages,
- you might want to check if the conversation has been initialized before you reach the page.
- For doing this, you can call the method:
-
- <code>ConversationUtils.ensureConversationRedirect(conversationName, redirectToJsp)</code>
-
- before the conversation is first accessed on this page, as in an initialization or
- prerender-method.
- </p>
- </subsection>
-
- <subsection name="End a conversation by name">
-<code>ConversationUtils.invalidateIfExists(conversationName)</code>
- </subsection>
-
- <subsection name="JPA Transaction">
- <b>Note</b>
- :
- Once again we would like to stress that Apache MyFaces Orchestra does not rely
- on annotations, the JPA thing was just the one we build the examples with,
- thats why we describe it at first.
- <p>Every method in your conversation
- bean is able to issue a database request or to call e.g. a DAO which will
- do it. Its ensured that during the whole lifetime of this conversation
- bean all database code will see the same entity manager.
- </p>
- <p>Methods
- which change data has to be annotated with the
- <code>@Transactional</code>
- annotation.
- </p>
- <p>Which means, that every changed/inserted/deleted entity
- will be flushed to the database and committed.
- </p>
- <p>Thats an important
- thing to understand. You
- <b>can</b>
- change an entity whenever you want,
- but it will only be flushed after such an annotated method has been
- invoked.
- </p>
-
-
- </subsection>
-
- <subsection name="Access a conversation">
-
- <p>
- From within a conversation scoped bean you can use
-
- <code>Conversation.getCurrentInstance()</code>
-
- or the ConversationManager API if you are outside of a conversation or would like to access another
- conversation
-
- <code>ConversationManager.getConversation(conversationName)</code>
- </p>
-
- </subsection>
-
- <subsection name="Add beans to a conversation">
- As e.g a http session or the request map, internally the conversation is also just a map
- of beans.
- <br/>
- Using the spring configuration you're able to add just one bean, the conversation scoped
- bean to the conversation with the same name as the bean.
- <br/>
- But there are ways to add other objects using the Conversation API.
-
- <p>
- Once you have access to the conversation object you can do:
-
- <ul>
- <li>conversation.setAttribute(key, value)</li>
- <li>conversation.hasAttribute(key)</li>
- <li>conversation.getAttribute(key)</li>
- <li>conversation.removeAttribute(key)</li>
- </ul>
- </p>
-
- <p>
- Any bean implementing the <code>ConversationBindingListener</code> interface
- will receive the <code>valueBound()/valueUnbound()</code>.
-
- <ul>
- <li>valueBound()<br/>
- Will be invoked AFTER the bean has been added to the conversation map.
- </li>
-
- <li>valueUnbound()<br/>
- Will be invoked AFTER the bean has been removed from the conversation map.<br/>
- This will happen if you call <code>removeAttribute(key)</code> or if the
- conversation ends, either manually or automatically due to a timeout.
- </li>
- </ul>
-
- <b>Notice:</b> In <code>valueUnbound()</code> you can't assume that a faces context
- will be available.
- </p>
- </subsection>
-
- <subsection name="Using older Orchestra Releases">
- <p>
- The documentation above applies to the most recent Orchestra code. When using older
- releases, the following information is useful.
- </p>
- <subsection name="Using aop:scoped-proxy">
- <p>
- For Orchestra 1.0, you should add an <code><aop:scoped-proxy /></code>
- within the declaration of each bean that is of conversation scope. This ensures
- that you will never have a reference to the real instance of your bean, but to
- a proxy to it. There is no difference in the way how you work with this instance
- in your code, but if you end a conversation and restart it, you'll appreciate the
- difference: the proxy will make sure that your application will see the new instance.
- </p>
- <p>
- This is automatically done for you with Orchestra 1.1 and later.
- </p>
- </subsection>
- <subsection name="Flash Scope">
- In version 1.0, the name "flash scope" was used for what is now called
- "access scope". The two concepts are the same; when using orchestra 1.1
- you must simply write "flash" wherever the more modern documentation
- states "access". Orchestra 1.1 supports the old term for backwards
- compatibility, so configuration files written for 1.0 should work fine
- with release 1.1.
- </subsection>
- </subsection>
- </section>
- </body>
-</document>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
+ "http://www.apache.org/dtd/xdoc.dtd">
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ -->
+
+<document>
+ <properties>
+ <title>Usage</title>
+ </properties>
+
+ <body>
+ <section name="Usage">
+ <p>
+ Once you have configured the system as described in
+ the installation document you can start using the new scope.
+ </p>
+
+ <p>
+ One more prerequisite: instead of configuring your beans in the faces-config.xml
+ configuration you have to do this in your spring configuration now. You can
+ take over all your beans into the Spring configuration, Spring also provides
+ a session and a request scope.
+ </p>
+
+ <p>
+ With this in place, we'll start evaluating the Orchestra-relevant use-cases now - so we'll
+ together look at what you will want to do with Orchestra.
+ </p>
+
+ <subsection name="Starting a conversation">
+ In the beginning, we'll want to start a conversation. Doing that is a no-brainer in Orchestra - if
+ you've declared the relevant managed beans as in the following example:
+ <code><pre>
+<bean name="userInfo"
+ class="my.app.pck.backings.UserInfo"
+ scope="conversation.access"
+ autowire="byName">
+ <aop:scoped-proxy />
+</bean>
+ </pre></code>
+ <p>
+ We've learned about this syntax in the small example in the introduction - a short repetition:
+ <br/>
+ The scope-attribute of the bean-element will be defining the name of the scope; the
+ names can be whatever you like but we recommend "conversation.access" and "conversation.manual".
+ </p>
+ <p>The
+ <code>autowire="byName"</code>
+ Setting this property is fully optional. However, it
+ lowers the amount of configuration required. With this property set, Spring will scan your
+ bean configuration. Whenever it finds a bean with the same name as the property, it
+ will inject an instance of this bean configuration into this property.
+ </p>
+ <p>For example, if you configure a bean named
+ <code>userInfoDao</code>
+ and your bean has a
+ <code>setUserInfoDao()</code>
+ method Spring will inject an instance of this DAO into your bean.
+ </p>
+ <p>
+ Alternatively you could provide a custom conversation name:
+ </p>
+ <code><pre>
+<bean name="bean1"
+ class="my.app.pck.backings.bean1"
+ scope="conversation.manual"
+ orchestra:conversationName="multibean"
+ autowire="byName">
+ <aop:scoped-proxy />
+</bean>
+<bean name="bean2"
+ class="my.app.pck.backings.bean2"
+ scope="conversation.manual"
+ orchestra:conversationName="multibean"
+ autowire="byName">
+ <aop:scoped-proxy />
+</bean>
+ </pre></code>
+ <p>
+ As you can see in the above example we put two beans into the same conversation, which
+ means they share the same persistence context.<br />
+ This opens the possibility to keep the "one class per page" paradigm and still
+ allows you to pass entities between these two pages (e.g. Master/Detail scenarios).
+ </p>
+ </subsection>
+
+ <subsection name="Closing a conversation">
+ <p>
+ Closing a conversation is straightforward as well. If the bean is in a scope
+ that has been marked with lifetime=access then the conversation terminates
+ when a request is processed without referring to anything in that conversation.
+ If you've using a "manual" conversation instead, then you need to call:
+ <pre>
+ <code>Conversation.getCurrentInstance().invalidate()</code>
+ </pre>
+ from within the conversation-scoped bean. With this call, the conversation will cease to exist
+ and the bean will be cleared from the conversation.
+ </p>
+ </subsection>
+
+ <subsection name="Restart a conversation">
+ <p>
+ At times, you do not only want to close a conversation, but you also want to restart it
+ immediately. For this, use the following call:
+ <pre>
+public void invalidateAndRestart()
+{
+ YouBean bean = (YourBean)
+ ConversationUtils.invalidateAndRestart(Conversation.getCurrentInstance());
+ bean.setUser(createdUser.getId());
+}
+ </pre>
+
+ With the returned object, you can do configuration and initialization work.
+ </p>
+ </subsection>
+
+ <subsection name="Ensure a conversation is running">
+ <p>
+ If you have a conversation running over a multitude of pages,
+ you might want to check if the conversation has been initialized before you reach the page.
+ For doing this, you can call the method:
+
+ <code>ConversationUtils.ensureConversationRedirect(conversationName, redirectToJsp)</code>
+
+ before the conversation is first accessed on this page, as in an initialization or
+ prerender-method.
+ </p>
+ </subsection>
+
+ <subsection name="End a conversation by name">
+<code>ConversationUtils.invalidateIfExists(conversationName)</code>
+ </subsection>
+
+ <subsection name="JPA Transaction">
+ <b>Note</b>
+ :
+ Once again we would like to stress that Apache MyFaces Orchestra does not rely
+ on annotations, the JPA thing was just the one we build the examples with,
+ thats why we describe it at first.
+ <p>Every method in your conversation
+ bean is able to issue a database request or to call e.g. a DAO which will
+ do it. Its ensured that during the whole lifetime of this conversation
+ bean all database code will see the same entity manager.
+ </p>
+ <p>Methods
+ which change data has to be annotated with the
+ <code>@Transactional</code>
+ annotation.
+ </p>
+ <p>Which means, that every changed/inserted/deleted entity
+ will be flushed to the database and committed.
+ </p>
+ <p>Thats an important
+ thing to understand. You
+ <b>can</b>
+ change an entity whenever you want,
+ but it will only be flushed after such an annotated method has been
+ invoked.
+ </p>
+
+
+ </subsection>
+
+ <subsection name="Access a conversation">
+
+ <p>
+ From within a conversation scoped bean you can use
+
+ <code>Conversation.getCurrentInstance()</code>
+
+ or the ConversationManager API if you are outside of a conversation or would like to access another
+ conversation
+
+ <code>ConversationManager.getConversation(conversationName)</code>
+ </p>
+
+ </subsection>
+
+ <subsection name="Add beans to a conversation">
+ As e.g a http session or the request map, internally the conversation is also just a map
+ of beans.
+ <br/>
+ Using the spring configuration you're able to add just one bean, the conversation scoped
+ bean to the conversation with the same name as the bean.
+ <br/>
+ But there are ways to add other objects using the Conversation API.
+
+ <p>
+ Once you have access to the conversation object you can do:
+
+ <ul>
+ <li>conversation.setAttribute(key, value)</li>
+ <li>conversation.hasAttribute(key)</li>
+ <li>conversation.getAttribute(key)</li>
+ <li>conversation.removeAttribute(key)</li>
+ </ul>
+ </p>
+
+ <p>
+ Any bean implementing the <code>ConversationBindingListener</code> interface
+ will receive the <code>valueBound()/valueUnbound()</code>.
+
+ <ul>
+ <li>valueBound()<br/>
+ Will be invoked AFTER the bean has been added to the conversation map.
+ </li>
+
+ <li>valueUnbound()<br/>
+ Will be invoked AFTER the bean has been removed from the conversation map.<br/>
+ This will happen if you call <code>removeAttribute(key)</code> or if the
+ conversation ends, either manually or automatically due to a timeout.
+ </li>
+ </ul>
+
+ <b>Notice:</b> In <code>valueUnbound()</code> you can't assume that a faces context
+ will be available.
+ </p>
+ </subsection>
+
+ <subsection name="Using older Orchestra Releases">
+ <p>
+ The documentation above applies to the most recent Orchestra code. When using older
+ releases, the following information is useful.
+ </p>
+ <subsection name="Using aop:scoped-proxy">
+ <p>
+ For Orchestra 1.0, you should add an <code><aop:scoped-proxy /></code>
+ within the declaration of each bean that is of conversation scope. This ensures
+ that you will never have a reference to the real instance of your bean, but to
+ a proxy to it. There is no difference in the way how you work with this instance
+ in your code, but if you end a conversation and restart it, you'll appreciate the
+ difference: the proxy will make sure that your application will see the new instance.
+ </p>
+ <p>
+ This is automatically done for you with Orchestra 1.1 and later.
+ </p>
+ </subsection>
+ <subsection name="Flash Scope">
+ In version 1.0, the name "flash scope" was used for what is now called
+ "access scope". The two concepts are the same; when using orchestra 1.1
+ you must simply write "flash" wherever the more modern documentation
+ states "access". Orchestra 1.1 supports the old term for backwards
+ compatibility, so configuration files written for 1.0 should work fine
+ with release 1.1.
+ </subsection>
+ </subsection>
+ </section>
+ </body>
+</document>
Propchange: myfaces/orchestra/trunk/core/src/site/xdoc/usage.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: myfaces/orchestra/trunk/core/src/site/xdoc/viewController.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/viewController.xml?rev=617625&r1=617624&r2=617625&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/viewController.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/viewController.xml Fri Feb 1 12:02:48 2008
@@ -1,199 +1,199 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
- "http://www.apache.org/dtd/xdoc.dtd">
-<!--
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
- -->
-<document>
- <properties>
- <title>ViewController</title>
- </properties>
-
- <body>
- <section name="View Controller">
-
- <p>
- The ViewController is just a concept which binds a specific bean to a web-page.
- In JSF this means, you have a managed bean configured which directly matches to a view-id.
- </p>
- <p>
- If you follow this concept you'll gain some very comfortable things. They are:
- <br />
- Notifications:
- <ul>
- <li>initView
- <br />
- This event will be fired after the JSF <code>RESTORE_VIEW</code> phase.
- </li>
- <li>preProcess
- <br />
- This event will be fired before the JSF <code>INVOKE_APPLICATION</code> phase.
- </li>
- <li>preRenderView
- <br />
- This event will be fired before the JSF <code>PRE_RENDER</code> phase.
- </li>
- </ul>
- The ViewController concept is also the base for the core15 annotation
- <code>@ConversationRequire</code> which allows you to issue a redirect if a
- conversations timed-out in the mid of a e.g. wizzard style pageflow.
- <br />
- <br />
- <b>Notice:</b> Your view controller bean has to be configured inside the spring-configuration file.
-
- </p>
-
- <subsection name="Installation">
-
- <p>
- In a JSF environment Orchestra already configures the JSF system in a way which allows
- you to start using this concept.
- This has been done by installing the PhaseListener
- <code>org.apache.myfaces.orchestra.viewController.jsf.ViewControllerPhaseListener</code>.
- <br/>
- However, there is a way which allows you to adjust the configuration as required.
- </p>
- <p>
- To make the ViewController work you need to have two things:
- <ul>
- <li>A NameMapper (org.apache.myfaces.orchestra.viewController.ViewControllerNameMapper)
- <br/>
- The NameMapper is responsible to build a managed-bean name out of the view-id.
- </li>
- <li>An Executor (org.apache.myfaces.orchestra.viewController.AbstractViewControllerExecutor)
- <br/>
- The Executor finally will invoke some methods on this managed-bean then
- (if there is a bean with the mapped name).
- </li>
- </ul>
-
- Both things will be used by the
- <code>ViewControllerManager</code>. Now, if you are in need
- of a custom name mapping scheme, just create jour own
- <code>ViewControllerManager</code> by inheriting from the
- <code>org.apache.myfaces.orchestra.viewController.AbstractViewControllerManager</code>
- class. Two methods you have to implement allow you to provide custom implementations for the
- <code>>NameMapper</code> and the <code>Executor</code>.
- <br/>
- Finally you have to configure your implementation by adding an bean definition with the name
- <code>org.apache.myfaces.orchestra.viewController.ViewControllerManager</code>. For example:
- <pre>
-<bean
- name="org.apache.myfaces.orchestra.viewController.ViewControllerManager"
- class="your.package.YourViewController"
- scope="singleton">
-
-</bean>
- </pre>
-
- </p>
-
- </subsection>
-
- <subsection name="DefaultViewControllerNameMapper">
- There is a default NameMapper which will be used if you do not provide your own.
- The mapping will be as follows:
- <ul>
- <li>Convert each character after a "/" to upper-case</li>
- <li>Remove any occurence of the "/" character</li>
- <li>Stop at the first "." character and remove the rest</li>
- <li>Prefix with a "_" character if the result is a reserved word or an invalid bean name</li>
- </ul>
- Examples:
- <table>
- <tr>
- <th>View-Id</th>
- <th>Bean name</th>
- </tr>
- <tr>
- <td>mainform.jsp</td>
- <td>mainform</td>
- </tr>
- <tr>
- <td>userData/password.jsp</td>
- <td>userDataPassword</td>
- </tr>
- <tr>
- <td>requestScope.jsp</td>
- <td>_requestScope</td>
- </tr>
- <tr>
- <td>123set.jsp</td>
- <td>_123set</td>
- </tr>
- </table>
- </subsection>
-
- <subsection name="ViewControllerExecutor (AbstractViewControllerExecutor)">
- The ViewControllerExecutor is responsible to invoke the notification methods on your
- managed-bean.<br />
- Currently the Orchestra standard provides the following methods:
- <ul>
- <li>ReflectiveViewControllerExecutor (default)
- <br />
- The <code>ReflectiveViewControllerExecutor</code> uses reflection to lookup the
- following public methods: initView, preRenderView, preProcess. <br />
- All of the methods are optional.
- </li>
- <li>InterfaceViewControllerExecutor
- <br />
- The <code>InterfaceViewControllerExecutor</code> requires you to implement the
- <code>org.apache.myfaces.orchestra.viewController.ViewController</code> interface.
- </li>
- <li>AnnotationsViewControllerExecutor (core15)
- <br />
- The <code>AnnotationsViewControllerExecutor</code> might be the most powerful one.
- It allows you to configure a managed bean as view controller without following any
- naming scheme. Not for the bean name nor for the method name.<br />
- This is a feature of the core15 module.
- </li>
- </ul>
- Again, you have to configure a custom <code>ViewControllerManager</code> if you
- do not want the default <code>ReflectiveViewControllerExecutor</code>.<br />
- </subsection>
-
- <subsection name="AnnotationsViewController">
- To work with the <code>AnnotationsViewController</code> you have to use the core15
- module. Once you added the jar to your classpath and configured the
- <a href="installation.html">required import</a> statement
- in your configuration file you are done.
- <br />
- The biggest advantage the <code>AnnotationsViewController</code> provides is, that you do
- not have to follow any naming scheme. Just annotate your managed-bean with the
- <code>@ViewController</code> annotation.
- <br />
- Example:
- <pre>
-@ViewController(
- viewIds={"/annotations/Page1.jsp", "/annotations/Page2.jsp", "/annotations/Page3.jsp"})
-public class MultiViewController
-{
- </pre>
- Which means the class <code>MultiViewController</code> is responsible for the three
- configured pages and will receive the notification to the methods annotated with the
- <ul>
- <li>@InitView</li>
- <li>@PreProcess</li>
- <li>@PreRenderView</li>
- </ul>
- annotation.
- </subsection>
-
- </section>
- </body>
-</document>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
+ "http://www.apache.org/dtd/xdoc.dtd">
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ -->
+<document>
+ <properties>
+ <title>ViewController</title>
+ </properties>
+
+ <body>
+ <section name="View Controller">
+
+ <p>
+ The ViewController is just a concept which binds a specific bean to a web-page.
+ In JSF this means, you have a managed bean configured which directly matches to a view-id.
+ </p>
+ <p>
+ If you follow this concept you'll gain some very comfortable things. They are:
+ <br />
+ Notifications:
+ <ul>
+ <li>initView
+ <br />
+ This event will be fired after the JSF <code>RESTORE_VIEW</code> phase.
+ </li>
+ <li>preProcess
+ <br />
+ This event will be fired before the JSF <code>INVOKE_APPLICATION</code> phase.
+ </li>
+ <li>preRenderView
+ <br />
+ This event will be fired before the JSF <code>PRE_RENDER</code> phase.
+ </li>
+ </ul>
+ The ViewController concept is also the base for the core15 annotation
+ <code>@ConversationRequire</code> which allows you to issue a redirect if a
+ conversations timed-out in the mid of a e.g. wizzard style pageflow.
+ <br />
+ <br />
+ <b>Notice:</b> Your view controller bean has to be configured inside the spring-configuration file.
+
+ </p>
+
+ <subsection name="Installation">
+
+ <p>
+ In a JSF environment Orchestra already configures the JSF system in a way which allows
+ you to start using this concept.
+ This has been done by installing the PhaseListener
+ <code>org.apache.myfaces.orchestra.viewController.jsf.ViewControllerPhaseListener</code>.
+ <br/>
+ However, there is a way which allows you to adjust the configuration as required.
+ </p>
+ <p>
+ To make the ViewController work you need to have two things:
+ <ul>
+ <li>A NameMapper (org.apache.myfaces.orchestra.viewController.ViewControllerNameMapper)
+ <br/>
+ The NameMapper is responsible to build a managed-bean name out of the view-id.
+ </li>
+ <li>An Executor (org.apache.myfaces.orchestra.viewController.AbstractViewControllerExecutor)
+ <br/>
+ The Executor finally will invoke some methods on this managed-bean then
+ (if there is a bean with the mapped name).
+ </li>
+ </ul>
+
+ Both things will be used by the
+ <code>ViewControllerManager</code>. Now, if you are in need
+ of a custom name mapping scheme, just create jour own
+ <code>ViewControllerManager</code> by inheriting from the
+ <code>org.apache.myfaces.orchestra.viewController.AbstractViewControllerManager</code>
+ class. Two methods you have to implement allow you to provide custom implementations for the
+ <code>>NameMapper</code> and the <code>Executor</code>.
+ <br/>
+ Finally you have to configure your implementation by adding an bean definition with the name
+ <code>org.apache.myfaces.orchestra.viewController.ViewControllerManager</code>. For example:
+ <pre>
+<bean
+ name="org.apache.myfaces.orchestra.viewController.ViewControllerManager"
+ class="your.package.YourViewController"
+ scope="singleton">
+
+</bean>
+ </pre>
+
+ </p>
+
+ </subsection>
+
+ <subsection name="DefaultViewControllerNameMapper">
+ There is a default NameMapper which will be used if you do not provide your own.
+ The mapping will be as follows:
+ <ul>
+ <li>Convert each character after a "/" to upper-case</li>
+ <li>Remove any occurence of the "/" character</li>
+ <li>Stop at the first "." character and remove the rest</li>
+ <li>Prefix with a "_" character if the result is a reserved word or an invalid bean name</li>
+ </ul>
+ Examples:
+ <table>
+ <tr>
+ <th>View-Id</th>
+ <th>Bean name</th>
+ </tr>
+ <tr>
+ <td>mainform.jsp</td>
+ <td>mainform</td>
+ </tr>
+ <tr>
+ <td>userData/password.jsp</td>
+ <td>userDataPassword</td>
+ </tr>
+ <tr>
+ <td>requestScope.jsp</td>
+ <td>_requestScope</td>
+ </tr>
+ <tr>
+ <td>123set.jsp</td>
+ <td>_123set</td>
+ </tr>
+ </table>
+ </subsection>
+
+ <subsection name="ViewControllerExecutor (AbstractViewControllerExecutor)">
+ The ViewControllerExecutor is responsible to invoke the notification methods on your
+ managed-bean.<br />
+ Currently the Orchestra standard provides the following methods:
+ <ul>
+ <li>ReflectiveViewControllerExecutor (default)
+ <br />
+ The <code>ReflectiveViewControllerExecutor</code> uses reflection to lookup the
+ following public methods: initView, preRenderView, preProcess. <br />
+ All of the methods are optional.
+ </li>
+ <li>InterfaceViewControllerExecutor
+ <br />
+ The <code>InterfaceViewControllerExecutor</code> requires you to implement the
+ <code>org.apache.myfaces.orchestra.viewController.ViewController</code> interface.
+ </li>
+ <li>AnnotationsViewControllerExecutor (core15)
+ <br />
+ The <code>AnnotationsViewControllerExecutor</code> might be the most powerful one.
+ It allows you to configure a managed bean as view controller without following any
+ naming scheme. Not for the bean name nor for the method name.<br />
+ This is a feature of the core15 module.
+ </li>
+ </ul>
+ Again, you have to configure a custom <code>ViewControllerManager</code> if you
+ do not want the default <code>ReflectiveViewControllerExecutor</code>.<br />
+ </subsection>
+
+ <subsection name="AnnotationsViewController">
+ To work with the <code>AnnotationsViewController</code> you have to use the core15
+ module. Once you added the jar to your classpath and configured the
+ <a href="installation.html">required import</a> statement
+ in your configuration file you are done.
+ <br />
+ The biggest advantage the <code>AnnotationsViewController</code> provides is, that you do
+ not have to follow any naming scheme. Just annotate your managed-bean with the
+ <code>@ViewController</code> annotation.
+ <br />
+ Example:
+ <pre>
+@ViewController(
+ viewIds={"/annotations/Page1.jsp", "/annotations/Page2.jsp", "/annotations/Page3.jsp"})
+public class MultiViewController
+{
+ </pre>
+ Which means the class <code>MultiViewController</code> is responsible for the three
+ configured pages and will receive the notification to the methods annotated with the
+ <ul>
+ <li>@InitView</li>
+ <li>@PreProcess</li>
+ <li>@PreRenderView</li>
+ </ul>
+ annotation.
+ </subsection>
+
+ </section>
+ </body>
+</document>
Propchange: myfaces/orchestra/trunk/core/src/site/xdoc/viewController.xml
------------------------------------------------------------------------------
svn:eol-style = native