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.ApplicationRuntimeException;
018 import org.apache.hivemind.util.Defense;
019 import org.apache.tapestry.IExternalPage;
020 import org.apache.tapestry.IRequestCycle;
021
022 /**
023 * A callback for returning to an {@link org.apache.tapestry.IExternalPage}.
024 * <p>
025 * Example usage of <tt>ExternalCallback</tt>:
026 * <p>
027 * The External page ensure a user is authenticated in the
028 * {@link org.apache.tapestry.IPage#validate(IRequestCycle)} method. If the user is not
029 * authenticated, they are redirected to the Login page, after setting a callback in the Login page.
030 * <p>
031 * The Login page <tt>formSubmit()</tt> {@link org.apache.tapestry.IActionListener} authenticates
032 * the user and then invokes {@link ICallback#performCallback(IRequestCycle)} to the External page.
033 *
034 * <pre>
035 * public class External extends BasePage implements IExternalPage {
036 *
037 * private Integer _itemId;
038 *
039 * public void validate(IRequestCycle cycle) throws RequestCycleException {
040 * Visit visit = (Visit) getVisit();
041 *
042 * if (!visit.isAuthenticated()) {
043 * Login login = (Login) cycle.getPage("Login");
044 *
045 * login.setCallback
046 * (new ExternalCallback(this, cycle.getServiceParameters()));
047 *
048 * throw new PageRedirectException(login);
049 * }
050 * }
051 *
052 * public void activateExternalPage(Object[] params, IRequestCycle cycle)
053 * throws RequestCycleException {
054 * _itemId = (Integer) params[0];
055 * }
056 * }
057 *
058 * public Login extends BasePage {
059 *
060 * private ICallback _callback;
061 *
062 * public void setCallback(ICallback _callback) {
063 * _callback = callback;
064 * }
065 *
066 * public void formSubmit(IRequestCycle cycle) {
067 * // Authentication code
068 * ..
069 *
070 * Visit visit = (Visit) getVisit();
071 *
072 * visit.setAuthenticated(true);
073 *
074 * if (_callback != null) {
075 * _callback.performCallback(cycle);
076 * }
077 * }
078 * }
079 * </pre>
080 *
081 * @see org.apache.tapestry.IExternalPage
082 * @see org.apache.tapestry.engine.ExternalService
083 * @author Malcolm Edgar
084 * @since 2.3
085 */
086
087 public class ExternalCallback implements ICallback
088 {
089 private static final long serialVersionUID = -6783421589702643930L;
090
091 private String _pageName;
092
093 private Object[] _parameters;
094
095 /**
096 * Creates a new ExternalCallback for the named <tt>IExternalPage</tt>. The parameters (which
097 * may be null) is retained, not copied.
098 */
099
100 public ExternalCallback(String pageName, Object[] parameters)
101 {
102 Defense.notNull(pageName, "pageName");
103
104 _pageName = pageName;
105 _parameters = parameters;
106 }
107
108 /**
109 * Creates a new ExternalCallback for the page. The parameters (which may be null) is retained,
110 * not copied.
111 */
112
113 public ExternalCallback(IExternalPage page, Object[] parameters)
114 {
115 Defense.notNull(page, "page");
116
117 _pageName = page.getPageName();
118 _parameters = parameters;
119 }
120
121 /**
122 * Invokes {@link IRequestCycle#activate(org.apache.tapestry.IPage)} to select the previously identified
123 * <tt>IExternalPage</tt> as the response page and activates the page by invoking
124 * <tt>activateExternalPage()</tt> with the callback parameters and request cycle.
125 */
126
127 public void performCallback(IRequestCycle cycle)
128 {
129 Defense.notNull(cycle, "cycle");
130
131 try
132 {
133 IExternalPage page = (IExternalPage) cycle.getPage(_pageName);
134
135 cycle.activate(page);
136
137 page.activateExternalPage(_parameters, cycle);
138 }
139 catch (ClassCastException ex)
140 {
141 throw new ApplicationRuntimeException(CallbackMessages.pageNotExternal(_pageName), ex);
142 }
143 }
144
145 public String toString()
146 {
147 StringBuffer buffer = new StringBuffer("ExternalCallback[");
148
149 buffer.append(_pageName);
150
151 if (_parameters != null)
152 {
153 for (int i = 0; i < _parameters.length; i++)
154 {
155 if (i == 0)
156 buffer.append('/');
157 else
158 buffer.append(", ");
159
160 buffer.append(_parameters[i]);
161 }
162 }
163
164 buffer.append(']');
165
166 return buffer.toString();
167 }
168 }