001 /*
002 * Copyright (c) OSGi Alliance (2000, 2008). All Rights Reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.osgi.service.http;
017
018 import java.io.IOException;
019 import java.net.URL;
020
021 import javax.servlet.http.HttpServletRequest;
022 import javax.servlet.http.HttpServletResponse;
023
024 /**
025 * This interface defines methods that the Http Service may call to get
026 * information about a registration.
027 *
028 * <p>
029 * Servlets and resources may be registered with an <code>HttpContext</code>
030 * object; if no <code>HttpContext</code> object is specified, a default
031 * <code>HttpContext</code> object is used. Servlets that are registered using the
032 * same <code>HttpContext</code> object will share the same
033 * <code>ServletContext</code> object.
034 *
035 * <p>
036 * This interface is implemented by users of the <code>HttpService</code>.
037 *
038 * @version $Revision: 5673 $
039 */
040 public interface HttpContext {
041 /**
042 * <code>HttpServletRequest</code> attribute specifying the name of the
043 * authenticated user. The value of the attribute can be retrieved by
044 * <code>HttpServletRequest.getRemoteUser</code>. This attribute name is
045 * <code>org.osgi.service.http.authentication.remote.user</code>.
046 *
047 * @since 1.1
048 */
049 public static final String REMOTE_USER = "org.osgi.service.http.authentication.remote.user";
050 /**
051 * <code>HttpServletRequest</code> attribute specifying the scheme used in
052 * authentication. The value of the attribute can be retrieved by
053 * <code>HttpServletRequest.getAuthType</code>. This attribute name is
054 * <code>org.osgi.service.http.authentication.type</code>.
055 *
056 * @since 1.1
057 */
058 public static final String AUTHENTICATION_TYPE = "org.osgi.service.http.authentication.type";
059 /**
060 * <code>HttpServletRequest</code> attribute specifying the
061 * <code>Authorization</code> object obtained from the
062 * <code>org.osgi.service.useradmin.UserAdmin</code> service. The value of the
063 * attribute can be retrieved by
064 * <code>HttpServletRequest.getAttribute(HttpContext.AUTHORIZATION)</code>.
065 * This attribute name is <code>org.osgi.service.useradmin.authorization</code>.
066 *
067 * @since 1.1
068 */
069 public static final String AUTHORIZATION = "org.osgi.service.useradmin.authorization";
070
071 /**
072 * Handles security for the specified request.
073 *
074 * <p>
075 * The Http Service calls this method prior to servicing the specified
076 * request. This method controls whether the request is processed in the
077 * normal manner or an error is returned.
078 *
079 * <p>
080 * If the request requires authentication and the Authorization header in
081 * the request is missing or not acceptable, then this method should set the
082 * WWW-Authenticate header in the response object, set the status in the
083 * response object to Unauthorized(401) and return <code>false</code>. See
084 * also RFC 2617: <i>HTTP Authentication: Basic and Digest Access
085 * Authentication </i> (available at http://www.ietf.org/rfc/rfc2617.txt).
086 *
087 * <p>
088 * If the request requires a secure connection and the <code>getScheme</code>
089 * method in the request does not return 'https' or some other acceptable
090 * secure protocol, then this method should set the status in the response
091 * object to Forbidden(403) and return <code>false</code>.
092 *
093 * <p>
094 * When this method returns <code>false</code>, the Http Service will send
095 * the response back to the client, thereby completing the request. When
096 * this method returns <code>true</code>, the Http Service will proceed with
097 * servicing the request.
098 *
099 * <p>
100 * If the specified request has been authenticated, this method must set the
101 * {@link #AUTHENTICATION_TYPE} request attribute to the type of
102 * authentication used, and the {@link #REMOTE_USER} request attribute to
103 * the remote user (request attributes are set using the
104 * <code>setAttribute</code> method on the request). If this method does not
105 * perform any authentication, it must not set these attributes.
106 *
107 * <p>
108 * If the authenticated user is also authorized to access certain resources,
109 * this method must set the {@link #AUTHORIZATION} request attribute to the
110 * <code>Authorization</code> object obtained from the
111 * <code>org.osgi.service.useradmin.UserAdmin</code> service.
112 *
113 * <p>
114 * The servlet responsible for servicing the specified request determines
115 * the authentication type and remote user by calling the
116 * <code>getAuthType</code> and <code>getRemoteUser</code> methods,
117 * respectively, on the request.
118 *
119 * @param request the HTTP request
120 * @param response the HTTP response
121 * @return <code>true</code> if the request should be serviced, <code>false</code>
122 * if the request should not be serviced and Http Service will send
123 * the response back to the client.
124 * @throws java.io.IOException may be thrown by this method. If this
125 * occurs, the Http Service will terminate the request and close
126 * the socket.
127 */
128 public boolean handleSecurity(HttpServletRequest request,
129 HttpServletResponse response) throws IOException;
130
131 /**
132 * Maps a resource name to a URL.
133 *
134 * <p>
135 * Called by the Http Service to map a resource name to a URL. For servlet
136 * registrations, Http Service will call this method to support the
137 * <code>ServletContext</code> methods <code>getResource</code> and
138 * <code>getResourceAsStream</code>. For resource registrations, Http Service
139 * will call this method to locate the named resource. The context can
140 * control from where resources come. For example, the resource can be
141 * mapped to a file in the bundle's persistent storage area via
142 * <code>bundleContext.getDataFile(name).toURL()</code> or to a resource in
143 * the context's bundle via <code>getClass().getResource(name)</code>
144 *
145 * @param name the name of the requested resource
146 * @return URL that Http Service can use to read the resource or
147 * <code>null</code> if the resource does not exist.
148 */
149 public URL getResource(String name);
150
151 /**
152 * Maps a name to a MIME type.
153 *
154 * Called by the Http Service to determine the MIME type for the name. For
155 * servlet registrations, the Http Service will call this method to support
156 * the <code>ServletContext</code> method <code>getMimeType</code>. For
157 * resource registrations, the Http Service will call this method to
158 * determine the MIME type for the Content-Type header in the response.
159 *
160 * @param name determine the MIME type for this name.
161 * @return MIME type (e.g. text/html) of the name or <code>null</code> to
162 * indicate that the Http Service should determine the MIME type
163 * itself.
164 */
165 public String getMimeType(String name);
166 }