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 1098159 2011-04-30 21:07:49Z dennisl $
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 * @param inputEncoding the input encoding of the site descriptor, not null.
141 * @param outputEncoding the output encoding wanted, not null.
142 * @return the <code>DecorationModel</code> object corresponding to the <code>site.xml</code> file with some
143 * interpolations.
144 * @throws SiteToolException if any
145 */
146 DecorationModel getDecorationModel( MavenProject project, List<MavenProject> reactorProjects,
147 ArtifactRepository localRepository, List<ArtifactRepository> repositories,
148 String siteDirectory, Locale locale, String inputEncoding,
149 String outputEncoding )
150 throws SiteToolException;
151
152 /**
153 * Populate the reports menu part of the decoration model.
154 *
155 * @param decorationModel the Doxia DecorationModel, not null.
156 * @param locale the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm.
157 * @param categories a map to put on the decoration model, not null.
158 */
159 void populateReportsMenu( DecorationModel decorationModel, Locale locale,
160 Map<String, List<MavenReport>> categories );
161
162 /**
163 * Interpolating several expressions in the site descriptor content. Actually, the expressions can be in
164 * the project, the environment variables and the specific properties like <code>encoding</code>.
165 * <p/>
166 * For instance:
167 * <dl>
168 * <dt>${project.name}</dt>
169 * <dd>The value from the POM of:
170 * <p>
171 * <project><br>
172 * <name>myProjectName</name><br>
173 * </project>
174 * </p></dd>
175 * <dt>${my.value}</dt>
176 * <dd>The value from the POM of:
177 * <p>
178 * <properties><br>
179 * <my.value>hello</my.value><br>
180 * </properties>
181 * </p></dd>
182 * <dt>${JAVA_HOME}</dt>
183 * <dd>The value of JAVA_HOME in the environment variables</dd>
184 * </dl>
185 *
186 * @param props a map used for interpolation, not null.
187 * @param aProject a Maven project, not null.
188 * @param inputEncoding the input encoding of the site descriptor, not null.
189 * @param outputEncoding the output encoding wanted, not null.
190 * @param siteDescriptorContent the site descriptor file, not null.
191 * @return the site descriptor content based on the <code>site.xml</code> file with interpolated strings.
192 * @throws SiteToolException if errors happened during the interpolation.
193 */
194 String getInterpolatedSiteDescriptorContent( Map<String, String> props, MavenProject aProject,
195 String siteDescriptorContent, String inputEncoding,
196 String outputEncoding )
197 throws SiteToolException;
198
199 /**
200 * Returns the parent POM with interpolated URLs. Attempts to source this value from the
201 * <code>reactorProjects</code> parameters if available (reactor env model attributes
202 * are interpolated), or if the reactor is unavailable (-N) resorts to the
203 * <code>project.getParent().getUrl()</code> value which will NOT have been interpolated.
204 * <p/>
205 * TODO: once bug is fixed in Maven proper, remove this.
206 *
207 * @param aProject a Maven project, not null.
208 * @param reactorProjects the Maven reactor projects, not null.
209 * @param localRepository the Maven local repository, not null.
210 * @return the parent project with interpolated URLs.
211 */
212 MavenProject getParentProject( MavenProject aProject, List<MavenProject> reactorProjects,
213 ArtifactRepository localRepository );
214
215 /**
216 * Populate the parent menu part of the decoration model.
217 *
218 * @param decorationModel the Doxia DecorationModel, not null.
219 * @param locale the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm.
220 * @param project a Maven project, not null.
221 * @param parentProject a Maven parent project, not null.
222 * @param keepInheritedRefs used for inherited references.
223 */
224 void populateParentMenu( DecorationModel decorationModel, Locale locale, MavenProject project,
225 MavenProject parentProject, boolean keepInheritedRefs );
226
227 /**
228 * Populate the parent menu part of the decoration model.
229 *
230 * @param decorationModel the Doxia DecorationModel, not null.
231 * @param locale the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm.
232 * @param project a Maven project, not null.
233 * @param parentProject a Maven parent project, not null.
234 * @param keepInheritedRefs used for inherited references.
235 * @deprecated Please use
236 * {@link #populateParentMenu(DecorationModel, Locale, MavenProject, MavenProject, boolean)} instead
237 */
238 void populateProjectParentMenu( DecorationModel decorationModel, Locale locale, MavenProject project,
239 MavenProject parentProject, boolean keepInheritedRefs );
240
241 /**
242 * Populate the modules menu part of the decoration model.
243 *
244 * @param project a Maven project, not null.
245 * @param reactorProjects the Maven reactor projects, not null.
246 * @param localRepository the Maven local repository, not null.
247 * @param decorationModel the Doxia site descriptor model, not null.
248 * @param locale the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm.
249 * @param keepInheritedRefs used for inherited references.
250 * @throws SiteToolException if any
251 * @deprecated Please use
252 * {@link #populateModulesMenu(MavenProject, List, ArtifactRepository, DecorationModel, Locale, boolean)}
253 * instead
254 */
255 void populateModules( MavenProject project, List<MavenProject> reactorProjects, ArtifactRepository localRepository,
256 DecorationModel decorationModel, Locale locale, boolean keepInheritedRefs )
257 throws SiteToolException;
258
259 /**
260 * Populate the modules menu part of the decoration model.
261 *
262 * @param project a Maven project, not null.
263 * @param reactorProjects the Maven reactor projects, not null.
264 * @param localRepository the Maven local repository, not null.
265 * @param decorationModel the Doxia site descriptor model, not null.
266 * @param locale the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm.
267 * @param keepInheritedRefs used for inherited references.
268 * @throws SiteToolException if any
269 */
270 void populateModulesMenu( MavenProject project, List<MavenProject> reactorProjects,
271 ArtifactRepository localRepository, DecorationModel decorationModel, Locale locale,
272 boolean keepInheritedRefs )
273 throws SiteToolException;
274
275 /**
276 * Init the <code>localesList</code> variable.
277 * <p>If the <code>locales</code> variable is available, the first valid token will be the
278 * <code>defaultLocale</code> for this instance of the Java Virtual Machine.</p>
279 *
280 * @param locales A comma separated list of locales supported by Maven. The first valid token will be the
281 * default Locale for this instance of the Java Virtual Machine.
282 * @return a list of <code>Locale</code>
283 */
284 List<Locale> getAvailableLocales( String locales );
285
286 /**
287 * Converts a locale code like "en", "en_US" or "en_US_win" to a <code>java.util.Locale</code>
288 * object.
289 * <p>If localeCode = <code>default</code>, return the current value of the default locale for this instance
290 * of the Java Virtual Machine.</p>
291 *
292 * @param localeCode the locale code string.
293 * @return a java.util.Locale object instanced or null if errors occurred
294 * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Locale.html">java.util.Locale#getDefault()</a>
295 */
296 Locale codeToLocale( String localeCode );
297 }