KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > beehive > netui > pageflow > SharedFlowController


1 /*
2 * Copyright 2004 The Apache Software Foundation.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 *
16 * $Header:$
17 */
18 package org.apache.beehive.netui.pageflow;
19
20 import org.apache.struts.action.ActionForward;
21 import org.apache.struts.action.ActionForm;
22 import org.apache.struts.action.ActionMapping;
23
24 import javax.servlet.http.HttpServletRequest JavaDoc;
25 import javax.servlet.http.HttpServletResponse JavaDoc;
26 import javax.servlet.http.HttpSession JavaDoc;
27 import javax.servlet.ServletContext JavaDoc;
28
29 import org.apache.beehive.netui.pageflow.internal.AdapterManager;
30 import org.apache.beehive.netui.pageflow.internal.InternalConstants;
31
32
33 /**
34  * <p>
35  * Base "shared flow" class for controller logic, exception handlers, and state that can be shared by any number of page
36  * flows. A shared flow is <i>not</i> a page flow; it is used by page flows, but never becomes the "current page flow"
37  * (see {@link PageFlowController} for information on page flows and the "current page flow").
38  * The class is configured through the
39  * {@link org.apache.beehive.netui.pageflow.annotations.Jpf.Controller &#64;Jpf.Controller} annotation.
40  * </p>
41  *
42  * <p>
43  * A shared flow comes into existance in one of two ways:
44  * <ul>
45  * <li>
46  * A page flow is hit, and the page flow refers to the shared flow in its
47  * {@link org.apache.beehive.netui.pageflow.annotations.Jpf.Controller#sharedFlowRefs sharedFlowRefs}
48  * annotation attribute, or
49  * </li>
50  * <li>
51  * Any page flow is hit, and the <code>&lt;default-shared-flow-refs&gt;</code> element in
52  * /WEB-INF/beehive-netui-config.xml declares that this shared flow will be used by all page flows in the web
53  * application.
54  * </li>
55  * </ul>
56  * When a shared flow is created, it is stored in the user session. It is only removed through a call to
57  * {@link #remove} or through a call to {@link PageFlowUtils#removeSharedFlow}.
58  * </p>
59  *
60  * <p>
61  * Shared flow actions are defined with <i>action methods</i> or <i>action annotations</i> that determine the next URI
62  * to be displayed, after optionally performing arbitrary logic. A page or page flow can raise a shared flow action
63  * using the pattern <code>"</code><i>shared-flow-name</i><code>.</code><i>action-name</i><code>"</code>. The shared
64  * flow name is the one chosen by the page flow
65  * in {@link org.apache.beehive.netui.pageflow.annotations.Jpf.SharedFlowRef#name name}
66  * on {@link org.apache.beehive.netui.pageflow.annotations.Jpf.SharedFlowRef &#64;Jpf.SharedFlowRef}.
67  * </p>
68  *
69  * <p>
70  * A referenced shared flow gets the chance to handle any uncaught page flow exception. It declares its exception
71  * handling through {@link org.apache.beehive.netui.pageflow.annotations.Jpf.Controller#catches catches}
72  * on {@link org.apache.beehive.netui.pageflow.annotations.Jpf.Controller &#64;Jpf.Controller}.
73  * </p>
74  *
75  * <p>
76  * Properties in the current shared flow instance can be accessed from JSP 2.0-style expressions like this one:
77  * <code>${sharedFlow.</code><i>sharedFlowName</i><code>.someProperty}</code>.
78  * </p>
79  *
80  * <p>
81  * There may only be one shared flow in any package.
82  * </p>
83  *
84  * @see PageFlowController
85  */
86 public abstract class SharedFlowController
87         extends FlowController
88         implements PageFlowConstants
89 {
90     private transient String JavaDoc _modulePath;
91     
92     /**
93      * Get the Struts module path for actions in this shared flow.
94      *
95      * @return the Struts module path for actions in this shared flow.
96      */
97     public String JavaDoc getModulePath()
98     {
99         if ( _modulePath == null )
100         {
101             String JavaDoc className = getClass().getName();
102             int lastDot = className.lastIndexOf( '.' );
103             assert lastDot != -1 : className;
104             className = className.substring( 0, lastDot );
105             _modulePath = "/-" + className.replace( '.', '/' );
106         }
107         
108         return _modulePath;
109     }
110     
111     /**
112      * Store this object in the user session, in the appropriate place. Used by the framework; normally should not be
113      * called directly.
114      */
115     public void persistInSession( HttpServletRequest JavaDoc request, HttpServletResponse JavaDoc response )
116     {
117         request.getSession().setAttribute( InternalConstants.SHARED_FLOW_ATTR_PREFIX + getClass().getName(), this );
118     }
119     
120     /**
121      * Ensures that any changes to this object will be replicated in a cluster (for failover),
122      * even if the replication scheme uses a change-detection algorithm that relies on
123      * HttpSession.setAttribute to be aware of changes. Note that this method is used by the framework
124      * and does not need to be called explicitly in most cases.
125      *
126      * @param request the current HttpServletRequest
127      */
128     public void ensureFailover( HttpServletRequest JavaDoc request )
129     {
130         ServletContainerAdapter servletContainerAdapter = AdapterManager.getServletContainerAdapter( getServletContext() );
131         servletContainerAdapter.ensureFailover( InternalConstants.SHARED_FLOW_ATTR_PREFIX + getClass().getName(), this, request );
132     }
133     
134     /**
135      * Get the URI.
136      * @return <code>null</code>, as this object is not URL-addressible.
137      */
138     public String JavaDoc getURI()
139     {
140         return "/";
141     }
142     
143     /**
144      * Get the display name. The display name for a shared flow is simply the class name.
145      * @return the name of the shared flow class.
146      */
147     public String JavaDoc getDisplayName()
148     {
149         return getClass().getName();
150     }
151     
152     /**
153      * Get a legacy PreviousPageInfo.
154      * @deprecated This method will be removed without replacement in a future release.
155      */
156     public PreviousPageInfo getPreviousPageInfoLegacy( PageFlowController curJpf, HttpServletRequest JavaDoc request )
157     {
158         assert curJpf != null;
159         return curJpf.getCurrentPageInfo();
160     }
161     
162     /**
163      * Store information about recent pages displayed. This is a framework-invoked method that should not normally be
164      * called directly.
165      */
166     public void savePreviousPageInfo( ActionForward forward, ActionForm form, ActionMapping mapping,
167                                       HttpServletRequest JavaDoc request, ServletContext JavaDoc servletContext,
168                                       boolean isSpecialForward )
169     {
170         //
171 // Special case: if the given forward has a path to a page in the current pageflow, let that pageflow save
172 // the info on this page. Otherwise, don't ever save any info on what we're forwarding to.
173 //
174 if ( ! isSpecialForward && forward != null ) // i.e., it's a straight Forward to a path, not a navigateTo, etc.
175 {
176             PageFlowController currentJpf = PageFlowUtils.getCurrentPageFlow( request );
177             
178             if ( currentJpf != null )
179             {
180                 if ( forward.getContextRelative() && forward.getPath().startsWith( currentJpf.getModulePath() ) )
181                 {
182                     currentJpf.savePreviousPageInfo( forward, form, mapping, request, servletContext, isSpecialForward );
183                 }
184             }
185         }
186     }
187
188     /**
189      * Store information about the most recent action invocation. This is a framework-invoked method that should not
190      * normally be called directly
191      */
192     void savePreviousActionInfo( ActionForm form, HttpServletRequest JavaDoc request, ActionMapping mapping,
193                                  ServletContext JavaDoc servletContext )
194     {
195         //
196 // Save this previous-action info in the *current page flow*.
197 //
198 PageFlowController currentJpf = PageFlowUtils.getCurrentPageFlow( request );
199         if ( currentJpf != null ) currentJpf.savePreviousActionInfo( form, request, mapping, servletContext );
200     }
201
202     /**
203      * Remove this instance from the session. When inside a shared flow action, {@link #remove} may be called instead.
204      */
205     protected synchronized void removeFromSession( HttpServletRequest JavaDoc request )
206     {
207         PageFlowUtils.removeSharedFlow( getClass().getName(), request );
208     }
209 }
210
Popular Tags