org.itsnat.core

Interface ItsNatServlet

All Known Subinterfaces:

ItsNatHttpServlet

public interface ItsNatServlet

Is the ItsNat wrapper of the javax.servlet.Servlet object. Bridges the normal servlet infrastructure with ItsNat.

To bridge a standard Servlet with ItsNat call ItsNat.get().createItsNatServlet(this) into the overloaded Servlet.init(ServletConfig) method. This call creates a new ItsNatServlet bound to the standard Servlet.

Use this init method to setup the ItsNatServlet (using ItsNatServletConfig), to register page and fragment templates (calling registerItsNatDocumentTemplate(String,String,Object) and registerItsNatDocFragmentTemplate(String,String,Object)) and to register ItsNat request listeners (ItsNatServletRequestListener).

To redirect normal requests to ItsNat call the method processRequest(javax.servlet.ServletRequest,javax.servlet.ServletResponse).

Author:

Jose Maria Arranz Santamaria

See Also:

HttpServletWrapper

Method Summary

Methods

Modifier and Type	Method and Description
void	addCreateItsNatComponentListener(CreateItsNatComponentListener listener) Adds a new user defined component factory.
void	addEventListener(EventListener listener) Adds a global event listener to this servlet.
void	addItsNatAttachedClientEventListener(ItsNatAttachedClientEventListener listener) Adds a remote control listener to this servlet.
void	addItsNatServletRequestListener(ItsNatServletRequestListener listener) Registers a new ItsNat request listener.
javax.servlet.ServletRequest	createServletRequest(javax.servlet.ServletRequest request, Map<String,String[]> params) Creates a new request object wrapping the provided request object replacing parameters with the provided collection.
ItsNat	getItsNat() Returns the ItsNat "root" object used to create this servlet.
ItsNatDocFragmentTemplate	getItsNatDocFragmentTemplate(String name) Returns the document fragment template registered with the specified name.
ItsNatDocumentTemplate	getItsNatDocumentTemplate(String name) Returns the document template registered with the specified name.
ItsNatServletConfig	getItsNatServletConfig() Returns the utility object used to setup the ItsNat servlet.
ItsNatServletContext	getItsNatServletContext() Returns the ItsNat application context this ItsNat servlet belongs to.
javax.servlet.Servlet	getServlet() Returns the wrapped javax.servlet.Servlet object.
void	processRequest(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response) Called to redirect a normal servlet request to the ItsNat servlet.
ItsNatDocFragmentTemplate	registerItsNatDocFragmentTemplate(String name, String mime, Object source) Registers a markup source to be used as a document fragment template with the specified name and MIME type.
ItsNatDocumentTemplate	registerItsNatDocumentTemplate(String name, String mime, Object source) Registers a markup source to be used as a document template with the specified name and MIME type.
ItsNatDocumentTemplate	registerItsNatDocumentTemplateAttachedServer(String name, String mime) Registers an attached server template with the specified name and MIME type.
void	removeCreateItsNatComponentListener(CreateItsNatComponentListener listener) Removes the specified user defined component factory.
void	removeEventListener(EventListener listener) Removes the specified global event listener.
void	removeItsNatAttachedClientEventListener(ItsNatAttachedClientEventListener listener) Removes the specified remote control listener.
void	removeItsNatServletRequestListener(ItsNatServletRequestListener listener) Unregisters the specified request listener.

Method Detail

getServlet

javax.servlet.Servlet getServlet()

Returns the wrapped javax.servlet.Servlet object.

Returns:

the wrapped servlet object.

getItsNat

ItsNat getItsNat()

Returns the ItsNat "root" object used to create this servlet.

Returns:

the parent ItsNat object.

See Also:

ItsNat.createItsNatServlet(javax.servlet.Servlet)

getItsNatServletConfig

ItsNatServletConfig getItsNatServletConfig()

Returns the utility object used to setup the ItsNat servlet.

Returns:

the configuration object.

getItsNatServletContext

ItsNatServletContext getItsNatServletContext()

Returns the ItsNat application context this ItsNat servlet belongs to.

Returns:

the context object.

See Also:

ItsNat.getItsNatServletContext(javax.servlet.ServletContext)

registerItsNatDocumentTemplate

ItsNatDocumentTemplate registerItsNatDocumentTemplate(String name,
                                                    String mime,
                                                    Object source)

Registers a markup source to be used as a document template with the specified name and MIME type.

The specified MIME type may be different to the "intrinsic" MIME of the specified file. For instance the loaded file may be XHTML (MIME application/xhtml+xml) but it can be registered with HTML MIME (text/html) to achieve the maximum compatibility.

A markup template is a normal (X)HTML, SVG, XUL or XML local or remote file.

Markup source can be a file path, a remote URL (specified as a String) or a TemplateSource object.

Parameters:

name - the name used to identify the template.

mime - the MIME type.

source - the markup source.

Returns:

the document template descriptor.

See Also:

registerItsNatDocFragmentTemplate(String,String,Object), getItsNatDocumentTemplate(String)

registerItsNatDocumentTemplateAttachedServer

ItsNatDocumentTemplate registerItsNatDocumentTemplateAttachedServer(String name,
                                                                  String mime)

Registers an attached server template with the specified name and MIME type.

An attached server template does not need a template file because the client page is sent to the server as the initial template.

Parameters:

name - the name used to identify the template.

mime - the MIME type.

Returns:

the document template descriptor.

See Also:

registerItsNatDocumentTemplate(String,String,Object)

getItsNatDocumentTemplate

ItsNatDocumentTemplate getItsNatDocumentTemplate(String name)

Returns the document template registered with the specified name.

Parameters:

name - the name used to look for.

Returns:

the document template with this name or null if not found.

registerItsNatDocFragmentTemplate

ItsNatDocFragmentTemplate registerItsNatDocFragmentTemplate(String name,
                                                          String mime,
                                                          Object source)

Registers a markup source to be used as a document fragment template with the specified name and MIME type.

The specified MIME type may be different to the "intrinsic" MIME of the specified file. For instance the loaded file may be XHTML (application/xhtml+xml) but it can be registered as HTML (text/html) to achieve the maximum compatibility.

Because the main purpose of document fragments is to be included into documents, you should be use the same HTML (text/html) or XHTML (application/xhtml+xml) MIME as the document target.

A markup template fragment is a normal (X)HTML, SVG, XUL or XML local or remote file. The fragment part is:

1. (X)HTML: the node group below the <head> and <body>. They are two fragments, an <itsnat:include> tag can select the appropriated fragment or using the concrete ItsNatHTMLDocFragmentTemplate method.
2. SVG: the node group below the <svg> element.
3. XUL: the node group below the <window> element.
4. XML: the node group below the document root element. The root element tag can have any name.

Markup source can be a file path, a remote URL (specified as a String) or a TemplateSource object.

Parameters:

name - the name used to identify the template.

mime - the MIME type.

source - the markup source.

Returns:

the fragment template descriptor.

See Also:

registerItsNatDocumentTemplate(String,String,Object), getItsNatDocFragmentTemplate(String)

getItsNatDocFragmentTemplate

ItsNatDocFragmentTemplate getItsNatDocFragmentTemplate(String name)

Returns the document fragment template registered with the specified name.

Parameters:

name - the name used to look for.

Returns:

the document fragment template with this name or null if not found.

addItsNatServletRequestListener

void addItsNatServletRequestListener(ItsNatServletRequestListener listener)

Registers a new ItsNat request listener. This listener is called when this ItsNat servlet receives a new client request.

If an ItsNatDocument is involved, this listener is called before listeners registered in the template. Typical use is for logging, preprocessing, filtering etc.

Parameters:

listener - the listener to register.

See Also:

removeItsNatServletRequestListener(ItsNatServletRequestListener), ItsNatDocumentTemplate.addItsNatServletRequestListener(ItsNatServletRequestListener), processRequest(javax.servlet.ServletRequest,javax.servlet.ServletResponse)

removeItsNatServletRequestListener

void removeItsNatServletRequestListener(ItsNatServletRequestListener listener)

Unregisters the specified request listener.

Parameters:

listener - the request listener to remove.

See Also:

addItsNatServletRequestListener(ItsNatServletRequestListener)

addItsNatAttachedClientEventListener

void addItsNatAttachedClientEventListener(ItsNatAttachedClientEventListener listener)

Adds a remote control listener to this servlet. This listener is called when a remote view/control is requested to control a document loaded using this servlet.

The listener is called before calling the template and document listener counterparts (if defined).

Parameters:

listener - the listener to add.

See Also:

removeItsNatAttachedClientEventListener(ItsNatAttachedClientEventListener), ItsNatDocumentTemplate.addItsNatAttachedClientEventListener(ItsNatAttachedClientEventListener), ItsNatDocument.addItsNatAttachedClientEventListener(ItsNatAttachedClientEventListener)

removeItsNatAttachedClientEventListener

void removeItsNatAttachedClientEventListener(ItsNatAttachedClientEventListener listener)

Removes the specified remote control listener.

Parameters:

listener - the listener to remove.

See Also:

addItsNatAttachedClientEventListener(ItsNatAttachedClientEventListener)

addEventListener

void addEventListener(EventListener listener)

Adds a global event listener to this servlet. This listener is called when any DOM event (standard or extended) is received by this servlet.

The listener is called before calling any DOM event listener registered in templates and documents. This listener registry is passive, in no way the client is modified (no listener is registered on the client) and usually used for monitoring.

Parameters:

listener - the listener to add.

See Also:

removeEventListener(EventListener), ItsNatDocumentTemplate.addEventListener(EventListener), ItsNatDocument.addEventListener(EventListener)

removeEventListener

void removeEventListener(EventListener listener)

Removes the specified global event listener.

Parameters:

listener - the listener to remove.

See Also:

addEventListener(EventListener)

addCreateItsNatComponentListener

void addCreateItsNatComponentListener(CreateItsNatComponentListener listener)

Adds a new user defined component factory. This listener is called when the framework needs to create a component instance.

The listener is called before calling the template listener counterparts (if defined).

Parameters:

listener - the listener factory to register.

See Also:

removeCreateItsNatComponentListener(CreateItsNatComponentListener), ItsNatDocumentTemplate.addCreateItsNatComponentListener(CreateItsNatComponentListener)

removeCreateItsNatComponentListener

void removeCreateItsNatComponentListener(CreateItsNatComponentListener listener)

Removes the specified user defined component factory.

Parameters:

listener - the listener factory to remove.

See Also:

addCreateItsNatComponentListener(CreateItsNatComponentListener)

processRequest

void processRequest(javax.servlet.ServletRequest request,
                  javax.servlet.ServletResponse response)

Called to redirect a normal servlet request to the ItsNat servlet.

ItsNat requests are processed by the registered ItsNatServletRequestListener objects.

Parameters:

request - the standard servlet request.

response - the standard servlet response.

createServletRequest

javax.servlet.ServletRequest createServletRequest(javax.servlet.ServletRequest request,
                                                Map<String,String[]> params)

Creates a new request object wrapping the provided request object replacing parameters with the provided collection.

This method can be used to avoid the problem of read-only parameters of the standard ServletRequest object.

With exception of methods returning parameters, every method call is forwarded to the wrapped ServletRequest object.

In a HTTP environment (the request object to wrap implements HttpServletRequest), the resulting object implements HttpServletRequest.

Parameters:

request - the servlet request object to wrap.

params - a collection with the new parameters.

Returns:

a new request object.