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 java.io.IOException; |
|
18 | import java.util.HashMap; |
|
19 | import java.util.Map; |
|
20 | ||
21 | import org.apache.hivemind.ApplicationRuntimeException; |
|
22 | import org.apache.hivemind.util.Defense; |
|
23 | import org.apache.tapestry.IExternalPage; |
|
24 | import org.apache.tapestry.IPage; |
|
25 | import org.apache.tapestry.IRequestCycle; |
|
26 | import org.apache.tapestry.Tapestry; |
|
27 | import org.apache.tapestry.services.LinkFactory; |
|
28 | import org.apache.tapestry.services.ResponseRenderer; |
|
29 | import org.apache.tapestry.services.ServiceConstants; |
|
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 | 3 | 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 | 3 | Defense.isAssignable(parameter, ExternalServiceParameter.class, "parameter"); |
126 | ||
127 | 1 | ExternalServiceParameter esp = (ExternalServiceParameter) parameter; |
128 | ||
129 | 1 | Map parameters = new HashMap(); |
130 | ||
131 | 1 | parameters.put(ServiceConstants.PAGE, esp.getPageName()); |
132 | 1 | parameters.put(ServiceConstants.PARAMETER, esp.getServiceParameters()); |
133 | ||
134 | 1 | return _linkFactory.constructLink(this, post, parameters, true); |
135 | } |
|
136 | ||
137 | public void service(IRequestCycle cycle) throws IOException |
|
138 | { |
|
139 | 2 | String pageName = cycle.getParameter(ServiceConstants.PAGE); |
140 | 2 | IPage rawPage = cycle.getPage(pageName); |
141 | ||
142 | 2 | IExternalPage page = null; |
143 | ||
144 | try |
|
145 | { |
|
146 | 2 | page = (IExternalPage) rawPage; |
147 | } |
|
148 | 1 | catch (ClassCastException ex) |
149 | { |
|
150 | 1 | throw new ApplicationRuntimeException(EngineMessages.pageNotCompatible( |
151 | rawPage, |
|
152 | IExternalPage.class), rawPage, null, ex); |
|
153 | 1 | } |
154 | ||
155 | 1 | Object[] parameters = _linkFactory.extractListenerParameters(cycle); |
156 | ||
157 | 1 | cycle.setListenerParameters(parameters); |
158 | ||
159 | 1 | cycle.activate(page); |
160 | ||
161 | 1 | page.activateExternalPage(parameters, cycle); |
162 | ||
163 | 1 | _responseRenderer.renderResponse(cycle); |
164 | 1 | } |
165 | ||
166 | public String getName() |
|
167 | { |
|
168 | 0 | return Tapestry.EXTERNAL_SERVICE; |
169 | } |
|
170 | ||
171 | /** @since 4.0 */ |
|
172 | ||
173 | public void setResponseRenderer(ResponseRenderer responseRenderer) |
|
174 | { |
|
175 | 1 | _responseRenderer = responseRenderer; |
176 | 1 | } |
177 | ||
178 | /** @since 4.0 */ |
|
179 | public void setLinkFactory(LinkFactory linkFactory) |
|
180 | { |
|
181 | 2 | _linkFactory = linkFactory; |
182 | 2 | } |
183 | } |