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.java 1604423 2014-06-21 15:34:44Z hboutemy $ 39 */ 40 public interface SiteTool 41 { 42 /** Plexus Role */ 43 String ROLE = SiteTool.class.getName(); 44 45 /** 46 * The locale by default for all default bundles 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 * Calculate the relative path between two URLs or between two files. 82 * 83 * For example: 84 * <dl> 85 * <dt>to = "http://maven.apache.org" and from = "http://maven.apache.org"</dt> 86 * <dd>return ""</dd> 87 * <dt>to = "http://maven.apache.org" and from = "http://maven.apache.org/plugins/maven-site-plugin/"</dt> 88 * <dd>return "../.."</dd> 89 * <dt>to = "http://maven.apache.org/plugins/maven-site-plugin/" and from = "http://maven.apache.org"</dt> 90 * <dd>return "plugins/maven-site-plugin"</dd> 91 * <dt>to = "/myproject/myproject-module1" and from = "/myproject/myproject"</dt> 92 * <dd>return "../myproject-module1"</dd> 93 * </dl> 94 * <b>Note</b>: The file separator depends on the system. 95 * 96 * @param to the <code>to</code> url of file as string 97 * @param from the <code>from</code> url of file as string 98 * @return a relative path from <code>from</code> to <code>to</code>. 99 */ 100 String getRelativePath( String to, String from ); 101 102 /** 103 * Get a site descriptor from the project's base directory. 104 * 105 * @param siteDirectory The path to the directory containing the <code>site.xml</code> file, relative to the 106 * project base directory. If null, using by default "src/site". 107 * @param basedir not null. 108 * @param locale the locale wanted for the site descriptor. If not null, searching for 109 * <code>site_<i>localeLanguage</i>.xml</code>, otherwise searching for <code>site.xml</code>. 110 * @return the site descriptor relative file, i.e. <code>src/site/site.xml</code>, depending on parameter values. 111 */ 112 File getSiteDescriptorFromBasedir( String siteDirectory, File basedir, Locale locale ); 113 114 /** 115 * Get a site descriptor from one of the repositories. 116 * 117 * @param project the Maven project, not null. 118 * @param localRepository the Maven local repository, not null. 119 * @param repositories the Maven remote repositories, not null. 120 * @param locale the locale wanted for the site descriptor. If not null, searching for 121 * <code>site_<i>localeLanguage</i>.xml</code>, otherwise searching for <code>site.xml</code>. 122 * @return the site descriptor into the local repository after download of it from repositories or null if not 123 * found in repositories. 124 * @throws SiteToolException if any 125 */ 126 File getSiteDescriptorFromRepository( MavenProject project, ArtifactRepository localRepository, 127 List<ArtifactRepository> repositories, Locale locale ) 128 throws SiteToolException; 129 130 /** 131 * Get a decoration model for a project. 132 * 133 * @param project the Maven project, not null. 134 * @param reactorProjects the Maven reactor projects, not null. 135 * @param localRepository the Maven local repository, not null. 136 * @param repositories the Maven remote repositories, not null. 137 * @param siteDirectory The path to the directory containing the <code>site.xml</code> file, relative to the 138 * project base directory. If null, using by default "src/site". 139 * @param locale the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm. 140 * @return the <code>DecorationModel</code> object corresponding to the <code>site.xml</code> file with some 141 * interpolations. 142 * @throws SiteToolException if any 143 */ 144 DecorationModel getDecorationModel( MavenProject project, List<MavenProject> reactorProjects, 145 ArtifactRepository localRepository, List<ArtifactRepository> repositories, 146 String siteDirectory, Locale locale ) 147 throws SiteToolException; 148 149 /** 150 * Populate the reports menu part of the decoration model. 151 * 152 * @param decorationModel the Doxia DecorationModel, not null. 153 * @param locale the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm. 154 * @param categories a map to put on the decoration model, not null. 155 */ 156 void populateReportsMenu( DecorationModel decorationModel, Locale locale, 157 Map<String, List<MavenReport>> categories ); 158 159 /** 160 * Interpolating several expressions in the site descriptor content. Actually, the expressions can be in 161 * the project, the environment variables and the specific properties like <code>encoding</code>. 162 * <p/> 163 * For instance: 164 * <dl> 165 * <dt>${project.name}</dt> 166 * <dd>The value from the POM of: 167 * <p> 168 * <project><br> 169 * <name>myProjectName</name><br> 170 * </project> 171 * </p></dd> 172 * <dt>${my.value}</dt> 173 * <dd>The value from the POM of: 174 * <p> 175 * <properties><br> 176 * <my.value>hello</my.value><br> 177 * </properties> 178 * </p></dd> 179 * <dt>${JAVA_HOME}</dt> 180 * <dd>The value of JAVA_HOME in the environment variables</dd> 181 * </dl> 182 * 183 * @param props a map used for interpolation, not null. 184 * @param aProject a Maven project, not null. 185 * @param inputEncoding the input encoding of the site descriptor, not null. 186 * @param outputEncoding the output encoding wanted, not null. 187 * @param siteDescriptorContent the site descriptor file, not null. 188 * @return the site descriptor content based on the <code>site.xml</code> file with interpolated strings. 189 * @throws SiteToolException if errors happened during the interpolation. 190 */ 191 String getInterpolatedSiteDescriptorContent( Map<String, String> props, MavenProject aProject, 192 String siteDescriptorContent ) 193 throws SiteToolException; 194 195 /** 196 * Returns the parent POM with interpolated URLs. Attempts to source this value from the 197 * <code>reactorProjects</code> parameters if available (reactor env model attributes 198 * are interpolated), or if the reactor is unavailable (-N) resorts to the 199 * <code>project.getParent().getUrl()</code> value which will NOT have been interpolated. 200 * <p/> 201 * TODO: once bug is fixed in Maven proper, remove this. 202 * 203 * @param aProject a Maven project, not null. 204 * @param reactorProjects the Maven reactor projects, not null. 205 * @param localRepository the Maven local repository, not null. 206 * @return the parent project with interpolated URLs. 207 */ 208 MavenProject getParentProject( MavenProject aProject, List<MavenProject> reactorProjects, 209 ArtifactRepository localRepository ); 210 211 /** 212 * Populate the parent menu part of the decoration model. 213 * 214 * @param decorationModel the Doxia DecorationModel, not null. 215 * @param locale the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm. 216 * @param project a Maven project, not null. 217 * @param parentProject a Maven parent project, not null. 218 * @param keepInheritedRefs used for inherited references. 219 */ 220 void populateParentMenu( DecorationModel decorationModel, Locale locale, MavenProject project, 221 MavenProject parentProject, boolean keepInheritedRefs ); 222 223 /** 224 * Populate the parent menu part of the decoration model. 225 * 226 * @param decorationModel the Doxia DecorationModel, not null. 227 * @param locale the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm. 228 * @param project a Maven project, not null. 229 * @param parentProject a Maven parent project, not null. 230 * @param keepInheritedRefs used for inherited references. 231 * @deprecated Please use 232 * {@link #populateParentMenu(DecorationModel, Locale, MavenProject, MavenProject, boolean)} instead 233 */ 234 void populateProjectParentMenu( DecorationModel decorationModel, Locale locale, MavenProject project, 235 MavenProject parentProject, boolean keepInheritedRefs ); 236 237 /** 238 * Populate the modules menu part of the decoration model. 239 * 240 * @param project a Maven project, not null. 241 * @param reactorProjects the Maven reactor projects, not null. 242 * @param localRepository the Maven local repository, not null. 243 * @param decorationModel the Doxia site descriptor model, not null. 244 * @param locale the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm. 245 * @param keepInheritedRefs used for inherited references. 246 * @throws SiteToolException if any 247 * @deprecated Please use 248 * {@link #populateModulesMenu(MavenProject, List, ArtifactRepository, DecorationModel, Locale, boolean)} 249 * instead 250 */ 251 void populateModules( MavenProject project, List<MavenProject> reactorProjects, ArtifactRepository localRepository, 252 DecorationModel decorationModel, Locale locale, boolean keepInheritedRefs ) 253 throws SiteToolException; 254 255 /** 256 * Populate the modules menu part of the decoration model. 257 * 258 * @param project a Maven project, not null. 259 * @param reactorProjects the Maven reactor projects, not null. 260 * @param localRepository the Maven local repository, not null. 261 * @param decorationModel the Doxia site descriptor model, not null. 262 * @param locale the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm. 263 * @param keepInheritedRefs used for inherited references. 264 * @throws SiteToolException if any 265 */ 266 void populateModulesMenu( MavenProject project, List<MavenProject> reactorProjects, 267 ArtifactRepository localRepository, DecorationModel decorationModel, Locale locale, 268 boolean keepInheritedRefs ) 269 throws SiteToolException; 270 271 /** 272 * Init the <code>localesList</code> variable. 273 * <p>If the <code>locales</code> variable is available, the first valid token will be the 274 * <code>defaultLocale</code> for this instance of the Java Virtual Machine.</p> 275 * 276 * @param locales A comma separated list of locales supported by Maven. The first valid token will be the 277 * default Locale for this instance of the Java Virtual Machine. 278 * @return a list of <code>Locale</code> 279 */ 280 List<Locale> getAvailableLocales( String locales ); 281 282 /** 283 * Converts a locale code like "en", "en_US" or "en_US_win" to a <code>java.util.Locale</code> 284 * object. 285 * <p>If localeCode = <code>default</code>, return the current value of the default locale for this instance 286 * of the Java Virtual Machine.</p> 287 * 288 * @param localeCode the locale code string. 289 * @return a java.util.Locale object instanced or null if errors occurred 290 * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Locale.html">java.util.Locale#getDefault()</a> 291 */ 292 Locale codeToLocale( String localeCode ); 293 }