HttpService


1   /*
2    * $Header: /cvshome/build/org.osgi.service.http/src/org/osgi/service/http/HttpService.java,v 1.13 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.util.Dictionary  ;
21  
22  import javax.servlet.Servlet  ;
23  import javax.servlet.ServletException  ;
24  
25  /**
26   * The Http Service allows other bundles in the OSGi environment to dynamically
27   * register resources and servlets into the URI namespace of Http Service. A
28   * bundle may later unregister its resources or servlets.
29   * 
30   * @version $Revision: 1.13 $
31   * @see HttpContext
32   */
33  public interface HttpService {
34      /**
35       * Registers a servlet into the URI namespace.
36       * 
37       * <p>
38       * The alias is the name in the URI namespace of the Http Service at which
39       * the registration will be mapped.
40       * 
41       * <p>
42       * An alias must begin with slash ('/') and must not end with slash ('/'),
43       * with the exception that an alias of the form &quot;/&quot; is used to
44       * denote the root alias. See the specification text for details on how HTTP
45       * requests are mapped to servlet and resource registrations.
46       * 
47       * <p>
48       * The Http Service will call the servlet's <code>init</code> method before
49       * returning.
50       * 
51       * <pre>
52       * httpService.registerServlet(&quot;/myservlet&quot;, servlet, initparams, context);
53       * </pre>
54       * 
55       * <p>
56       * Servlets registered with the same <code>HttpContext</code> object will
57       * share the same <code>ServletContext</code>. The Http Service will call the
58       * <code>context</code> argument to support the <code>ServletContext</code>
59       * methods <code>getResource</code>,<code>getResourceAsStream</code> and
60       * <code>getMimeType</code>, and to handle security for requests. If the
61       * <code>context</code> argument is <code>null</code>, a default
62       * <code>HttpContext</code> object is used (see
63       * {@link #createDefaultHttpContext}).
64       * 
65       * @param alias name in the URI namespace at which the servlet is registered
66       * @param servlet the servlet object to register
67       * @param initparams initialization arguments for the servlet or
68       *        <code>null</code> if there are none. This argument is used by the
69       *        servlet's <code>ServletConfig</code> object.
70       * @param context the <code>HttpContext</code> object for the registered
71       *        servlet, or <code>null</code> if a default <code>HttpContext</code> is
72       *        to be created and used.
73       * @throws NamespaceException if the registration fails because the alias
74       *            is already in use.
75       * @throws javax.servlet.ServletException if the servlet's <code>init</code>
76       *            method throws an exception, or the given servlet object has
77       *            already been registered at a different alias.
78       * @throws java.lang.IllegalArgumentException if any of the arguments are
79       *            invalid
80       */
81      public void registerServlet(String   alias, Servlet   servlet,
82              Dictionary   initparams, HttpContext context)
83              throws ServletException  , NamespaceException;
84  
85      /**
86       * Registers resources into the URI namespace.
87       * 
88       * <p>
89       * The alias is the name in the URI namespace of the Http Service at which
90       * the registration will be mapped. An alias must begin with slash ('/') and
91       * must not end with slash ('/'), with the exception that an alias of the
92       * form &quot;/&quot; is used to denote the root alias. The name parameter
93       * must also not end with slash ('/'). See the specification text for
94       * details on how HTTP requests are mapped to servlet and resource
95       * registrations.
96       * <p>
97       * For example, suppose the resource name /tmp is registered to the alias
98       * /files. A request for /files/foo.txt will map to the resource name
99       * /tmp/foo.txt.
100      * 
101      * <pre>
102      * httpservice.registerResources(&quot;/files&quot;, &quot;/tmp&quot;, context);
103      * </pre>
104      * 
105      * The Http Service will call the <code>HttpContext</code> argument to map
106      * resource names to URLs and MIME types and to handle security for
107      * requests. If the <code>HttpContext</code> argument is <code>null</code>, a
108      * default <code>HttpContext</code> is used (see
109      * {@link #createDefaultHttpContext}).
110      * 
111      * @param alias name in the URI namespace at which the resources are
112      *        registered
113      * @param name the base name of the resources that will be registered
114      * @param context the <code>HttpContext</code> object for the registered
115      *        resources, or <code>null</code> if a default <code>HttpContext</code>
116      *        is to be created and used.
117      * @throws NamespaceException if the registration fails because the alias
118      *            is already in use.
119      * @throws java.lang.IllegalArgumentException if any of the parameters
120      *            are invalid
121      */
122     public void registerResources(String   alias, String   name,
123             HttpContext context) throws NamespaceException;
124 
125     /**
126      * Unregisters a previous registration done by <code>registerServlet</code> or
127      * <code>registerResources</code> methods.
128      * 
129      * <p>
130      * After this call, the registered alias in the URI name-space will no
131      * longer be available. If the registration was for a servlet, the Http
132      * Service must call the <code>destroy</code> method of the servlet before
133      * returning.
134      * <p>
135      * If the bundle which performed the registration is stopped or otherwise
136      * "unget"s the Http Service without calling {@link #unregister} then Http
137      * Service must automatically unregister the registration. However, if the
138      * registration was for a servlet, the <code>destroy</code> method of the
139      * servlet will not be called in this case since the bundle may be stopped.
140      * {@link #unregister} must be explicitly called to cause the
141      * <code>destroy</code> method of the servlet to be called. This can be done
142      * in the <code>BundleActivator.stop</code> method of the
143      * bundle registering the servlet.
144      * 
145      * @param alias name in the URI name-space of the registration to unregister
146      * @throws java.lang.IllegalArgumentException if there is no registration
147      *            for the alias or the calling bundle was not the bundle which
148      *            registered the alias.
149      */
150     public void unregister(String   alias);
151 
152     /**
153      * Creates a default <code>HttpContext</code> for registering servlets or
154      * resources with the HttpService, a new <code>HttpContext</code> object is
155      * created each time this method is called.
156      * 
157      * <p>
158      * The behavior of the methods on the default <code>HttpContext</code> is
159      * defined as follows:
160      * <ul>
161      * <li><code>getMimeType</code>- Does not define any customized MIME types
162      * for the Content-Type header in the response, and always returns
163      * <code>null</code>.
164      * <li><code>handleSecurity</code>- Performs implementation-defined
165      * authentication on the request.
166      * <li><code>getResource</code>- Assumes the named resource is in the
167      * context bundle; this method calls the context bundle's
168      * <code>Bundle.getResource</code> method, and returns the appropriate URL to
169      * access the resource. On a Java runtime environment that supports
170      * permissions, the Http Service needs to be granted 
171      * <code>org.osgi.framework.AdminPermission[*,RESOURCE]</code>.
172      * </ul>
173      * 
174      * @return a default <code>HttpContext</code> object.
175      * @since 1.1
176      */
177     public HttpContext createDefaultHttpContext();
178 }
179
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags