1 package org.apache.maven.doxia.tools; 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.util.List; 24 import java.util.Locale; 25 import java.util.Map; 26 27 import org.apache.maven.artifact.Artifact; 28 import org.apache.maven.artifact.repository.ArtifactRepository; 29 import org.apache.maven.doxia.site.decoration.DecorationModel; 30 import org.apache.maven.project.MavenProject; 31 import org.apache.maven.reporting.MavenReport; 32 33 /** 34 * Tool to play with <a href="http://maven.apache.org/doxia/">Doxia</a> objects 35 * like <code>DecorationModel</code>. 36 * 37 * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a> 38 * @version $Id: SiteTool.html 1018749 2017-09-26 18:39:07Z rfscholte $ 39 */ 40 public interface SiteTool 41 { 42 /** Plexus Role */ 43 String ROLE = SiteTool.class.getName(); 44 45 /** 46 * The locale by default for a Maven Site 47 * @see Locale#ENGLISH 48 */ 49 Locale DEFAULT_LOCALE = Locale.ENGLISH; 50 51 /** 52 * Get a skin artifact from one of the repositories. 53 * 54 * @param localRepository the Maven local repository, not null. 55 * @param remoteArtifactRepositories the Maven remote repositories, not null. 56 * @param decoration the Doxia site descriptor model, not null. 57 * @return the <code>Skin</code> artifact defined in a <code>DecorationModel</code> from a given project and a 58 * local repository 59 * @throws SiteToolException if any 60 */ 61 Artifact getSkinArtifactFromRepository( ArtifactRepository localRepository, 62 List<ArtifactRepository> remoteArtifactRepositories, 63 DecorationModel decoration ) 64 throws SiteToolException; 65 66 /** 67 * Get the default skin artifact for a project from one of the repositories. 68 * 69 * @param localRepository the Maven local repository, not null. 70 * @param remoteArtifactRepositories the Maven remote repositories, not null. 71 * @return the default <code>Skin</code> artifact from a given project and a local repository 72 * @throws SiteToolException if any 73 * @see org.apache.maven.doxia.site.decoration.Skin#getDefaultSkin() 74 * @see #getSkinArtifactFromRepository(ArtifactRepository, List, DecorationModel) 75 */ 76 Artifact getDefaultSkinArtifact( ArtifactRepository localRepository, 77 List<ArtifactRepository> remoteArtifactRepositories ) 78 throws SiteToolException; 79 80 /** 81 * Get a site descriptor from the project's site directory. 82 * 83 * @param siteDirectory the site directory, not null 84 * @param locale the locale wanted for the site descriptor. If not null, searching for 85 * <code>site_<i>localeLanguage</i>.xml</code>, otherwise searching for <code>site.xml</code>. 86 * @return the site descriptor file 87 */ // used by maven-pdf-plugin (should not?) 88 File getSiteDescriptor( File siteDirectory, Locale locale ); 89 90 /** 91 * Interpolating several expressions in the site descriptor content. Actually, the expressions can be in 92 * the project, the environment variables and the specific properties like <code>encoding</code>. 93 * <p/> 94 * For instance: 95 * <dl> 96 * <dt>${project.name}</dt> 97 * <dd>The value from the POM of: 98 * <p> 99 * <project><br> 100 * <name>myProjectName</name><br> 101 * </project> 102 * </p></dd> 103 * <dt>${my.value}</dt> 104 * <dd>The value from the POM of: 105 * <p> 106 * <properties><br> 107 * <my.value>hello</my.value><br> 108 * </properties> 109 * </p></dd> 110 * <dt>${JAVA_HOME}</dt> 111 * <dd>The value of JAVA_HOME in the environment variables</dd> 112 * </dl> 113 * 114 * @param props a map used for interpolation, not null. 115 * @param aProject a Maven project, not null. 116 * @param siteDescriptorContent the site descriptor file, not null. 117 * @return the interpolated site descriptor content. 118 * @throws SiteToolException if errors happened during the interpolation. 119 */ // used by maven-pdf-plugin (should not?) 120 String getInterpolatedSiteDescriptorContent( Map<String, String> props, MavenProject aProject, 121 String siteDescriptorContent ) 122 throws SiteToolException; 123 124 /** 125 * Get a decoration model for a project. 126 * 127 * @param siteDirectory the site directory, may be null if project from repository 128 * @param locale the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm. 129 * @param project the Maven project, not null. 130 * @param reactorProjects the Maven reactor projects, not null. 131 * @param localRepository the Maven local repository, not null. 132 * @param repositories the Maven remote repositories, not null. 133 * @return the <code>DecorationModel</code> object corresponding to the <code>site.xml</code> file with some 134 * interpolations. 135 * @throws SiteToolException if any 136 * @since 1.7, was previously with other parameter types and order 137 */ 138 DecorationModel getDecorationModel( File siteDirectory, Locale locale, MavenProject project, 139 List<MavenProject> reactorProjects, ArtifactRepository localRepository, 140 List<ArtifactRepository> repositories ) 141 throws SiteToolException; 142 143 /** 144 * Populate the pre-defined <code>reports</code> menu of the decoration model, 145 * if used through <code><menu ref="reports"/></code>. Notice this menu reference is translated into 146 * 2 separate menus: "Project Information" and "Project Reports". 147 * 148 * @param decorationModel the Doxia Sitetools DecorationModel, not null. 149 * @param locale the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm. 150 * @param reportsPerCategory reports per category to put in "Reports" or "Information" menus, not null. 151 * @see MavenReport#CATEGORY_PROJECT_INFORMATION 152 * @see MavenReport#CATEGORY_PROJECT_REPORTS 153 */ 154 void populateReportsMenu( DecorationModel decorationModel, Locale locale, 155 Map<String, List<MavenReport>> reportsPerCategory ); 156 157 /** 158 * Extracts from a comma-separated list the locales that are available in <code>site-tool</code> 159 * resource bundle. Notice that <code>default</code> value will be changed to the default locale of 160 * the JVM. 161 * 162 * @param locales A comma separated list of locales 163 * @return a list of <code>Locale</code>, which at least contains the Maven default locale which is english 164 * @since 1.7, was previously getAvailableLocales(String) 165 */ 166 List<Locale> getSiteLocales( String locales ); 167 168 /** 169 * Calculate the relative path between two URLs or between two files. 170 * 171 * For example: 172 * <dl> 173 * <dt>to = "http://maven.apache.org" and from = "http://maven.apache.org"</dt> 174 * <dd>return ""</dd> 175 * <dt>to = "http://maven.apache.org" and from = "http://maven.apache.org/plugins/maven-site-plugin/"</dt> 176 * <dd>return "../.."</dd> 177 * <dt>to = "http://maven.apache.org/plugins/maven-site-plugin/" and from = "http://maven.apache.org"</dt> 178 * <dd>return "plugins/maven-site-plugin"</dd> 179 * <dt>to = "/myproject/myproject-module1" and from = "/myproject/myproject"</dt> 180 * <dd>return "../myproject-module1"</dd> 181 * </dl> 182 * <b>Note</b>: The file separator depends on the system. 183 * Maven-specific urls are supported, like <code>dav:https://dav.codehaus.org/</code> or 184 * <code>scm:svn:https://svn.apache.org/repos/asf</code>. 185 * 186 * @param to the <code>to</code> url of file as string 187 * @param from the <code>from</code> url of file as string 188 * @return a relative path from <code>from</code> to <code>to</code>. 189 */ 190 String getRelativePath( String to, String from ); 191 192 /** 193 * Returns the parent POM with interpolated URLs. 194 * If called from Maven 3, just returns <code>project.getParent()</code>, which is already 195 * interpolated. But when called from Maven 2, attempts to source this value from the 196 * <code>reactorProjects</code> parameters if available (reactor env model attributes 197 * are interpolated), or if the reactor is unavailable (-N) resorts to the 198 * <code>project.getParent().getUrl()</code> value which will NOT have been interpolated. 199 * 200 * @param aProject a Maven project, not null. 201 * @param reactorProjects the Maven reactor projects, not null. 202 * @param localRepository the Maven local repository, not null. 203 * @return the parent project with interpolated URLs. 204 */ 205 MavenProject getParentProject( MavenProject aProject, List<MavenProject> reactorProjects, 206 ArtifactRepository localRepository ); 207 }