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$ 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 * 260 * @see #date(SinkEventAttributes) 261 */ 262 void date(); 263 264 /** 265 * Starts the date element. This is used to identify the date of the document: there is no strict definition 266 * if it is <b>creation date</b> or <b>last modification date</b>, which are the 2 classical semantics. 267 * There is no formal formatting requirements either. 268 * <br/> 269 * The date is recommended (but it is not a requirement) to be aligned to the 270 * <a href="http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=26780">ISO-8601</a> 271 * standard, i.e.: 272 * <pre>YYYY-MM-DD</pre> 273 * where 274 * <ul> 275 * <li><code>YYYY</code> is the year in the Gregorian calendar,</li> 276 * <li><code>MM</code> is the month of the year between 01 (January) and 12 (December),</li> 277 * <li>and <code>DD</code> is the day of the month between 01 and 31.</li> 278 * </ul> 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 }