1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.maven.reporting;
20
21 import java.io.File;
22 import java.util.Locale;
23
24 import org.apache.maven.doxia.sink.Sink;
25
26 /**
27 * The basis for a Maven report.
28 *
29 * @author Brett Porter
30 * @author <a href="evenisse@apache.org">Emmanuel Venisse</a>
31 * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
32 * @since 2.0
33 */
34 public interface MavenReport {
35 /** Plexus lookup name */
36 String ROLE = MavenReport.class.getName();
37
38 /** Category for project information reports */
39 String CATEGORY_PROJECT_INFORMATION = "Project Info";
40
41 /** Category for project reports */
42 String CATEGORY_PROJECT_REPORTS = "Project Reports";
43
44 /**
45 * Generate the report depending the wanted locale.
46 * <br>
47 * Mainly used for external reports like javadoc.
48 *
49 * @param sink the sink to use for the generation.
50 * @param locale the wanted locale to generate the report.
51 * @throws MavenReportException if any
52 */
53 void generate(Sink sink, Locale locale) throws MavenReportException;
54
55 /**
56 * Get the path relative to {@link #getReportOutputDirectory()} where the report's main output
57 * file will be written. The last component is the name of the file without any extension. The
58 * actual output extension will by added by the sink implementation.
59 * <p>
60 * Note: This method won't be {@code default} anymore when {@link #getOutputName()} is removed.
61 * You are advised to implement it as soon as possible.
62 *
63 * @since 4.0.0
64 * @return the relative output path of this report
65 */
66 default String getOutputPath() {
67 return getOutputName();
68 }
69
70 /**
71 * @deprecated Method name does not properly reflect its purpose. Implement and use
72 * {@link #getOutputPath()} instead.
73 */
74 @Deprecated
75 String getOutputName();
76
77 /**
78 * Get the category name for this report.
79 *
80 * @return the category name of this report. Should be {@link #CATEGORY_PROJECT_INFORMATION}
81 * or {@link #CATEGORY_PROJECT_REPORTS}
82 */
83 String getCategoryName();
84
85 /**
86 * Get the localized report name.
87 *
88 * @param locale the wanted locale to return the report's name.
89 * @return the name of this report
90 */
91 String getName(Locale locale);
92
93 /**
94 * Get the localized report description.
95 *
96 * @param locale the wanted locale to return the report's description.
97 * @return the description of this report
98 */
99 String getDescription(Locale locale);
100
101 /**
102 * Set a new shared report output directory. This directory may contain the output of other
103 * reports as well.
104 *
105 * @param outputDirectory the new shared report output directory
106 */
107 void setReportOutputDirectory(File outputDirectory);
108
109 /**
110 * Get the shared report output directory.
111 *
112 * @return the current shared report output directory
113 */
114 File getReportOutputDirectory();
115
116 /**
117 * An external report is a report which calls a third party program which generates some reports too.
118 * A good example is javadoc tool.
119 *
120 * @return {@code true} if this report is external, {@code false} otherwise.
121 * Default should be {@code false}.
122 */
123 boolean isExternalReport();
124
125 /**
126 * Verify some conditions before generating the report.
127 *
128 * @return {@code true} if this report can be generated, {@code false} otherwise.
129 * Default should be {@code true}.
130 * @throws MavenReportException if any
131 */
132 boolean canGenerateReport() throws MavenReportException;
133 }