001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: /* $Id: Renderer.java 535883 2007-05-07 14:30:23Z jeremias $ */
019:
020: package org.apache.fop.render;
021:
022: // Java
023: import java.io.OutputStream;
024: import java.io.IOException;
025:
026: // FOP
027: import org.apache.fop.apps.FOPException;
028: import org.apache.fop.area.PageViewport;
029: import org.apache.fop.area.LineArea;
030: import org.apache.fop.area.OffDocumentItem;
031: import org.apache.fop.fonts.FontInfo;
032: import org.apache.fop.apps.FOUserAgent;
033:
034: /**
035: * Interface implemented by all renderers. This interface is used to control
036: * the rendering of pages and to let block and inline level areas call the
037: * appropriate method to render themselves. <p>
038: *
039: * A Renderer implementation takes areas/spaces and produces output in some
040: * format.</p> <p>
041: *
042: * Typically, most renderers are subclassed from FOP's abstract implementations
043: * ({@link AbstractRenderer}, {@link PrintRenderer}) which already handle a lot
044: * of things letting you concentrate on the details of the output format.
045: */
046: public interface Renderer {
047:
048: /**
049: * Role constant for Avalon.
050: */
051: String ROLE = Renderer.class.getName();
052:
053: /**
054: * Get the MIME type of the renderer.
055: *
056: * @return The MIME type of the renderer, may return null if not applicable.
057: */
058: String getMimeType();
059:
060: /**
061: * Initiates the rendering phase.
062: * This must only be called once for a rendering. If
063: * stopRenderer is called then this may be called again
064: * for a new document rendering.
065: *
066: * @param outputStream The OutputStream to use for output
067: * @exception IOException If an I/O error occurs
068: */
069: void startRenderer(OutputStream outputStream) throws IOException;
070:
071: /**
072: * Signals the end of the rendering phase.
073: * The renderer should reset to an initial state and dispose of
074: * any resources for the completed rendering.
075: *
076: * @exception IOException If an I/O error occurs
077: */
078: void stopRenderer() throws IOException;
079:
080: /**
081: * Set the User Agent.
082: *
083: * @param agent The User Agent
084: */
085: void setUserAgent(FOUserAgent agent);
086:
087: /**
088: * Set up the given FontInfo.
089: *
090: * @param fontInfo The font information
091: */
092: void setupFontInfo(FontInfo fontInfo);
093:
094: /**
095: * Reports if out of order rendering is supported. <p>
096: *
097: * Normally, all pages of a document are rendered in their natural order
098: * (page 1, page 2, page 3 etc.). Some output formats (such as PDF) allow
099: * pages to be output in random order. This is helpful to reduce resource
100: * strain on the system because a page that cannot be fully resolved
101: * doesn't block subsequent pages that are already fully resolved. </p>
102: *
103: * @return True if this renderer supports out of order rendering.
104: */
105: boolean supportsOutOfOrder();
106:
107: /**
108: * Tells the renderer to process an item not explicitly placed on the
109: * document (e.g., PDF bookmarks). Note - not all renderers will process
110: * all off-document items.
111: *
112: * @param odi The off-document item to be rendered
113: */
114: void processOffDocumentItem(OffDocumentItem odi);
115:
116: /**
117: * @return the adapter for painting Java2D images (or null if not supported)
118: */
119: Graphics2DAdapter getGraphics2DAdapter();
120:
121: /**
122: * @return the adapter for painting RenderedImages (or null if not supported)
123: */
124: ImageAdapter getImageAdapter();
125:
126: /**
127: * This is called if the renderer supports out of order rendering. The
128: * renderer should prepare the page so that a page further on in the set of
129: * pages can be rendered. The body of the page should not be rendered. The
130: * page will be rendered at a later time by the call to {@link
131: * #renderPage(PageViewport)}.
132: *
133: * @param page The page viewport to use
134: */
135: void preparePage(PageViewport page);
136:
137: /**
138: * Tells the renderer that a new page sequence starts.
139: *
140: * @param seqTitle The title of the page sequence
141: */
142: void startPageSequence(LineArea seqTitle);
143:
144: /**
145: * Tells the renderer to render a particular page. A renderer typically
146: * reponds by packing up the current page and writing it immediately to the
147: * output device.
148: *
149: * @param page The page to be rendered
150: * @exception IOException if an I/O error occurs
151: * @exception FOPException if a FOP interal error occurs.
152: */
153: void renderPage(PageViewport page) throws IOException, FOPException;
154:
155: }
|