org.osgi.service.http.HttpContext Maven / Gradle / Ivy

Go to download
/*
 * Copyright (c) OSGi Alliance (2000, 2008). 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.
 * 
 * 
 * Servlets and resources may be registered with an HttpContext
 * object; if no HttpContext object is specified, a default
 * HttpContext object is used. Servlets that are registered using the
 * same HttpContext object will share the same
 * ServletContext object.
 * 
 * 

 * This interface is implemented by users of the HttpService.
 * 
 * @version $Revision: 5673 $
 */
public interface HttpContext {
	/**
	 * HttpServletRequest attribute specifying the name of the
	 * authenticated user. The value of the attribute can be retrieved by
	 * HttpServletRequest.getRemoteUser. This attribute name is
	 * org.osgi.service.http.authentication.remote.user.
	 * 
	 * @since 1.1
	 */
	public static final String	REMOTE_USER			= "org.osgi.service.http.authentication.remote.user";
	/**
	 * HttpServletRequest attribute specifying the scheme used in
	 * authentication. The value of the attribute can be retrieved by
	 * HttpServletRequest.getAuthType. This attribute name is
	 * org.osgi.service.http.authentication.type.
	 * 
	 * @since 1.1
	 */
	public static final String	AUTHENTICATION_TYPE	= "org.osgi.service.http.authentication.type";
	/**
	 * HttpServletRequest attribute specifying the
	 * Authorization object obtained from the
	 * org.osgi.service.useradmin.UserAdmin service. The value of the
	 * attribute can be retrieved by
	 * HttpServletRequest.getAttribute(HttpContext.AUTHORIZATION).
	 * This attribute name is org.osgi.service.useradmin.authorization.
	 * 
	 * @since 1.1
	 */
	public static final String	AUTHORIZATION		= "org.osgi.service.useradmin.authorization";

	/**
	 * Handles security for the specified request.
	 * 
	 * 

	 * 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.
	 * 
	 * 

	 * 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 false. See
	 * also RFC 2617: HTTP Authentication: Basic and Digest Access
	 * Authentication  (available at http://www.ietf.org/rfc/rfc2617.txt).
	 * 
	 * 

	 * If the request requires a secure connection and the getScheme
	 * 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 false.
	 * 
	 * 

	 * When this method returns false, the Http Service will send
	 * the response back to the client, thereby completing the request. When
	 * this method returns true, the Http Service will proceed with
	 * servicing the request.
	 * 
	 * 

	 * 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
	 * setAttribute method on the request). If this method does not
	 * perform any authentication, it must not set these attributes.
	 * 
	 * 

	 * If the authenticated user is also authorized to access certain resources,
	 * this method must set the {@link #AUTHORIZATION} request attribute to the
	 * Authorization object obtained from the
	 * org.osgi.service.useradmin.UserAdmin service.
	 * 
	 * 

	 * The servlet responsible for servicing the specified request determines
	 * the authentication type and remote user by calling the
	 * getAuthType and getRemoteUser methods,
	 * respectively, on the request.
	 * 
	 * @param request the HTTP request
	 * @param response the HTTP response
	 * @return true if the request should be serviced, false
	 *         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.
	 * 
	 * 
	 * 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
	 * ServletContext methods getResource and
	 * getResourceAsStream. 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
	 * bundleContext.getDataFile(name).toURL() or to a resource in
	 * the context's bundle via getClass().getResource(name)
	 * 
	 * @param name the name of the requested resource
	 * @return URL that Http Service can use to read the resource or
	 *         null 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 ServletContext method getMimeType. 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 null to
	 *         indicate that the Http Service should determine the MIME type
	 *         itself.
	 */
	public String getMimeType(String name);
}