001: /*
002: ItsNat Java Web Application Framework
003: Copyright (C) 2007 Innowhere Software Services S.L., Spanish Company
004: Author: Jose Maria Arranz Santamaria
005:
006: This program is free software: you can redistribute it and/or modify
007: it under the terms of the GNU Affero General Public License as published by
008: the Free Software Foundation, either version 3 of the License, or
009: (at your option) any later version. See the GNU Affero General Public
010: License for more details. See the copy of the GNU Affero General Public License
011: included in this program. If not, see <http://www.gnu.org/licenses/>.
012: */
013:
014: package org.itsnat.core;
015:
016: import org.itsnat.core.event.ItsNatServletRequestListener;
017: import org.itsnat.core.event.RemoteControlEventListener;
018: import javax.servlet.Servlet;
019: import javax.servlet.ServletRequest;
020: import javax.servlet.ServletResponse;
021: import org.itsnat.comp.CreateItsNatComponentListener;
022:
023: /**
024: * Is the ItsNat wrapper of the <code>javax.servlet.Servlet</code> object.
025: * Bridges the normal servlet infrastructure with ItsNat.
026: *
027: * <p>To bridge a standard Servlet with ItsNat call <code>ItsNat.get().createItsNatServlet(this)</code>
028: * into the overloaded <code>Servlet.init(ServletConfig)</code> method.
029: * This call creates a new ItsNatServlet bound to the standard Servlet.
030: * </p>
031: *
032: * <p>Use this <code>init</code> method to setup the ItsNatServlet
033: * (using {@link ItsNatServletConfig}), to register page and fragment templates
034: * (calling {@link #registerDocumentTemplate(String,String,String)} and
035: * {@link #registerDocFragmentTemplate(String,String,String)}) and
036: * to register ItsNat request listeners ({@link ItsNatServletRequestListener}).
037: * </p>
038: *
039: * <p>To redirect normal requests to ItsNat call the method
040: * {@link #processRequest(javax.servlet.ServletRequest,javax.servlet.ServletResponse)}.</p>
041: *
042: * @author Jose Maria Arranz Santamaria
043: * @see org.itsnat.core.http.HttpServletWrapper
044: */
045: public interface ItsNatServlet {
046: /**
047: * Returns the wrapped <code>javax.servlet.Servlet</code> object.
048: *
049: * @return the wrapped servlet object.
050: */
051: public Servlet getServlet();
052:
053: /**
054: * Returns the ItsNat "root" object used to create this servlet.
055: *
056: * @return the parent ItsNat object.
057: * @see ItsNat#createItsNatServlet(javax.servlet.Servlet)
058: */
059: public ItsNat getItsNat();
060:
061: /**
062: * Returns the utility object used to setup the ItsNat servlet.
063: *
064: * @return the configuration object.
065: */
066: public ItsNatServletConfig getItsNatServletConfig();
067:
068: /**
069: * Returns the ItsNat application context this ItsNat servlet belongs to.
070: *
071: * @return the context object.
072: */
073: public ItsNatServletContext getItsNatServletContext();
074:
075: /**
076: * Registers a file used as a document template with the specified name and MIME type.
077: *
078: * <p>The specified MIME type may be different to the "intrinsic" MIME of the specified
079: * file. For instance the loaded file may be XHTML (application/xhtml+xml) but
080: * it can be registered as HTML (text/html) to achieve the maximum compatibility.</p>
081: *
082: * A markup template file is a normal (X)HTML or XML file.
083: *
084: * @param name the name used to identify the template.
085: * @param mime the MIME type.
086: * @param path the file path of the template.
087: * @see #registerDocFragmentTemplate(String,String,String)
088: * @see #getDocumentTemplate(String)
089: */
090: public DocumentTemplate registerDocumentTemplate(String name,
091: String mime, String path);
092:
093: /**
094: * Returns the document template registered with the specified name.
095: *
096: * @param name the name used to look for.
097: * @return the document template with this name or null if not found.
098: */
099: public DocumentTemplate getDocumentTemplate(String name);
100:
101: /**
102: * Registers a file used as a document fragment template with the specified name and MIME type.
103: *
104: * <p>The specified MIME type may be different to the "intrinsic" MIME of the specified
105: * file. For instance the loaded file may be XHTML (application/xhtml+xml) but
106: * it can be registered as HTML (text/html) to achieve the maximum compatibility.</p>
107: *
108: * <p>A markup template file is a normal (X)HTML or XML file. The fragment part is:</p>
109: *
110: * <ol>
111: * <li>(X)HTML: the node group below the <head> and <body>. They are two fragments,
112: * an <itsnat:include> tag can select the appropriated fragment or using
113: * the concrete {@link org.itsnat.core.html.HTMLDocFragmentTemplate} method.
114: * </li>
115: * <li>XML: the node group below the root element. The root element tag can have any name.</li>
116: * </ol>
117: *
118: * @param name the name used to identify the template.
119: * @param mime the MIME type.
120: * @param path the file path of the template.
121: * @see #registerDocumentTemplate(String,String,String)
122: * @see #getDocFragmentTemplate(String)
123: */
124: public DocFragmentTemplate registerDocFragmentTemplate(String name,
125: String mime, String path);
126:
127: /**
128: * Returns the document fragment template registered with the specified name.
129: *
130: * @param name the name used to look for.
131: * @return the document fragment template with this name or null if not found.
132: */
133: public DocFragmentTemplate getDocFragmentTemplate(String name);
134:
135: /**
136: * Registers a new ItsNat request listener. This listener is called when this ItsNat servlet receives
137: * a new client request.
138: *
139: * <p>If an ItsNatDocument is involved, this listener is called before listeners registered in the template.
140: * Typical use is for logging, preprocessing, filtering etc.</p>
141: *
142: * @param listener the listener to register.
143: * @see #removeItsNatServletRequestListener(ItsNatServletRequestListener)
144: * @see DocumentTemplate#addItsNatServletRequestListener(ItsNatServletRequestListener)
145: * @see #processRequest(javax.servlet.ServletRequest,javax.servlet.ServletResponse)
146: */
147: public void addItsNatServletRequestListener(
148: ItsNatServletRequestListener listener);
149:
150: /**
151: * Unregisters the specified request listener.
152: *
153: * @param listener the request listener to remove.
154: * @see #addItsNatServletRequestListener(ItsNatServletRequestListener)
155: */
156: public void removeItsNatServletRequestListener(
157: ItsNatServletRequestListener listener);
158:
159: /**
160: * Adds a remote control listener to this servlet. This listener is called when a remote view/control
161: * is requested to control a document loaded using this servlet.
162: *
163: * <p>The listener is called <i>before</i> calling the template and document listener counterparts (if defined).</p>
164: *
165: * @param listener the listener to add.
166: * @see #removeRemoteControlEventListener(RemoteControlEventListener)
167: * @see DocumentTemplate#addRemoteControlEventListener(RemoteControlEventListener)
168: * @see ItsNatDocument#addRemoteControlEventListener(RemoteControlEventListener)
169: */
170: public void addRemoteControlEventListener(
171: RemoteControlEventListener listener);
172:
173: /**
174: * Removes the specified remote control listener.
175: *
176: * @param listener the listener to remove.
177: * @see #addRemoteControlEventListener(RemoteControlEventListener)
178: */
179: public void removeRemoteControlEventListener(
180: RemoteControlEventListener listener);
181:
182: /**
183: * Adds a new user defined component factory. This listener is called when the framework needs
184: * to create a component instance.
185: *
186: * <p>The listener is called <i>before</i> calling the template listener counterparts (if defined).</p>
187: *
188: * @param listener the listener factory to register.
189: * @see #removeCreateItsNatComponentListener(CreateItsNatComponentListener)
190: * @see DocumentTemplate#addCreateItsNatComponentListener(CreateItsNatComponentListener)
191: */
192: public void addCreateItsNatComponentListener(
193: CreateItsNatComponentListener listener);
194:
195: /**
196: * Removes the specified user defined component factory.
197: *
198: * @param listener the listener factory to remove.
199: * @see #addCreateItsNatComponentListener(CreateItsNatComponentListener)
200: */
201: public void removeCreateItsNatComponentListener(
202: CreateItsNatComponentListener listener);
203:
204: /**
205: * Called to redirect a normal servlet request to the ItsNat servlet.
206: *
207: * <p>ItsNat requests are processed by the registered {@link ItsNatServletRequestListener} objects.</p>
208: *
209: * @param request the standard servlet request.
210: * @param response the standard servlet response.
211: */
212: public void processRequest(ServletRequest request,
213: ServletResponse response);
214: }
|