| // Copyright 2004, 2005 The Apache Software Foundation |
| // |
| // Licensed 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. |
| |
| package org.apache.tapestry.engine; |
| |
| import java.io.IOException; |
| import java.util.HashMap; |
| import java.util.Map; |
| |
| import org.apache.hivemind.ApplicationRuntimeException; |
| import org.apache.hivemind.util.Defense; |
| import org.apache.tapestry.IExternalPage; |
| import org.apache.tapestry.IPage; |
| import org.apache.tapestry.IRequestCycle; |
| import org.apache.tapestry.Tapestry; |
| import org.apache.tapestry.services.LinkFactory; |
| import org.apache.tapestry.services.ResponseRenderer; |
| import org.apache.tapestry.services.ServiceConstants; |
| |
| /** |
| * The external service enables external applications to reference Tapestry pages via a URL. Pages |
| * which can be referenced by the external service must implement the {@link IExternalPage} |
| * interface. The external service enables the bookmarking of pages. |
| * |
| * <p> |
| * You can try and second guess the URL format used by Tapestry. The default URL format for the |
| * external service is: <blockquote> |
| * <tt>http://localhost/app?service=external/<i>[Page Name]</i>&sp=[Param 0]&sp=[Param 1]...</tt> |
| * </blockquote> For example to view the "ViewCustomer" page the service parameters 5056 (customer |
| * ID) and 309 (company ID) the external service URL would be: <blockquote> |
| * <tt>http://localhost/myapp?service=external&context=<b>ViewCustomer</b>&sp=<b>5056</b>&sp=<b>302</b></tt> |
| * </blockquote> In this example external service will get a "ViewCustomer" page and invoke the |
| * {@link IExternalPage#activateExternalPage(Object[], IRequestCycle)}method with the parameters: |
| * Object[] { new Integer(5056), new Integer(302) }. |
| * <p> |
| * Note service parameters (sp) need to be prefixed by valid |
| * {@link org.apache.tapestry.util.io.DataSqueezerImpl}adaptor char. These adaptor chars are |
| * automatically provided in URL's created by the <tt>buildGesture()</tt> method. However if you |
| * hand coded an external service URL you will need to ensure valid prefix chars are present. |
| * <p> |
| * <table border="1" cellpadding="2"> |
| * <tr> |
| * <th>Prefix char(s)</th> |
| * <th>Mapped Java Type</th> |
| * </tr> |
| * <tr> |
| * <td> TF</td> |
| * <td> boolean</td> |
| * </tr> |
| * <tr> |
| * <td> b</td> |
| * <td> byte</td> |
| * </tr> |
| * <tr> |
| * <td> c</td> |
| * <td> char</td> |
| * </tr> |
| * <tr> |
| * <td> d</td> |
| * <td> double</td> |
| * </tr> |
| * <tr> |
| * <td> -0123456789</td> |
| * <td> integer</td> |
| * </tr> |
| * <tr> |
| * <td> l</td> |
| * <td> long</td> |
| * </tr> |
| * <tr> |
| * <td> S</td> |
| * <td> String</td> |
| * </tr> |
| * <tr> |
| * <td> s</td> |
| * <td> short</td> |
| * </tr> |
| * <tr> |
| * <td> other chars</td> |
| * <td> <tt>String</tt> without truncation of first char</td> |
| * </tr> |
| * </table> |
| * <p> |
| * <p> |
| * A good rule of thumb is to keep the information encoded in the URL short and simple, and restrict |
| * it to just Strings and Integers. Integers can be encoded as-is. Prefixing all Strings with the |
| * letter 'S' will ensure that they are decoded properly. Again, this is only relevant if an |
| * {@link org.apache.tapestry.IExternalPage}is being referenced from static HTML or JSP and the URL |
| * must be assembled in user code ... when the URL is generated by Tapestry, it is automatically |
| * created with the correct prefixes and encodings (as with any other service). |
| * |
| * @see org.apache.tapestry.IExternalPage |
| * @author Howard Lewis Ship |
| * @author Malcolm Edgar |
| * @since 2.2 |
| */ |
| |
| public class ExternalService implements IEngineService |
| { |
| /** @since 4.0 */ |
| |
| private ResponseRenderer _responseRenderer; |
| |
| /** @since 4.0 */ |
| private LinkFactory _linkFactory; |
| |
| /** |
| * {@inheritDoc} |
| * |
| * @return The URL for the service. The URL will always be encoded when it is returned. |
| */ |
| public ILink getLink(boolean post, Object parameter) |
| { |
| Defense.isAssignable(parameter, ExternalServiceParameter.class, "parameter"); |
| |
| ExternalServiceParameter esp = (ExternalServiceParameter) parameter; |
| |
| Map parameters = new HashMap(); |
| |
| parameters.put(ServiceConstants.PAGE, esp.getPageName()); |
| parameters.put(ServiceConstants.PARAMETER, esp.getServiceParameters()); |
| |
| return _linkFactory.constructLink(this, post, parameters, true); |
| } |
| |
| public void service(IRequestCycle cycle) throws IOException |
| { |
| String pageName = cycle.getParameter(ServiceConstants.PAGE); |
| IPage rawPage = cycle.getPage(pageName); |
| |
| IExternalPage page = null; |
| |
| try |
| { |
| page = (IExternalPage) rawPage; |
| } |
| catch (ClassCastException ex) |
| { |
| throw new ApplicationRuntimeException(EngineMessages.pageNotCompatible( |
| rawPage, |
| IExternalPage.class), rawPage, null, ex); |
| } |
| |
| Object[] parameters = _linkFactory.extractListenerParameters(cycle); |
| |
| cycle.setListenerParameters(parameters); |
| |
| cycle.activate(page); |
| |
| page.activateExternalPage(parameters, cycle); |
| |
| _responseRenderer.renderResponse(cycle); |
| } |
| |
| public String getName() |
| { |
| return Tapestry.EXTERNAL_SERVICE; |
| } |
| |
| /** @since 4.0 */ |
| |
| public void setResponseRenderer(ResponseRenderer responseRenderer) |
| { |
| _responseRenderer = responseRenderer; |
| } |
| |
| /** @since 4.0 */ |
| public void setLinkFactory(LinkFactory linkFactory) |
| { |
| _linkFactory = linkFactory; |
| } |
| } |