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 java.text.DateFormat;
017: import java.text.NumberFormat;
018: import org.itsnat.core.event.ItsNatServletRequestListener;
019: import org.itsnat.core.event.RemoteControlEventListener;
020: import org.itsnat.comp.CreateItsNatComponentListener;
021:
022: /**
023: * Represents a document (page) template. Concrete documents are created
024: * using this template.
025: *
026: * @see ItsNatServlet#registerDocumentTemplate(String,String,String)
027: * @see ItsNatServlet#getDocumentTemplate(String)
028: * @author Jose Maria Arranz Santamaria
029: */
030: public interface DocumentTemplate extends MarkupTemplate {
031: /**
032: * Returns the default synchronous mode of AJAX events.
033: *
034: * <p>This feature only affects to (X)HTML documents.</p>
035: *
036: * <p>The default value is defined by {@link ItsNatServletConfig#getDefaultSyncMode()}</p>
037: *
038: * @return the synchronous mode.
039: * @see #setDefaultSyncMode(int)
040: * @see SyncMode
041: */
042: public int getDefaultSyncMode();
043:
044: /**
045: * Sets the default synchronous mode of AJAX events.
046: *
047: * @param syncMode the new synchronous mode.
048: * @see #getDefaultSyncMode()
049: */
050: public void setDefaultSyncMode(int syncMode);
051:
052: /**
053: * Returns the default timeout of asynchronous AJAX events.
054: *
055: * <p>This feature only affects to (X)HTML documents
056: * and is ignored in synchronous AJAX events</p>
057: *
058: * <p>When an unfinished AJAX request takes more time than the specified timeout,
059: * the request is aborted.</p>
060: *
061: * <p>The default value is defined by {@link ItsNatServletConfig#getAJAXTimeout()}</p>
062: *
063: * @return the timeout of asynchronous AJAX events in miliseconds.
064: * @see #setAJAXTimeout(long)
065: */
066: public long getAJAXTimeout();
067:
068: /**
069: * Sets the default timeout of asynchronous AJAX events.
070: *
071: * @param timeout the new timeout. If negative no timeout is defined.
072: * @see #getAJAXTimeout()
073: */
074: public void setAJAXTimeout(long timeout);
075:
076: /**
077: * Returns whether JavaScript code and/or markup sent to the client is
078: * automatically compressed if the browser accepts this encoding.
079: *
080: * <p>The default value is defined by {@link ItsNatServletConfig#getUseGZip()}</p>
081: *
082: * @return the bitwise value containing whether gzip is used to encode JavaScript code and/or markup.
083: * @see #setUseGZip(int)
084: */
085: public int getUseGZip();
086:
087: /**
088: * Sets whether JavaScript code and/or markup sent to the client is
089: * automatically compressed if the browser accepts this encoding.
090: *
091: * <p>A bitwise value must be used using {@link UseGZip} constants, for instance:
092: * setUseGZip(UseGZip.MARKUP | UseGZip.SCRIPT).</p>
093: *
094: *
095: * @param value a bitwise value.
096: * @see #getUseGZip()
097: * @see UseGZip
098: */
099: public void setUseGZip(int value);
100:
101: /**
102: * Informs whether the initial JavaScript code is sent inline into the loaded page
103: * or is loaded externally.
104: *
105: * <p>This feature only affects to (X)HTML documents.</p>
106: *
107: * <p>The default value is defined by {@link ItsNatServletConfig#isLoadScriptInline()}</p>
108: *
109: * @return true if fast mode is enabled.
110: * @see #setLoadScriptInline(boolean)
111: */
112: public boolean isLoadScriptInline();
113:
114: /**
115: * Sets the initial JavaScript code is sent inline into the loaded page
116: * or is loaded externally.
117: *
118: * @param value true to sent inline.
119: * @see #isLoadScriptInline()
120: */
121: public void setLoadScriptInline(boolean value);
122:
123: /**
124: * Informs whether the fast load mode is enabled.
125: *
126: * <p>This feature only affects to (X)HTML documents.</p>
127: *
128: * <p>The default value is defined by {@link ItsNatServletConfig#isFastLoadMode()}</p>
129: *
130: * @return true if fast mode is enabled.
131: * @see #setFastLoadMode(boolean)
132: */
133: public boolean isFastLoadMode();
134:
135: /**
136: * Sets whether fast load mode is used.
137: *
138: * @param fastLoadMode true to enable fast load.
139: * @see #isFastLoadMode()
140: */
141: public void setFastLoadMode(boolean fastLoadMode);
142:
143: /**
144: * Informs whether the speed oriented node cache is enabled.
145: *
146: * <p>This feature only affects to (X)HTML documents.</p>
147: *
148: * <p>The default value is defined by {@link ItsNatServletConfig#isNodeCacheEnabled()}</p>
149: *
150: * @return true if node cache is enabled.
151: * @see #setNodeCacheEnabled(boolean)
152: */
153: public boolean isNodeCacheEnabled();
154:
155: /**
156: * Sets whether the speed oriented node cache is enabled.
157: *
158: * @param enable true to enable node cache.
159: * @see #isNodeCacheEnabled()
160: */
161: public void setNodeCacheEnabled(boolean enable);
162:
163: /**
164: * Informs whether components are build automatically using the necessary
165: * markup declarations.
166: *
167: * <p>If this feature is enabled any component registered
168: * into the component manager and associated to a DOM element
169: * being removed from the tree is removed and disposed automatically.</p>
170: *
171: * <p>The default value is defined by {@link ItsNatServletConfig#isAutoBuildComponents()}</p>
172: *
173: * @return true if automatic component build is enabled.
174: * @see #setAutoBuildComponents(boolean)
175: */
176: public boolean isAutoBuildComponents();
177:
178: /**
179: * Sets whether components are build automatically using the necessary
180: * markup declarations.
181: *
182: * @param value true to enable automatic component build.
183: * @see #isAutoBuildComponents()
184: */
185: public void setAutoBuildComponents(boolean value);
186:
187: /**
188: * Informs whether dom utils and components use by default the original
189: * (saved as pattern) markup to render.
190: *
191: * <p>The default value is defined by {@link ItsNatServletConfig#isUsePatternMarkupToRender()}</p>
192: *
193: * @return true if by default the original markup is used.
194: * @see #setUsePatternMarkupToRender(boolean)
195: */
196: public boolean isUsePatternMarkupToRender();
197:
198: /**
199: * Sets whether dom utils and components use by default the original
200: * (saved as pattern) markup to render.
201: *
202: * @param value true to enable the use of original markup to render.
203: * @see #isUsePatternMarkupToRender()
204: */
205: public void setUsePatternMarkupToRender(boolean value);
206:
207: /**
208: * Informs whether the necessary framework JavaScript files are included
209: * into the page automatically.
210: *
211: * <p>This feature only affects to (X)HTML documents.</p>
212: *
213: * <p>The default value is defined by {@link ItsNatServletConfig#isAddFrameworkScriptFiles()}</p>
214: *
215: * @return true if framework files are included automatically.
216: * @see #setAddFrameworkScriptFiles(boolean)
217: */
218: public boolean isAddFrameworkScriptFiles();
219:
220: /**
221: * Sets whether the necessary framework JavaScript files are included
222: * into the page automatically.
223: *
224: * @param value true to include the framework files automatically.
225: * @see #isAddFrameworkScriptFiles()
226: */
227: public void setAddFrameworkScriptFiles(boolean value);
228:
229: /**
230: * Returns the relative web path directory where the necessary framework JavaScript files are located.
231: * This path only has sense if framework files are included automatically.
232: *
233: * <p>For instance: is the path is "js" framework files must be located in:
234: * http://<host>:<port>/<app>/js</p>
235: *
236: * <p>This feature only affects to (X)HTML documents.</p>
237: *
238: * <p>The default value is defined by {@link ItsNatServletConfig#getFrameworkScriptFilesBasePath()}</p>
239: *
240: * @return the relative web path of framework files.
241: * @see #isAddFrameworkScriptFiles()
242: * @see #setFrameworkScriptFilesBasePath(String)
243: */
244: public String getFrameworkScriptFilesBasePath();
245:
246: /**
247: * Returns the relative web path where the necessary framework JavaScript files are located.
248: * This path only has sense if framework files are included automatically.
249: *
250: * @param path the relative web path of framework files.
251: * @see #isAddFrameworkScriptFiles()
252: */
253: public void setFrameworkScriptFilesBasePath(String path);
254:
255: /**
256: * Returns the default data format used by components such as
257: * {@link org.itsnat.comp.html.ItsNatHTMLInputTextFormatted}.
258: *
259: * <p>The default value is defined by {@link ItsNatServletConfig#getDefaultDateFormat()}</p>
260: *
261: * @return the default date format.
262: * @see #setDefaultDateFormat(DateFormat)
263: */
264: public DateFormat getDefaultDateFormat();
265:
266: /**
267: * Sets the default data format used by components such as
268: * {@link org.itsnat.comp.html.ItsNatHTMLInputTextFormatted}.
269: *
270: * @param format the default data format.
271: * @see #getDefaultDateFormat()
272: */
273: public void setDefaultDateFormat(DateFormat format);
274:
275: /**
276: * Returns the default number format used by components such as
277: * {@link org.itsnat.comp.html.ItsNatHTMLInputTextFormatted}.
278: *
279: * <p>The default value is defined by {@link ItsNatServletConfig#getDefaultNumberFormat()}</p>
280: *
281: * @return the default data format.
282: * @see #setDefaultNumberFormat(NumberFormat)
283: */
284: public NumberFormat getDefaultNumberFormat();
285:
286: /**
287: * Sets the default data format used by components such as
288: * {@link org.itsnat.comp.html.ItsNatHTMLInputTextFormatted}.
289: *
290: * @param format the default data format.
291: * @see #getDefaultNumberFormat()
292: */
293: public void setDefaultNumberFormat(NumberFormat format);
294:
295: /**
296: * Returns the default max wait until a server fired event with
297: * {@link ItsNatDocument#dispatchEvent(org.w3c.dom.events.EventTarget,org.w3c.dom.events.Event)}
298: * is processed by the client and returns.
299: *
300: * <p>This feature only affects to (X)HTML documents.</p>
301: *
302: * <p>The default value is defined by {@link ItsNatServletConfig#getEventDispatcherMaxWait()}</p>
303: *
304: * @return the default max wait in milliseconds.
305: * @see #setEventDispatcherMaxWait(long)
306: * @see ItsNatDocument#getItsNatNode(org.w3c.dom.Node)
307: */
308: public long getEventDispatcherMaxWait();
309:
310: /**
311: * Sets the default max wait until a server fired event with
312: * {@link ItsNatDocument#dispatchEvent(org.w3c.dom.events.EventTarget,org.w3c.dom.events.Event)}
313: * is processed by the client and returns.
314: *
315: * @param wait the default max wait in milliseconds.
316: * @see #getEventDispatcherMaxWait()
317: */
318: public void setEventDispatcherMaxWait(long wait);
319:
320: /**
321: * Informs whether referrer feature is enabled by default.
322: *
323: * <p>The default value is defined by {@link ItsNatServletConfig#isReferrerEnabled()}</p>
324: *
325: * <p>This feature only affects to (X)HTML documents (because requires AJAX).</p>
326: *
327: * <p>This feature only works if AJAX is enabled.</p>
328: *
329: * @return true if referrer is enabled.
330: * @see #setReferrerEnabled(boolean)
331: * @see #isAJAXEnabled()
332: * @see ItsNatServletRequest#getItsNatDocumentReferrer()
333: */
334: public boolean isReferrerEnabled();
335:
336: /**
337: * Sets whether referrer feature is enabled by default.
338: *
339: * @param enabled if referrer is enabled.
340: * @see #isReferrerEnabled()
341: */
342: public void setReferrerEnabled(boolean enabled);
343:
344: /**
345: * Informs whether referrer "push" feature is enabled by default.
346: *
347: * <p>The default value is defined by {@link ItsNatServletConfig#isReferrerPushEnabled()}</p>
348: *
349: * @return true if referrer "push" is enabled, if false documents created with this template can not be accessed by the referrer.
350: * @see #setReferrerPushEnabled(boolean)
351: * @see #isReferrerEnabled()
352: * @see ItsNatDocument#addReferrerItsNatServletRequestListener(ItsNatServletRequestListener)
353: */
354: public boolean isReferrerPushEnabled();
355:
356: /**
357: * Sets whether referrer "push" feature is enabled by default.
358: *
359: * @param enabled if referrer "push" is enabled.
360: * @see #isReferrerPushEnabled()
361: */
362: public void setReferrerPushEnabled(boolean enabled);
363:
364: /**
365: * Informs whether AJAX events are enabled.
366: *
367: * <p>The default value is defined by {@link ItsNatServletConfig#isAJAXEnabled()}</p>
368: *
369: * <p>This feature only affects to (X)HTML documents.</p>
370: *
371: * @return true if AJAX is enabled.
372: * @see #setAJAXEnabled(boolean)
373: */
374: public boolean isAJAXEnabled();
375:
376: /**
377: * Sets whether AJAX events are enabled.
378: *
379: * @param enabled if AJAX is enabled.
380: * @see #isAJAXEnabled()
381: */
382: public void setAJAXEnabled(boolean enabled);
383:
384: /**
385: * Informs whether JavaScript is enabled.
386: *
387: * <p>The default value is defined by {@link ItsNatServletConfig#isScriptingEnabled()}</p>
388: *
389: * <p>This feature only affects to (X)HTML documents.</p>
390: *
391: * @return true if AJAX is enabled.
392: * @see #setScriptingEnabled(boolean)
393: */
394: public boolean isScriptingEnabled();
395:
396: /**
397: * Sets whether JavaScript is enabled.
398: *
399: * <p>If JavaScript is disabled then AJAX is disabled too.</p>
400: *
401: * @param enabled if JavaScript is enabled.
402: * @see #isScriptingEnabled()
403: * @see #setAJAXEnabled(boolean)
404: */
405: public void setScriptingEnabled(boolean enabled);
406:
407: /**
408: * Informs whether the auto clean event listeners mode is enabled.
409: *
410: * <p>The default value is defined by {@link ItsNatServletConfig#isAutoCleanEventListeners()}</p>
411: *
412: * <p>This feature only affects to (X)HTML documents.</p>
413: *
414: * @return true if enabled.
415: * @see #setAutoCleanEventListeners(boolean)
416: */
417: public boolean isAutoCleanEventListeners();
418:
419: /**
420: * Sets whether the auto clean event listeners mode is enabled.
421: *
422: * @param enabled if auto clean event listeners is enabled.
423: * @see #isAutoCleanEventListeners()
424: */
425: public void setAutoCleanEventListeners(boolean enabled);
426:
427: /**
428: * Registers a new ItsNat request listener. This listener is called when the framework loads
429: * a new requested document using this template or an AJAX event is received
430: * with a document target loaded by this template.
431: *
432: * @param listener the listener register.
433: * @see #removeItsNatServletRequestListener(ItsNatServletRequestListener)
434: * @see ItsNatServlet#addItsNatServletRequestListener(ItsNatServletRequestListener)
435: */
436: public void addItsNatServletRequestListener(
437: ItsNatServletRequestListener listener);
438:
439: /**
440: * Unregisters the specified user defined request listener.
441: *
442: * @param listener the request listener to remove.
443: * @see #addItsNatServletRequestListener(ItsNatServletRequestListener)
444: */
445: public void removeItsNatServletRequestListener(
446: ItsNatServletRequestListener listener);
447:
448: /**
449: * Adds a remote control listener to this template. This listener is called when a remote view/control
450: * is requested to control a document loaded using this template.
451: *
452: * <p>The listener is called <i>before</i> calling the document registered listener counterparts (if defined).</p>
453: *
454: * @param listener the listener to add.
455: * @see #removeRemoteControlEventListener(RemoteControlEventListener)
456: * @see ItsNatServlet#addRemoteControlEventListener(RemoteControlEventListener)
457: * @see ItsNatDocument#addRemoteControlEventListener(RemoteControlEventListener)
458: */
459: public void addRemoteControlEventListener(
460: RemoteControlEventListener listener);
461:
462: /**
463: * Removes the specified remote control listener.
464: *
465: * @param listener the listener to remove.
466: * @see #addRemoteControlEventListener(RemoteControlEventListener)
467: */
468: public void removeRemoteControlEventListener(
469: RemoteControlEventListener listener);
470:
471: /**
472: * Adds a new user defined component factory. This listener is called when the framework needs
473: * to create a component instance.
474: *
475: * @param listener the listener factory to register.
476: * @see #removeCreateItsNatComponentListener(CreateItsNatComponentListener)
477: * @see ItsNatServlet#addCreateItsNatComponentListener(CreateItsNatComponentListener)
478: */
479: public void addCreateItsNatComponentListener(
480: CreateItsNatComponentListener listener);
481:
482: /**
483: * Removes the specified user defined component factory.
484: *
485: * @param listener the listener factory to remove.
486: * @see #addCreateItsNatComponentListener(CreateItsNatComponentListener)
487: */
488: public void removeCreateItsNatComponentListener(
489: CreateItsNatComponentListener listener);
490:
491: /**
492: * Registers an artifact with the specified name.
493: *
494: * @param name the artifact name
495: * @param value the artifact.
496: * @see #getArtifact(String)
497: * @see #removeArtifact(String)
498: * @see org.itsnat.core.NameValue
499: */
500: public void registerArtifact(String name, Object value);
501:
502: /**
503: * Returns the artifact with the specified name.
504: *
505: * @param name the artifact name to look for.
506: * @return the artifact or null if not found.
507: * @see #registerArtifact(String,Object)
508: * @see #getArtifact(String,boolean)
509: */
510: public Object getArtifact(String name);
511:
512: /**
513: * Removes the artifact with the specified name.
514: *
515: * @param name the artifact name to look for.
516: * @return the removed artifact.
517: * @see #registerArtifact(String,Object)
518: */
519: public Object removeArtifact(String name);
520:
521: /**
522: * Returns the artifact with the specified name.
523: *
524: * <p>If no artifact is found and <code>cascade</code> is true,
525: * the method {@link ItsNatServletConfig#getArtifact(String)}
526: * is called to continue searching.</p>
527: *
528: * @param name the artifact name to look for.
529: * @return the artifact or null if not found.
530: * @see #getArtifact(String)
531: */
532: public Object getArtifact(String name, boolean cascade);
533: }
|