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