| /* |
| * $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 $ |
| * |
| * Copyright (c) OSGi Alliance (2000, 2006). All Rights Reserved. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.osgi.service.http; |
| |
| import java.io.IOException; |
| import java.net.URL; |
| |
| import javax.servlet.http.HttpServletRequest; |
| import javax.servlet.http.HttpServletResponse; |
| |
| /** |
| * This interface defines methods that the Http Service may call to get |
| * information about a registration. |
| * |
| * <p> |
| * Servlets and resources may be registered with an <code>HttpContext</code> |
| * object; if no <code>HttpContext</code> object is specified, a default |
| * <code>HttpContext</code> object is used. Servlets that are registered using the |
| * same <code>HttpContext</code> object will share the same |
| * <code>ServletContext</code> object. |
| * |
| * <p> |
| * This interface is implemented by users of the <code>HttpService</code>. |
| * |
| * @version $Revision: 1.12 $ |
| */ |
| public interface HttpContext { |
| /** |
| * <code>HttpServletRequest</code> attribute specifying the name of the |
| * authenticated user. The value of the attribute can be retrieved by |
| * <code>HttpServletRequest.getRemoteUser</code>. This attribute name is |
| * <code>org.osgi.service.http.authentication.remote.user</code>. |
| * |
| * @since 1.1 |
| */ |
| public static final String REMOTE_USER = "org.osgi.service.http.authentication.remote.user"; |
| /** |
| * <code>HttpServletRequest</code> attribute specifying the scheme used in |
| * authentication. The value of the attribute can be retrieved by |
| * <code>HttpServletRequest.getAuthType</code>. This attribute name is |
| * <code>org.osgi.service.http.authentication.type</code>. |
| * |
| * @since 1.1 |
| */ |
| public static final String AUTHENTICATION_TYPE = "org.osgi.service.http.authentication.type"; |
| /** |
| * <code>HttpServletRequest</code> attribute specifying the |
| * <code>Authorization</code> object obtained from the |
| * <code>org.osgi.service.useradmin.UserAdmin</code> service. The value of the |
| * attribute can be retrieved by |
| * <code>HttpServletRequest.getAttribute(HttpContext.AUTHORIZATION)</code>. |
| * This attribute name is <code>org.osgi.service.useradmin.authorization</code>. |
| * |
| * @since 1.1 |
| */ |
| public static final String AUTHORIZATION = "org.osgi.service.useradmin.authorization"; |
| |
| /** |
| * Handles security for the specified request. |
| * |
| * <p> |
| * The Http Service calls this method prior to servicing the specified |
| * request. This method controls whether the request is processed in the |
| * normal manner or an error is returned. |
| * |
| * <p> |
| * If the request requires authentication and the Authorization header in |
| * the request is missing or not acceptable, then this method should set the |
| * WWW-Authenticate header in the response object, set the status in the |
| * response object to Unauthorized(401) and return <code>false</code>. See |
| * also RFC 2617: <i>HTTP Authentication: Basic and Digest Access |
| * Authentication </i> (available at http://www.ietf.org/rfc/rfc2617.txt). |
| * |
| * <p> |
| * If the request requires a secure connection and the <code>getScheme</code> |
| * method in the request does not return 'https' or some other acceptable |
| * secure protocol, then this method should set the status in the response |
| * object to Forbidden(403) and return <code>false</code>. |
| * |
| * <p> |
| * When this method returns <code>false</code>, the Http Service will send |
| * the response back to the client, thereby completing the request. When |
| * this method returns <code>true</code>, the Http Service will proceed with |
| * servicing the request. |
| * |
| * <p> |
| * If the specified request has been authenticated, this method must set the |
| * {@link #AUTHENTICATION_TYPE} request attribute to the type of |
| * authentication used, and the {@link #REMOTE_USER} request attribute to |
| * the remote user (request attributes are set using the |
| * <code>setAttribute</code> method on the request). If this method does not |
| * perform any authentication, it must not set these attributes. |
| * |
| * <p> |
| * If the authenticated user is also authorized to access certain resources, |
| * this method must set the {@link #AUTHORIZATION} request attribute to the |
| * <code>Authorization</code> object obtained from the |
| * <code>org.osgi.service.useradmin.UserAdmin</code> service. |
| * |
| * <p> |
| * The servlet responsible for servicing the specified request determines |
| * the authentication type and remote user by calling the |
| * <code>getAuthType</code> and <code>getRemoteUser</code> methods, |
| * respectively, on the request. |
| * |
| * @param request the HTTP request |
| * @param response the HTTP response |
| * @return <code>true</code> if the request should be serviced, <code>false</code> |
| * if the request should not be serviced and Http Service will send |
| * the response back to the client. |
| * @throws java.io.IOException may be thrown by this method. If this |
| * occurs, the Http Service will terminate the request and close |
| * the socket. |
| */ |
| public boolean handleSecurity(HttpServletRequest request, |
| HttpServletResponse response) throws IOException; |
| |
| /** |
| * Maps a resource name to a URL. |
| * |
| * <p> |
| * Called by the Http Service to map a resource name to a URL. For servlet |
| * registrations, Http Service will call this method to support the |
| * <code>ServletContext</code> methods <code>getResource</code> and |
| * <code>getResourceAsStream</code>. For resource registrations, Http Service |
| * will call this method to locate the named resource. The context can |
| * control from where resources come. For example, the resource can be |
| * mapped to a file in the bundle's persistent storage area via |
| * <code>bundleContext.getDataFile(name).toURL()</code> or to a resource in |
| * the context's bundle via <code>getClass().getResource(name)</code> |
| * |
| * @param name the name of the requested resource |
| * @return URL that Http Service can use to read the resource or |
| * <code>null</code> if the resource does not exist. |
| */ |
| public URL getResource(String name); |
| |
| /** |
| * Maps a name to a MIME type. |
| * |
| * Called by the Http Service to determine the MIME type for the name. For |
| * servlet registrations, the Http Service will call this method to support |
| * the <code>ServletContext</code> method <code>getMimeType</code>. For |
| * resource registrations, the Http Service will call this method to |
| * determine the MIME type for the Content-Type header in the response. |
| * |
| * @param name determine the MIME type for this name. |
| * @return MIME type (e.g. text/html) of the name or <code>null</code> to |
| * indicate that the Http Service should determine the MIME type |
| * itself. |
| */ |
| public String getMimeType(String name); |
| } |