org.apache.maven.doxia.tools.SiteTool Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of doxia-integration-tools Show documentation
Show all versions of doxia-integration-tools Show documentation
A collection of tools to help the integration of Doxia Sitetools in Maven plugins.
package org.apache.maven.doxia.tools;
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
import java.io.File;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import org.apache.maven.artifact.Artifact;
import org.apache.maven.artifact.repository.ArtifactRepository;
import org.apache.maven.doxia.site.decoration.DecorationModel;
import org.apache.maven.project.MavenProject;
import org.apache.maven.reporting.MavenReport;
/**
* Tool to play with Doxia objects
* like DecorationModel.
*
* @author Vincent Siveton
*/
public interface SiteTool
{
/** Plexus Role */
String ROLE = SiteTool.class.getName();
/**
* The locale by default for a Maven Site
* @see Locale#ENGLISH
*/
Locale DEFAULT_LOCALE = Locale.ENGLISH;
/**
* Get a skin artifact from one of the repositories.
*
* @param localRepository the Maven local repository, not null.
* @param remoteArtifactRepositories the Maven remote repositories, not null.
* @param decoration the Doxia site descriptor model, not null.
* @return the Skin artifact defined in a DecorationModel from a given project and a
* local repository
* @throws SiteToolException if any
*/
Artifact getSkinArtifactFromRepository( ArtifactRepository localRepository,
List remoteArtifactRepositories,
DecorationModel decoration )
throws SiteToolException;
/**
* Get the default skin artifact for a project from one of the repositories.
*
* @param localRepository the Maven local repository, not null.
* @param remoteArtifactRepositories the Maven remote repositories, not null.
* @return the default Skin artifact from a given project and a local repository
* @throws SiteToolException if any
* @see org.apache.maven.doxia.site.decoration.Skin#getDefaultSkin()
* @see #getSkinArtifactFromRepository(ArtifactRepository, List, DecorationModel)
*/
Artifact getDefaultSkinArtifact( ArtifactRepository localRepository,
List remoteArtifactRepositories )
throws SiteToolException;
/**
* Get a site descriptor from the project's site directory.
*
* @param siteDirectory the site directory, not null
* @param locale the locale wanted for the site descriptor. If not null, searching for
* site_localeLanguage.xml, otherwise searching for site.xml.
* @return the site descriptor file
*/ // used by maven-pdf-plugin (should not?)
File getSiteDescriptor( File siteDirectory, Locale locale );
/**
* Interpolating several expressions in the site descriptor content. Actually, the expressions can be in
* the project, the environment variables and the specific properties like encoding.
*
* For instance:
*
* - ${project.name}
* - The value from the POM of:
*
* <project>
* <name>myProjectName</name>
* </project>
*
* - ${my.value}
* - The value from the POM of:
*
* <properties>
* <my.value>hello</my.value>
* </properties>
*
* - ${JAVA_HOME}
* - The value of JAVA_HOME in the environment variables
*
*
* @param props a map used for interpolation, not null.
* @param aProject a Maven project, not null.
* @param siteDescriptorContent the site descriptor file, not null.
* @return the interpolated site descriptor content.
* @throws SiteToolException if errors happened during the interpolation.
*/ // used by maven-pdf-plugin (should not?)
String getInterpolatedSiteDescriptorContent( Map props, MavenProject aProject,
String siteDescriptorContent )
throws SiteToolException;
/**
* Get a decoration model for a project.
*
* @param siteDirectory the site directory, may be null if project from repository
* @param locale the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm.
* @param project the Maven project, not null.
* @param reactorProjects the Maven reactor projects, not null.
* @param localRepository the Maven local repository, not null.
* @param repositories the Maven remote repositories, not null.
* @return the DecorationModel object corresponding to the site.xml file with some
* interpolations.
* @throws SiteToolException if any
* @since 1.7, was previously with other parameter types and order
*/
DecorationModel getDecorationModel( File siteDirectory, Locale locale, MavenProject project,
List reactorProjects, ArtifactRepository localRepository,
List repositories )
throws SiteToolException;
/**
* Populate the pre-defined reports menu of the decoration model,
* if used through <menu ref="reports"/>. Notice this menu reference is translated into
* 2 separate menus: "Project Information" and "Project Reports".
*
* @param decorationModel the Doxia Sitetools DecorationModel, not null.
* @param locale the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm.
* @param reportsPerCategory reports per category to put in "Reports" or "Information" menus, not null.
* @see MavenReport#CATEGORY_PROJECT_INFORMATION
* @see MavenReport#CATEGORY_PROJECT_REPORTS
*/
void populateReportsMenu( DecorationModel decorationModel, Locale locale,
Map> reportsPerCategory );
/**
* Extracts from a comma-separated list the locales that are available in site-tool
* resource bundle. Notice that default value will be changed to the default locale of
* the JVM.
*
* @param locales A comma separated list of locales
* @return a list of Locale, which at least contains the Maven default locale which is english
* @since 1.7, was previously getAvailableLocales(String)
*/
List getSiteLocales( String locales );
/**
* Calculate the relative path between two URLs or between two files.
*
* For example:
*
* - to = "http://maven.apache.org" and from = "http://maven.apache.org"
* - return ""
* - to = "http://maven.apache.org" and from = "http://maven.apache.org/plugins/maven-site-plugin/"
* - return "../.."
* - to = "http://maven.apache.org/plugins/maven-site-plugin/" and from = "http://maven.apache.org"
* - return "plugins/maven-site-plugin"
* - to = "/myproject/myproject-module1" and from = "/myproject/myproject"
* - return "../myproject-module1"
*
* Note: The file separator depends on the system.
* Maven-specific urls are supported, like dav:https://dav.codehaus.org/ or
* scm:svn:https://svn.apache.org/repos/asf.
*
* @param to the to url of file as string
* @param from the from url of file as string
* @return a relative path from from to to.
*/
String getRelativePath( String to, String from );
/**
* Returns the parent POM with interpolated URLs.
* If called from Maven 3, just returns project.getParent(), which is already
* interpolated. But when called from Maven 2, attempts to source this value from the
* reactorProjects parameters if available (reactor env model attributes
* are interpolated), or if the reactor is unavailable (-N) resorts to the
* project.getParent().getUrl() value which will NOT have been interpolated.
*
* @param aProject a Maven project, not null.
* @param reactorProjects the Maven reactor projects, not null.
* @param localRepository the Maven local repository, not null.
* @return the parent project with interpolated URLs.
*/
MavenProject getParentProject( MavenProject aProject, List reactorProjects,
ArtifactRepository localRepository );
}