You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by bu...@apache.org on 2013/03/23 00:38:44 UTC
svn commit: r855627 - in /websites/staging/deltaspike/trunk/content: ./
deltaspike/jsf.html
Author: buildbot
Date: Fri Mar 22 23:38:44 2013
New Revision: 855627
Log:
Staging update by buildbot for deltaspike
Modified:
websites/staging/deltaspike/trunk/content/ (props changed)
websites/staging/deltaspike/trunk/content/deltaspike/jsf.html
Propchange: websites/staging/deltaspike/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Fri Mar 22 23:38:44 2013
@@ -1 +1 @@
-1430546
+1460054
Modified: websites/staging/deltaspike/trunk/content/deltaspike/jsf.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/deltaspike/jsf.html (original)
+++ websites/staging/deltaspike/trunk/content/deltaspike/jsf.html Fri Mar 22 23:38:44 2013
@@ -78,7 +78,202 @@
<div class="page-title">
<h1>JSF</h1>
</div>
- <h1 id="jsf">Jsf</h1>
+ <h1 id="type-safe-view-configs">Type-safe View-Configs</h1>
+<h2 id="intro">Intro</h2>
+<p>Type-safe view-configs are static configs which can be used in combination with every view-technology which is based on Java.
+Currently DeltaSpike itself provides an integration for JSF, however, the basic concepts are independent of it.
+(Since DeltaSpike provides the default integration only for JSF, the whole documentation for view-configs is located here.)</p>
+<p>Thanks to features like multiple (meta-data-)inheritance via interfaces, it provides a powerful approach to bind meta-data to one or multiple views.
+In case of the JSF integration it's possible to provide e.g. type-safe meta-data for security, navigation, callbacks for view-controllers.
+Beyond configuring view (/pages) via this concept, it's also possible to use the (view-)config classes for type-safe navigation.
+Since it's std. Java, you can benefit from any Java-IDE and you don't need special IDE-Addons to use it efficiently.</p>
+<p>Even the concepts provided by modules (of DeltaSpike itself) are based on the basic API provided by the Core. So it's possible to introduce custom concepts the same way DeltaSpike itself does.</p>
+<h2 id="basic-api-usages">Basic API usages</h2>
+<p>Usually users don't need to be aware of all descriptors, SPIs,... which are described by this documentation.</p>
+<p>There are a lot of possibilities to configure views and some of them are optional.
+The following examples show some of them in combination with features provided by the JSF- and Security-Module of DeltaSpike.</p>
+<p>The following example shows the minimal syntax for providing a config for a view (/page).</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyPage</span> <span class="kd">implements</span> <span class="n">ViewConfig</span>
+<span class="o">{</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Since it's a class (and not an interface) it's autom. recognized as config for a page (and not a folder) and the default settings get applied during bootstrapping.
+In case of JSF you can use it for navigation e.g. via action-methods.</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span class="n">Class</span><span class="o"><?</span> <span class="kd">extends</span> <span class="n">ViewConfig</span><span class="o">></span> <span class="n">toNextPage</span><span class="o">()</span>
+<span class="o">{</span>
+ <span class="k">return</span> <span class="n">MyPage</span><span class="o">.</span><span class="na">class</span><span class="o">;</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>This leads to a forward to /myPage.xhtml. Information like base-path, file- (and folder-)name/s, file-extension, navigation mode, view-params,... can be customized with the corresponding (meta-data-)annotations.
+One of those annotations provided by the JSF module (which is optional) is @View. That means the following example leads to the same as the first one.</p>
+<div class="codehilite"><pre><span class="nd">@View</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyPage</span> <span class="kd">implements</span> <span class="n">ViewConfig</span>
+<span class="o">{</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>But it's also possible to reflect the folder structure via nesting of interfaces and classes. An example for it is:</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span class="kd">interface</span> <span class="nc">Pages</span>
+<span class="o">{</span>
+ <span class="kd">public</span> <span class="kd">class</span> <span class="nc">Index</span> <span class="kd">implements</span> <span class="n">ViewConfig</span> <span class="o">{</span> <span class="o">}</span>
+
+ <span class="kd">public</span> <span class="kd">interface</span> <span class="nc">AdminArea</span> <span class="kd">extends</span> <span class="n">ViewConfig</span>
+ <span class="o">{</span>
+ <span class="kd">public</span> <span class="kd">class</span> <span class="nc">Index</span> <span class="kd">implements</span> <span class="n">Admin</span> <span class="o">{</span> <span class="o">}</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>In case of the JSF integration it leads to the following view-ids:<br/>
+/pages/index.xhtml<br/>
+/pages/adminArea/index.xhtml<br/></p>
+<p>Like the optional @View for pages represented by the classes, it's possible to use the optional @Folder annotation for directories represented by the (nested) interfaces.</p>
+<p>Furthermore, it's possible to inherit meta-data along with the normal inheritance.</p>
+<p>In the following example Pages.Admin.Index, Pages.Admin.Home and Pages.Admin.Statistics.Home inherit the meta-data from Pages.Admin because they implement the interface whereas Pages.Admin.Statistics.Index doesn't. However, Pages.Admin.Home overrides View#navigation. During the bootstrapping process the meta-data gets merged and at runtime you only see the final result (which is cached).</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span class="kd">interface</span> <span class="nc">Pages</span>
+<span class="o">{</span>
+ <span class="nd">@View</span><span class="o">(</span><span class="n">name</span> <span class="o">=</span> <span class="s">"home"</span><span class="o">,</span> <span class="n">extension</span> <span class="o">=</span> <span class="n">JSP</span><span class="o">)</span> <span class="kd">public</span> <span class="kd">class</span> <span class="nc">Index</span> <span class="kd">implements</span> <span class="n">ViewConfig</span> <span class="o">{</span> <span class="o">}</span>
+
+ <span class="nd">@View</span><span class="o">(</span><span class="n">navigation</span> <span class="o">=</span> <span class="n">REDIRECT</span><span class="o">,</span> <span class="n">viewParams</span> <span class="o">=</span> <span class="n">INCLUDE</span><span class="o">)</span>
+ <span class="kd">public</span> <span class="kd">interface</span> <span class="nc">Admin</span> <span class="kd">extends</span> <span class="n">ViewConfig</span>
+ <span class="o">{</span>
+ <span class="kd">public</span> <span class="kd">interface</span> <span class="nc">Statistics</span>
+ <span class="o">{</span>
+ <span class="nd">@View</span> <span class="c1">//optional</span>
+ <span class="kd">public</span> <span class="kd">class</span> <span class="nc">Index</span> <span class="kd">implements</span> <span class="n">ViewConfig</span> <span class="o">{</span> <span class="o">}</span>
+
+ <span class="kd">public</span> <span class="kd">class</span> <span class="nc">Home</span> <span class="kd">implements</span> <span class="n">Admin</span> <span class="o">{</span> <span class="o">}</span>
+ <span class="o">}</span>
+
+ <span class="kd">public</span> <span class="kd">class</span> <span class="nc">Index</span> <span class="kd">implements</span> <span class="n">Admin</span> <span class="o">{</span> <span class="o">}</span>
+
+ <span class="nd">@View</span><span class="o">(</span><span class="n">navigation</span> <span class="o">=</span> <span class="n">FORWARD</span><span class="o">)</span>
+ <span class="kd">public</span> <span class="kd">class</span> <span class="nc">Home</span> <span class="kd">implements</span> <span class="n">Admin</span> <span class="o">{</span> <span class="o">}</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>In this case Pages.Admin.Statistics is just an interface to reflect the folder structure. For sure it's also possible that it extends an existing view-config interface and other folders and/or pages inherit its meta-data (like Pages.Admin).</p>
+<p>Furthermore, inheritance can be used to ensure navigation to the correct area in the application. In the following example the return type of the action-method (and therefore the compiler of Java) ensures that the navigation target of this method is within the admin-area.</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span class="n">Class</span><span class="o"><?</span> <span class="kd">extends</span> <span class="n">Pages</span><span class="o">.</span><span class="na">Admin</span><span class="o">></span> <span class="n">toNextPage</span><span class="o">()</span>
+<span class="o">{</span>
+ <span class="k">return</span> <span class="n">Pages</span><span class="o">.</span><span class="na">Admin</span><span class="o">.</span><span class="na">Index</span><span class="o">.</span><span class="na">class</span><span class="o">;</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h3 id="using-folder">Using @Folder</h3>
+<p>[TODO]</p>
+<h3 id="navigation-parameters">Navigation Parameters</h3>
+<p>[TODO]</p>
+<h4 id="static-configuration-via-navigationparameter">Static Configuration via @NavigationParameter</h4>
+<p>[TODO]</p>
+<h4 id="dynamic-configuration-via-navigationparametercontext">Dynamic Configuration via NavigationParameterContext</h4>
+<p>[TODO]</p>
+<h3 id="security-integration-via-secured">Security Integration via @Secured</h3>
+<p>This annotation is a custom view-meta-data provided by the Security-module which allows to integrate 3rd party frameworks (or custom approaches) to secure pages as well as whole folders.
+You can annotate specific parts or a marker-interface. CustomAccessDecisionVoter used in the following example can be any implementation of org.apache.deltaspike.security.api.authorization.AccessDecisionVoter.
+All parts which inherit from SecuredPages (Pages.Admin, Pages.Admin.Index and Pages.Admin.Home) are protected by CustomAccessDecisionVoter.<br/></p>
+<p>(It's easy to check this hierarchy in a modern Java-IDE. Only for displaying the final meta-data for every node in the IDE a special plug-in would be needed.)</p>
+<div class="codehilite"><pre><span class="nd">@Secured</span><span class="o">(</span><span class="n">CustomAccessDecisionVoter</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">SecuredPages</span> <span class="o">{}</span>
+
+<span class="nd">@View</span><span class="o">(</span><span class="n">navigation</span> <span class="o">=</span> <span class="n">REDIRECT</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">Pages</span> <span class="kd">extends</span> <span class="n">ViewConfig</span>
+<span class="o">{</span>
+ <span class="kd">public</span> <span class="kd">class</span> <span class="nc">Index</span> <span class="kd">implements</span> <span class="n">Pages</span> <span class="o">{</span> <span class="o">}</span>
+
+ <span class="kd">public</span> <span class="kd">interface</span> <span class="nc">Admin</span> <span class="kd">extends</span> <span class="n">Pages</span><span class="o">,</span> <span class="n">SecuredPages</span>
+ <span class="o">{</span>
+ <span class="kd">public</span> <span class="kd">class</span> <span class="nc">Index</span> <span class="kd">implements</span> <span class="n">Admin</span> <span class="o">{</span> <span class="o">}</span>
+
+ <span class="nd">@View</span><span class="o">(</span><span class="n">navigation</span> <span class="o">=</span> <span class="n">FORWARD</span><span class="o">)</span>
+ <span class="kd">public</span> <span class="kd">class</span> <span class="nc">Home</span> <span class="kd">implements</span> <span class="n">Admin</span> <span class="o">{</span> <span class="o">}</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>For sure it's also possible to use it without a special interface. In this case you would need:</p>
+<div class="codehilite"><pre><span class="nd">@View</span><span class="o">(</span><span class="n">navigation</span> <span class="o">=</span> <span class="n">REDIRECT</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">Pages</span> <span class="kd">extends</span> <span class="n">ViewConfig</span>
+<span class="o">{</span>
+ <span class="kd">public</span> <span class="kd">class</span> <span class="nc">Index</span> <span class="kd">implements</span> <span class="n">Pages</span> <span class="o">{</span> <span class="o">}</span>
+
+ <span class="nd">@Secured</span><span class="o">(</span><span class="n">CustomAccessDecisionVoter</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
+ <span class="kd">public</span> <span class="kd">interface</span> <span class="nc">Admin</span> <span class="kd">extends</span> <span class="n">Pages</span>
+ <span class="o">{</span>
+ <span class="kd">public</span> <span class="kd">class</span> <span class="nc">Index</span> <span class="kd">implements</span> <span class="n">Admin</span> <span class="o">{</span> <span class="o">}</span>
+
+ <span class="nd">@View</span><span class="o">(</span><span class="n">navigation</span> <span class="o">=</span> <span class="n">FORWARD</span><span class="o">)</span>
+ <span class="kd">public</span> <span class="kd">class</span> <span class="nc">Home</span> <span class="kd">implements</span> <span class="n">Admin</span> <span class="o">{</span> <span class="o">}</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>or</p>
+<div class="codehilite"><pre><span class="nv">@View</span><span class="p">(</span><span class="n">navigation</span> <span class="o">=</span> <span class="n">REDIRECT</span><span class="p">)</span>
+<span class="n">public</span> <span class="n">interface</span> <span class="n">Pages</span> <span class="n">extends</span> <span class="n">ViewConfig</span>
+<span class="p">{</span>
+ <span class="n">public</span> <span class="n">class</span> <span class="n">Index</span> <span class="n">implements</span> <span class="n">Pages</span> <span class="p">{</span> <span class="p">}</span>
+
+ <span class="n">public</span> <span class="n">interface</span> <span class="n">Admin</span> <span class="n">extends</span> <span class="n">Pages</span>
+ <span class="p">{</span>
+ <span class="nv">@Secured</span><span class="p">(</span><span class="n">CustomAccessDecisionVoter</span><span class="o">.</span><span class="n">class</span><span class="p">)</span>
+ <span class="n">public</span> <span class="n">class</span> <span class="n">Index</span> <span class="n">implements</span> <span class="n">Admin</span> <span class="p">{</span> <span class="p">}</span>
+
+ <span class="nv">@Secured</span><span class="p">(</span><span class="n">CustomAccessDecisionVoter</span><span class="o">.</span><span class="n">class</span><span class="p">)</span>
+ <span class="nv">@View</span><span class="p">(</span><span class="n">navigation</span> <span class="o">=</span> <span class="n">FORWARD</span><span class="p">)</span>
+ <span class="n">public</span> <span class="n">class</span> <span class="n">Home</span> <span class="n">implements</span> <span class="n">Admin</span> <span class="p">{</span> <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h3 id="view-controller-callbacks-via-viewcontrollerbean">View-Controller Callbacks via @ViewControllerBean</h3>
+<p>This annotation is a custom view-meta-data provided by the JSF-module which allows to configure beans which should act as view-controllers. That means they can use view-controller callbacks like @InitView, @PreViewAction, @PreRenderView and @PostRenderView. The following example shows the usage of @PreRenderView.</p>
+<div class="codehilite"><pre><span class="c1">//@View //optional</span>
+<span class="nd">@ViewControllerBean</span><span class="o">(</span><span class="n">MyPageController</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyPage</span> <span class="kd">implements</span> <span class="n">ViewConfig</span>
+<span class="o">{</span>
+<span class="o">}</span>
+
+<span class="nd">@Model</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyPageController</span>
+<span class="o">{</span>
+ <span class="nd">@PreRenderView</span>
+ <span class="kd">protected</span> <span class="kt">void</span> <span class="nf">load</span><span class="o">()</span>
+ <span class="o">{</span>
+ <span class="c1">//...</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h3 id="referencing-views-via-viewref">Referencing Views via @ViewRef</h3>
+<p>[TODO]</p>
+<h3 id="configuring-a-default-error-view">Configuring a Default Error-View</h3>
+<p>[TODO]</p>
+<h3 id="using-matches">Using @Matches</h3>
+<p>[TODO]</p>
+<h3 id="using-viewconfigresolver">Using ViewConfigResolver</h3>
+<p>[TODO]</p>
+<h2 id="advanced-api-usages">Advanced API usages</h2>
+<p>[TODO]</p>
+<h3 id="creating-custom-meta-data-via-viewmetadata">Creating Custom Meta-Data via @ViewMetaData</h3>
+<p>[TODO]</p>
+<h3 id="creating-custom-callbacks-via-viewmetadata">Creating Custom Callbacks via @ViewMetaData</h3>
+<p>[TODO]</p>
+<h2 id="view-config-spi">View-Config SPI</h2>
+<p>[TODO]</p>
</div>
</div>