1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 package org.apache.maven.doxia.tools; 20 21 import java.io.File; 22 import java.util.List; 23 import java.util.Locale; 24 import java.util.Map; 25 26 import org.apache.maven.artifact.Artifact; 27 import org.apache.maven.doxia.site.SiteModel; 28 import org.apache.maven.doxia.site.Skin; 29 import org.apache.maven.project.MavenProject; 30 import org.apache.maven.reporting.MavenReport; 31 import org.eclipse.aether.RepositorySystemSession; 32 import org.eclipse.aether.repository.RemoteRepository; 33 34 /** 35 * Tool to play with <a href="http://maven.apache.org/doxia/">Doxia</a> objects 36 * like <code>SiteModel</code>. 37 * 38 * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a> 39 */ 40 public interface SiteTool { 41 /** 42 * The locale by default for a Maven Site. 43 * 44 * @see Locale#ROOT 45 */ 46 Locale DEFAULT_LOCALE = Locale.ROOT; 47 48 /** 49 * Get a skin artifact from one of the repositories. 50 * 51 * @param repoSession the repository system session, not null. 52 * @param remoteProjectRepositories the Maven remote project repositories, not null. 53 * @param skin the Skin model, not null. 54 * @return the <code>Skin</code> artifact defined in a <code>SiteModel</code> from a given project 55 * @throws SiteToolException if any 56 */ 57 Artifact getSkinArtifactFromRepository( 58 RepositorySystemSession repoSession, List<RemoteRepository> remoteProjectRepositories, Skin skin) 59 throws SiteToolException; 60 61 /** 62 * Get a site descriptor from the project's site directory. 63 * 64 * @param siteDirectory the site directory, not null 65 * @param locale the locale wanted for the site descriptor, not null. Most specific 66 * to least specific lookup from <code>site_language_country_variant.xml</code>, 67 * <code>site_language_country.xml</code>, <code>site_language.xml}</code>, 68 * to <code>site.xml</code> as last resort for {@link Locale#ROOT}, if provided 69 * locale defines a variant and/or a country and/or a language. 70 * @return the most specific site descriptor file for the given locale 71 */ 72 File getSiteDescriptor(File siteDirectory, Locale locale); 73 74 /** 75 * Interpolating several expressions in the site descriptor content. Actually, the expressions can be in 76 * the project, the environment variables and the specific properties like <code>encoding</code>. 77 * <p> 78 * For instance: 79 * <dl> 80 * <dt>${project.name}</dt> 81 * <dd>The value from the POM of: 82 * <p> 83 * <project><br> 84 * <name>myProjectName</name><br> 85 * </project> 86 * </p></dd> 87 * <dt>${my.value}</dt> 88 * <dd>The value from the POM of: 89 * <p> 90 * <properties><br> 91 * <my.value>hello</my.value><br> 92 * </properties> 93 * </p></dd> 94 * <dt>${JAVA_HOME}</dt> 95 * <dd>The value of JAVA_HOME in the environment variables</dd> 96 * </dl> 97 * 98 * @param props a map used for interpolation, not null. 99 * @param aProject a Maven project, not null. 100 * @param siteDescriptorContent the site descriptor file, not null. 101 * @return the interpolated site descriptor content. 102 * @throws SiteToolException if errors happened during the interpolation. 103 */ 104 // used by maven-pdf-plugin (should not?) 105 String getInterpolatedSiteDescriptorContent( 106 Map<String, String> props, MavenProject aProject, String siteDescriptorContent) throws SiteToolException; 107 108 /** 109 * Get a site model for a project. 110 * 111 * @param siteDirectory the site directory, may be null if project from repository 112 * @param locale the locale used for the i18n in SiteModel, not null. 113 * See {@link #getSiteDescriptor(File, Locale)} for details. 114 * @param project the Maven project, not null. 115 * @param reactorProjects the Maven reactor projects, not null. 116 * @param repoSession the repository system session, not null. 117 * @param remoteProjectRepositories the Maven remote project repositories, not null. 118 * @return the <code>SiteModel</code> object corresponding to the <code>site.xml</code> file with some 119 * interpolations. 120 * @throws SiteToolException if any 121 * @since 1.7, was previously with other parameter types and order 122 */ 123 SiteModel getSiteModel( 124 File siteDirectory, 125 Locale locale, 126 MavenProject project, 127 List<MavenProject> reactorProjects, 128 RepositorySystemSession repoSession, 129 List<RemoteRepository> remoteProjectRepositories) 130 throws SiteToolException; 131 132 /** 133 * Populate the pre-defined <code>reports</code> menu of the site model, 134 * if used through <code><menu ref="reports"/></code>. Notice this menu reference is translated into 135 * 2 separate menus: "Project Information" and "Project Reports". 136 * 137 * @param siteModel the Doxia Sitetools SiteModel, not null. 138 * @param locale the locale used for the i18n in SiteModel, not null. 139 * See {@link #getSiteDescriptor(File, Locale)} for details. 140 * @param reportsPerCategory reports per category to put in "Reports" or "Information" menus, not null. 141 * @see MavenReport#CATEGORY_PROJECT_INFORMATION 142 * @see MavenReport#CATEGORY_PROJECT_REPORTS 143 */ 144 void populateReportsMenu(SiteModel siteModel, Locale locale, Map<String, List<MavenReport>> reportsPerCategory); 145 146 /** 147 * Extracts from a comma-separated list the locales that are available in <code>site-tool</code> 148 * resource bundle. 149 * 150 * @param locales A comma separated list of locales 151 * @return a list of <code>Locale</code>s. 152 * @since 1.7, was previously getAvailableLocales(String) 153 */ 154 List<Locale> getSiteLocales(String locales); 155 156 /** 157 * Calculate the relative path between two URLs or between two files. 158 * 159 * For example: 160 * <dl> 161 * <dt>to = "http://maven.apache.org" and from = "http://maven.apache.org"</dt> 162 * <dd>return ""</dd> 163 * <dt>to = "http://maven.apache.org" and from = "http://maven.apache.org/plugins/maven-site-plugin/"</dt> 164 * <dd>return "../.."</dd> 165 * <dt>to = "http://maven.apache.org/plugins/maven-site-plugin/" and from = "http://maven.apache.org"</dt> 166 * <dd>return "plugins/maven-site-plugin"</dd> 167 * <dt>to = "/myproject/myproject-module1" and from = "/myproject/myproject"</dt> 168 * <dd>return "../myproject-module1"</dd> 169 * </dl> 170 * <b>Note</b>: The file separator depends on the system. 171 * Maven-specific urls are supported, like <code>dav:https://dav.codehaus.org/</code> or 172 * <code>scm:svn:https://svn.apache.org/repos/asf</code>. 173 * 174 * @param to the <code>to</code> url of file as string 175 * @param from the <code>from</code> url of file as string 176 * @return a relative path from <code>from</code> to <code>to</code>. 177 */ 178 String getRelativePath(String to, String from); 179 }