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.comp;
015:
016: import javax.swing.ButtonGroup;
017: import org.itsnat.comp.free.ItsNatFreeButtonNormal;
018: import org.itsnat.comp.free.ItsNatFreeButtonNormalLabel;
019: import org.itsnat.comp.free.ItsNatFreeCheckBox;
020: import org.itsnat.comp.free.ItsNatFreeCheckBoxLabel;
021: import org.itsnat.comp.free.ItsNatFreeComboBox;
022: import org.itsnat.comp.free.ItsNatFreeInclude;
023: import org.itsnat.comp.free.ItsNatFreeLabel;
024: import org.itsnat.comp.free.ItsNatFreeListMultSel;
025: import org.itsnat.comp.free.ItsNatFreeRadioButton;
026: import org.itsnat.comp.free.ItsNatFreeRadioButtonLabel;
027: import org.itsnat.comp.free.ItsNatFreeTable;
028: import org.itsnat.comp.free.ItsNatFreeTree;
029: import org.itsnat.core.ItsNatDocument;
030: import org.itsnat.core.NameValue;
031: import org.w3c.dom.Element;
032: import org.w3c.dom.Node;
033:
034: /**
035: * Utility interface to manage (create, register etc) ItsNat components of
036: * the associated {@link ItsNatDocument}.
037: *
038: * @author Jose Maria Arranz Santamaria
039: * @see ItsNatDocument#getItsNatComponentManager()
040: */
041: public interface ItsNatComponentManager {
042: /**
043: * Returns the associated ItsNat document (parent of this object).
044: *
045: * @return the associated ItsNat document.
046: */
047: public ItsNatDocument getItsNatDocument();
048:
049: /**
050: * Returns the ItsNat button group with the specified name.
051: *
052: * @param name the button group name to search for.
053: * @return the ItsNat button group, if not found a new one is registered and returned.
054: * @see #getItsNatButtonGroup(javax.swing.ButtonGroup)
055: */
056: public ItsNatButtonGroup getItsNatButtonGroup(String name);
057:
058: /**
059: * Returns the ItsNat button group with the specified Swing button group.
060: *
061: * @param group the Swing button group to search for.
062: * @return the ItsNat button group, if not found a new one is registered and returned.
063: * @see #getItsNatButtonGroup(String)
064: */
065: public ItsNatButtonGroup getItsNatButtonGroup(ButtonGroup group);
066:
067: /**
068: * Creates a new ItsNat button group with a generated name and a new <code>javax.swing.ButtonGroup</code>.
069: *
070: * <p>Generated name is unique per document.</p>
071: *
072: * @return a new ItsNat button group.
073: */
074: public ItsNatButtonGroup createItsNatButtonGroup();
075:
076: /**
077: * Creates a new component object associated to the specified node.
078: *
079: * <p>All registered {@link CreateItsNatComponentListener} listeners are used
080: * to create the component.</p>
081: *
082: * @param node the node to associate the new component.
083: * @param compType the component type, if null the type is obtained from the node.
084: * @param artifacts declared artifacts, may be null.
085: * @return the new component, is null if no component can be created with the submitted parameters.
086: * @see org.itsnat.core.DocumentTemplate#addCreateItsNatComponentListener(CreateItsNatComponentListener)
087: */
088: public ItsNatComponent createItsNatComponent(Node node,
089: String compType, NameValue[] artifacts);
090:
091: /**
092: * Creates a new component object associated to the specified node.
093: *
094: * <p>Current implementation calls:</p>
095: * <blockquote><pre>
096: * return createItsNatComponent(node,null,null);
097: * </pre></blockquote>
098: *
099: *
100: * @param node the node to associate the new component.
101: * @return the new component, is null if no component can be created.
102: * @see #createItsNatComponent(org.w3c.dom.Node,String,NameValue[])
103: */
104: public ItsNatComponent createItsNatComponent(Node node);
105:
106: /**
107: * Creates a new component object associated to the node with the specified id attribute.
108: *
109: * <p>Current implementation calls:</p>
110: * <blockquote><pre>
111: * return createItsNatComponentById(id,null,null);
112: * </pre></blockquote>
113: *
114: *
115: * @param id the attribute id of the node to associate the new component.
116: * @return the new component, is null if no component can be created.
117: * @see #createItsNatComponentById(String,String,NameValue[])
118: */
119: public ItsNatComponent createItsNatComponentById(String id);
120:
121: /**
122: * Creates a new component object associated to the node with the specified id attribute.
123: *
124: * <p>Current implementation:</p>
125: * <blockquote><pre>
126: * Document doc = getItsNatDocument().getDocument();
127: * Element node = doc.getElementById(id);
128: * return createItsNatComponent(node,compType,artifacts);
129: * </pre></blockquote>
130: *
131: *
132: * @param id the attribute id of the node to associate the new component.
133: * @param compType the component type, if null the type is obtained from the node.
134: * @param artifacts declared artifacts, may be null.
135: * @return the new component, is null if no component can be created.
136: * @see #createItsNatComponent(org.w3c.dom.Node,String,NameValue[])
137: */
138: public ItsNatComponent createItsNatComponentById(String id,
139: String compType, NameValue[] artifacts);
140:
141: /**
142: * Creates and adds to the manager registry a new component object associated to the specified node.
143: *
144: * <p>Component creation is delegated to the method {@link #createItsNatComponent(org.w3c.dom.Node,String,NameValue[])},
145: * if no component can be created nothing is registered.</p>
146: *
147: * <p>If the node specified was registered as excluded calling
148: * {@link #addExcludedNodeAsItsNatComponent(org.w3c.dom.Node)} no component is created and registered.</p>
149: *
150: *
151: * @param node the node to associate the new component.
152: * @param compType the component type, if null the type is obtained from the node.
153: * @param artifacts declared artifacts, may be null.
154: * @return the new component, is null if no component can be created with the submitted parameters.
155: * @see #addItsNatComponent(ItsNatComponent)
156: */
157: public ItsNatComponent addItsNatComponent(Node node,
158: String compType, NameValue[] artifacts);
159:
160: /**
161: * Creates and adds to the manager registry a new component object associated to the specified node.
162: *
163: * <p>Current implementation calls:</p>
164: * <blockquote><pre>
165: * return addItsNatComponent(node,null,null);
166: * </pre></blockquote>
167: *
168: * @param node the node to associate the new component.
169: * @return the new component, is null if no component can be created with the submitted parameters.
170: * @see #addItsNatComponent(org.w3c.dom.Node,String,NameValue[])
171: */
172: public ItsNatComponent addItsNatComponent(Node node);
173:
174: /**
175: * Creates and adds to the manager registry a new component object associated to the node with the specified id attribute.
176: *
177: * <p>Current implementation calls:</p>
178: * <blockquote><pre>
179: * return addItsNatComponentById(id,null,null);
180: * </pre></blockquote>
181: *
182: *
183: * @param id the attribute id of the node to associate the new component.
184: * @return the new component, is null if no component can be created with the submitted parameters.
185: * @see #addItsNatComponentById(String,String,NameValue[])
186: */
187: public ItsNatComponent addItsNatComponentById(String id);
188:
189: /**
190: * Creates and adds to the manager registry a new component object associated to the node with the specified id attribute.
191: *
192: * <p>Current implementation:</p>
193: * <blockquote><pre>
194: * Document doc = getItsNatDocument().getDocument();
195: * Element node = doc.getElementById(id);
196: * return addItsNatComponent(node,compType,artifacts);
197: * </pre></blockquote>
198: *
199: *
200: * @param id the attribute id of the node to associate the new component.
201: * @param compType the component type, if null the type is obtained from the node.
202: * @param artifacts declared artifacts, may be null.
203: * @return the new component, is null if no component can be created with the submitted parameters.
204: * @see #addItsNatComponent(org.w3c.dom.Node,String,NameValue[])
205: */
206: public ItsNatComponent addItsNatComponentById(String id,
207: String compType, NameValue[] artifacts);
208:
209: /**
210: * Adds to the manager registry the specified component object.
211: *
212: * <p>This method ignores the "excluded registry".</p>
213: *
214: *
215: * @param comp the component to register.
216: * @see #addItsNatComponent(org.w3c.dom.Node,String,NameValue[])
217: * @see #addExcludedNodeAsItsNatComponent(org.w3c.dom.Node)
218: */
219: public void addItsNatComponent(ItsNatComponent comp);
220:
221: /**
222: * Returns the registered component associated to the node which id attribute is specified.
223: *
224: * <p>Current implementation:</p>
225: * <blockquote><pre>
226: * Document doc = getItsNatDocument().getDocument();
227: * Element node = doc.getElementById(id);
228: * return findItsNatComponent(node);
229: * </pre></blockquote>
230: *
231: * @param id the attribute id of the node to search.
232: * @return the component associated to the specified node or null if not found.
233: * @see #findItsNatComponent(org.w3c.dom.Node)
234: */
235: public ItsNatComponent findItsNatComponentById(String id);
236:
237: /**
238: * Returns the registered component associated to the specified node.
239: *
240: * @param node the node the search the associated component.
241: * @return the component associated to the specified node or null if not found.
242: * @see #addItsNatComponent(org.w3c.dom.Node)
243: */
244: public ItsNatComponent findItsNatComponent(Node node);
245:
246: /**
247: * Unregisters the component associated to the specified node.
248: *
249: * @param node the node the search the associated component.
250: * @return the component associated to the specified node or null if not found.
251: * @see #findItsNatComponent(org.w3c.dom.Node)
252: */
253: public ItsNatComponent removeItsNatComponent(Node node);
254:
255: /**
256: * Unregisters the component associated to the node specified by the id attribute.
257: *
258: * <p>Current implementation:</p>
259: * <blockquote><pre>
260: * Document doc = getItsNatDocument().getDocument();
261: * Element node = doc.getElementById(id);
262: * return removeItsNatComponent(node);
263: * </pre></blockquote>
264: *
265: * @param id the attribute id of the node to search.
266: * @return the component associated to the specified node or null if not found.
267: * @see #removeItsNatComponent(org.w3c.dom.Node)
268: */
269: public ItsNatComponent removeItsNatComponent(String id);
270:
271: /**
272: * Registers the specified node in the excluded registry.
273: *
274: * <p>No component is created and registered with {@link #addItsNatComponent(org.w3c.dom.Node,String,NameValue[])}
275: * if the specified node is in the excluded registry.</p>
276: *
277: *
278: * @param node the node to exclude.
279: */
280: public void addExcludedNodeAsItsNatComponent(Node node);
281:
282: /**
283: * Removes the specified node from the excluded registry.
284: *
285: * @param node the node to exclude.
286: * @see #addExcludedNodeAsItsNatComponent(org.w3c.dom.Node)
287: */
288: public void removeExcludedNodeAsItsNatComponent(Node node);
289:
290: /**
291: * Informs whether the specified node is in the excluded registry.
292: *
293: * @param node the node to search for.
294: * @see #addExcludedNodeAsItsNatComponent(org.w3c.dom.Node)
295: */
296: public boolean isExcludedNodeAsItsNatComponent(Node node);
297:
298: /**
299: * Navigates recursively the subtree below the specified node (included) and for every node tries
300: * to create and register the built-in component associated to the node.
301: *
302: * @param node the node parent of the subtree.
303: * @return an array with the components created and registered.
304: * @see #buildItsNatComponents()
305: * @see #removeItsNatComponents(org.w3c.dom.Node,boolean)
306: * @see #addItsNatComponent(org.w3c.dom.Node)
307: */
308: public ItsNatComponent[] buildItsNatComponents(Node node);
309:
310: /**
311: * Navigates recursively the document tree and for every node tries
312: * to create and register the built-in component associated to the node.
313: *
314: * <p>Current implementation is:</p>
315: * <blockquote><pre>
316: * Document doc = getItsNatDocument().getDocument();
317: * return buildItsNatComponents(doc);
318: * </pre></blockquote>
319: *
320: * @return an array with the components created and registered.
321: * @see #buildItsNatComponents(org.w3c.dom.Node)
322: */
323: public ItsNatComponent[] buildItsNatComponents();
324:
325: /**
326: * Navigates recursively the subtree below the specified node (included) and for every node removes
327: * the associated component if any from the registry and optionally disposes it.
328: *
329: * @param node the node parent of the subtree.
330: * @param dispose if every component found is disposed.
331: * @return an array with the components removed.
332: * @see #removeItsNatComponents(boolean)
333: * @see #removeItsNatComponent(org.w3c.dom.Node)
334: * @see #buildItsNatComponents(org.w3c.dom.Node)
335: */
336: public ItsNatComponent[] removeItsNatComponents(Node node,
337: boolean dispose);
338:
339: /**
340: * Navigates recursively the document and for every node removes
341: * the associated component if any from the registry and optionally disposes it.
342: *
343: * @param dispose if every component found is disposed.
344: * @return an array with the components removed.
345: * @see #removeItsNatComponents(org.w3c.dom.Node,boolean)
346: */
347: public ItsNatComponent[] removeItsNatComponents(boolean dispose);
348:
349: /**
350: * Creates a default label editor instance using the specified component
351: * as the editor.
352: *
353: * <p>Current implementation supports {@link org.itsnat.comp.html.ItsNatHTMLInputText},
354: * {@link org.itsnat.comp.html.ItsNatHTMLSelectComboBox}, {@link org.itsnat.comp.html.ItsNatHTMLInputCheckBox}
355: * and {@link org.itsnat.comp.html.ItsNatHTMLTextArea} as editors.</p>
356: *
357: * @param compEditor the component used as editor. If null {@link org.itsnat.comp.html.ItsNatHTMLInputText} (text not formatted version) is used.
358: * @return a default label editor instance.
359: */
360: public ItsNatLabelEditor createDefaultItsNatLabelEditor(
361: ItsNatComponent compEditor);
362:
363: /**
364: * Creates a default list editor instance using the specified component
365: * as the editor.
366: *
367: * <p>Current implementation supports {@link org.itsnat.comp.html.ItsNatHTMLInputText},
368: * {@link org.itsnat.comp.html.ItsNatHTMLSelectComboBox}, {@link org.itsnat.comp.html.ItsNatHTMLInputCheckBox}
369: * and {@link org.itsnat.comp.html.ItsNatHTMLTextArea} as editors.</p>
370: *
371: * @param compEditor the component used as editor. If null {@link org.itsnat.comp.html.ItsNatHTMLInputText} (text not formatted version) is used.
372: * @return a default list item editor instance.
373: */
374: public ItsNatListCellEditor createDefaultItsNatListCellEditor(
375: ItsNatComponent compEditor);
376:
377: /**
378: * Creates a default table editor instance using the specified component
379: * as the editor.
380: *
381: * <p>Current implementation supports {@link org.itsnat.comp.html.ItsNatHTMLInputText},
382: * {@link org.itsnat.comp.html.ItsNatHTMLSelectComboBox}, {@link org.itsnat.comp.html.ItsNatHTMLInputCheckBox}
383: * and {@link org.itsnat.comp.html.ItsNatHTMLTextArea} as editors.</p>
384: *
385: * @param compEditor the component used as editor. If null {@link org.itsnat.comp.html.ItsNatHTMLInputText} (text not formatted version) is used.
386: * @return a default table cell editor instance.
387: */
388: public ItsNatTableCellEditor createDefaultItsNatTableCellEditor(
389: ItsNatComponent compEditor);
390:
391: //public ItsNatTableHeaderCellEditor createItsNatTableHeaderCellEditor();
392:
393: /**
394: * Creates a default tree node editor instance using the specified component
395: * as the editor.
396: *
397: * <p>Current implementation supports {@link org.itsnat.comp.html.ItsNatHTMLInputText},
398: * {@link org.itsnat.comp.html.ItsNatHTMLSelectComboBox}, {@link org.itsnat.comp.html.ItsNatHTMLInputCheckBox}
399: * and {@link org.itsnat.comp.html.ItsNatHTMLTextArea} as editors.</p>
400: *
401: * @param compEditor the component used as editor. If null {@link org.itsnat.comp.html.ItsNatHTMLInputText} (text not formatted version) is used.
402: * @return a default tree node editor instance.
403: */
404: public ItsNatTreeCellEditor createDefaultItsNatTreeCellEditor(
405: ItsNatComponent compEditor);
406:
407: /**
408: * Creates a new default label renderer.
409: *
410: * @return a new default label renderer.
411: */
412: public ItsNatLabelRenderer createDefaultItsNatLabelRenderer();
413:
414: /**
415: * Creates a new default list element content renderer.
416: *
417: * @return a new default list element content renderer.
418: */
419: public ItsNatListCellRenderer createDefaultItsNatListCellRenderer();
420:
421: /**
422: * Creates a new default table cell content renderer.
423: *
424: * @return a new default table cell content renderer.
425: */
426: public ItsNatTableCellRenderer createDefaultItsNatTableCellRenderer();
427:
428: /**
429: * Creates a new default table header cell content renderer.
430: *
431: * @return a new default table header cell content renderer.
432: */
433: public ItsNatTableHeaderCellRenderer createDefaultItsNatTableHeaderCellRenderer();
434:
435: /**
436: * Creates a new default tree node content renderer.
437: *
438: * @return a new default tree node content renderer.
439: */
440: public ItsNatTreeCellRenderer createDefaultItsNatTreeCellRenderer();
441:
442: /**
443: * Creates a new default list structure manager.
444: *
445: * @return a new default list structure manager.
446: */
447: public ItsNatListStructure createDefaultItsNatListStructure();
448:
449: /**
450: * Creates a new default table structure manager.
451: *
452: * @return a new default table structure manager.
453: */
454: public ItsNatTableStructure createDefaultItsNatTableStructure();
455:
456: /**
457: * Creates a new default tree structure manager.
458: *
459: * @return a new default tree structure manager.
460: */
461: public ItsNatTreeStructure createDefaultItsNatTreeStructure();
462:
463: /**
464: * Creates a new free include component.
465: *
466: * @param element the DOM element associated. Can not be null.
467: * @param artifacts artifacts used to construct the component. May be null.
468: * @return a new free include component.
469: */
470: public ItsNatFreeInclude createItsNatFreeInclude(Element element,
471: NameValue[] artifacts);
472:
473: /**
474: * Creates a new free label component.
475: *
476: * @param element the DOM element associated. Can not be null.
477: * @param artifacts artifacts used to construct the component. May be null.
478: * @return a new free label component.
479: */
480: public ItsNatFreeLabel createItsNatFreeLabel(Element element,
481: NameValue[] artifacts);
482:
483: /**
484: * Creates a new free normal button component.
485: *
486: * @param element the DOM element associated. Can not be null.
487: * @param artifacts artifacts used to construct the component. May be null.
488: * @return a new free normal button component.
489: */
490: public ItsNatFreeButtonNormal createItsNatFreeButtonNormal(
491: Element element, NameValue[] artifacts);
492:
493: /**
494: * Creates a new free normal button component with a label.
495: *
496: * @param element the DOM element associated. Can not be null.
497: * @param artifacts artifacts used to construct the component. May be null.
498: * @return a new free normal button component.
499: */
500: public ItsNatFreeButtonNormalLabel createItsNatFreeButtonNormalLabel(
501: Element element, NameValue[] artifacts);
502:
503: /**
504: * Creates a new free check box component.
505: *
506: * @param element the DOM element associated. Can not be null.
507: * @param artifacts artifacts used to construct the component. May be null.
508: * @return a new free check box component.
509: */
510: public ItsNatFreeCheckBox createItsNatFreeCheckBox(Element element,
511: NameValue[] artifacts);
512:
513: /**
514: * Creates a new free check box component with a label.
515: *
516: * @param element the DOM element associated. Can not be null.
517: * @param artifacts artifacts used to construct the component. May be null.
518: * @return a new free check box component.
519: */
520: public ItsNatFreeCheckBoxLabel createItsNatFreeCheckBoxLabel(
521: Element element, NameValue[] artifacts);
522:
523: /**
524: * Creates a new free radio button component.
525: *
526: * @param element the DOM element associated. Can not be null.
527: * @param artifacts artifacts used to construct the component. May be null.
528: * @return a new free radio buttom component.
529: */
530: public ItsNatFreeRadioButton createItsNatFreeRadioButton(
531: Element element, NameValue[] artifacts);
532:
533: /**
534: * Creates a new free radio buttom component with a label.
535: *
536: * @param element the DOM element associated. Can not be null.
537: * @param artifacts artifacts used to construct the component. May be null.
538: * @return a new free radio buttom component.
539: */
540: public ItsNatFreeRadioButtonLabel createItsNatFreeRadioButtonLabel(
541: Element element, NameValue[] artifacts);
542:
543: /**
544: * Creates a new free combo box component.
545: *
546: *
547: * @param element the DOM element associated. Can not be null.
548: * @param structure the specified structure, if null then is obtained from artifacts ("useStructure"), if not defined then from markup ("useStructure" attribute), if not defined the default structure is used.
549: * @param artifacts artifacts used to construct the component. May be null.
550: * @return a new free combo box component.
551: * @see #createDefaultItsNatListStructure()
552: */
553: public ItsNatFreeComboBox createItsNatFreeComboBox(Element element,
554: ItsNatListStructure structure, NameValue[] artifacts);
555:
556: /**
557: * Creates a new free list component.
558: *
559: * @param element the DOM element associated. Can not be null.
560: * @param structure the specified structure, if null then is obtained from artifacts ("useStructure"), if not defined then from markup ("useStructure" attribute), if not defined the default structure is used.
561: * @param artifacts artifacts used to construct the component. May be null.
562: * @return a new free list component.
563: * @see #createDefaultItsNatListStructure()
564: */
565: public ItsNatFreeListMultSel createItsNatFreeListMultSel(
566: Element element, ItsNatListStructure structure,
567: NameValue[] artifacts);
568:
569: /**
570: * Creates a new free table component.
571: *
572: *
573: * @param element the DOM element associated. Can not be null.
574: * @param structure the specified structure, if null then is obtained from artifacts ("useStructure"), if not defined then from markup ("useStructure" attribute), if not defined the default structure is used.
575: * @param artifacts artifacts used to construct the component. May be null.
576: * @return a new free table component.
577: * @see #createDefaultItsNatTableStructure()
578: */
579: public ItsNatFreeTable createItsNatFreeTable(Element element,
580: ItsNatTableStructure structure, NameValue[] artifacts);
581:
582: /**
583: * Creates a new free tree component.
584: *
585: *
586: * @param element the DOM element associated. Can not be null.
587: * @param treeTable true if this tree is a tree-table.
588: * @param rootless true if this tree is rootless (root node has not view).
589: * @param structure the specified structure, if null then is obtained from artifacts ("useStructure"), if not defined then from markup ("useStructure" attribute), if not defined the default structure is used.
590: * @param artifacts artifacts used to construct the component. May be null.
591: * @return a new free tree component.
592: * @see #createDefaultItsNatTreeStructure()
593: * @see #createItsNatFreeTree(Element,NameValue[])
594: */
595: public ItsNatFreeTree createItsNatFreeTree(Element element,
596: boolean treeTable, boolean rootless,
597: ItsNatTreeStructure structure, NameValue[] artifacts);
598:
599: /**
600: * Creates a new free tree component.
601: *
602: * <p>By default is not a tree-table unless "treeTable" is defined in the artifacts (value "true") or as a markup attribute (value "true").</p>
603: * <p>By default the root node has view unless "rootless" is defined in the artifacts (value "true") or as a markup attribute (value "true").</p>
604: * <p>The structure is obtained from artifacts ("useStructure"), if not defined then from markup ("useStructure" attribute), if not defined the default structure is used.
605: *
606: *
607: * @param element the DOM element associated. Can not be null.
608: * @param artifacts artifacts used to construct the component. May be null.
609: * @return a new free tree component.
610: * @see #createItsNatFreeTree(Element,boolean,boolean,ItsNatTreeStructure,NameValue[])
611: */
612: public ItsNatFreeTree createItsNatFreeTree(Element element,
613: NameValue[] artifacts);
614:
615: }
|