1 package org.apache.maven.doxia.siterenderer; 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 java.io.File; 23 import java.io.FileNotFoundException; 24 import java.io.IOException; 25 import java.io.UnsupportedEncodingException; 26 import java.io.Writer; 27 import java.util.Collection; 28 import java.util.Locale; 29 import java.util.Map; 30 31 import org.apache.maven.artifact.Artifact; 32 import org.apache.maven.doxia.site.decoration.DecorationModel; 33 34 /** 35 * <p>Site Renderer interface: render a collection of documents into a site, ie decored with a site template 36 * (eventually packaged as skin).</p> 37 * 38 * @author <a href="mailto:evenisse@codehaus.org">Emmanuel Venisse</a> 39 */ 40 public interface Renderer // TODO rename to SiteRenderer 41 { 42 /** 43 * Render a collection of documents into a site. 44 * 45 * @param documents the documents to render. 46 * @param siteRenderingContext the SiteRenderingContext to use. 47 * @param outputDirectory the output directory to write results. 48 * @throws RendererException if it bombs. 49 * @throws IOException if it bombs. 50 */ 51 void render( Collection<DocumentRenderer> documents, SiteRenderingContext siteRenderingContext, 52 File outputDirectory ) 53 throws RendererException, IOException; 54 55 /** 56 * Generate a document output integrated in a site from a document content, 57 * i.e. merge the document content into the site template. 58 * 59 * @param writer the Writer to use. 60 * @param content the document content to be merged. 61 * @param siteRenderingContext the SiteRenderingContext to use. 62 * @throws RendererException if it bombs. 63 * @since 1.8 64 */ 65 void mergeDocumentIntoSite( Writer writer, DocumentContent content, SiteRenderingContext siteRenderingContext ) 66 throws RendererException; 67 68 /** 69 * Create a Site Rendering Context for a site using a skin. 70 * 71 * @param skin a skin 72 * @param attributes attributes to use 73 * @param decoration a decoration model 74 * @param defaultWindowTitle default window title 75 * @param locale locale to use 76 * @return a SiteRenderingContext. 77 * @throws RendererException if it bombs. 78 * @throws java.io.IOException if it bombs. 79 * @since 1.7.3 was previously with skin as File instead of Artifact 80 */ 81 SiteRenderingContext createContextForSkin( Artifact skin, Map<String, ?> attributes, DecorationModel decoration, 82 String defaultWindowTitle, Locale locale ) 83 throws RendererException, IOException; 84 85 /** 86 * Copy resource files from skin, template, and site resources. 87 * 88 * @param siteRenderingContext the SiteRenderingContext to use. 89 * @param outputDirectory output directory as file 90 * @throws IOException if it bombs. 91 * @since 1.7 92 */ 93 void copyResources( SiteRenderingContext siteRenderingContext, File outputDirectory ) 94 throws IOException; 95 96 /** 97 * Locate Doxia document source files in the site source context. 98 * 99 * @param siteRenderingContext the SiteRenderingContext to use 100 * @param editable Doxia document renderer as editable? (should not set editable if generated Doxia source) 101 * @return the Doxia document renderers in a Map keyed by output file name. 102 * @throws IOException if it bombs. 103 * @throws RendererException if it bombs. 104 * @since 1.8 105 */ 106 Map<String, DocumentRenderer> locateDocumentFiles( SiteRenderingContext siteRenderingContext, boolean editable ) 107 throws IOException, RendererException; 108 109 /** 110 * Render a document written in a Doxia markup language. This method is an internal method, used by 111 * {@link DoxiaDocumentRenderer}. 112 * 113 * @param writer the writer to render the document to. 114 * @param docRenderingContext the document's rendering context, which is expected to have a non-null parser id. 115 * @param siteContext the site's rendering context 116 * @throws RendererException if it bombs. 117 * @throws FileNotFoundException if it bombs. 118 * @throws UnsupportedEncodingException if it bombs. 119 */ 120 void renderDocument( Writer writer, RenderingContext docRenderingContext, SiteRenderingContext siteContext ) 121 throws RendererException, FileNotFoundException, UnsupportedEncodingException; 122 }