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