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.util.Dictionary;
019
020 import javax.servlet.Servlet;
021 import javax.servlet.ServletException;
022
023 /**
024 * The Http Service allows other bundles in the OSGi environment to dynamically
025 * register resources and servlets into the URI namespace of Http Service. A
026 * bundle may later unregister its resources or servlets.
027 *
028 * @version $Revision: 5673 $
029 * @see HttpContext
030 */
031 public interface HttpService {
032 /**
033 * Registers a servlet into the URI namespace.
034 *
035 * <p>
036 * The alias is the name in the URI namespace of the Http Service at which
037 * the registration will be mapped.
038 *
039 * <p>
040 * An alias must begin with slash ('/') and must not end with slash ('/'),
041 * with the exception that an alias of the form "/" is used to
042 * denote the root alias. See the specification text for details on how HTTP
043 * requests are mapped to servlet and resource registrations.
044 *
045 * <p>
046 * The Http Service will call the servlet's <code>init</code> method before
047 * returning.
048 *
049 * <pre>
050 * httpService.registerServlet("/myservlet", servlet, initparams, context);
051 * </pre>
052 *
053 * <p>
054 * Servlets registered with the same <code>HttpContext</code> object will
055 * share the same <code>ServletContext</code>. The Http Service will call the
056 * <code>context</code> argument to support the <code>ServletContext</code>
057 * methods <code>getResource</code>,<code>getResourceAsStream</code> and
058 * <code>getMimeType</code>, and to handle security for requests. If the
059 * <code>context</code> argument is <code>null</code>, a default
060 * <code>HttpContext</code> object is used (see
061 * {@link #createDefaultHttpContext}).
062 *
063 * @param alias name in the URI namespace at which the servlet is registered
064 * @param servlet the servlet object to register
065 * @param initparams initialization arguments for the servlet or
066 * <code>null</code> if there are none. This argument is used by the
067 * servlet's <code>ServletConfig</code> object.
068 * @param context the <code>HttpContext</code> object for the registered
069 * servlet, or <code>null</code> if a default <code>HttpContext</code> is
070 * to be created and used.
071 * @throws NamespaceException if the registration fails because the alias
072 * is already in use.
073 * @throws javax.servlet.ServletException if the servlet's <code>init</code>
074 * method throws an exception, or the given servlet object has
075 * already been registered at a different alias.
076 * @throws java.lang.IllegalArgumentException if any of the arguments are
077 * invalid
078 */
079 public void registerServlet(String alias, Servlet servlet,
080 Dictionary initparams, HttpContext context)
081 throws ServletException, NamespaceException;
082
083 /**
084 * Registers resources into the URI namespace.
085 *
086 * <p>
087 * The alias is the name in the URI namespace of the Http Service at which
088 * the registration will be mapped. An alias must begin with slash ('/') and
089 * must not end with slash ('/'), with the exception that an alias of the
090 * form "/" is used to denote the root alias. The name parameter
091 * must also not end with slash ('/') with the exception that a name of the
092 * form "/" is used to denote the root of the bundle. See the
093 * specification text for details on how HTTP requests are mapped to servlet
094 * and resource registrations.
095 * <p>
096 * For example, suppose the resource name /tmp is registered to the alias
097 * /files. A request for /files/foo.txt will map to the resource name
098 * /tmp/foo.txt.
099 *
100 * <pre>
101 * httpservice.registerResources("/files", "/tmp", context);
102 * </pre>
103 *
104 * The Http Service will call the <code>HttpContext</code> argument to map
105 * resource names to URLs and MIME types and to handle security for
106 * requests. If the <code>HttpContext</code> argument is <code>null</code>,
107 * a default <code>HttpContext</code> is used (see
108 * {@link #createDefaultHttpContext}).
109 *
110 * @param alias name in the URI namespace at which the resources are
111 * registered
112 * @param name the base name of the resources that will be registered
113 * @param context the <code>HttpContext</code> object for the registered
114 * resources, or <code>null</code> if a default
115 * <code>HttpContext</code> is to be created and used.
116 * @throws NamespaceException if the registration fails because the alias is
117 * already in use.
118 * @throws java.lang.IllegalArgumentException if any of the parameters are
119 * invalid
120 */
121 public void registerResources(String alias, String name,
122 HttpContext context) throws NamespaceException;
123
124 /**
125 * Unregisters a previous registration done by <code>registerServlet</code> or
126 * <code>registerResources</code> methods.
127 *
128 * <p>
129 * After this call, the registered alias in the URI name-space will no
130 * longer be available. If the registration was for a servlet, the Http
131 * Service must call the <code>destroy</code> method of the servlet before
132 * returning.
133 * <p>
134 * If the bundle which performed the registration is stopped or otherwise
135 * "unget"s the Http Service without calling {@link #unregister} then Http
136 * Service must automatically unregister the registration. However, if the
137 * registration was for a servlet, the <code>destroy</code> method of the
138 * servlet will not be called in this case since the bundle may be stopped.
139 * {@link #unregister} must be explicitly called to cause the
140 * <code>destroy</code> method of the servlet to be called. This can be done
141 * in the <code>BundleActivator.stop</code> method of the
142 * bundle registering the servlet.
143 *
144 * @param alias name in the URI name-space of the registration to unregister
145 * @throws java.lang.IllegalArgumentException if there is no registration
146 * for the alias or the calling bundle was not the bundle which
147 * registered the alias.
148 */
149 public void unregister(String alias);
150
151 /**
152 * Creates a default <code>HttpContext</code> for registering servlets or
153 * resources with the HttpService, a new <code>HttpContext</code> object is
154 * created each time this method is called.
155 *
156 * <p>
157 * The behavior of the methods on the default <code>HttpContext</code> is
158 * defined as follows:
159 * <ul>
160 * <li><code>getMimeType</code>- Does not define any customized MIME types
161 * for the Content-Type header in the response, and always returns
162 * <code>null</code>.
163 * <li><code>handleSecurity</code>- Performs implementation-defined
164 * authentication on the request.
165 * <li><code>getResource</code>- Assumes the named resource is in the
166 * context bundle; this method calls the context bundle's
167 * <code>Bundle.getResource</code> method, and returns the appropriate URL to
168 * access the resource. On a Java runtime environment that supports
169 * permissions, the Http Service needs to be granted
170 * <code>org.osgi.framework.AdminPermission[*,RESOURCE]</code>.
171 * </ul>
172 *
173 * @return a default <code>HttpContext</code> object.
174 * @since 1.1
175 */
176 public HttpContext createDefaultHttpContext();
177 }