1 /**
2 * Copyright (C) 2005-2009 Alfresco Software Limited.
3 *
4 * This file is part of the Spring Surf Extension project.
5 *
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19 package org.springframework.extensions.webscripts;
20
21 import java.io.IOException;
22 import java.io.InputStream;
23 import java.io.Serializable;
24 import java.util.Map;
25 import java.util.Set;
26
27
28 /**
29 * Web Script Description
30 *
31 * @author davidc
32 */
33 public interface Description
34 {
35 /**
36 * Enumeration of "required" Authentication level
37 */
38 public enum RequiredAuthentication
39 {
40 none,
41 guest,
42 user,
43 admin
44 }
45
46 /**
47 * Enumeration of "required" Transaction level
48 */
49 public enum RequiredTransaction
50 {
51 none,
52 required,
53 requiresnew
54 }
55
56 /**
57 * Enumeration of transaction capability
58 */
59 public enum TransactionCapability
60 {
61 readonly,
62 readwrite
63 }
64
65 /**
66 * Transaction Requirements
67 */
68 public interface RequiredTransactionParameters
69 {
70 /**
71 * Get required transaction semantics
72 *
73 * @return required transaction
74 */
75 public RequiredTransaction getRequired();
76
77 /**
78 * Get transaction capability (readonly,readwrite)
79 *
80 * @return
81 */
82 public TransactionCapability getCapability();
83
84 /**
85 * Get buffer size (for caching transactional response)
86 *
87 * @return
88 */
89 public int getBufferSize();
90 }
91
92 /**
93 * Caching requirements
94 */
95 public interface RequiredCache
96 {
97 /**
98 * Determine if Web Script should ever be cached
99 *
100 * @return true => do not cache, false => caching may or not occur
101 */
102 public boolean getNeverCache();
103
104 /**
105 * Determine if Web Script content is for public caching
106 *
107 * @return true => content is public, so allow cache
108 */
109 public boolean getIsPublic();
110
111 /**
112 * Must cache re-validate to ensure content is fresh
113 *
114 * @return true => must re-validate
115 */
116 public boolean getMustRevalidate();
117 }
118
119 /**
120 * Enumeration of ways to specify format
121 */
122 public enum FormatStyle
123 {
124 any, // any of the following styles
125 extension, // /a/b/c.x
126 argument // /a/b/c?format=x
127 }
128
129 /**
130 * Gets the root path of the store of this web script
131 *
132 * @return root path of store
133 */
134 public String getStorePath();
135
136 /**
137 * Gets the path within the store of this web script
138 *
139 * @return path within store
140 */
141 public String getScriptPath();
142
143 /**
144 * Gets the package (Path version of getScriptPath)
145 *
146 */
147 public Path getPackage();
148
149 /**
150 * Gets the path of the description xml document for this web script
151 *
152 * @return document location (path)
153 */
154 public String getDescPath();
155
156 /**
157 * Gets the description xml document for this web script
158 *
159 * @return source document
160 */
161 public InputStream getDescDocument()
162 throws IOException;
163
164 /**
165 * Gets the id of this service
166 *
167 * @return service id
168 */
169 public String getId();
170
171 /**
172 * Gets the kind of service.
173 *
174 * A Web Script may explicitly define its backing-bean implementation. The backing bean
175 * implementation is identified by a Spring bean whose id is:
176 *
177 * webscript.<kind>
178 *
179 * The <kind> may be dot separated.
180 *
181 * @return the kind of service (or null, for a vanilla declarative web script)
182 */
183 public String getKind();
184
185 /**
186 * Gets the short name of this service
187 *
188 * @return service short name
189 */
190 public String getShortName();
191
192 /**
193 * Gets the description of this service
194 */
195 public String getDescription();
196
197 /**
198 * Gets the family(s) of this service in the order that they are defined
199 */
200 public Set<String> getFamilys();
201
202 /**
203 * Gets the required authentication level for execution of this service
204 *
205 * @return the required authentication level
206 */
207 public RequiredAuthentication getRequiredAuthentication();
208
209 /**
210 * Gets the ID of the user that the service should be run as or <code>null</code> if the service is to be run as the
211 * authenticated user.
212 *
213 * @return a user name or <code>null</code> if not applicable
214 */
215 public String getRunAs();
216
217 /**
218 * Gets the required transaction level
219 *
220 * @return the required transaction level
221 */
222 public RequiredTransaction getRequiredTransaction();
223
224 /**
225 * Gets the transaction parameters
226 *
227 * @return the transaction parameters
228 */
229 public RequiredTransactionParameters getRequiredTransactionParameters();
230
231 /**
232 * Gets the required level of caching
233 * @return
234 */
235 public RequiredCache getRequiredCache();
236
237 /**
238 * Gets the HTTP method this service is bound to
239 *
240 * @return HTTP method
241 */
242 public String getMethod();
243
244 /**
245 * Gets the URIs this service supports
246 *
247 * @return array of URIs in order specified in service description document
248 */
249 public String[] getURIs();
250
251 /**
252 * Gets the style of Format discriminator supported by this web script
253 *
254 * @return format style
255 */
256 public FormatStyle getFormatStyle();
257
258 /**
259 * Gets the default response format
260 *
261 * Note: the default response format is the first listed in the service
262 * description document
263 *
264 * @return default response format (or null, if format not known until run-time)
265 */
266 public String getDefaultFormat();
267
268 /**
269 * Gets the formats available for negotiation
270 *
271 * @return negotiated formats
272 */
273 public NegotiatedFormat[] getNegotiatedFormats();
274
275 /**
276 * Gets web script specific extensions
277 *
278 * @return map of extensions by name
279 */
280 public Map<String, Serializable> getExtensions();
281
282 /**
283 * Enumeration of lifecycle which indicates the status of this web script
284 */
285 public enum Lifecycle
286 {
287 none,
288 sample,
289 draft,
290 draft_public_api,
291 public_api,
292 deprecated,
293 internal
294 }
295
296 /**
297 * Get the lifecycle
298 */
299 Lifecycle getLifecycle();
300 }