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.doxia.site.decoration.DecorationModel;
28  import org.apache.maven.doxia.site.decoration.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>DecorationModel</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>DecorationModel</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      // used by maven-pdf-plugin (should not?)
73      File getSiteDescriptor(File siteDirectory, Locale locale);
74  
75      /**
76       * Interpolating several expressions in the site descriptor content. Actually, the expressions can be in
77       * the project, the environment variables and the specific properties like <code>encoding</code>.
78       * <p>
79       * For instance:
80       * <dl>
81       * <dt>${project.name}</dt>
82       * <dd>The value from the POM of:
83       * <p>
84       * &lt;project&gt;<br>
85       * &nbsp;&nbsp;&lt;name&gt;myProjectName&lt;/name&gt;<br>
86       * &lt;/project&gt;
87       * </p></dd>
88       * <dt>${my.value}</dt>
89       * <dd>The value from the POM of:
90       * <p>
91       * &lt;properties&gt;<br>
92       * &nbsp;&nbsp;&lt;my.value&gt;hello&lt;/my.value&gt;<br>
93       * &lt;/properties&gt;
94       * </p></dd>
95       * <dt>${JAVA_HOME}</dt>
96       * <dd>The value of JAVA_HOME in the environment variables</dd>
97       * </dl>
98       *
99       * @param props a map used for interpolation, not null.
100      * @param aProject a Maven project, not null.
101      * @param siteDescriptorContent the site descriptor file, not null.
102      * @return the interpolated site descriptor content.
103      * @throws SiteToolException if errors happened during the interpolation.
104      */
105     // used by maven-pdf-plugin (should not?)
106     String getInterpolatedSiteDescriptorContent(
107             Map<String, String> props, MavenProject aProject, String siteDescriptorContent) throws SiteToolException;
108 
109     /**
110      * Get a decoration model for a project.
111      *
112      * @param siteDirectory the site directory, may be null if project from repository
113      * @param locale the locale used for the i18n in DecorationModel, not null.
114      * See {@link #getSiteDescriptor(File, Locale)} for details.
115      * @param project the Maven project, not null.
116      * @param reactorProjects the Maven reactor projects, not null.
117      * @param repoSession the repository system session, not null.
118      * @param remoteProjectRepositories the Maven remote project repositories, not null.
119      * @return the <code>DecorationModel</code> object corresponding to the <code>site.xml</code> file with some
120      * interpolations.
121      * @throws SiteToolException if any
122      * @since 1.7, was previously with other parameter types and order
123      */
124     DecorationModel getDecorationModel(
125             File siteDirectory,
126             Locale locale,
127             MavenProject project,
128             List<MavenProject> reactorProjects,
129             RepositorySystemSession repoSession,
130             List<RemoteRepository> remoteProjectRepositories)
131             throws SiteToolException;
132 
133     /**
134      * Populate the pre-defined <code>reports</code> menu of the decoration model,
135      * if used through <code>&lt;menu ref="reports"/&gt;</code>. Notice this menu reference is translated into
136      * 2 separate menus: "Project Information" and "Project Reports".
137      *
138      * @param decorationModel the Doxia Sitetools DecorationModel, not null.
139      * @param locale the locale used for the i18n in DecorationModel, not null.
140      * See {@link #getSiteDescriptor(File, Locale)} for details.
141      * @param reportsPerCategory reports per category to put in "Reports" or "Information" menus, not null.
142      * @see MavenReport#CATEGORY_PROJECT_INFORMATION
143      * @see MavenReport#CATEGORY_PROJECT_REPORTS
144      */
145     void populateReportsMenu(
146             DecorationModel decorationModel, Locale locale, Map<String, List<MavenReport>> reportsPerCategory);
147 
148     /**
149      * Extracts from a comma-separated list the locales that are available in <code>site-tool</code>
150      * resource bundle.
151      *
152      * @param locales A comma separated list of locales
153      * @return a list of <code>Locale</code>s.
154      * @since 1.7, was previously getAvailableLocales(String)
155      */
156     List<Locale> getSiteLocales(String locales);
157 
158     /**
159      * Calculate the relative path between two URLs or between two files.
160      *
161      * For example:
162      * <dl>
163      * <dt>to = "http://maven.apache.org" and from = "http://maven.apache.org"</dt>
164      * <dd>return ""</dd>
165      * <dt>to = "http://maven.apache.org" and from = "http://maven.apache.org/plugins/maven-site-plugin/"</dt>
166      * <dd>return "../.."</dd>
167      * <dt>to = "http://maven.apache.org/plugins/maven-site-plugin/" and from = "http://maven.apache.org"</dt>
168      * <dd>return "plugins/maven-site-plugin"</dd>
169      * <dt>to = "/myproject/myproject-module1" and from = "/myproject/myproject"</dt>
170      * <dd>return "../myproject-module1"</dd>
171      * </dl>
172      * <b>Note</b>: The file separator depends on the system.
173      * Maven-specific urls are supported, like <code>dav:https://dav.codehaus.org/</code> or
174      * <code>scm:svn:https://svn.apache.org/repos/asf</code>.
175      *
176      * @param to the <code>to</code> url of file as string
177      * @param from the <code>from</code> url of file as string
178      * @return a relative path from <code>from</code> to <code>to</code>.
179      */
180     String getRelativePath(String to, String from);
181 }