Package org.apache.maven.doxia.tools

## Interface SiteTool

All Known Implementing Classes:
  `DefaultSiteTool`

    public interface SiteTool

Tool to play with Doxia objects like `DecorationModel`.

Version:
  $Id: SiteTool.java 1725099 2016-01-17 16:17:34Z hboutemy $
Author:
  Vincent Siveton

### Field Summary

Fields
`static java.util.Locale` `DEFAULT_LOCALE` The locale by default for a Maven Site
`static java.lang.String` `ROLE` Plexus Role

### Method Summary

All Methods Instance Methods Abstract Methods

`DecorationModel`

`getDecorationModel​(java.io.File siteDirectory, java.util.Locale locale, org.apache.maven.project.MavenProject project, java.util.List<org.apache.maven.project.MavenProject> reactorProjects, org.apache.maven.artifact.repository.ArtifactRepository localRepository, java.util.List<org.apache.maven.artifact.repository.ArtifactRepository> repositories)`

Get a decoration model for a project.

`org.apache.maven.artifact.Artifact` `getDefaultSkinArtifact​(org.apache.maven.artifact.repository.ArtifactRepository localRepository, java.util.List<org.apache.maven.artifact.repository.ArtifactRepository> remoteArtifactRepositories)` Get the default skin artifact for a project from one of the repositories.
`java.lang.String` `getInterpolatedSiteDescriptorContent​(java.util.Map<java.lang.String,​java.lang.String> props, org.apache.maven.project.MavenProject aProject, java.lang.String siteDescriptorContent)` Interpolating several expressions in the site descriptor content.
`org.apache.maven.project.MavenProject` `getParentProject​(org.apache.maven.project.MavenProject aProject, java.util.List<org.apache.maven.project.MavenProject> reactorProjects, org.apache.maven.artifact.repository.ArtifactRepository localRepository)` Returns the parent POM with interpolated URLs.
`java.lang.String` `getRelativePath​(java.lang.String to, java.lang.String from)` Calculate the relative path between two URLs or between two files.
`java.io.File` `getSiteDescriptor​(java.io.File siteDirectory, java.util.Locale locale)` Get a site descriptor from the project's site directory.
`java.util.List<java.util.Locale>` `getSiteLocales​(java.lang.String locales)` Extracts from a comma-separated list the locales that are available in `site-tool` resource bundle.
`org.apache.maven.artifact.Artifact` `getSkinArtifactFromRepository​(org.apache.maven.artifact.repository.ArtifactRepository localRepository, java.util.List<org.apache.maven.artifact.repository.ArtifactRepository> remoteArtifactRepositories, DecorationModel decoration)` Get a skin artifact from one of the repositories.
`void` `populateReportsMenu​(DecorationModel decorationModel, java.util.Locale locale, java.util.Map<java.lang.String,​java.util.List<org.apache.maven.reporting.MavenReport>> reportsPerCategory)` Populate the pre-defined `reports` menu of the decoration model, if used through `<menu ref="reports"/>`.

### Field Detail

#### ROLE

    static final java.lang.String ROLE

Plexus Role

#### DEFAULT_LOCALE

    static final java.util.Locale DEFAULT_LOCALE

The locale by default for a Maven Site

See Also:
  `Locale.ENGLISH`

### Method Detail

#### getSkinArtifactFromRepository

    org.apache.maven.artifact.Artifact getSkinArtifactFromRepository​(org.apache.maven.artifact.repository.ArtifactRepository localRepository,
                                                                     java.util.List<org.apache.maven.artifact.repository.ArtifactRepository> remoteArtifactRepositories,
                                                                     DecorationModel decoration)
                                                              throws SiteToolException

Get a skin artifact from one of the repositories.

Parameters:
  `localRepository` - the Maven local repository, not null.
  `remoteArtifactRepositories` - the Maven remote repositories, not null.
  `decoration` - the Doxia site descriptor model, not null.
Returns:
  the `Skin` artifact defined in a `DecorationModel` from a given project and a local repository
Throws:
  `SiteToolException` - if any

#### getDefaultSkinArtifact

    org.apache.maven.artifact.Artifact getDefaultSkinArtifact​(org.apache.maven.artifact.repository.ArtifactRepository localRepository,
                                                              java.util.List<org.apache.maven.artifact.repository.ArtifactRepository> remoteArtifactRepositories)
                                                       throws SiteToolException

Get the default skin artifact for a project from one of the repositories.

Parameters:
  `localRepository` - the Maven local repository, not null.
  `remoteArtifactRepositories` - the Maven remote repositories, not null.
Returns:
  the default `Skin` artifact from a given project and a local repository
Throws:
  `SiteToolException` - if any
See Also:
  `Skin.getDefaultSkin()`, `getSkinArtifactFromRepository(ArtifactRepository, List, DecorationModel)`

#### getSiteDescriptor

    java.io.File getSiteDescriptor​(java.io.File siteDirectory,
                                   java.util.Locale locale)

Get a site descriptor from the project's site directory.

Parameters:
  `siteDirectory` - the site directory, not null
  `locale` - the locale wanted for the site descriptor. If not null, searching for `site_localeLanguage.xml`, otherwise searching for `site.xml`.
Returns:
  the site descriptor file

#### getInterpolatedSiteDescriptorContent

    java.lang.String getInterpolatedSiteDescriptorContent​(java.util.Map<java.lang.String,​java.lang.String> props,
                                                          org.apache.maven.project.MavenProject aProject,
                                                          java.lang.String siteDescriptorContent)
                                                   throws SiteToolException

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

Parameters:
  `props` - a map used for interpolation, not null.
  `aProject` - a Maven project, not null.
  `siteDescriptorContent` - the site descriptor file, not null.
Returns:
  the interpolated site descriptor content.
Throws:
  `SiteToolException` - if errors happened during the interpolation.

#### getDecorationModel

    DecorationModel getDecorationModel​(java.io.File siteDirectory,
                                       java.util.Locale locale,
                                       org.apache.maven.project.MavenProject project,
                                       java.util.List<org.apache.maven.project.MavenProject> reactorProjects,
                                       org.apache.maven.artifact.repository.ArtifactRepository localRepository,
                                       java.util.List<org.apache.maven.artifact.repository.ArtifactRepository> repositories)
                                throws SiteToolException

Get a decoration model for a project.

Parameters:
  `siteDirectory` - the site directory, may be null if project from repository
  `locale` - the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm.
  `project` - the Maven project, not null.
  `reactorProjects` - the Maven reactor projects, not null.
  `localRepository` - the Maven local repository, not null.
  `repositories` - the Maven remote repositories, not null.
Returns:
  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

#### populateReportsMenu

    void populateReportsMenu​(DecorationModel decorationModel,
                             java.util.Locale locale,
                             java.util.Map<java.lang.String,​java.util.List<org.apache.maven.reporting.MavenReport>> reportsPerCategory)

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".

Parameters:
  `decorationModel` - the Doxia Sitetools DecorationModel, not null.
  `locale` - the locale used for the i18n in DecorationModel. If null, using the default locale in the jvm.
  `reportsPerCategory` - reports per category to put in "Reports" or "Information" menus, not null.
See Also:
  `MavenReport.CATEGORY_PROJECT_INFORMATION`, `MavenReport.CATEGORY_PROJECT_REPORTS`

#### getSiteLocales

    java.util.List<java.util.Locale> getSiteLocales​(java.lang.String locales)

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.

Parameters:
  `locales` - A comma separated list of locales
Returns:
  a list of `Locale`, which at least contains the Maven default locale which is english
Since:
  1.7, was previously getAvailableLocales(String)

#### getRelativePath

    java.lang.String getRelativePath​(java.lang.String to,
                                     java.lang.String from)

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`.

Parameters:
  `to` - the `to` url of file as string
  `from` - the `from` url of file as string
Returns:
  a relative path from `from` to `to`.

#### getParentProject

    org.apache.maven.project.MavenProject getParentProject​(org.apache.maven.project.MavenProject aProject,
                                                           java.util.List<org.apache.maven.project.MavenProject> reactorProjects,
                                                           org.apache.maven.artifact.repository.ArtifactRepository localRepository)

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.

Parameters:
  `aProject` - a Maven project, not null.
  `reactorProjects` - the Maven reactor projects, not null.
  `localRepository` - the Maven local repository, not null.
Returns:
  the parent project with interpolated URLs.