HttpContext


1   /*
2    * $Header: /cvshome/build/org.osgi.service.http/src/org/osgi/service/http/HttpContext.java,v 1.12 2006/07/12 21:22:13 hargrave Exp $
3    *
4    * Copyright (c) OSGi Alliance (2000, 2006). All Rights Reserved.
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  package org.osgi.service.http;
19  
20  import java.io.IOException  ;
21  import java.net.URL  ;
22  
23  import javax.servlet.http.HttpServletRequest  ;
24  import javax.servlet.http.HttpServletResponse  ;
25  
26  /**
27   * This interface defines methods that the Http Service may call to get
28   * information about a registration.
29   * 
30   * <p>
31   * Servlets and resources may be registered with an <code>HttpContext</code>
32   * object; if no <code>HttpContext</code> object is specified, a default
33   * <code>HttpContext</code> object is used. Servlets that are registered using the
34   * same <code>HttpContext</code> object will share the same
35   * <code>ServletContext</code> object.
36   * 
37   * <p>
38   * This interface is implemented by users of the <code>HttpService</code>.
39   * 
40   * @version $Revision: 1.12 $
41   */
42  public interface HttpContext {
43      /**
44       * <code>HttpServletRequest</code> attribute specifying the name of the
45       * authenticated user. The value of the attribute can be retrieved by
46       * <code>HttpServletRequest.getRemoteUser</code>. This attribute name is
47       * <code>org.osgi.service.http.authentication.remote.user</code>.
48       * 
49       * @since 1.1
50       */
51      public static final String    REMOTE_USER         = "org.osgi.service.http.authentication.remote.user";
52      /**
53       * <code>HttpServletRequest</code> attribute specifying the scheme used in
54       * authentication. The value of the attribute can be retrieved by
55       * <code>HttpServletRequest.getAuthType</code>. This attribute name is
56       * <code>org.osgi.service.http.authentication.type</code>.
57       * 
58       * @since 1.1
59       */
60      public static final String    AUTHENTICATION_TYPE = "org.osgi.service.http.authentication.type";
61      /**
62       * <code>HttpServletRequest</code> attribute specifying the
63       * <code>Authorization</code> object obtained from the
64       * <code>org.osgi.service.useradmin.UserAdmin</code> service. The value of the
65       * attribute can be retrieved by
66       * <code>HttpServletRequest.getAttribute(HttpContext.AUTHORIZATION)</code>.
67       * This attribute name is <code>org.osgi.service.useradmin.authorization</code>.
68       * 
69       * @since 1.1
70       */
71      public static final String    AUTHORIZATION       = "org.osgi.service.useradmin.authorization";
72  
73      /**
74       * Handles security for the specified request.
75       * 
76       * <p>
77       * The Http Service calls this method prior to servicing the specified
78       * request. This method controls whether the request is processed in the
79       * normal manner or an error is returned.
80       * 
81       * <p>
82       * If the request requires authentication and the Authorization header in
83       * the request is missing or not acceptable, then this method should set the
84       * WWW-Authenticate header in the response object, set the status in the
85       * response object to Unauthorized(401) and return <code>false</code>. See
86       * also RFC 2617: <i>HTTP Authentication: Basic and Digest Access
87       * Authentication </i> (available at http://www.ietf.org/rfc/rfc2617.txt).
88       * 
89       * <p>
90       * If the request requires a secure connection and the <code>getScheme</code>
91       * method in the request does not return 'https' or some other acceptable
92       * secure protocol, then this method should set the status in the response
93       * object to Forbidden(403) and return <code>false</code>.
94       * 
95       * <p>
96       * When this method returns <code>false</code>, the Http Service will send
97       * the response back to the client, thereby completing the request. When
98       * this method returns <code>true</code>, the Http Service will proceed with
99       * servicing the request.
100      * 
101      * <p>
102      * If the specified request has been authenticated, this method must set the
103      * {@link #AUTHENTICATION_TYPE} request attribute to the type of
104      * authentication used, and the {@link #REMOTE_USER} request attribute to
105      * the remote user (request attributes are set using the
106      * <code>setAttribute</code> method on the request). If this method does not
107      * perform any authentication, it must not set these attributes.
108      * 
109      * <p>
110      * If the authenticated user is also authorized to access certain resources,
111      * this method must set the {@link #AUTHORIZATION} request attribute to the
112      * <code>Authorization</code> object obtained from the
113      * <code>org.osgi.service.useradmin.UserAdmin</code> service.
114      * 
115      * <p>
116      * The servlet responsible for servicing the specified request determines
117      * the authentication type and remote user by calling the
118      * <code>getAuthType</code> and <code>getRemoteUser</code> methods,
119      * respectively, on the request.
120      * 
121      * @param request the HTTP request
122      * @param response the HTTP response
123      * @return <code>true</code> if the request should be serviced, <code>false</code>
124      *         if the request should not be serviced and Http Service will send
125      *         the response back to the client.
126      * @throws java.io.IOException may be thrown by this method. If this
127      *            occurs, the Http Service will terminate the request and close
128      *            the socket.
129      */
130     public boolean handleSecurity(HttpServletRequest   request,
131             HttpServletResponse   response) throws IOException  ;
132 
133     /**
134      * Maps a resource name to a URL.
135      * 
136      * <p>
137      * Called by the Http Service to map a resource name to a URL. For servlet
138      * registrations, Http Service will call this method to support the
139      * <code>ServletContext</code> methods <code>getResource</code> and
140      * <code>getResourceAsStream</code>. For resource registrations, Http Service
141      * will call this method to locate the named resource. The context can
142      * control from where resources come. For example, the resource can be
143      * mapped to a file in the bundle's persistent storage area via
144      * <code>bundleContext.getDataFile(name).toURL()</code> or to a resource in
145      * the context's bundle via <code>getClass().getResource(name)</code>
146      * 
147      * @param name the name of the requested resource
148      * @return URL that Http Service can use to read the resource or
149      *         <code>null</code> if the resource does not exist.
150      */
151     public URL   getResource(String   name);
152 
153     /**
154      * Maps a name to a MIME type.
155      * 
156      * Called by the Http Service to determine the MIME type for the name. For
157      * servlet registrations, the Http Service will call this method to support
158      * the <code>ServletContext</code> method <code>getMimeType</code>. For
159      * resource registrations, the Http Service will call this method to
160      * determine the MIME type for the Content-Type header in the response.
161      * 
162      * @param name determine the MIME type for this name.
163      * @return MIME type (e.g. text/html) of the name or <code>null</code> to
164      *         indicate that the Http Service should determine the MIME type
165      *         itself.
166      */
167     public String   getMimeType(String   name);
168 }
169
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags