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><img></code> 752 * tag, while figure() opens a paragraph- or <code><div></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 }