001    // Copyright 2004, 2005 The Apache Software Foundation
002    //
003    // Licensed under the Apache License, Version 2.0 (the "License");
004    // you may not use this file except in compliance with the License.
005    // You may obtain a copy of the License at
006    //
007    //     http://www.apache.org/licenses/LICENSE-2.0
008    //
009    // Unless required by applicable law or agreed to in writing, software
010    // distributed under the License is distributed on an "AS IS" BASIS,
011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012    // See the License for the specific language governing permissions and
013    // limitations under the License.
014    
015    package org.apache.tapestry.callback;
016    
017    import org.apache.hivemind.util.Defense;
018    import org.apache.tapestry.IPage;
019    import org.apache.tapestry.IRequestCycle;
020    
021    /**
022     * Simple callback for returning to a page.
023     * <p>
024     * Example usage of <tt>PageCallback</tt>:
025     * <p>
026     * The Home page ensure a user is authenticated in the
027     * {@link org.apache.tapestry.IPage#validate(IRequestCycle)} method. If the user is not
028     * authenticated, they are redirected to the Login page, after setting a callback in the Login page.
029     * <p>
030     * The Login page <tt>formSubmit()</tt> {@link org.apache.tapestry.IActionListener} authenticates
031     * the user and then invokes {@link ICallback#performCallback(IRequestCycle)} to the Home page.
032     * 
033     * <pre>
034     * 
035     *  
036     *    public class Home extends BasePage {
037     *   
038     *        public void validate(IRequestCycle cycle) {            
039     *            Visit visit = (Visit) getVisit();
040     *        
041     *            if (!visit.isAuthenticated()) {
042     *                Login login = (Login) cycle.getPage(&quot;Login&quot;);
043     *  
044     *                login.setCallback(new PageCallback(this));
045     *                
046     *                throw new PageRedirectException(login);
047     *            }            
048     *        }
049     *    }
050     *  
051     *    public Login extends BasePage {
052     *   
053     *        private ICallback _callback;
054     *  
055     *        public void setCallback(ICallback _callback) {
056     *            _callback = callback;
057     *        }
058     *  
059     *        public void formSubmit(IRequestCycle cycle) {
060     *            // Authentication code
061     *            ..
062     *     
063     *            Visit visit = (Visit) getVisit();
064     *  
065     *            visit.setAuthenticated(true);
066     *    
067     *            if (_callback != null) {
068     *                _callback.performCallback(cycle);
069     *            }
070     *        }
071     *    }    
072     *    
073     *  
074     * </pre>
075     * 
076     * @author Howard Lewis Ship
077     * @since 0.2.9
078     */
079    
080    public class PageCallback implements ICallback
081    {
082        /**
083         * @since 2.0.4
084         */
085    
086        private static final long serialVersionUID = -3286806776105690068L;
087    
088        private String _pageName;
089    
090        public PageCallback(String pageName)
091        {
092            Defense.notNull(pageName, "pageName");
093            _pageName = pageName;
094        }
095    
096        public PageCallback(IPage page)
097        {
098            Defense.notNull(page, "page");
099    
100            _pageName = page.getPageName();
101        }
102    
103        public String toString()
104        {
105            return "PageCallback[" + _pageName + "]";
106        }
107    
108        /**
109         * Invokes {@link IRequestCycle#activate(String)} to select the previously identified page as
110         * the response page.
111         */
112    
113        public void performCallback(IRequestCycle cycle)
114        {
115            Defense.notNull(cycle, "cycle");
116    
117            cycle.activate(_pageName);
118        }
119    }