Top Description Fields Methods
org.apache.catalina

public Interface Wrapper

extends Container
Known Direct Implementers
org.apache.catalina.core.StandardWrapper
Imports
jakarta.servlet.MultipartConfigElement, .Servlet, .ServletException, .UnavailableException
A Wrapper is a Container that represents an individual servlet definition from the deployment descriptor of the web application. It provides a convenient mechanism to use Interceptors that see every single request to the servlet represented by this definition.

Implementations of Wrapper are responsible for managing the servlet life cycle for their underlying servlet class, including calling init() and destroy() at appropriate times.

The parent Container attached to a Wrapper will generally be an implementation of Context, representing the servlet context (and therefore the web application) within which this servlet executes.

Child Containers are not allowed on Wrapper implementations, so the addChild() method should throw an IllegalArgumentException.

Author
Craig R. McClanahan

Field Summary

Modifier and TypeField and Description
public static final String
ADD_MAPPING_EVENT

Container event for adding a wrapper.

public static final String
REMOVE_MAPPING_EVENT

Container event for removing a wrapper.

Inherited from org.apache.catalina.Container:
ADD_CHILD_EVENTADD_VALVE_EVENTREMOVE_CHILD_EVENTREMOVE_VALVE_EVENT

Method Summary

Modifier and TypeMethod and Description
public void
addInitParameter(String
Name of this initialization parameter to add
name, String
Value of this initialization parameter to add
value)

Add a new servlet initialization parameter for this servlet.

public void
addMapping(String
The new wrapper mapping
mapping)

Add a mapping associated with the Wrapper.

public void
addSecurityReference(String
Role name used within this servlet
name, String
Role name used within the web application
link)

Add a new security role reference record to the set of records for this servlet.

public Servlet

Returns:

a new Servlet instance
allocate()

Allocate an initialized instance of this Servlet that is ready to have its service() method called.

public void
deallocate(Servlet
The servlet to be returned
servlet)

Decrement the allocation count for the servlet instance.

public String

Returns:

the value for the specified initialization parameter name, if any; otherwise return null.
findInitParameter(String
Name of the requested initialization parameter
name)

public String[]

Returns:

the names of all defined initialization parameters for this servlet.
findInitParameters()

public String[]

Returns:

the mappings associated with this wrapper.
findMappings()

public String

Returns:

the security role link for the specified security role reference name, if any; otherwise return null.
findSecurityReference(String
Security role reference used within this servlet
name)

public String[]

Returns:

the set of security role reference names associated with this servlet, if any; otherwise return a zero-length array.
findSecurityReferences()

public long

Returns:

the available date/time for this servlet, in milliseconds since the epoch. If this date/time is in the future, any request for this servlet will return an SC_SERVICE_UNAVAILABLE error. If it is zero, the servlet is currently available. A value equal to Long.MAX_VALUE is considered to mean that unavailability is permanent.
getAvailable()

public int

Returns:

the load-on-startup order value (negative value means load on first call).
getLoadOnStartup()

public MultipartConfigElement

Returns:

the multi-part configuration for the associated Servlet. If no multi-part configuration has been defined, then null will be returned.
getMultipartConfigElement()

public String

Returns:

the run-as identity for this servlet.
getRunAs()

public Servlet

Returns:

the associated Servlet instance.
getServlet()

public String

Returns:

the fully qualified servlet class name for this servlet.
getServletClass()

public String[]

Returns:

Array of names of the methods supported by the underlying servlet
getServletMethods()

Gets the names of the methods supported by the underlying servlet.

public void
incrementErrorCount()

Increment the error count value used when monitoring.

public boolean

Returns:

true if the Servlet supports async
isAsyncSupported()

Does the associated Servlet support async processing?

public boolean

Returns:

true if the Servlet is enabled
isEnabled()

Is the associated Servlet enabled?

public boolean

Returns:

true if the Servlet can be overridden in a ServletContainerInitializer
isOverridable()

Is the Servlet overridable by a ServletContainerInitializer?

public boolean

Returns:

true if this Servlet is currently unavailable.
isUnavailable()

public void
load()

Load and initialize an instance of this Servlet, if there is not already at least one initialized instance.

public void
removeInitParameter(String
Name of the initialization parameter to remove
name)

Remove the specified initialization parameter from this Servlet.

public void
removeMapping(String
The pattern to remove
mapping)

Remove a mapping associated with the wrapper.

public void
removeSecurityReference(String
Security role used within this servlet to be removed
name)

Remove any security role reference for the specified role name.

public void
setAsyncSupported(boolean
the new value
asyncSupport)

Set the async support for the associated Servlet.

public void
setAvailable(long
The new available date/time
available)

Set the available date/time for this servlet, in milliseconds since the epoch.

public void
setEnabled(boolean
the new value
enabled)

Sets the enabled attribute for the associated servlet.

public void
setLoadOnStartup(int
New load-on-startup value
value)

Set the load-on-startup order value (negative value means load on first call).

public void
setMultipartConfigElement(MultipartConfigElement
The configuration associated with the Servlet
multipartConfig)

Set the multi-part configuration for the associated Servlet.

public void
setOverridable(boolean
the new value
overridable)

Sets the overridable attribute for this Servlet.

public void
setRunAs(String
New run-as identity value
runAs)

Set the run-as identity for this servlet.

public void
setServlet(Servlet
The associated Servlet
servlet)

Set the associated Servlet instance

public void
setServletClass(String
Servlet class name
servletClass)

Set the fully qualified servlet class name for this servlet.

public void
unavailable(UnavailableException
The exception that occurred, or null to mark this Servlet as permanently unavailable
unavailable)

Process an UnavailableException, marking this Servlet as unavailable for the specified amount of time.

public void
unload()

Unload all initialized instances of this servlet, after calling the destroy() method for each instance.

Inherited from org.apache.catalina.Container:
addChildaddContainerListeneraddPropertyChangeListenerbackgroundProcessfindChildfindChildrenfindContainerListenersfireContainerEventgetAccessLoggetBackgroundProcessorDelaygetCatalinaBasegetCatalinaHomegetClustergetConfigPathgetDomaingetLoggergetLogNamegetMBeanKeyPropertiesgetNamegetObjectNamegetParentgetParentClassLoadergetPipelinegetRealmgetServicegetStartStopThreadslogAccessremoveChildremoveContainerListenerremovePropertyChangeListenersetBackgroundProcessorDelaysetClustersetNamesetParentsetParentClassLoadersetRealmsetStartStopThreads

Field Detail

ADD_MAPPING_EVENTback to summary
public static final String ADD_MAPPING_EVENT

Container event for adding a wrapper.

REMOVE_MAPPING_EVENTback to summary
public static final String REMOVE_MAPPING_EVENT

Container event for removing a wrapper.

Method Detail

addInitParameterback to summary
public void addInitParameter(String name, String value)

Add a new servlet initialization parameter for this servlet.

Parameters
name:String

Name of this initialization parameter to add

value:String

Value of this initialization parameter to add

addMappingback to summary
public void addMapping(String mapping)

Add a mapping associated with the Wrapper.

Parameters
mapping:String

The new wrapper mapping

addSecurityReferenceback to summary
public void addSecurityReference(String name, String link)

Add a new security role reference record to the set of records for this servlet.

Parameters
name:String

Role name used within this servlet

link:String

Role name used within the web application

allocateback to summary
public Servlet allocate() throws ServletException

Allocate an initialized instance of this Servlet that is ready to have its service() method called. The previously initialized instance may be returned immediately.

Returns:Servlet

a new Servlet instance

Exceptions
ServletException:
  • if the Servlet init() method threw an exception
  • if a loading error occurs
deallocateback to summary
public void deallocate(Servlet servlet) throws ServletException

Decrement the allocation count for the servlet instance.

Parameters
servlet:Servlet

The servlet to be returned

Exceptions
ServletException:
if a deallocation error occurs
findInitParameterback to summary
public String findInitParameter(String name)
Parameters
name:String

Name of the requested initialization parameter

Returns:String

the value for the specified initialization parameter name, if any; otherwise return null.

findInitParametersback to summary
public String[] findInitParameters()
Returns:String[]

the names of all defined initialization parameters for this servlet.

findMappingsback to summary
public String[] findMappings()
Returns:String[]

the mappings associated with this wrapper.

findSecurityReferenceback to summary
public String findSecurityReference(String name)
Parameters
name:String

Security role reference used within this servlet

Returns:String

the security role link for the specified security role reference name, if any; otherwise return null.

findSecurityReferencesback to summary
public String[] findSecurityReferences()
Returns:String[]

the set of security role reference names associated with this servlet, if any; otherwise return a zero-length array.

getAvailableback to summary
public long getAvailable()
Returns:long

the available date/time for this servlet, in milliseconds since the epoch. If this date/time is in the future, any request for this servlet will return an SC_SERVICE_UNAVAILABLE error. If it is zero, the servlet is currently available. A value equal to Long.MAX_VALUE is considered to mean that unavailability is permanent.

getLoadOnStartupback to summary
public int getLoadOnStartup()
Returns:int

the load-on-startup order value (negative value means load on first call).

getMultipartConfigElementback to summary
public MultipartConfigElement getMultipartConfigElement()
Returns:MultipartConfigElement

the multi-part configuration for the associated Servlet. If no multi-part configuration has been defined, then null will be returned.

getRunAsback to summary
public String getRunAs()
Returns:String

the run-as identity for this servlet.

getServletback to summary
public Servlet getServlet()
Returns:Servlet

the associated Servlet instance.

getServletClassback to summary
public String getServletClass()
Returns:String

the fully qualified servlet class name for this servlet.

getServletMethodsback to summary
public String[] getServletMethods() throws ServletException

Gets the names of the methods supported by the underlying servlet. This is the same set of methods included in the Allow response header in response to an OPTIONS request method processed by the underlying servlet.

Returns:String[]

Array of names of the methods supported by the underlying servlet

Exceptions
ServletException:
If the target servlet cannot be loaded
incrementErrorCountback to summary
public void incrementErrorCount()

Increment the error count value used when monitoring.

isAsyncSupportedback to summary
public boolean isAsyncSupported()

Does the associated Servlet support async processing? Defaults to false.

Returns:boolean

true if the Servlet supports async

isEnabledback to summary
public boolean isEnabled()

Is the associated Servlet enabled? Defaults to true.

Returns:boolean

true if the Servlet is enabled

isOverridableback to summary
public boolean isOverridable()

Is the Servlet overridable by a ServletContainerInitializer?

Returns:boolean

true if the Servlet can be overridden in a ServletContainerInitializer

isUnavailableback to summary
public boolean isUnavailable()
Returns:boolean

true if this Servlet is currently unavailable.

loadback to summary
public void load() throws ServletException

Load and initialize an instance of this Servlet, if there is not already at least one initialized instance. This can be used, for example, to load Servlets that are marked in the deployment descriptor to be loaded at server startup time.

Exceptions
ServletException:
if the Servlet init() method threw an exception or if some other loading problem occurs
removeInitParameterback to summary
public void removeInitParameter(String name)

Remove the specified initialization parameter from this Servlet.

Parameters
name:String

Name of the initialization parameter to remove

removeMappingback to summary
public void removeMapping(String mapping)

Remove a mapping associated with the wrapper.

Parameters
mapping:String

The pattern to remove

removeSecurityReferenceback to summary
public void removeSecurityReference(String name)

Remove any security role reference for the specified role name.

Parameters
name:String

Security role used within this servlet to be removed

setAsyncSupportedback to summary
public void setAsyncSupported(boolean asyncSupport)

Set the async support for the associated Servlet.

Parameters
asyncSupport:boolean

the new value

setAvailableback to summary
public void setAvailable(long available)

Set the available date/time for this servlet, in milliseconds since the epoch. If this date/time is in the future, any request for this servlet will return an SC_SERVICE_UNAVAILABLE error. A value equal to Long.MAX_VALUE is considered to mean that unavailability is permanent.

Parameters
available:long

The new available date/time

setEnabledback to summary
public void setEnabled(boolean enabled)

Sets the enabled attribute for the associated servlet.

Parameters
enabled:boolean

the new value

setLoadOnStartupback to summary
public void setLoadOnStartup(int value)

Set the load-on-startup order value (negative value means load on first call).

Parameters
value:int

New load-on-startup value

setMultipartConfigElementback to summary
public void setMultipartConfigElement(MultipartConfigElement multipartConfig)

Set the multi-part configuration for the associated Servlet. To clear the multi-part configuration specify null as the new value.

Parameters
multipartConfig:MultipartConfigElement

The configuration associated with the Servlet

setOverridableback to summary
public void setOverridable(boolean overridable)

Sets the overridable attribute for this Servlet.

Parameters
overridable:boolean

the new value

setRunAsback to summary
public void setRunAs(String runAs)

Set the run-as identity for this servlet.

Parameters
runAs:String

New run-as identity value

setServletback to summary
public void setServlet(Servlet servlet)

Set the associated Servlet instance

Parameters
servlet:Servlet

The associated Servlet

setServletClassback to summary
public void setServletClass(String servletClass)

Set the fully qualified servlet class name for this servlet.

Parameters
servletClass:String

Servlet class name

unavailableback to summary
public void unavailable(UnavailableException unavailable)

Process an UnavailableException, marking this Servlet as unavailable for the specified amount of time.

Parameters
unavailable:UnavailableException

The exception that occurred, or null to mark this Servlet as permanently unavailable

unloadback to summary
public void unload() throws ServletException

Unload all initialized instances of this servlet, after calling the destroy() method for each instance. This can be used, for example, prior to shutting down the entire servlet engine, or prior to reloading all of the classes from the Loader associated with our Loader's repository.

Exceptions
ServletException:
if an unload error occurs