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 maven-doxia-tools Show documentation
A collection of tools to help the integration of Doxia in Maven plugins.
There is a newer version: 1.4
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;

/**
 * Tool to play with Doxia objects
 * like DecorationModel.
 *
 * @author Vincent Siveton
 * @version $Id: SiteTool.java 664310 2008-06-07 10:30:12Z bentmann $
 */
public interface SiteTool
{
    /** Plexus Role */
    String ROLE = SiteTool.class.getName();

    /**
     * The locale by default for all default bundles
     * @see Locale#ENGLISH
     */
    Locale DEFAULT_LOCALE = Locale.ENGLISH;

    /**
     * Get a site descriptor defined in the decoration 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;

    /**
     * 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.
     *
     * @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 );

    /**
     * Get a site descriptor from the project's base direcory.
     *
     * @param siteDirectory The path to the directory containing the site.xml file, relative to the
     * project base directory. If null, using by default "src/site".
     * @param basedir 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 relative file, i.e. src/site/site.xml, depending on parameter values.
     */
    File getSiteDescriptorFromBasedir( String siteDirectory, File basedir, Locale locale );

    /**
     * Get a site descriptor from one of the repositories.
     *
     * @param project the Maven project, not null.
     * @param localRepository the Maven local repository, not null.
     * @param repositories the Maven remote repositories, 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 into the local repository after download of it from repositories or null if not
     * found in repositories.
     * @throws SiteToolException if any
     */
    File getSiteDescriptorFromRepository( MavenProject project, ArtifactRepository localRepository, List repositories,
                                          Locale locale )
        throws SiteToolException;

    /**
     * Get a decoration model for a project.
     *
     * @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.
     * @param siteDirectory The path to the directory containing the site.xml file, relative to the
     * project base directory. If null, using by default "src/site".
     * @param locale the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm.
     * @param inputEncoding the input encoding of the site descriptor, not null.
     * @param outputEncoding the output encoding wanted, not null.
     * @return the DecorationModel object corresponding to the site.xml file with some
     * interpolations.
     * @throws SiteToolException if any
     */
    DecorationModel getDecorationModel( MavenProject project, List reactorProjects, ArtifactRepository localRepository,
                                        List repositories, String siteDirectory, Locale locale, String inputEncoding,
                                        String outputEncoding )
        throws SiteToolException;

    /**
     * Populate the report menu part of the decoration model.
     *
     * @param decorationModel the Doxia DecorationModel, not null.
     * @param locale the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm.
     * @param categories a map to put on the decoration model, not null.
     */
    void populateReportsMenu( DecorationModel decorationModel, Locale locale, Map categories );

    /**
     * Interpolating several expressions in the site descriptor content. Actually, the expressions could 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 inputEncoding the input encoding of the site descriptor, not null.
     * @param outputEncoding the output encoding wanted, not null.
     * @param siteDescriptorContent the site descriptor file, not null.
     * @return the site descriptor content based on the site.xml file with interpolated strings.
     * @throws SiteToolException if errors happened during the interpolation.
     */
    String getInterpolatedSiteDescriptorContent( Map props, MavenProject aProject, String siteDescriptorContent,
                                                 String inputEncoding, String outputEncoding )
        throws SiteToolException;

    /**
     * Returns the parent POM with interpolated URLs. 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.
     * 
     * TODO: once bug is fixed in Maven proper, remove this.
     *
     * @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 );

    /**
     * Populate the parent menu part of the decoration model.
     *
     * @param decorationModel the Doxia DecorationModel, not null.
     * @param locale the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm.
     * @param project a Maven project, not null.
     * @param parentProject a Maven parent project, not null.
     * @param keepInheritedRefs used for inherited references.
     */
    void populateProjectParentMenu( DecorationModel decorationModel, Locale locale, MavenProject project,
                                    MavenProject parentProject, boolean keepInheritedRefs );

    /**
     * Populate the modules menu part of the decoration model.
     *
     * @param project a Maven project, not null.
     * @param reactorProjects the Maven reactor projects, not null.
     * @param localRepository the Maven local repository, not null.
     * @param decorationModel the Doxia site descriptor model, not null.
     * @param locale the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm.
     * @param keepInheritedRefs used for inherited references.
     * @throws SiteToolException if any
     */
    void populateModules( MavenProject project, List reactorProjects, ArtifactRepository localRepository,
                          DecorationModel decorationModel, Locale locale, boolean keepInheritedRefs )
        throws SiteToolException;

    /**
     * Init the localesList variable.
     * 
If the locales variable is available, the first valid token will be the
     * defaultLocale for this instance of the Java Virtual Machine.
     *
     * @param locales A comma separated list of locales supported by Maven. The first valid token will be the
     * default Locale for this instance of the Java Virtual Machine.
     * @return a list of Locale
     */
    List getAvailableLocales( String locales );

    /**
     * Converts a locale code like "en", "en_US" or "en_US_win" to a java.util.Locale
     * object.
     * If localeCode = default, return the current value of the default locale for this instance
     * of the Java Virtual Machine.
     *
     * @param localeCode the locale code string.
     * @return a java.util.Locale object instancied or null if errors occurred
     * @see java.util.Locale#getDefault()
     */
    Locale codeToLocale( String localeCode );
}