KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > tapestry > engine > ExternalService


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 JavaDoc;
18 import java.util.HashMap JavaDoc;
19 import java.util.Map JavaDoc;
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  * <p>
36  * The external service may also be used by the Tapestry JSP taglibrary (
37  * {@link org.apache.tapestry.jsp.ExternalURLTag}and {@link org.apache.tapestry.jsp.ExternalTag}).
38  * <p>
39  * You can try and second guess the URL format used by Tapestry. The default URL format for the
40  * external service is: <blockquote>
41  * <tt>http://localhost/app?service=external/<i>[Page Name]</i>&amp;sp=[Param 0]&amp;sp=[Param 1]...</tt>
42  * </blockquote> For example to view the "ViewCustomer" page the service parameters 5056 (customer
43  * ID) and 309 (company ID) the external service URL would be: <blockquote>
44  * <tt>http://localhost/myapp?service=external&amp;context=<b>ViewCustomer</b>&amp;sp=<b>5056</b>&amp;sp=<b>302</b></tt>
45  * </blockquote> In this example external service will get a "ViewCustomer" page and invoke the
46  * {@link IExternalPage#activateExternalPage(Object[], IRequestCycle)}method with the parameters:
47  * Object[] { new Integer(5056), new Integer(302) }.
48  * <p>
49  * Note service parameters (sp) need to be prefixed by valid
50  * {@link org.apache.tapestry.util.io.DataSqueezerImpl}adaptor char. These adaptor chars are
51  * automatically provided in URL's created by the <tt>buildGesture()</tt> method. However if you
52  * hand coded an external service URL you will need to ensure valid prefix chars are present.
53  * <p>
54  * <table border="1" cellpadding="2">
55  * <tr>
56  * <th>Prefix char(s)</th>
57  * <th>Mapped Java Type</th>
58  * </tr>
59  * <tr>
60  * <td>&nbsp;TF</td>
61  * <td>&nbsp;boolean</td>
62  * </tr>
63  * <tr>
64  * <td>&nbsp;b</td>
65  * <td>&nbsp;byte</td>
66  * </tr>
67  * <tr>
68  * <td>&nbsp;c</td>
69  * <td>&nbsp;char</td>
70  * </tr>
71  * <tr>
72  * <td>&nbsp;d</td>
73  * <td>&nbsp;double</td>
74  * </tr>
75  * <tr>
76  * <td>&nbsp;-0123456789</td>
77  * <td>&nbsp;integer</td>
78  * </tr>
79  * <tr>
80  * <td>&nbsp;l</td>
81  * <td>&nbsp;long</td>
82  * </tr>
83  * <tr>
84  * <td>&nbsp;S</td>
85  * <td>&nbsp;String</td>
86  * </tr>
87  * <tr>
88  * <td>&nbsp;s</td>
89  * <td>&nbsp;short</td>
90  * </tr>
91  * <tr>
92  * <td>&nbsp;other chars</td>
93  * <td>&nbsp; <tt>String</tt> without truncation of first char</td>
94  * </tr>
95  * <table>
96  * <p>
97  * <p>
98  * A good rule of thumb is to keep the information encoded in the URL short and simple, and restrict
99  * it to just Strings and Integers. Integers can be encoded as-is. Prefixing all Strings with the
100  * letter 'S' will ensure that they are decoded properly. Again, this is only relevant if an
101  * {@link org.apache.tapestry.IExternalPage}is being referenced from static HTML or JSP and the URL
102  * must be assembled in user code ... when the URL is generated by Tapestry, it is automatically
103  * created with the correct prefixes and encodings (as with any other service).
104  *
105  * @see org.apache.tapestry.IExternalPage
106  * @see org.apache.tapestry.jsp.ExternalTag
107  * @see org.apache.tapestry.jsp.ExternalURLTag
108  * @author Howard Lewis Ship
109  * @author Malcolm Edgar
110  * @since 2.2
111  */
112
113 public class ExternalService implements IEngineService
114 {
115     /** @since 4.0 */
116
117     private ResponseRenderer _responseRenderer;
118
119     /** @since 4.0 */
120     private LinkFactory _linkFactory;
121
122     public ILink getLink(IRequestCycle cycle, Object JavaDoc parameter)
123     {
124         Defense.isAssignable(parameter, ExternalServiceParameter.class, "parameter");
125
126         ExternalServiceParameter esp = (ExternalServiceParameter) parameter;
127
128         Map JavaDoc parameters = new HashMap JavaDoc();
129         parameters.put(ServiceConstants.SERVICE, Tapestry.EXTERNAL_SERVICE);
130         parameters.put(ServiceConstants.PAGE, esp.getPageName());
131         parameters.put(ServiceConstants.PARAMETER, esp.getServiceParameters());
132
133         return _linkFactory.constructLink(cycle, parameters, true);
134     }
135
136     public void service(IRequestCycle cycle) throws IOException JavaDoc
137     {
138         String JavaDoc pageName = cycle.getParameter(ServiceConstants.PAGE);
139         IPage rawPage = cycle.getPage(pageName);
140
141         IExternalPage page = null;
142
143         try
144         {
145             page = (IExternalPage) rawPage;
146         }
147         catch (ClassCastException JavaDoc ex)
148         {
149             throw new ApplicationRuntimeException(EngineMessages.pageNotCompatible(
150                     rawPage,
151                     IExternalPage.class), rawPage, null, ex);
152         }
153
154         Object JavaDoc[] parameters = _linkFactory.extractListenerParameters(cycle);
155
156         cycle.setListenerParameters(parameters);
157
158         cycle.activate(page);
159
160         page.activateExternalPage(parameters, cycle);
161
162         _responseRenderer.renderResponse(cycle);
163     }
164
165     public String JavaDoc getName()
166     {
167         return Tapestry.EXTERNAL_SERVICE;
168     }
169
170     /** @since 4.0 */
171
172     public void setResponseRenderer(ResponseRenderer responseRenderer)
173     {
174         _responseRenderer = responseRenderer;
175     }
176
177     /** @since 4.0 */
178     public void setLinkFactory(LinkFactory linkFactory)
179     {
180         _linkFactory = linkFactory;
181     }
182 }
Popular Tags