View Javadoc

1   package org.apache.maven.doxia.sink;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *   http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  import org.apache.maven.doxia.logging.LogEnabled;
23  
24  /**
25   * A <i>Sink</i> consumes Doxia events to produce a resultant output format
26   * (eg Docbook, PDF, XHTML...).
27   * <p>
28   *   Doxia allows you to transform any supported input document format (ie for which a Parser exists)
29   *   into any supported output document format (ie for which a Sink exists).
30   * </p>
31   * <p>
32   *   A parser is responsible for reading an input document and emitting a sequence of Doxia events
33   *   which can then be consumed by a Doxia Sink. Thus, you can parse any front- end format
34   *   (eg APT, FML, Xdoc, ...) and have them all contribute to a final XHTML version of a web site.
35   *   All documents being parsed result in a stream of Doxia events (eg paragraph, bold, italic,
36   *   text,...), which are then fed into a XHTML Sink to produce a set of XHTML pages.
37   * </p>
38   * <p>
39   *   A Sink is ultimately responsible for the final format and structure of the output document.
40   *   For example, you can take a collection of APT documents, let a Parser emit a series of Doxia
41   *   events and have that be fed into a Sink to produce a single PDF, a book, a site, or a
42   *   Word document. The Sink is fully responsible for the final output.
43   * </p>
44   * <p>
45   *   You can easily integrate any custom (XML, Wiki,...) format by creating a Doxia Parser which
46   *   reads your input document and produces a proper sequence of Doxia events.
47   *   Those can then be fed into an arbitrary Sink to produce any desired final output.
48   * </p>
49   * <p>
50   * <b>Note</b>: All implemented sink <b>should</b> use UTF-8 as encoding.
51   * </p>
52   *
53   * @since 1.0-alpha-6
54   * @author <a href="mailto:jason@maven.org">Jason van Zyl</a>
55   * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
56   * @author ltheussl
57   * @version $Id: Sink.java 905077 2010-01-31 17:24:47Z hboutemy $
58   */
59  public interface Sink
60      extends LogEnabled
61  {
62      /** The Plexus Sink Role. */
63      String ROLE = Sink.class.getName();
64  
65      /**
66       * A numbering to handle a number list.
67       * @see #numberedList(int,SinkEventAttributes)
68       */
69      int NUMBERING_DECIMAL = 0;
70  
71      /**
72       * A numbering to handle a lower alpha list.
73       * @see #numberedList(int,SinkEventAttributes)
74       */
75      int NUMBERING_LOWER_ALPHA = 1;
76  
77      /**
78       * A numbering to handle a upper alpha list.
79       * @see #numberedList(int,SinkEventAttributes)
80       */
81      int NUMBERING_UPPER_ALPHA = 2;
82  
83      /**
84       * A numbering to handle a lower roman list.
85       * @see #numberedList(int,SinkEventAttributes)
86       */
87      int NUMBERING_LOWER_ROMAN = 3;
88  
89      /**
90       * A numbering to handle a upper roman list.
91       * @see #numberedList(int,SinkEventAttributes)
92       */
93      int NUMBERING_UPPER_ROMAN = 4;
94  
95      /**
96       * A level 1 section (section).
97       * @see #section(int,SinkEventAttributes)
98       */
99      int SECTION_LEVEL_1 = 1;
100 
101     /**
102      * A level 2 section (subsection).
103      * @see #section(int,SinkEventAttributes)
104      */
105     int SECTION_LEVEL_2 = 2;
106 
107     /**
108      * A level 3 section (sub-subsection).
109      * @see #section(int,SinkEventAttributes)
110      */
111     int SECTION_LEVEL_3 = 3;
112 
113     /**
114      * A level 4 section (sub-sub-subsection).
115      * @see #section(int,SinkEventAttributes)
116      */
117     int SECTION_LEVEL_4 = 4;
118 
119     /**
120      * A level 5 section (sub-sub-sub-subsection).
121      * @see #section(int,SinkEventAttributes)
122      */
123     int SECTION_LEVEL_5 = 5;
124 
125     /**
126      * Center alignment for table cells.
127      * @see #tableRows(int[], boolean)
128      */
129     int JUSTIFY_CENTER = 0;
130 
131     /**
132      * Left alignment for table cells.
133      * @see #tableRows(int[], boolean)
134      */
135     int JUSTIFY_LEFT = 1;
136 
137     /**
138      * Right alignment for table cells.
139      * @see #tableRows(int[], boolean)
140      */
141     int JUSTIFY_RIGHT = 2;
142 
143     /**
144      * Starts the head element.
145      *
146      * @see #head(SinkEventAttributes)
147      */
148     void head();
149 
150     /**
151      * Starts the head element.
152      *
153      * <p>
154      *   This contains information about the current document, (eg its title) that is not
155      *   considered document content. The head element is optional but if it exists, it has to be
156      *   unique within a sequence of Sink events that produces one output document, and it has
157      *   to come before the {@link #body(SinkEventAttributes)} element.
158      * </p>
159      * <p>
160      *   The canonical sequence of events for the head element is:
161      * </p>
162      * <pre>
163      *   sink.head();
164      *
165      *   sink.title();
166      *   sink.text( "Title" );
167      *   sink.title_();
168      *
169      *   sink.author();
170      *   sink.text( "Author" );
171      *   sink.author_();
172      *
173      *   sink.date();
174      *   sink.text( "Date" );
175      *   sink.date_();
176      *
177      *   sink.head_();
178      * </pre>
179      * <p>
180      *   but none of the enclosed events is required.  However, if they exist they have to occur
181      *   in the order shown, and the title() and date() events have to be unique (author() events
182      *   may occur any number of times).
183      * </p>
184      * <p>
185      *   Supported attributes are:
186      * </p>
187      * <blockquote>
188      *   {@link SinkEventAttributes#PROFILE PROFILE}, {@link SinkEventAttributes#LANG LANG}.
189      * </blockquote>
190      *
191      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
192      * @since 1.1
193      */
194     void head( SinkEventAttributes attributes );
195 
196     /**
197      * Ends the head element.
198      */
199     void head_();
200 
201     /**
202      * Starts the title element.
203      *
204      * @see #title(SinkEventAttributes)
205      */
206     void title();
207 
208     /**
209      * Starts the title element. This is used to identify the document.
210      *
211      * <p>
212      *   Supported attributes are the {@link SinkEventAttributes base attributes}.
213      * </p>
214      *
215      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
216      * @since 1.1
217      * @see #head(SinkEventAttributes)
218      */
219     void title( SinkEventAttributes attributes );
220 
221     /**
222      * Ends the title element.
223      */
224     void title_();
225 
226     /**
227      * Starts an author element.
228      *
229      * @see #author(SinkEventAttributes)
230      */
231     void author();
232 
233     /**
234      * Starts an author element. This is used to identify the author of the document.
235      *
236      * <p>
237      *   Supported attributes are: {@link SinkEventAttributes#EMAIL EMAIL}.
238      * </p>
239      *
240      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
241      * @since 1.1
242      * @see #head(SinkEventAttributes)
243      */
244     void author( SinkEventAttributes attributes );
245 
246     /**
247      * Ends an author element.
248      */
249     void author_();
250 
251     /**
252      * Starts the date element.
253      * <br/>
254      * The date is recommended (but it is not a requirement) to be align to the
255      * <a href="http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=26780">ISO-8601</a>
256      * standard, i.e.:
257      * <pre>
258      * YYYY-MM-DD
259      * </pre>
260      * where
261      * <ul>
262      * <li>YYYY is the year in the Gregorian calendar</li>
263      * <li>MM is the month of the year between 01 (January) and 12 (December)</li>
264      * <li>and DD is the day of the month between 01 and 31</li>
265      * </ul>
266      *
267      * @see #date(SinkEventAttributes)
268      */
269     void date();
270 
271     /**
272      * Starts the date element. This is used to identify the date of the document.
273      *
274      * <p>
275      *   Supported attributes are: none.
276      * </p>
277      *
278      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
279      * @since 1.1
280      * @see #head(SinkEventAttributes)
281      */
282     void date( SinkEventAttributes attributes );
283 
284     /**
285      * Ends the date element.
286      */
287     void date_();
288 
289     /**
290      * Starts the body of a document.
291      *
292      * @see #body(SinkEventAttributes)
293      */
294     void body();
295 
296     /**
297      * Starts the body of a document. This contains the document's content.
298      *
299      * <p>
300      *   Supported attributes are the {@link SinkEventAttributes base attributes}.
301      * </p>
302      *
303      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
304      * @since 1.1
305      * @see #head(SinkEventAttributes)
306      */
307     void body( SinkEventAttributes attributes );
308 
309     /**
310      * Ends the body element.
311      */
312     void body_();
313 
314     /**
315      * Starts a title heading element.
316      */
317     void sectionTitle();
318 
319     /**
320      * Ends a title heading element.
321      */
322     void sectionTitle_();
323 
324     /**
325      * Starts a first heading element which contains the topic of the section.
326      *
327      * @see #section(int,SinkEventAttributes)
328      */
329     void section1();
330 
331     /**
332      * Ends a first heading element.
333      */
334     void section1_();
335 
336     /**
337      * Starts a first title heading element. This element is optional, but if it exists,
338      * it has to be contained, and be the first element, within a {@link #section1()} element.
339      *
340      * @see #sectionTitle(int,SinkEventAttributes)
341      */
342     void sectionTitle1();
343 
344     /**
345      * Ends a first title heading element.
346      */
347     void sectionTitle1_();
348 
349     /**
350      * Starts a second heading element which contains the topic of the section.
351      * This has to be contained within a {@link #section1()} element.
352      *
353      * @see #section(int,SinkEventAttributes)
354      */
355     void section2();
356 
357     /**
358      * Ends a second heading element.
359      */
360     void section2_();
361 
362     /**
363      * Starts a second title heading element. This element is optional, but if it exists,
364      * it has to be contained, and be the first element, within a {@link #section2()} element.
365      *
366      * @see #sectionTitle(int,SinkEventAttributes)
367      */
368     void sectionTitle2();
369 
370     /**
371      * Ends a second title heading element.
372      */
373     void sectionTitle2_();
374 
375     /**
376      * Starts a third heading element which contains the topic of the section.
377      * This has to be contained within a {@link #section2()} element.
378      *
379      * @see #section(int,SinkEventAttributes)
380      */
381     void section3();
382 
383     /**
384      * Ends a third heading element.
385      */
386     void section3_();
387 
388     /**
389      * Starts a third title heading element. This element is optional, but if it exists,
390      * it has to be contained, and be the first element, within a {@link #section3()} element.
391      *
392      * @see #sectionTitle(int,SinkEventAttributes)
393      */
394     void sectionTitle3();
395 
396     /**
397      * Ends a third title heading element.
398      */
399     void sectionTitle3_();
400 
401     /**
402      * Starts a 4th heading element which contains the topic of the section.
403      * This has to be contained within a {@link #section3()} element.
404      *
405      * @see #section(int,SinkEventAttributes)
406      */
407     void section4();
408 
409     /**
410      * Ends a 4th heading element.
411      */
412     void section4_();
413 
414     /**
415      * Starts a 4th title heading element. This element is optional, but if it exists,
416      * it has to be contained, and be the first element, within a {@link #section4()} element.
417      *
418      * @see #sectionTitle(int,SinkEventAttributes)
419      */
420     void sectionTitle4();
421 
422     /**
423      * Ends a 4th title heading element.
424      */
425     void sectionTitle4_();
426 
427     /**
428      * Starts a 5th heading element which contains the topic of the section.
429      * This has to be contained within a {@link #section4()} element.
430      *
431      * @see #section(int,SinkEventAttributes)
432      */
433     void section5();
434 
435     /**
436      * Ends a 5th heading element.
437      */
438     void section5_();
439 
440     /**
441      * Starts a 5th title heading element. This element is optional, but if it exists,
442      * it has to be contained, and be the first element, within a {@link #section5()} element.
443      *
444      * @see #sectionTitle(int,SinkEventAttributes)
445      */
446     void sectionTitle5();
447 
448     /**
449      * Ends a 5th title heading element.
450      */
451     void sectionTitle5_();
452 
453     /**
454      * Start a new section at the given level.
455      *
456      * <p>
457      *   Sections with higher level have to be entirely contained within sections of lower level.
458      * </p>
459      * <p>
460      *   Supported attributes are the {@link SinkEventAttributes base attributes}.
461      * </p>
462      *
463      * @param level the section level.
464      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
465      * @since 1.1
466      */
467     void section( int level, SinkEventAttributes attributes );
468 
469     /**
470      * Ends a section at the given level.
471      *
472      * @param level the section level.
473      * @since 1.1
474      */
475     void section_( int level );
476 
477     /**
478      * Start a new section title at the given level.
479      *
480      * <p>
481      *    This element is optional, but if it exists, it has to be contained, and be the first
482      *    element, within a corresponding {@link #section(int,SinkEventAttributes) section}
483      *    element of the same level.
484      * </p>
485      * <p>
486      *   <b>NOTE:</b> It is strongly recommended not to make section titles implicit anchors.
487      *   Neither Parsers nor Sinks should insert any content that is not explicitly present
488      *   in the original source document, as this would lead to undefined behaviour for
489      *   multi-format processing chains. However, while Parsers <b>must never</b> emit anchors
490      *   for section titles, some specialized Sinks may implement such a feature if the resulting
491      *   output documents are not going to be further processed (and this is properly documented).
492      * </p>
493      * <p>
494      *   Supported attributes are the {@link SinkEventAttributes base attributes} plus
495      *   {@link SinkEventAttributes#ALIGN ALIGN}.
496      * </p>
497      *
498      * @param level the section title level.
499      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
500      * @since 1.1
501      */
502     void sectionTitle( int level, SinkEventAttributes attributes );
503 
504     /**
505      * Ends a section title at the given level.
506      *
507      * @param level the section title level.
508      * @since 1.1
509      */
510     void sectionTitle_( int level );
511 
512     /**
513      * Starts an unordered list element.
514      *
515      * @see #list(SinkEventAttributes)
516      */
517     void list();
518 
519     /**
520      * Starts an unordered list.
521      *
522      * <p>
523      *   Supported attributes are the {@link SinkEventAttributes base attributes}.
524      * </p>
525      *
526      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
527      * @since 1.1
528      */
529     void list( SinkEventAttributes attributes );
530 
531     /**
532      * Ends an unordered list element.
533      */
534     void list_();
535 
536     /**
537      * Starts a list item element within an unordered list.
538      *
539      * @see #listItem(SinkEventAttributes)
540      */
541     void listItem();
542 
543     /**
544      * Starts a list item element within an unordered list.
545      *
546      * <p>
547      *   Supported attributes are the {@link SinkEventAttributes base attributes}.
548      * </p>
549      *
550      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
551      * @since 1.1
552      */
553     void listItem( SinkEventAttributes attributes );
554 
555     /**
556      * Ends a list item element within an unordered list.
557      */
558     void listItem_();
559 
560     /**
561      * Starts an ordered list element.
562      *
563      * @param numbering the numbering style.
564      * @see #numberedList(int,SinkEventAttributes)
565      */
566     void numberedList( int numbering );
567 
568     /**
569      * Starts an ordered list element.
570      *
571      * <p>
572      *   Supported attributes are the {@link SinkEventAttributes base attributes}.
573      * </p>
574      *
575      * @param numbering the numbering style.
576      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
577      * @since 1.1
578      * @see #NUMBERING_DECIMAL
579      * @see #NUMBERING_LOWER_ALPHA
580      * @see #NUMBERING_LOWER_ROMAN
581      * @see #NUMBERING_UPPER_ALPHA
582      * @see #NUMBERING_UPPER_ROMAN
583      */
584     void numberedList( int numbering, SinkEventAttributes attributes );
585 
586     /**
587      * Ends an ordered list element.
588      */
589     void numberedList_();
590 
591     /**
592      * Starts a list item element within an ordered list.
593      *
594      * @see #numberedListItem(SinkEventAttributes)
595      */
596     void numberedListItem();
597 
598     /**
599      * Starts a list item element within an ordered list.
600      *
601      * <p>
602      *   Supported attributes are the {@link SinkEventAttributes base attributes}.
603      * </p>
604      *
605      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
606      * @since 1.1
607      */
608     void numberedListItem( SinkEventAttributes attributes );
609 
610     /**
611      * Ends a list item element within an ordered list.
612      */
613     void numberedListItem_();
614 
615     /**
616      * Starts a definition list element.
617      *
618      * @see #definitionList(SinkEventAttributes)
619      */
620     void definitionList();
621 
622     /**
623      * Starts a definition list.
624      *
625      * <p>
626      *   Supported attributes are the {@link SinkEventAttributes base attributes}.
627      * </p>
628      *
629      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
630      * @since 1.1
631      */
632     void definitionList( SinkEventAttributes attributes );
633 
634     /**
635      * Ends a definition list element.
636      */
637     void definitionList_();
638 
639     /**
640      * Starts a list item element within a definition list.
641      *
642      * @see #definitionListItem(SinkEventAttributes)
643      */
644     void definitionListItem();
645 
646     /**
647      * Starts a list item element within a definition list.
648      *
649      * <p>
650      *   Every definitionListItem has to contain exactly one {@link #definedTerm(SinkEventAttributes)}
651      *   and one {@link #definition(SinkEventAttributes)}, in this order.
652      * </p>
653      * <p>
654      *   Supported attributes are the {@link SinkEventAttributes base attributes}.
655      * </p>
656      *
657      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
658      * @since 1.1
659      */
660     void definitionListItem( SinkEventAttributes attributes );
661 
662     /**
663      * Ends a list item element within a definition list.
664      */
665     void definitionListItem_();
666 
667     /**
668      * Starts a definition element within a definition list.
669      *
670      * @see #definition(SinkEventAttributes)
671      */
672     void definition();
673 
674     /**
675      * Starts a definition element within a definition list.
676      *
677      * <p>
678      *   Supported attributes are the {@link SinkEventAttributes base attributes}.
679      * </p>
680      *
681      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
682      * @since 1.1
683      */
684     void definition( SinkEventAttributes attributes );
685 
686     /**
687      * Ends a definition element within a definition list.
688      */
689     void definition_();
690 
691     /**
692      * Starts a definition term element within a definition list.
693      *
694      * @see #definedTerm(SinkEventAttributes)
695      */
696     void definedTerm();
697 
698     /**
699      * Starts a definition term element within a definition list.
700      *
701      * <p>
702      *   Supported attributes are the {@link SinkEventAttributes base attributes}.
703      * </p>
704      *
705      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
706      * @since 1.1
707      */
708     void definedTerm( SinkEventAttributes attributes );
709 
710     /**
711      * Starts a definition term element within a definition list.
712      */
713     void definedTerm_();
714 
715     /**
716      * Starts a basic image embedding element.
717      *
718      * @see #figure(SinkEventAttributes)
719      */
720     void figure();
721 
722     /**
723      * Starts a basic image embedding element.
724      *
725      * <p>
726      *   The canonical sequence of events for the figure element is:
727      * </p>
728      * <pre>
729      *   sink.figure();
730      *
731      *   sink.figureGraphics( "figure.png" );
732      *
733      *   sink.figureCaption();
734      *   sink.text( "Figure caption",);
735      *   sink.figureCaption_();
736      *
737      *   sink.figure_();
738      * </pre>
739      * <p>
740      *   where the figureCaption element is optional.
741      * </p>
742      * <p>
743      *   However, <strong>NOTE</strong> that the order of figureCaption and
744      *   figureGraphics events is arbitrary,
745      *   ie a parser may emit the figureCaption before or after the figureGraphics.
746      *   Implementing sinks should be prepared to handle both possibilities.
747      * </p>
748      * <p>
749      *   <strong>NOTE</strong> also that the figureGraphics() event does not have to be embedded
750      *   inside figure(), in particular for in-line images the figureGraphics() should be used
751      *   stand-alone (in HTML language, figureGraphics() produces a <code>&lt;img&gt;</code>
752      *   tag, while figure() opens a paragraph- or <code>&lt;div&gt;</code>- like environment).
753      * </p>
754      * <p>
755      *   Supported attributes are the {@link SinkEventAttributes base attributes}.
756      * </p>
757      *
758      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
759      * @since 1.1
760      */
761     void figure( SinkEventAttributes attributes );
762 
763     /**
764      * Ends a basic image embedding element.
765      */
766     void figure_();
767 
768     /**
769      * Starts a caption of an image element.
770      *
771      * @see #figureCaption(SinkEventAttributes)
772      */
773     void figureCaption();
774 
775     /**
776      * Starts a figure caption.
777      *
778      * <p>
779      *   Supported attributes are the {@link SinkEventAttributes base attributes}.
780      * </p>
781      *
782      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
783      * @since 1.1
784      * @see #figure(SinkEventAttributes)
785      */
786     void figureCaption( SinkEventAttributes attributes );
787 
788     /**
789      * Ends a caption of an image.
790      */
791     void figureCaption_();
792 
793     /**
794      * Adding a source of a graphic.
795      *
796      * @param name the source
797      */
798     void figureGraphics( String name );
799 
800     /**
801      * Adds a graphic element.
802      *
803      * <p>
804      *   The <code>src</code> parameter should be a valid link, ie it can be an absolute
805      *   URL or a link relative to the current source document.
806      * </p>
807      * <p>
808      *   Supported attributes are the {@link SinkEventAttributes base attributes} plus:
809      * </p>
810      * <blockquote>
811      *   {@link SinkEventAttributes#SRC SRC}, {@link SinkEventAttributes#ALT ALT},
812      *   {@link SinkEventAttributes#WIDTH WIDTH}, {@link SinkEventAttributes#HEIGHT HEIGHT},
813      *   {@link SinkEventAttributes#ALIGN ALIGN}, {@link SinkEventAttributes#BORDER BORDER},
814      *   {@link SinkEventAttributes#HSPACE HSPACE}, {@link SinkEventAttributes#VSPACE VSPACE},
815      *   {@link SinkEventAttributes#ISMAP ISMAP}, {@link SinkEventAttributes#USEMAP USEMAP}.
816      * </blockquote>
817      * <p>
818      *   If the {@link SinkEventAttributes#SRC SRC} attribute is specified in SinkEventAttributes,
819      *   it will be overridden by the <code>src</code> parameter.
820      * </p>
821      *
822      * @param src the image source, a valid URL.
823      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
824      * @since 1.1
825      * @see #figure(SinkEventAttributes)
826      */
827     void figureGraphics( String src, SinkEventAttributes attributes );
828 
829     /**
830      * Starts a table element for marking up tabular information in a document.
831      *
832      * @see #table(SinkEventAttributes)
833      */
834     void table();
835 
836     /**
837      * Starts a table.
838      *
839      * <p>
840      *   The canonical sequence of events for the table element is:
841      * </p>
842      * <pre>
843      *   sink.table();
844      *
845      *   sink.tableRows( justify, true );
846      *
847      *   sink.tableRow();
848      *   sink.tableCell();
849      *   sink.text( "cell 1,1" );
850      *   sink.tableCell_();
851      *   sink.tableCell();
852      *   sink.text( "cell 1,2" );
853      *   sink.tableCell_();
854      *   sink.tableRow_();
855      *
856      *   sink.tableRows_();
857      *
858      *   sink.tableCaption();
859      *   sink.text( "Table caption" );
860      *   sink.tableCaption_();
861      *
862      *   sink.table_();
863      *
864      * </pre>
865      * <p>
866      *   where the tableCaption element is optional.
867      * </p>
868      * <p>
869      *   However, <strong>NOTE</strong> that the order of tableCaption and
870      *   {@link #tableRows(int[],boolean)} events is arbitrary,
871      *   ie a parser may emit the tableCaption before or after the tableRows.
872      *   Implementing sinks should be prepared to handle both possibilities.
873      * </p>
874      * <p>
875      *   Supported attributes are the {@link SinkEventAttributes base attributes} plus:
876      * </p>
877      * <blockquote>
878      *   {@link SinkEventAttributes#ALIGN ALIGN}, {@link SinkEventAttributes#BGCOLOR BGCOLOR},
879      *   {@link SinkEventAttributes#BORDER BORDER}, {@link SinkEventAttributes#CELLPADDING CELLPADDING},
880      *   {@link SinkEventAttributes#CELLSPACING CELLSPACING}, {@link SinkEventAttributes#FRAME FRAME},
881      *   {@link SinkEventAttributes#RULES RULES}, {@link SinkEventAttributes#SUMMARY SUMMARY},
882      *   {@link SinkEventAttributes#WIDTH WIDTH}.
883      * </blockquote>
884      *
885      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
886      * @since 1.1
887      */
888     void table( SinkEventAttributes attributes );
889 
890     /**
891      * Ends a table element.
892      */
893     void table_();
894 
895     /**
896      * Starts an element that contains rows of table data.
897      *
898      * @param justification the default justification of columns.
899      * This can be overridden by individual table rows or table cells.
900      * If null a left alignment is assumed by default. If this array
901      * has less elements than there are columns in the table then the value of
902      * the last array element will be taken as default for the remaining table cells.
903      * @param grid true to provide a grid, false otherwise.
904      * @see #table(SinkEventAttributes)
905      * @see #JUSTIFY_CENTER
906      * @see #JUSTIFY_LEFT
907      * @see #JUSTIFY_RIGHT
908      */
909     void tableRows( int[] justification, boolean grid );
910 
911     /**
912      * Ends an element that contains rows of table data.
913      */
914     void tableRows_();
915 
916     /**
917      * Starts a row element which acts as a container for a row of table cells.
918      *
919      * @see #tableRow(SinkEventAttributes)
920      */
921     void tableRow();
922 
923     /**
924      * Starts a table row.
925      *
926      * <p>
927      *   Supported attributes are the {@link SinkEventAttributes base attributes} plus:
928      * </p>
929      * <blockquote>
930      *   {@link SinkEventAttributes#ALIGN ALIGN}, {@link SinkEventAttributes#BGCOLOR BGCOLOR},
931      *   {@link SinkEventAttributes#VALIGN VALIGN}.
932      * </blockquote>
933      *
934      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
935      * @since 1.1
936      */
937     void tableRow( SinkEventAttributes attributes );
938 
939     /**
940      * Ends a row element.
941      */
942     void tableRow_();
943 
944     /**
945      * Starts a cell element which defines a cell that contains data.
946      *
947      * @see #tableCell(SinkEventAttributes)
948      */
949     void tableCell();
950 
951     /**
952      * Starts a cell element which defines a cell that contains data.
953      *
954      * @param width the size of the cell.
955      * @deprecated Use #tableCell(SinkEventAttributes) instead.
956      */
957     void tableCell( String width );
958 
959     /**
960      * Starts a table cell.
961      *
962      * <p>
963      *   Supported attributes are the {@link SinkEventAttributes base attributes} plus:
964      * </p>
965      * <blockquote>
966      *   {@link SinkEventAttributes#ABBRV ABBRV}, {@link SinkEventAttributes#ALIGN ALIGN},
967      *   {@link SinkEventAttributes#AXIS AXIS}, {@link SinkEventAttributes#BGCOLOR BGCOLOR},
968      *   {@link SinkEventAttributes#COLSPAN COLSPAN}, {@link SinkEventAttributes#HEADERS HEADERS},
969      *   {@link SinkEventAttributes#HEIGHT HEIGHT}, {@link SinkEventAttributes#NOWRAP NOWRAP},
970      *   {@link SinkEventAttributes#ROWSPAN ROWSPAN}, {@link SinkEventAttributes#SCOPE SCOPE},
971      *   {@link SinkEventAttributes#VALIGN VALIGN}, {@link SinkEventAttributes#WIDTH WIDTH}.
972      * </blockquote>
973      *
974      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
975      * @since 1.1
976      */
977     void tableCell( SinkEventAttributes attributes );
978 
979     /**
980      * Ends a cell element.
981      */
982     void tableCell_();
983 
984     /**
985      * Starts a cell element which defines a cell that contains header information.
986      *
987      * @see #tableHeaderCell(SinkEventAttributes)
988      */
989     void tableHeaderCell();
990 
991     /**
992      * Starts a cell element which defines a cell that contains header information.
993      *
994      * @param width the size of the header cell.
995      * @deprecated Use #tableHeaderCell(SinkEventAttributes) instead.
996      */
997     void tableHeaderCell( String width );
998 
999     /**
1000      * Starts a table header cell.
1001      *
1002      * <p>
1003      *   Supported attributes are the same as for {@link #tableCell(SinkEventAttributes) tableCell}.
1004      * </p>
1005      *
1006      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1007      * @since 1.1
1008      */
1009     void tableHeaderCell( SinkEventAttributes attributes );
1010 
1011     /**
1012      * Ends a cell header element.
1013      */
1014     void tableHeaderCell_();
1015 
1016     /**
1017      * Starts a caption element of a table.
1018      *
1019      * @see #tableCaption(SinkEventAttributes)
1020      */
1021     void tableCaption();
1022 
1023     /**
1024      * Starts a table caption.
1025      *
1026      * <p>
1027      *   Note that the order of tableCaption and
1028      *   {@link #tableRows(int[],boolean)} events is arbitrary,
1029      *   ie a parser may emit the tableCaption before or after the tableRows.
1030      *   Implementing sinks should be prepared to handle both possibilities.
1031      * </p>
1032      * <p>
1033      *   Supported attributes are the {@link SinkEventAttributes base attributes}
1034      *   plus {@link SinkEventAttributes#ALIGN ALIGN}.
1035      * </p>
1036      *
1037      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1038      * @since 1.1
1039      * @see #table(SinkEventAttributes)
1040      */
1041     void tableCaption( SinkEventAttributes attributes );
1042 
1043     /**
1044      * Ends a caption element of a table.
1045      */
1046     void tableCaption_();
1047 
1048     /**
1049      * Starts an element which represents a paragraph.
1050      *
1051      * @see #paragraph(SinkEventAttributes)
1052      */
1053     void paragraph();
1054 
1055     /**
1056      * Starts a paragraph.
1057      *
1058      * <p>
1059      *   Supported attributes are the {@link SinkEventAttributes base attributes}
1060      *   plus {@link SinkEventAttributes#ALIGN ALIGN}.
1061      * </p>
1062      *
1063      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1064      * @since 1.1
1065      */
1066     void paragraph( SinkEventAttributes attributes );
1067 
1068     /**
1069      * Ends a paragraph element.
1070      */
1071     void paragraph_();
1072 
1073     /**
1074      * Starts an element which indicates that whitespace in the enclosed text has semantic relevance.
1075      *
1076      * @param boxed true to add a box, false otherwise
1077      * @deprecated Use #verbatim(SinkEventAttributes) instead.
1078      */
1079     void verbatim( boolean boxed );
1080 
1081     /**
1082      * Starts a verbatim block, ie a block where whitespace has semantic relevance.
1083      *
1084      * <p>
1085      *   Text in a verbatim block must only be wrapped at the linebreaks in the source,
1086      *   and spaces should not be collapsed. It should be displayed in a fixed-width font to
1087      *   retain the formatting but the overall size may be chosen by the implementation.
1088      * </p>
1089      *
1090      * <p>
1091      *   Most Sink events may be emitted within a verbatim block, the only elements explicitly
1092      *   forbidden are font-changing events and figures. Also, verbatim blocks may not be nested.
1093      * </p>
1094      *
1095      * <p>
1096      *   Supported attributes are the {@link SinkEventAttributes base attributes} plus:
1097      * </p>
1098      * <blockquote>
1099      *   {@link SinkEventAttributes#DECORATION DECORATION} (value: "boxed"),
1100      *   {@link SinkEventAttributes#ALIGN ALIGN}, {@link SinkEventAttributes#WIDTH WIDTH}.
1101      * </blockquote>
1102      *
1103      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1104      * @since 1.1
1105      */
1106     void verbatim( SinkEventAttributes attributes );
1107 
1108     /**
1109      * Ends a verbatim element.
1110      */
1111     void verbatim_();
1112 
1113     /**
1114      * Adding a separator of sections from a text to each other.
1115      *
1116      * @see #horizontalRule(SinkEventAttributes)
1117      */
1118     void horizontalRule();
1119 
1120     /**
1121      * Adds a horizontal separator rule.
1122      *
1123      * <p>
1124      *   Supported attributes are the {@link SinkEventAttributes base attributes} plus:
1125      * </p>
1126      * <blockquote>
1127      *   {@link SinkEventAttributes#ALIGN ALIGN}, {@link SinkEventAttributes#NOSHADE NOSHADE},
1128      *   {@link SinkEventAttributes#SIZE SIZE}, {@link SinkEventAttributes#WIDTH WIDTH}.
1129      * </blockquote>
1130      *
1131      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1132      * @since 1.1
1133      */
1134     void horizontalRule( SinkEventAttributes attributes );
1135 
1136     /**
1137      * Adding a new page separator.
1138      */
1139     void pageBreak();
1140 
1141     /**
1142      * Starts an element which defines an anchor.
1143      *
1144      * @param name the name of the anchor.
1145      * @see #anchor(String,SinkEventAttributes)
1146      */
1147     void anchor( String name );
1148 
1149     /**
1150      * Starts an element which defines an anchor.
1151      *
1152      * <p>
1153      *   The <code>name</code> parameter has to be a valid SGML NAME token.
1154      *   According to the <a href="http://www.w3.org/TR/html4/types.html#type-name">
1155      *   HTML 4.01 specification section 6.2 SGML basic types</a>:
1156      * </p>
1157      * <p>
1158      *   <i>ID and NAME tokens must begin with a letter ([A-Za-z]) and may be
1159      *   followed by any number of letters, digits ([0-9]), hyphens ("-"),
1160      *   underscores ("_"), colons (":"), and periods (".").</i>
1161      * </p>
1162      * <p>
1163      *   Supported attributes are the {@link SinkEventAttributes base attributes}.
1164      *   If {@link SinkEventAttributes#NAME NAME} is specified in the SinkEventAttributes,
1165      *   it will be overwritten by the <code>name</code> parameter.
1166      * </p>
1167      *
1168      * @param name the name of the anchor. This has to be a valid SGML NAME token.
1169      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1170      * @since 1.1
1171      */
1172     void anchor( String name, SinkEventAttributes attributes );
1173 
1174     /**
1175      * Ends an anchor element.
1176      */
1177     void anchor_();
1178 
1179     /**
1180      * Starts an element which defines a link.
1181      *
1182      * @param name the name of the link.
1183      * @see #link(String,SinkEventAttributes)
1184      */
1185     void link( String name );
1186 
1187     /**
1188      * Starts a link.
1189      *
1190      * <p>
1191      *   The <code>name</code> parameter has to be a valid html <code>href</code>
1192      *   parameter, ie for internal links (links to an anchor within the same source
1193      *   document), <code>name</code> should start with the character "#".
1194      * </p>
1195      * <p>
1196      *   Supported attributes are the {@link SinkEventAttributes base attributes} plus:
1197      * </p>
1198      * <blockquote>
1199      *   {@link SinkEventAttributes#CHARSET CHARSET}, {@link SinkEventAttributes#COORDS COORDS},
1200      *   {@link SinkEventAttributes#HREF HREF}, {@link SinkEventAttributes#HREFLANG HREFLANG},
1201      *   {@link SinkEventAttributes#REL REL}, {@link SinkEventAttributes#REV REV},
1202      *   {@link SinkEventAttributes#SHAPE SHAPE}, {@link SinkEventAttributes#TARGET TARGET},
1203      *   {@link SinkEventAttributes#TYPE TYPE}.
1204      * </blockquote>
1205      * <p>
1206      *   If {@link SinkEventAttributes#HREF HREF} is specified in the
1207      *   SinkEventAttributes, it will be overwritten by the <code>name</code> parameter.
1208      * </p>
1209      *
1210      * @param name the name of the link.
1211      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1212      * @since 1.1
1213      */
1214     void link( String name, SinkEventAttributes attributes );
1215 
1216     /**
1217      * Ends a link element.
1218      */
1219     void link_();
1220 
1221     /**
1222      * Starts an italic element.
1223      *
1224      * Alternatively one may use {@link #text(String,SinkEventAttributes)} with
1225      *              {@link SinkEventAttributes#STYLE STYLE} instead.
1226      */
1227     void italic();
1228 
1229     /**
1230      * Ends an italic element.
1231      *
1232      * Alternatively one may use {@link #text(String,SinkEventAttributes)} with
1233      *              {@link SinkEventAttributes#STYLE STYLE} instead.
1234      */
1235     void italic_();
1236 
1237     /**
1238      * Starts a bold element.
1239      *
1240      * Alternatively one may use {@link #text(String,SinkEventAttributes)} with
1241      *              {@link SinkEventAttributes#STYLE STYLE} instead.
1242      */
1243     void bold();
1244 
1245     /**
1246      * Ends a bold element.
1247      *
1248      * Alternatively one may use {@link #text(String,SinkEventAttributes)} with
1249      *              {@link SinkEventAttributes#STYLE STYLE} instead.
1250      */
1251     void bold_();
1252 
1253     /**
1254      * Starts a monospaced element.
1255      *
1256      * Alternatively one may use {@link #text(String,SinkEventAttributes)} with
1257      *              {@link SinkEventAttributes#STYLE STYLE} instead.
1258      */
1259     void monospaced();
1260 
1261     /**
1262      * Ends a monospaced element.
1263      *
1264      * Alternatively one may use {@link #text(String,SinkEventAttributes)} with
1265      *              {@link SinkEventAttributes#STYLE STYLE} instead.
1266      */
1267     void monospaced_();
1268 
1269     /**
1270      * Adds a line break.
1271      *
1272      * @see #lineBreak(SinkEventAttributes)
1273      */
1274     void lineBreak();
1275 
1276     /**
1277      * Adds a line break.
1278      *
1279      * <p>
1280      *   Supported attributes are:
1281      * </p>
1282      * <blockquote>
1283      *   {@link SinkEventAttributes#ID ID}, {@link SinkEventAttributes#CLASS CLASS},
1284      *   {@link SinkEventAttributes#TITLE TITLE}, {@link SinkEventAttributes#STYLE STYLE}.
1285      * </blockquote>
1286      *
1287      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1288      * @since 1.1
1289      */
1290     void lineBreak( SinkEventAttributes attributes );
1291 
1292     /**
1293      * Adding a non breaking space, <i>ie</i> a space without any special formatting operations.
1294      */
1295     void nonBreakingSpace();
1296 
1297     /**
1298      * Adding a text.
1299      *
1300      * @param text The text to write.
1301      * @see #text(String,SinkEventAttributes)
1302      */
1303     void text( String text );
1304 
1305     /**
1306      * Adds a text.
1307      *
1308      * <p>
1309      *   The <code>text</code> parameter should contain only real content, ie any
1310      *   ignorable/collapsable whitespace/EOLs or other pretty-printing should
1311      *   be removed/normalized by a parser.
1312      * </p>
1313      * <p>
1314      *   If <code>text</code> contains any variants of line terminators, they should
1315      *   be normalized to the System EOL by an implementing Sink.
1316      * </p>
1317      * <p>
1318      *   Supported attributes are the {@link SinkEventAttributes base attributes} plus
1319      * </p>
1320      * <blockquote>
1321      *   {@link SinkEventAttributes#VALIGN VALIGN} (values "sub", "sup"),
1322      *   {@link SinkEventAttributes#DECORATION DECORATION} (values "underline", "overline", "line-through"),
1323      *   {@link SinkEventAttributes#STYLE STYLE} (values "italic", "bold", "monospaced").
1324      * </blockquote>
1325      *
1326      * @param text The text to write.
1327      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1328      * @since 1.1
1329      */
1330     void text( String text, SinkEventAttributes attributes );
1331 
1332     /**
1333      * Adding a raw text, <i>ie</i> a text without any special formatting operations.
1334      *
1335      * @param text The text to write.
1336      */
1337     void rawText( String text );
1338 
1339     /**
1340      * Add a comment.
1341      *
1342      * @param comment The comment to write.
1343      * @since 1.1
1344      */
1345     void comment( String comment );
1346 
1347     /**
1348      * Add an unknown event. This may be used by parsers to notify a general Sink about
1349      * an event that doesn't fit into any event defined by the Sink API.
1350      * Depending on the parameters, a Sink may decide whether or not to process the event,
1351      * emit it as raw text, as a comment, log it, etc.
1352      *
1353      * @param name The name of the event.
1354      * @param requiredParams An optional array of required parameters to the event.
1355      * May be <code>null</code>.
1356      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
1357      * @since 1.1
1358      */
1359     void unknown( String name, Object[] requiredParams, SinkEventAttributes attributes );
1360 
1361     /**
1362      * Flush the writer or the stream, if needed.
1363      * Flushing a previously-flushed Sink has no effect.
1364      */
1365     void flush();
1366 
1367     /**
1368      * Close the writer or the stream, if needed.
1369      * Closing a previously-closed Sink has no effect.
1370      */
1371     void close();
1372 }