org.codehaus.enunciate.modules.docs
Class DocumentationDeploymentModule

java.lang.Object
  extended by org.codehaus.enunciate.modules.BasicDeploymentModule
      extended by org.codehaus.enunciate.modules.FreemarkerDeploymentModule
          extended by org.codehaus.enunciate.modules.docs.DocumentationDeploymentModule
All Implemented Interfaces:
EnunciateClasspathListener, EnunciateModelAware, DeploymentModule, DocumentationAwareModule, FacetAware, ProjectTitleAware

public class DocumentationDeploymentModule
extends FreemarkerDeploymentModule
implements DocumentationAwareModule, EnunciateClasspathListener, FacetAware

Documentation Module

The documentation deployment module is responsible for generating the documentation for the API. This includes both the HTML pages and any other static content, e.g. client libraries.

The order of the documentation module is 100, essentially putting it after the generation of any static documents (e.g. WSDL, schemas) or static downloads (e.g. client libraries), but before the assembly of the war (see the spring-app module, order 200).

Steps

The only significant steps in the documentation module are the "generate" step and the "build" step.

generate

During the generate step, the documentation deployment module generates an XML file that conforms to this schema containing all the documentation for the entire API in a structured form.

build

The build step is where all the documentation files are generated as needed and assembled into a single directory. The first step is to copy the static files (the "base") to the build directory. The documentation base can be specified in the configuration, or you can use the default base.

Then, the documentation module generates another XML file conforming to this schema that contains the information for the files available for download in a structured form. By default, all named artifacts are included as a download (see the architecture guide for details). Other downloads can also be specified in the configuration.

Finally, the XML generated in the generate phase and the XML generated for the download files is processed together to create the static documentation elements. By default, a Freemarker Processing Template is applied to process the XML. You can supply your own Freemarker processing template in the configuration, or you can supply a custom an XML Stylesheet Transformation to generate your site documentation. Click here to see the default Freemarker XML Processing Template used by Enunciate, which might be helpful as a starter for you to create your own custom one. Click here for an example XSLT file.

Configuration

The configuration for the documentation deployment module is specified by the "docs" element under the "modules" element in the Enunciate configuration file.

attributes

The "download" element

There can be any number of "download" elements specified. This element is used to indicate another file or Enunciate artifact that is to be included in the "downloads" page. The download element supports the following attributes:

The "additional-css" element

You can apply additinoal css files to the generated documentation. Use the "file" attribute to specify the additional css file to apply.

The "facets" element

The "facets" element is applicable to the documentation module to configure which facets are to be included/excluded from the documentation artifacts. For more information, see API Facets

Artifacts

docs

The documentation deployment module exports only one artifact: the build directory for the documentation. The artifact id is "docs", and it is exported during the "build" step.

Author:
Ryan Heaton

Field Summary
 
Fields inherited from class org.codehaus.enunciate.modules.BasicDeploymentModule
enunciate
 
Constructor Summary
DocumentationDeploymentModule()
           
 
Method Summary
 void addAdditionalCss(java.lang.String additionalCss)
          Adds an additional css file to the generated documentation.
 void addDownload(DownloadConfig download)
          Adds a download to the documentation.
 void addFacetExclude(java.lang.String name)
          Add a facet exclude.
 void addFacetInclude(java.lang.String name)
          Add a facet include.
protected  void buildBase()
          Builds the base output directory.
protected  void doBuild()
          Default implementation is a no-op.
 void doFreemarkerGenerate()
          The generate logic builds the XML documentation structure for the enunciated API.
protected  void doFreemarkerXMLProcessing(java.net.URL freemarkerXMLProcessingTemplateURL)
           
protected  void doXmlTransform()
          Do the XSLT tranformation to generate the documentation.
protected  void doXSLT(java.net.URL xsltURL)
           
protected  void generateDownloadsXML()
          Generates the downloads xml indicating the available downloads.
 java.util.List<java.lang.String> getAdditionalCss()
          The additional css files.
 java.lang.String getBase()
          The documentation "base".
 org.apache.commons.digester.RuleSet getConfigurationRules()
          Default implementation returns null.
 java.lang.String getCopyright()
          The copyright (posted on the website).
 java.lang.String getCss()
          The cascading stylesheet to use instead of the default.
 java.lang.String getDefaultNamespace()
          The default namespace for the purposes of generating documentation.
 java.io.File getDocsBuildDir()
          The directory into which the documentation is put.
 java.lang.String getDocsDir()
          The subdirectory in the web application where the documentation will be put.
protected  java.net.URL getDocsTemplateURL()
          The URL to the Freemarker template for processing the base documentation xml file.
 java.util.Collection<DownloadConfig> getDownloads()
          The configured list of downloads to add to the documentation.
protected  java.net.URL getDownloadsTemplateURL()
          The URL to the Freemarker template for processing the downloads xml file.
 java.util.Set<java.lang.String> getFacetExcludes()
          The set of facets to exclude.
 java.util.Set<java.lang.String> getFacetIncludes()
          The set of facets to include.
 java.net.URL getFreemarkerDOCSXmlTemplateURL()
           
 java.net.URL getFreemarkerXMLProcessingTemplateURL()
          The url to the freemarker XML processing template that will be used to transforms the docs.xml to the site documentation.
 java.lang.String getGroupRestResources()
          How to group the REST resources together.
 java.lang.String getIndexPageName()
          The name of the index page.
 java.lang.String getJavadocTagHandling()
          JavaDoc tag handing.
 java.lang.String getName()
          The name of the deployment module.
protected  freemarker.template.ObjectWrapper getObjectWrapper()
          The object wrapper to use for the model.
 int getOrder()
          The order of execution for the deployment module.
protected  java.lang.String getRelativePathToRootDir()
          Get the relative path to the root directory from the docs directory.
 java.lang.String getSplashPackage()
          The package that contains the splash page documentation for the API.
 java.lang.String getTitle()
          The title of the documentation.
 void init(Enunciate enunciate)
          Sets the enunciate mechanism.
 void initModel(EnunciateFreemarkerModel model)
          Initialize the model.
 boolean isApplyWadlFilter()
          Whether to apply a filter for the WADL files that will attempt to resolve the paths dynamically.
 boolean isApplyWsdlFilter()
          Whether to apply a filter for the WSDL files that will attempt to resolve the soap paths dynamically.
 boolean isDisableRestMountpoint()
          Whether to disable the REST mountpoint documentation.
 boolean isForceExampleJson()
          Whether to force example JSON.
 boolean isIncludeDefaultDownloads()
          Whether to include the default downloads (named artifacts) in the downloads section.
 boolean isIncludeExampleJson()
          Whether to include example JSON in the documentation.
 boolean isIncludeExampleXml()
          Whether to include example XML in the documentation.
protected  java.io.InputStream loadDefaultBase()
          Loads the default base for the documentation.
 void onClassesFound(java.util.Set<java.lang.String> classes)
          Logic for handling a set of classes that were found on the Enunciate classpath.
 void setApplyWadlFilter(boolean applyWadlFilter)
          Whether to apply a filter for the WADL files that will attempt to resolve the paths dynamically.
 void setApplyWsdlFilter(boolean applyWsdlFilter)
          Whether to apply a filter for the WSDL files that will attempt to resolve the soap paths dynamically.
 void setBase(java.lang.String base)
          The documentation "base".
 void setCopyright(java.lang.String copyRight)
          The copyright (posted on the website).
 void setCss(java.lang.String css)
          The cascading stylesheet to use instead of the default.
 void setDefaultNamespace(java.lang.String defaultNamespace)
          The default namespace for the purposes of generating documentation.
 void setDisableRestMountpoint(boolean disableRestMountpoint)
          Whether to disable the REST mountpoint documentation.
 void setDocsDir(java.lang.String docsDir)
          The subdirectory in the web application where the documentation will be put.
 void setForceExampleJson(boolean forceExampleJson)
          Whether to force example JSON.
 void setFreemarkerDOCSXmlTemplate(java.lang.String freemarkerXmlTemplate)
           
 void setFreemarkerDOCSXmlTemplateURL(java.net.URL freemarkerDOCSXmlTemplateURL)
           
 void setFreemarkerXMLProcessingTemplate(java.lang.String freemarkerProcessingTemplate)
          The Freemarker XML processing template file that will be used to transforms the docs.xml to the site documentation.
 void setFreemarkerXMLProcessingTemplateURL(java.net.URL freemarkerXMLProcessingTemplateURL)
          The url to the freemarker XML processing template that will be used to transforms the docs.xml to the site documentation.
 void setGroupRestResources(java.lang.String groupRestResources)
          How to group the REST resources together.
 void setIncludeDefaultDownloads(boolean includeDefaultDownloads)
          Whether to include the default downloads (named artifacts) in the downloads section.
 void setIncludeExampleJson(boolean includeExampleJson)
          Whether to include example JSON in the documentation.
 void setIncludeExampleXml(boolean includeExampleXml)
          Whether to include example XML in the documentation.
 void setIndexPageName(java.lang.String indexPageName)
          The name of the index page.
 void setJavadocTagHandling(java.lang.String javadocTagHandling)
          The javadoc tag handling.
 void setSplashPackage(java.lang.String splashPackage)
          The package that contains the splash page documentation for the API.
 void setTitle(java.lang.String title)
          The title of the documentation.
 void setTitleConditionally(java.lang.String title)
          Set the title for this project iff it hasn't already been set.
 void setXslt(java.lang.String xslt)
          The stylesheet to use to generate the documentation.
 void setXsltURL(java.net.URL xslt)
          Set the url to the xslt to use to generate the documentation.
 
Methods inherited from class org.codehaus.enunciate.modules.FreemarkerDeploymentModule
close, doGenerate, getConfiguration, getModel, getModelInternal, getTemplateExceptionHandler, getTemplateLoader, processTemplate, processTemplate, processTemplate, processTemplate
 
Methods inherited from class org.codehaus.enunciate.modules.BasicDeploymentModule
debug, doCompile, doPackage, getAliases, getBuildDir, getCompileDir, getEnunciate, getGenerateDir, getPackageDir, getValidator, info, isDisabled, setBuildDir, setCompileDir, setDisabled, setGenerateDir, setPackageDir, step, warn
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.codehaus.enunciate.modules.DeploymentModule
close, getAliases, getValidator, isDisabled, step
 

Constructor Detail

DocumentationDeploymentModule

public DocumentationDeploymentModule()
Method Detail

getName

public java.lang.String getName()
Description copied from interface: DeploymentModule
The name of the deployment module. Identifies its section in the enunciate configuration.

Specified by:
getName in interface DeploymentModule
Overrides:
getName in class BasicDeploymentModule
Returns:
"docs"

getOrder

public int getOrder()
Description copied from interface: DeploymentModule
The order of execution for the deployment module.

Specified by:
getOrder in interface DeploymentModule
Overrides:
getOrder in class BasicDeploymentModule
Returns:
100

onClassesFound

public void onClassesFound(java.util.Set<java.lang.String> classes)
Description copied from interface: EnunciateClasspathListener
Logic for handling a set of classes that were found on the Enunciate classpath.

Specified by:
onClassesFound in interface EnunciateClasspathListener
Parameters:
classes - The classes that were found.

getSplashPackage

public java.lang.String getSplashPackage()
The package that contains the splash page documentation for the API.

Returns:
The package that contains the splash page documentation for the API.

setSplashPackage

public void setSplashPackage(java.lang.String splashPackage)
The package that contains the splash page documentation for the API.

Parameters:
splashPackage - The package that contains the splash page documentation for the API.

getCopyright

public java.lang.String getCopyright()
The copyright (posted on the website).

Returns:
The copyright (posted on the website).

setCopyright

public void setCopyright(java.lang.String copyRight)
The copyright (posted on the website).

Parameters:
copyRight - The copyright (posted on the website).

getTitle

public java.lang.String getTitle()
The title of the documentation.

Specified by:
getTitle in interface DocumentationAwareModule
Returns:
The title of the documentation.

setTitle

public void setTitle(java.lang.String title)
The title of the documentation.

Specified by:
setTitle in interface DocumentationAwareModule
Parameters:
title - The title of the documentation.

setTitleConditionally

public void setTitleConditionally(java.lang.String title)
Set the title for this project iff it hasn't already been set.

Specified by:
setTitleConditionally in interface ProjectTitleAware
Parameters:
title - The title.

getJavadocTagHandling

public java.lang.String getJavadocTagHandling()
JavaDoc tag handing.

Returns:
The javadoc tag handling.

setJavadocTagHandling

public void setJavadocTagHandling(java.lang.String javadocTagHandling)
The javadoc tag handling.

Parameters:
javadocTagHandling - The javadoc tag handling.

addDownload

public void addDownload(DownloadConfig download)
Adds a download to the documentation.

Parameters:
download - The download to add.

getDownloads

public java.util.Collection<DownloadConfig> getDownloads()
The configured list of downloads to add to the documentation.

Returns:
The configured list of downloads to add to the documentation.

addAdditionalCss

public void addAdditionalCss(java.lang.String additionalCss)
Adds an additional css file to the generated documentation.

Parameters:
additionalCss - The additional css.

getAdditionalCss

public java.util.List<java.lang.String> getAdditionalCss()
The additional css files.

Returns:
The additional css files.

isIncludeDefaultDownloads

public boolean isIncludeDefaultDownloads()
Whether to include the default downloads (named artifacts) in the downloads section.

Returns:
Whether to include the default downloads (named artifacts) in the downloads section.

setIncludeDefaultDownloads

public void setIncludeDefaultDownloads(boolean includeDefaultDownloads)
Whether to include the default downloads (named artifacts) in the downloads section.

Parameters:
includeDefaultDownloads - Whether to include the default downloads (named artifacts) in the downloads section.

isIncludeExampleXml

public boolean isIncludeExampleXml()
Whether to include example XML in the documentation.

Returns:
Whether to include example XML in the documentation.

setIncludeExampleXml

public void setIncludeExampleXml(boolean includeExampleXml)
Whether to include example XML in the documentation.

Parameters:
includeExampleXml - Whether to include example XML in the documentation.

isIncludeExampleJson

public boolean isIncludeExampleJson()
Whether to include example JSON in the documentation.

Returns:
Whether to include example JSON in the documentation.

setIncludeExampleJson

public void setIncludeExampleJson(boolean includeExampleJson)
Whether to include example JSON in the documentation.

Parameters:
includeExampleJson - Whether to include example JSON in the documentation.

isForceExampleJson

public boolean isForceExampleJson()
Whether to force example JSON. Default is to only include the example JSON only if Jackson is available on the classpath.

Returns:
Whether to force example JSON.

setForceExampleJson

public void setForceExampleJson(boolean forceExampleJson)
Whether to force example JSON.

Parameters:
forceExampleJson - Whether to force example JSON.

setXslt

public void setXslt(java.lang.String xslt)
             throws java.net.MalformedURLException
The stylesheet to use to generate the documentation.

Parameters:
xslt - The stylesheet to use to generate the documentation.
Throws:
java.net.MalformedURLException

setXsltURL

public void setXsltURL(java.net.URL xslt)
Set the url to the xslt to use to generate the documentation.

Parameters:
xslt - The xslt.

setFreemarkerXMLProcessingTemplate

public void setFreemarkerXMLProcessingTemplate(java.lang.String freemarkerProcessingTemplate)
                                        throws java.net.MalformedURLException
The Freemarker XML processing template file that will be used to transforms the docs.xml to the site documentation. For more information, see http://freemarker.sourceforge.net/docs/xgui.html.

Parameters:
freemarkerProcessingTemplate - The Freemarker XML processing template file that will be used to transforms the docs.xml to the site documentation.
Throws:
java.net.MalformedURLException

getFreemarkerXMLProcessingTemplateURL

public java.net.URL getFreemarkerXMLProcessingTemplateURL()
The url to the freemarker XML processing template that will be used to transforms the docs.xml to the site documentation. For more information, see http://freemarker.sourceforge.net/docs/xgui.html

Returns:
The url to the freemarker XML processing template.

setFreemarkerXMLProcessingTemplateURL

public void setFreemarkerXMLProcessingTemplateURL(java.net.URL freemarkerXMLProcessingTemplateURL)
The url to the freemarker XML processing template that will be used to transforms the docs.xml to the site documentation.

Parameters:
freemarkerXMLProcessingTemplateURL - The url to the freemarker XML processing template.

setFreemarkerDOCSXmlTemplate

public void setFreemarkerDOCSXmlTemplate(java.lang.String freemarkerXmlTemplate)
                                  throws java.net.MalformedURLException
Throws:
java.net.MalformedURLException

getFreemarkerDOCSXmlTemplateURL

public java.net.URL getFreemarkerDOCSXmlTemplateURL()

setFreemarkerDOCSXmlTemplateURL

public void setFreemarkerDOCSXmlTemplateURL(java.net.URL freemarkerDOCSXmlTemplateURL)

getCss

public java.lang.String getCss()
The cascading stylesheet to use instead of the default. This is ignored if the 'base' is also set.

Returns:
The cascading stylesheet to use.

setCss

public void setCss(java.lang.String css)
The cascading stylesheet to use instead of the default. This is ignored if the 'base' is also set.

Parameters:
css - The cascading stylesheet to use instead of the default.

getBase

public java.lang.String getBase()
The documentation "base". The documentation base is the initial contents of the directory where the documentation will be output. Can be a zip file or a directory.

Returns:
The documentation "base".

setBase

public void setBase(java.lang.String base)
The documentation "base".

Parameters:
base - The documentation "base".

getDocsTemplateURL

protected java.net.URL getDocsTemplateURL()
                                   throws java.net.MalformedURLException
The URL to the Freemarker template for processing the base documentation xml file.

Returns:
The URL to the Freemarker template for processing the base documentation xml file.
Throws:
java.net.MalformedURLException

getDownloadsTemplateURL

protected java.net.URL getDownloadsTemplateURL()
The URL to the Freemarker template for processing the downloads xml file.

Returns:
The URL to the Freemarker template for processing the downloads xml file.

getDocsDir

public java.lang.String getDocsDir()
The subdirectory in the web application where the documentation will be put.

Specified by:
getDocsDir in interface DocumentationAwareModule
Returns:
The subdirectory in the web application where the documentation will be put.

setDocsDir

public void setDocsDir(java.lang.String docsDir)
The subdirectory in the web application where the documentation will be put.

Specified by:
setDocsDir in interface DocumentationAwareModule
Parameters:
docsDir - The subdirectory in the web application where the documentation will be put.

isApplyWsdlFilter

public boolean isApplyWsdlFilter()
Whether to apply a filter for the WSDL files that will attempt to resolve the soap paths dynamically.

Returns:
Whether to apply a filter for the WSDL files that will attempt to resolve the soap paths dynamically.

setApplyWsdlFilter

public void setApplyWsdlFilter(boolean applyWsdlFilter)
Whether to apply a filter for the WSDL files that will attempt to resolve the soap paths dynamically.

Parameters:
applyWsdlFilter - Whether to apply a filter for the WSDL files that will attempt to resolve the soap paths dynamically.

isApplyWadlFilter

public boolean isApplyWadlFilter()
Whether to apply a filter for the WADL files that will attempt to resolve the paths dynamically.

Returns:
Whether to apply a filter for the WADL files that will attempt to resolve the paths dynamically.

setApplyWadlFilter

public void setApplyWadlFilter(boolean applyWadlFilter)
Whether to apply a filter for the WADL files that will attempt to resolve the paths dynamically.

Parameters:
applyWadlFilter - Whether to apply a filter for the WADL files that will attempt to resolve the paths dynamically.

getIndexPageName

public java.lang.String getIndexPageName()
The name of the index page.

Specified by:
getIndexPageName in interface DocumentationAwareModule
Returns:
The name of the index page.

setIndexPageName

public void setIndexPageName(java.lang.String indexPageName)
The name of the index page.

Specified by:
setIndexPageName in interface DocumentationAwareModule
Parameters:
indexPageName - The name of the index page.

isDisableRestMountpoint

public boolean isDisableRestMountpoint()
Whether to disable the REST mountpoint documentation.

Returns:
Whether to disable the REST mountpoint documentation.

setDisableRestMountpoint

public void setDisableRestMountpoint(boolean disableRestMountpoint)
Whether to disable the REST mountpoint documentation.

Parameters:
disableRestMountpoint - Whether to disable the REST mountpoint documentation.

getDefaultNamespace

public java.lang.String getDefaultNamespace()
The default namespace for the purposes of generating documentation.

Returns:
The default namespace for the purposes of generating documentation.

setDefaultNamespace

public void setDefaultNamespace(java.lang.String defaultNamespace)
The default namespace for the purposes of generating documentation.

Parameters:
defaultNamespace - The default namespace for the purposes of generating documentation.

getGroupRestResources

public java.lang.String getGroupRestResources()
How to group the REST resources together.

Returns:
How to group the REST resources together.

setGroupRestResources

public void setGroupRestResources(java.lang.String groupRestResources)
How to group the REST resources together.

Parameters:
groupRestResources - How to group the REST resources together.

getDocsBuildDir

public java.io.File getDocsBuildDir()
The directory into which the documentation is put.

Returns:
The directory into which the documentation is put.

init

public void init(Enunciate enunciate)
          throws EnunciateException
Description copied from class: BasicDeploymentModule
Sets the enunciate mechanism.

Specified by:
init in interface DeploymentModule
Overrides:
init in class BasicDeploymentModule
Parameters:
enunciate - The enunciate mechanism.
Throws:
EnunciateException

initModel

public void initModel(EnunciateFreemarkerModel model)
Description copied from interface: EnunciateModelAware
Initialize the model.

Specified by:
initModel in interface EnunciateModelAware
Overrides:
initModel in class FreemarkerDeploymentModule
Parameters:
model - The model to initialize.

doFreemarkerGenerate

public void doFreemarkerGenerate()
                          throws EnunciateException,
                                 java.io.IOException,
                                 freemarker.template.TemplateException
The generate logic builds the XML documentation structure for the enunciated API.

Specified by:
doFreemarkerGenerate in class FreemarkerDeploymentModule
Throws:
EnunciateException
java.io.IOException
freemarker.template.TemplateException

doBuild

protected void doBuild()
                throws EnunciateException,
                       java.io.IOException
Description copied from class: BasicDeploymentModule
Default implementation is a no-op.

Overrides:
doBuild in class BasicDeploymentModule
Throws:
EnunciateException
java.io.IOException

generateDownloadsXML

protected void generateDownloadsXML()
                             throws java.io.IOException,
                                    EnunciateException
Generates the downloads xml indicating the available downloads.

Throws:
java.io.IOException
EnunciateException

buildBase

protected void buildBase()
                  throws java.io.IOException
Builds the base output directory.

Throws:
java.io.IOException

doXmlTransform

protected void doXmlTransform()
                       throws java.io.IOException,
                              EnunciateException
Do the XSLT tranformation to generate the documentation.

Throws:
java.io.IOException
EnunciateException

doFreemarkerXMLProcessing

protected void doFreemarkerXMLProcessing(java.net.URL freemarkerXMLProcessingTemplateURL)
                                  throws java.io.IOException,
                                         EnunciateException
Throws:
java.io.IOException
EnunciateException

doXSLT

protected void doXSLT(java.net.URL xsltURL)
               throws java.io.IOException,
                      EnunciateException
Throws:
java.io.IOException
EnunciateException

getRelativePathToRootDir

protected java.lang.String getRelativePathToRootDir()
Get the relative path to the root directory from the docs directory.

Returns:
the relative path to the root directory.

getFacetIncludes

public java.util.Set<java.lang.String> getFacetIncludes()
The set of facets to include.

Specified by:
getFacetIncludes in interface FacetAware
Returns:
The set of facets to include.

addFacetInclude

public void addFacetInclude(java.lang.String name)
Add a facet include.

Parameters:
name - The name.

getFacetExcludes

public java.util.Set<java.lang.String> getFacetExcludes()
The set of facets to exclude.

Specified by:
getFacetExcludes in interface FacetAware
Returns:
The set of facets to exclude.

addFacetExclude

public void addFacetExclude(java.lang.String name)
Add a facet exclude.

Parameters:
name - The name.

loadDefaultBase

protected java.io.InputStream loadDefaultBase()
Loads the default base for the documentation.

Returns:
The default base for the documentation.

getObjectWrapper

protected freemarker.template.ObjectWrapper getObjectWrapper()
Description copied from class: FreemarkerDeploymentModule
The object wrapper to use for the model.

Overrides:
getObjectWrapper in class FreemarkerDeploymentModule
Returns:
The object wrapper to use for the model.

getConfigurationRules

public org.apache.commons.digester.RuleSet getConfigurationRules()
Description copied from class: BasicDeploymentModule
Default implementation returns null.

Specified by:
getConfigurationRules in interface DeploymentModule
Overrides:
getConfigurationRules in class BasicDeploymentModule
Returns:
null.