Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
ExternalService |
|
| 1.4;1.4 |
1 | // Copyright 2004, 2005 The Apache Software Foundation | |
2 | // | |
3 | // Licensed under the Apache License, Version 2.0 (the "License"); | |
4 | // you may not use this file except in compliance with the License. | |
5 | // You may obtain a copy of the License at | |
6 | // | |
7 | // http://www.apache.org/licenses/LICENSE-2.0 | |
8 | // | |
9 | // Unless required by applicable law or agreed to in writing, software | |
10 | // distributed under the License is distributed on an "AS IS" BASIS, | |
11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
12 | // See the License for the specific language governing permissions and | |
13 | // limitations under the License. | |
14 | ||
15 | package org.apache.tapestry.engine; | |
16 | ||
17 | import org.apache.hivemind.ApplicationRuntimeException; | |
18 | import org.apache.hivemind.util.Defense; | |
19 | import org.apache.tapestry.IExternalPage; | |
20 | import org.apache.tapestry.IPage; | |
21 | import org.apache.tapestry.IRequestCycle; | |
22 | import org.apache.tapestry.Tapestry; | |
23 | import org.apache.tapestry.services.LinkFactory; | |
24 | import org.apache.tapestry.services.ResponseRenderer; | |
25 | import org.apache.tapestry.services.ServiceConstants; | |
26 | ||
27 | import java.io.IOException; | |
28 | import java.util.HashMap; | |
29 | import java.util.Map; | |
30 | ||
31 | /** | |
32 | * The external service enables external applications to reference Tapestry pages via a URL. Pages | |
33 | * which can be referenced by the external service must implement the {@link IExternalPage} | |
34 | * interface. The external service enables the bookmarking of pages. | |
35 | * | |
36 | * <p> | |
37 | * You can try and second guess the URL format used by Tapestry. The default URL format for the | |
38 | * external service is: <blockquote> | |
39 | * <tt>http://localhost/app?service=external/<i>[Page Name]</i>&sp=[Param 0]&sp=[Param 1]...</tt> | |
40 | * </blockquote> For example to view the "ViewCustomer" page the service parameters 5056 (customer | |
41 | * ID) and 309 (company ID) the external service URL would be: <blockquote> | |
42 | * <tt>http://localhost/myapp?service=external&context=<b>ViewCustomer</b>&sp=<b>5056</b>&sp=<b>302</b></tt> | |
43 | * </blockquote> In this example external service will get a "ViewCustomer" page and invoke the | |
44 | * {@link IExternalPage#activateExternalPage(Object[], IRequestCycle)}method with the parameters: | |
45 | * Object[] { new Integer(5056), new Integer(302) }. | |
46 | * <p> | |
47 | * Note service parameters (sp) need to be prefixed by valid | |
48 | * {@link org.apache.tapestry.util.io.DataSqueezerImpl}adaptor char. These adaptor chars are | |
49 | * automatically provided in URL's created by the <tt>buildGesture()</tt> method. However if you | |
50 | * hand coded an external service URL you will need to ensure valid prefix chars are present. | |
51 | * <p> | |
52 | * <table border="1" cellpadding="2"> | |
53 | * <tr> | |
54 | * <th>Prefix char(s)</th> | |
55 | * <th>Mapped Java Type</th> | |
56 | * </tr> | |
57 | * <tr> | |
58 | * <td> TF</td> | |
59 | * <td> boolean</td> | |
60 | * </tr> | |
61 | * <tr> | |
62 | * <td> b</td> | |
63 | * <td> byte</td> | |
64 | * </tr> | |
65 | * <tr> | |
66 | * <td> c</td> | |
67 | * <td> char</td> | |
68 | * </tr> | |
69 | * <tr> | |
70 | * <td> d</td> | |
71 | * <td> double</td> | |
72 | * </tr> | |
73 | * <tr> | |
74 | * <td> -0123456789</td> | |
75 | * <td> integer</td> | |
76 | * </tr> | |
77 | * <tr> | |
78 | * <td> l</td> | |
79 | * <td> long</td> | |
80 | * </tr> | |
81 | * <tr> | |
82 | * <td> S</td> | |
83 | * <td> String</td> | |
84 | * </tr> | |
85 | * <tr> | |
86 | * <td> s</td> | |
87 | * <td> short</td> | |
88 | * </tr> | |
89 | * <tr> | |
90 | * <td> other chars</td> | |
91 | * <td> <tt>String</tt> without truncation of first char</td> | |
92 | * </tr> | |
93 | * </table> | |
94 | * <p> | |
95 | * <p> | |
96 | * A good rule of thumb is to keep the information encoded in the URL short and simple, and restrict | |
97 | * it to just Strings and Integers. Integers can be encoded as-is. Prefixing all Strings with the | |
98 | * letter 'S' will ensure that they are decoded properly. Again, this is only relevant if an | |
99 | * {@link org.apache.tapestry.IExternalPage}is being referenced from static HTML or JSP and the URL | |
100 | * must be assembled in user code ... when the URL is generated by Tapestry, it is automatically | |
101 | * created with the correct prefixes and encodings (as with any other service). | |
102 | * | |
103 | * @see org.apache.tapestry.IExternalPage | |
104 | * @author Howard Lewis Ship | |
105 | * @author Malcolm Edgar | |
106 | * @since 2.2 | |
107 | */ | |
108 | ||
109 | 0 | public class ExternalService implements IEngineService |
110 | { | |
111 | /** @since 4.0 */ | |
112 | ||
113 | private ResponseRenderer _responseRenderer; | |
114 | ||
115 | /** @since 4.0 */ | |
116 | private LinkFactory _linkFactory; | |
117 | ||
118 | /** | |
119 | * {@inheritDoc} | |
120 | * | |
121 | * @return The URL for the service. The URL will always be encoded when it is returned. | |
122 | */ | |
123 | public ILink getLink(boolean post, Object parameter) | |
124 | { | |
125 | 0 | Defense.isAssignable(parameter, ExternalServiceParameter.class, "parameter"); |
126 | ||
127 | 0 | ExternalServiceParameter esp = (ExternalServiceParameter) parameter; |
128 | ||
129 | 0 | Map parameters = new HashMap(); |
130 | ||
131 | 0 | parameters.put(ServiceConstants.PAGE, esp.getPageName()); |
132 | 0 | parameters.put(ServiceConstants.PARAMETER, esp.getServiceParameters()); |
133 | ||
134 | 0 | return _linkFactory.constructLink(this, post, parameters, true); |
135 | } | |
136 | ||
137 | public void service(IRequestCycle cycle) throws IOException | |
138 | { | |
139 | 0 | String pageName = cycle.getParameter(ServiceConstants.PAGE); |
140 | 0 | IPage rawPage = cycle.getPage(pageName); |
141 | ||
142 | 0 | IExternalPage page = null; |
143 | ||
144 | try | |
145 | { | |
146 | 0 | page = (IExternalPage) rawPage; |
147 | } | |
148 | 0 | catch (ClassCastException ex) |
149 | { | |
150 | 0 | throw new ApplicationRuntimeException(EngineMessages.pageNotCompatible(rawPage,IExternalPage.class), rawPage, null, ex); |
151 | 0 | } |
152 | ||
153 | 0 | Object[] parameters = _linkFactory.extractListenerParameters(cycle); |
154 | ||
155 | 0 | cycle.setListenerParameters(parameters); |
156 | ||
157 | 0 | cycle.activate(page); |
158 | ||
159 | 0 | page.activateExternalPage(parameters, cycle); |
160 | ||
161 | 0 | _responseRenderer.renderResponse(cycle); |
162 | 0 | } |
163 | ||
164 | public String getName() | |
165 | { | |
166 | 0 | return Tapestry.EXTERNAL_SERVICE; |
167 | } | |
168 | ||
169 | /** @since 4.0 */ | |
170 | ||
171 | public void setResponseRenderer(ResponseRenderer responseRenderer) | |
172 | { | |
173 | 0 | _responseRenderer = responseRenderer; |
174 | 0 | } |
175 | ||
176 | /** @since 4.0 */ | |
177 | public void setLinkFactory(LinkFactory linkFactory) | |
178 | { | |
179 | 0 | _linkFactory = linkFactory; |
180 | 0 | } |
181 | } |