org.ops4j.pax.web.service.whiteboard

Interface ServletMapping

All Superinterfaces:

ContextRelated

public interface ServletMapping
extends ContextRelated

Servlet mapping contains all the information required to register a Servlet (either directly or using whiteboard pattern).

This interface may be used directly, when user registers OSGi services using it as Constants.OBJECTCLASS (explicit whiteboard approach) or will be used internally, when user registers actual Servlet instance with service properties (or class annotations) (as recommended by Whiteboard specification).

Registering a Servlet can be done in two ways:

• registering a service with this interface - all the information is included in service itself (explicit Whiteboard approach)
• registering a Servlet service, while required properties (mapping, name, parameters) are specified using service registration properties or annotations (OSGi CMPN Whiteboard approach)

Since:

0.4.0, April 05, 2008

Author:

Alin Dreghiciu, Grzegorz Grzybek

Method Summary

Modifier and Type	Method and Description
String	getAlias() Get an alias to use for servlet registration.
Boolean	getAsyncSupported() Get flag for supporting asynchronous servlet invocation.
String[]	getErrorPages() Get error page declarations to use for the servlet being registered.
Map<String,String>	getInitParameters() Get init parameters for the servlet being registered.
Integer	getLoadOnStartup() Get load on startup value for the servlet being registered.
javax.servlet.MultipartConfigElement	getMultipartConfig() Get MultipartConfigElement to configuration multipart support for the servlet being registered.
javax.servlet.Servlet	getServlet() Get an actual Servlet instance to register.
Class<? extends javax.servlet.Servlet>	getServletClass() Get a class of Servlet to register.
String	getServletName() Get a name of the servlet being registered.
String[]	getUrlPatterns() Get URL patterns to map into the servlet being registered.

Methods inherited from interface org.ops4j.pax.web.service.whiteboard.ContextRelated

getContextId, getContextSelectFilter

Method Detail

getServlet

javax.servlet.Servlet getServlet()

Get an actual Servlet instance to register.

In whiteboard method, this is actual OSGi service instance.

Returns:

the servlet to register

getServletClass

Class<? extends javax.servlet.Servlet> getServletClass()

Get a class of Servlet to register. Matches <servlet>/<servlet-class> element from web.xml. If getServlet() is also specified, servlet class isn't used.

There's no whiteboard specific method to specify this class.

Returns:

the servlet's class to instantiate and register

getServletName

String getServletName()

Get a name of the servlet being registered. Matches <servlet>/<servlet-name> element from web.xml.

In whiteboard method, this can be specified as:

• HttpWhiteboardConstants.HTTP_WHITEBOARD_SERVLET_NAME property
• servlet-name service registration property (legacy Pax Web Whiteboard approach)

If not specified, the name defaults to fully qualified class name of the servlet.

Returns:

name of the Servlet being mapped.

getUrlPatterns

String[] getUrlPatterns()

Get URL patterns to map into the servlet being registered. URL patterns should be specified according to Servlet API 4 specification (chapter 12.2) and OSGi CMPN R6+ Whiteboard specification (chapter 140.4). It matches <servlet-mapping>/<url-pattern> elements from web.xml.

In whiteboard method, this can be specified as:

• HttpWhiteboardConstants.HTTP_WHITEBOARD_SERVLET_PATTERN property
• org.osgi.service.http.whiteboard.propertytypes.HttpWhiteboardServletPattern annotation
• urlPatterns service registration property (legacy Pax Web Whiteboard approach)

When passing service registration property, it should be one of String, String[] or Collection<String> types.

Returns:

an array of url patterns servlet maps to

getAlias

String getAlias()

Get an alias to use for servlet registration. An alias is defined in OSGi CMPN specification of HTTP Service and is often (even in specification) confused with servlet name: name in the URI namespace. For the purpose of Pax Web and consistency, single alias is treated as one-element array of URL Patterns if the patterns are not specified.

There's no whiteboard specific method to specify an alias.

Returns:

resource alias - effectively changed into 1-element array of urlPatterns

getErrorPages

String[] getErrorPages()

Get error page declarations to use for the servlet being registered. The declarations mark the servlet as error servlet matching <error-page>/<error-code> and <error-page>/<exception-type> elementss from web.xml.

In whiteboard method, this can be specified as:

• HttpWhiteboardConstants.HTTP_WHITEBOARD_SERVLET_ERROR_PAGE property
• org.osgi.service.http.whiteboard.propertytypes.HttpWhiteboardServletErrorPage annotation

Returns:

Servlet async-supported flag

getAsyncSupported

Boolean getAsyncSupported()

Get flag for supporting asynchronous servlet invocation. It matches <servlet>/<async-supported> element from web.xml.

In whiteboard method, this can be specified as:

• HttpWhiteboardConstants.HTTP_WHITEBOARD_SERVLET_ASYNC_SUPPORTED property
• org.osgi.service.http.whiteboard.propertytypes.HttpWhiteboardServletAsyncSupported annotation

Returns:

Servlet async-supported flag

getMultipartConfig

javax.servlet.MultipartConfigElement getMultipartConfig()

Get MultipartConfigElement to configuration multipart support for the servlet being registered. See Servlet API 4 specification (chapter 3.2 File upload) for details. It matches <servlet>/<multipart-config> element from web.xml.

In whiteboard method, this can be specified as:

• org.osgi.service.http.whiteboard.HttpWhiteboardConstants#HTTP_WHITEBOARD_SERVLET_MULTIPART_* properties
• org.osgi.service.http.whiteboard.propertytypes.HttpWhiteboardServletMultipart annotation

Returns:

Servlet multipart configuration

getInitParameters

Map<String,String> getInitParameters()

Get init parameters for the servlet being registered. It matches <servlet>/<init-param> elements from web.xml.

In whiteboard method, this can be specified as (no annotation here):

• HttpWhiteboardConstants.HTTP_WHITEBOARD_SERVLET_INIT_PARAM_PREFIX prefixed properties (OSGi CMPN Whiteboard approach)
• init. prefixed properties (or prefix may be specified using init-prefix service registration property (legacy Pax Web Whiteboard approach)

Returns:

map of initialization parameters.

getLoadOnStartup

Integer getLoadOnStartup()

Get load on startup value for the servlet being registered. It matches <servlet>/<load-on-startup> element from web.xml.

Whiteboard specification doesn't mention this parameter.

Returns:

Servlet load-on-startup configuration