001: /*
002: * Contains fragments from Apache Tomcat distribution. The file
003: * has been modified by Nabh for the Web services framework.
004: * Modifications (c) 2005 Nabh Information Systems, Inc.
005: *
006: * Copyright 2004 The Apache Software Foundation
007: *
008: * Licensed under the Apache License, Version 2.0 (the "License");
009: * you may not use this file except in compliance with the License.
010: * You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing, software
015: * distributed under the License is distributed on an "AS IS" BASIS,
016: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: * See the License for the specific language governing permissions and
018: * limitations under the License.
019: */
020:
021: package com.nabhinc.core;
022:
023: import java.util.Enumeration;
024: import java.util.Locale;
025:
026: /**
027: * @author Padmanabh Dabke
028: * Abstract view of a request made to a Web service.
029: * This object is accessible via thread-local <code>RequestContext</code> object.
030: * It is also accessible via <code>RequestInfo</code> object passed to the
031: * interceptors and Web services during invocation.
032: */
033: public interface WebServiceRequest {
034: public static final String USER_INFO = "stringbeans.ws.user_info";
035:
036: /**
037: *
038: * Returns the value of the named attribute as an <code>Object</code>, or
039: * <code>null</code> if no attribute of the given name exists. If the
040: * service lives in a Web service container, this must return the corresponding
041: * attribute on the Web service request.
042: */
043:
044: public Object getAttribute(String name);
045:
046: /**
047: * Returns an <code>Enumeration</code> containing the names of the
048: * attributes available to this request. This method returns an empty
049: * <code>Enumeration</code> if the request has no attributes available to
050: * it.
051: *
052: *
053: * @return an <code>Enumeration</code> of strings containing the names of
054: * the request's attributes
055: *
056: */
057:
058: public Enumeration getAttributeNames();
059:
060: /**
061: * Returns the Internet Protocol (IP) address of the client or last proxy
062: * that sent the request. For HTTP-based services, same as the value of the CGI
063: * variable <code>REMOTE_ADDR</code>.
064: *
065: * @return a <code>String</code> containing the IP address of the client
066: * that sent the request
067: *
068: */
069:
070: public String getRemoteAddr();
071:
072: /**
073: * Returns the fully qualified name of the client or the last proxy that
074: * sent the request. If the engine cannot or chooses not to resolve the
075: * hostname (to improve performance), this method returns the dotted-string
076: * form of the IP address. For HTTP-based services, same as the value of the CGI
077: * variable <code>REMOTE_HOST</code>.
078: *
079: * @return a <code>String</code> containing the fully qualified name of
080: * the client
081: *
082: */
083:
084: public String getRemoteHost();
085:
086: /**
087: *
088: * Stores an attribute in this request. Attributes are reset between
089: * requests. This method is most often used in conjunction with
090: * {@link RequestDispatcher}.
091: *
092: * <p>
093: * Attribute names should follow the same conventions as package names.
094: * Names beginning with <code>java.*</code>,<code>javax.*</code>, and
095: * <code>com.sun.*</code>, are reserved for use by Sun Microsystems. <br>
096: * If the object passed in is null, the effect is the same as calling
097: * {@link #removeAttribute}.<br>
098: * It is warned that when the request is dispatched from a Web service
099: * residing in a different Web app, object set by this method may not
100: * be correctly retrieved.
101: *
102: *
103: * @param name
104: * a <code>String</code> specifying the name of the attribute
105: *
106: * @param o
107: * the <code>Object</code> to be stored
108: *
109: */
110:
111: public void setAttribute(String name, Object o);
112:
113: /**
114: *
115: * Removes an attribute from this request. This method is not generally
116: * needed as attributes only persist as long as the request is being
117: * handled.
118: *
119: * <p>
120: * Attribute names should follow the same conventions as package names.
121: * Names beginning with <code>java.*</code>,<code>javax.*</code>, and
122: * <code>com.sun.*</code>, are reserved for use by Sun Microsystems.
123: *
124: *
125: * @param name
126: * a <code>String</code> specifying the name of the attribute
127: * to remove
128: *
129: */
130:
131: public void removeAttribute(String name);
132:
133: /**
134: *
135: * Returns the preferred <code>Locale</code> that the client will accept
136: * content in, based on the Accept-Language header. If the client request
137: * doesn't provide an Accept-Language header, this method returns the
138: * default locale for the server.
139: *
140: *
141: * @return the preferred <code>Locale</code> for the client
142: *
143: */
144:
145: public Locale getLocale();
146:
147: /**
148: *
149: * Returns an <code>Enumeration</code> of <code>Locale</code> objects
150: * indicating, in decreasing order starting with the preferred locale, the
151: * locales that are acceptable to the client based on the Accept-Language
152: * header. If the client request doesn't provide an Accept-Language header,
153: * this method returns an <code>Enumeration</code> containing one
154: * <code>Locale</code>, the default locale for the server.
155: *
156: *
157: * @return an <code>Enumeration</code> of preferred <code>Locale</code>
158: * objects for the client
159: *
160: */
161:
162: public Enumeration getLocales();
163:
164: /**
165: *
166: * Check if this request was made using a secure channel.
167: *
168: * @return true if the request was made using a secure channel, false otherwise.
169: *
170: */
171:
172: public boolean isSecure();
173:
174: /**
175: * String identifier for Basic authentication. Value "BASIC"
176: */
177: public static final String BASIC_AUTH = "BASIC";
178: /**
179: * String identifier for Form authentication. Value "FORM"
180: */
181: public static final String FORM_AUTH = "FORM";
182: /**
183: * String identifier for Client Certificate authentication. Value "CLIENT_CERT"
184: */
185: public static final String CLIENT_CERT_AUTH = "CLIENT_CERT";
186: /**
187: * String identifier for Digest authentication. Value "DIGEST"
188: */
189: public static final String DIGEST_AUTH = "DIGEST";
190:
191: /**
192: * Returns the name of the authentication scheme used to protect
193: * the service. All Web service containers support basic, form and client
194: * certificate authentication, and may additionally support digest
195: * authentication.
196: * If the user is not authenticated <code>null</code> is returned.
197: *
198: * <p>Same as the value of the CGI variable AUTH_TYPE.
199: *
200: *
201: * @return one of the static members BASIC_AUTH,
202: * FORM_AUTH, CLIENT_CERT_AUTH, DIGEST_AUTH
203: * (suitable for == comparison) or
204: * the container-specific string indicating
205: * the authentication scheme, or
206: * <code>null</code> if the request was
207: * not authenticated.
208: *
209: */
210:
211: public String getAuthType();
212:
213: /**
214: *
215: * Returns the login of the user making this request, if the
216: * user has been authenticated, or <code>null</code> if the user
217: * has not been authenticated.
218: * Whether the user name is sent with each subsequent request
219: * depends on the browser and type of authentication. Same as the
220: * value of the CGI variable REMOTE_USER.
221: *
222: * @return a <code>String</code> specifying the login
223: * of the user making this request, or <code>null</code>
224: * if the user login is not known
225: *
226: */
227:
228: public String getRemoteUser();
229:
230: /**
231: *
232: * Returns a boolean indicating whether the authenticated user is included
233: * in the specified logical "role". Roles and role membership can be
234: * defined using deployment descriptors. If the user has not been
235: * authenticated, the method returns <code>false</code>.
236: *
237: * @param role a <code>String</code> specifying the name
238: * of the role
239: *
240: * @return a <code>boolean</code> indicating whether
241: * the user making this request belongs to a given role;
242: * <code>false</code> if the user has not been
243: * authenticated
244: *
245: */
246:
247: public boolean isUserInRole(String role);
248:
249: /**
250: *
251: * Returns a <code>java.security.Principal</code> object containing
252: * the name of the current authenticated user. If the user has not been
253: * authenticated, the method returns <code>null</code>.
254: *
255: * @return a <code>java.security.Principal</code> containing
256: * the name of the user making this request;
257: * <code>null</code> if the user has not been
258: * authenticated
259: *
260: */
261:
262: public java.security.Principal getUserPrincipal();
263:
264: /**
265: *
266: * Returns the current <code>HttpSession</code>
267: * associated with this request or, if there is no
268: * current session and <code>create</code> is true, returns
269: * a new session.
270: *
271: * <p>If <code>create</code> is <code>false</code>
272: * and the request has no valid <code>HttpSession</code>,
273: * this method returns <code>null</code>.
274: *
275: * <p>To make sure the session is properly maintained,
276: * you must call this method before
277: * the response is committed. If the container is using cookies
278: * to maintain session integrity and is asked to create a new session
279: * when the response is committed, an IllegalStateException is thrown.
280: *
281: *
282: *
283: *
284: * @param create <code>true</code> to create
285: * a new session for this request if necessary;
286: * <code>false</code> to return <code>null</code>
287: * if there's no current session
288: *
289: *
290: * @return the <code>HttpSession</code> associated
291: * with this request or <code>null</code> if
292: * <code>create</code> is <code>false</code>
293: * and the request has no valid session
294: *
295: * @see #getSession()
296: *
297: *
298: */
299:
300: public WebServiceSession getSession(boolean create);
301:
302: /**
303: *
304: * Returns the current session associated with this request,
305: * or if the request does not have a session, creates one.
306: *
307: * @return the <code>HttpSession</code> associated
308: * with this request
309: *
310: * @see #getSession(boolean)
311: *
312: */
313:
314: public WebServiceSession getSession();
315:
316: /**
317: *
318: * Returns the value of the specified request header
319: * as a <code>long</code> value that represents a
320: * <code>Date</code> object. Use this method with
321: * headers that contain dates, such as
322: * <code>If-Modified-Since</code>.
323: *
324: * <p>The date is returned as
325: * the number of milliseconds since January 1, 1970 GMT.
326: * The header name is case insensitive.
327: *
328: * <p>If the request did not have a header of the
329: * specified name, this method returns -1. If the header
330: * can't be converted to a date, the method throws
331: * an <code>IllegalArgumentException</code>.
332: *
333: * @param name a <code>String</code> specifying the
334: * name of the header
335: *
336: * @return a <code>long</code> value
337: * representing the date specified
338: * in the header expressed as
339: * the number of milliseconds
340: * since January 1, 1970 GMT,
341: * or -1 if the named header
342: * was not included with the
343: * request
344: *
345: * @exception IllegalArgumentException If the header value
346: * can't be converted
347: * to a date
348: *
349: */
350:
351: public long getDateHeader(String name);
352:
353: /**
354: *
355: * Returns the value of the specified request header
356: * as a <code>String</code>. If the request did not include a header
357: * of the specified name, this method returns <code>null</code>.
358: * If there are multiple headers with the same name, this method
359: * returns the first head in the request.
360: * The header name is case insensitive. You can use
361: * this method with any request header.
362: *
363: * @param name a <code>String</code> specifying the
364: * header name
365: *
366: * @return a <code>String</code> containing the
367: * value of the requested
368: * header, or <code>null</code>
369: * if the request does not
370: * have a header of that name
371: *
372: */
373:
374: public String getHeader(String name);
375:
376: /**
377: *
378: * Returns all the values of the specified request header
379: * as an <code>Enumeration</code> of <code>String</code> objects.
380: *
381: * <p>Some headers, such as <code>Accept-Language</code> can be sent
382: * by clients as several headers each with a different value rather than
383: * sending the header as a comma separated list.
384: *
385: * <p>If the request did not include any headers
386: * of the specified name, this method returns an empty
387: * <code>Enumeration</code>.
388: * The header name is case insensitive. You can use
389: * this method with any request header.
390: *
391: * @param name a <code>String</code> specifying the
392: * header name
393: *
394: * @return an <code>Enumeration</code> containing
395: * the values of the requested header. If
396: * the request does not have any headers of
397: * that name return an empty
398: * enumeration. If
399: * the container does not allow access to
400: * header information, return null
401: *
402: */
403:
404: public Enumeration getHeaders(String name);
405:
406: /**
407: *
408: * Returns an enumeration of all the header names
409: * this request contains. If the request has no
410: * headers, this method returns an empty enumeration.
411: *
412: * <p>Some Web service containers do not allow
413: * services to access headers using this method, in
414: * which case this method returns <code>null</code>
415: *
416: * @return an enumeration of all the
417: * header names sent with this
418: * request; if the request has
419: * no headers, an empty enumeration;
420: * if the Web service container does not
421: * allow services to use this method,
422: * <code>null</code>
423: *
424: *
425: */
426:
427: public Enumeration getHeaderNames();
428:
429: /**
430: *
431: * Returns the value of the specified request header
432: * as an <code>int</code>. If the request does not have a header
433: * of the specified name, this method returns -1. If the
434: * header cannot be converted to an integer, this method
435: * throws a <code>NumberFormatException</code>.
436: *
437: * <p>The header name is case insensitive.
438: *
439: * @param name a <code>String</code> specifying the name
440: * of a request header
441: *
442: * @return an integer expressing the value
443: * of the request header or -1
444: * if the request doesn't have a
445: * header of this name
446: *
447: * @exception NumberFormatException If the header value
448: * can't be converted
449: * to an <code>int</code>
450: */
451:
452: public int getIntHeader(String name);
453:
454: }
|