001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (http://www.alkacon.com)
006 *
007 * This library is free software; you can redistribute it and/or
008 * modify it under the terms of the GNU Lesser General Public
009 * License as published by the Free Software Foundation; either
010 * version 2.1 of the License, or (at your option) any later version.
011 *
012 * This library is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * For further information about Alkacon Software GmbH & Co. KG, please see the
018 * company website: http://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: http://www.opencms.org
022 *
023 * You should have received a copy of the GNU Lesser General Public
024 * License along with this library; if not, write to the Free Software
025 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
026 */
027
028package org.opencms.report;
029
030import org.opencms.i18n.CmsMessageContainer;
031
032import java.util.List;
033import java.util.Locale;
034
035/**
036 * This is the interface for the report classes which are used for the output
037 * during operations that run on a spearate Thread in OpenCms,
038 * like publish, import, export etc.<p>
039 *
040 * @since 6.0.0
041 */
042public interface I_CmsReport {
043
044    /** Indicates default formatting. */
045    int FORMAT_DEFAULT = 0;
046
047    /** Indicates error formatting. */
048    int FORMAT_ERROR = 5;
049
050    /** Indicates headline formatting. */
051    int FORMAT_HEADLINE = 2;
052
053    /** Indicates note formatting. */
054    int FORMAT_NOTE = 3;
055
056    /** Indicates OK formatting. */
057    int FORMAT_OK = 4;
058
059    /** Indicates warning formatting. */
060    int FORMAT_WARNING = 1;
061
062    /** Request parameter value that this report should create an "extended" output. */
063    String REPORT_TYPE_EXTENDED = "extended";
064
065    /** Request parameter value that this report should create a "simple" output. */
066    String REPORT_TYPE_SIMPLE = "simple";
067
068    /**
069     * Adds an error object to the list of errors that occurred during the report.<p>
070     *
071     * @param obj the error object
072     */
073    void addError(Object obj);
074
075    /**
076     * Adds a warning object to the list of warnings that occurred during the report.<p>
077     *
078     * @param obj the error object
079     */
080    void addWarning(Object obj);
081
082    /**
083     * Formats the runtime formatted as "hh:mm:ss".<p>
084     *
085     * @return the runtime formatted as "hh:mm:ss"
086     */
087    String formatRuntime();
088
089    /**
090     * Returns a list of all errors that occurred during the report.<p>
091     *
092     * @return an error list that occurred during the report
093     */
094    List<Object> getErrors();
095
096    /**
097     * Returns the time of last report entry.<p>
098     *
099     * Will return zero if no entry has been written.<p>
100     *
101     * @return time of last report entry
102     */
103    long getLastEntryTime();
104
105    /**
106     * Returns the locale this report was initialized with.<p>
107     *
108     * @return the locale this report was initialized with
109     */
110    Locale getLocale();
111
112    /**
113     * Updates this report, this processes all new output added since
114     * the last call to this method.<p>
115     *
116     * This is only required in case the output is written to a HTML page,
117     * if the shell output is used, this will just return an empty String.<p>
118     *
119     * @return new elements that have been added to the report and not yet processed.
120     */
121    String getReportUpdate();
122
123    /**
124     * Fetches the report update for this report since the last time this method was called.<p>
125     *
126     * @param formatter the formatter to use for formatting the report output
127     *
128     * @return the output for report elements that have been added to the report and not yet processed
129     */
130    String getReportUpdate(I_CmsReportUpdateFormatter formatter);
131
132    /**
133     * Returns the time this report has been running.<p>
134     *
135     * @return the time this report has been running
136     */
137    long getRuntime();
138
139    /**
140     * Returns the original site root of the user who started this report,
141     * or <code>null</code> if the original site root has not been set.<p>
142     *
143     * @return the original site root of the user who started this report
144     */
145    String getSiteRoot();
146
147    /**
148     * Returns a list of all warnings that occurred during the report.<p>
149     *
150     * @return a warning list that occurred during the report
151     */
152    List<Object> getWarnings();
153
154    /**
155     * Returns if the report generated an error output.<p>
156     *
157     * @return true if the report generated an error, otherwise false
158     */
159    boolean hasError();
160
161    /**
162     * Returns if the report generated a warning output.<p>
163     *
164     * @return true if the report generated a warning, otherwise false
165     */
166    boolean hasWarning();
167
168    /**
169     * Prints a localized message to the report.<p>
170     *
171     * @param container the String to add
172     */
173    void print(CmsMessageContainer container);
174
175    /**
176     * Prints a localized message to the report, using the indicated formatting.<p>
177     *
178     * Use the contants starting with <code>FORMAT</code> from this interface
179     * to indicate which formatting to use.<p>
180     *
181     * @param container the String to add
182     * @param format the formatting to use for the output
183     */
184    void print(CmsMessageContainer container, int format);
185
186    /**
187     * Adds a line break to the report.<p>
188     */
189    void println();
190
191    /**
192     * Prints a localized message to the report.<p>
193     *
194     * @param container the message container to add
195     */
196    void println(CmsMessageContainer container);
197
198    /**
199     * Prints a localized message to the report, using the indicated formatting.<p>
200     *
201     * Use the contants starting with <code>FORMAT</code> from this interface
202     * to indicate which formatting to use.<p>
203     *
204     * @param container the message container to add
205     * @param format the formatting to use for the output
206     */
207    void println(CmsMessageContainer container, int format);
208
209    /**
210     * Adds an Exception to the report, ensuring that the Exception content is
211     * processed to generate a valid output esp. for HTML pages.<p>
212     *
213     * The exception will be stored and the output will later be processed
214     * in a special way.<p>
215     *
216     * @param t the exception to add
217     */
218    void println(Throwable t);
219
220    /**
221     * Prints a localized message followed by a parametera and dots to the report.<p>
222     *
223     * @param container the Message to add
224     * @param param the Parameter to add
225     */
226    void printMessageWithParam(CmsMessageContainer container, Object param);
227
228    /**
229     * Convenience method to print a localized message, followed by a parameter and dots to the report.<p>
230     *
231     * The output follows the pattern: ( 3 / 8 ) Deleting filename.txt ...
232     *
233     * @param m the number of the report output
234     * @param n the total number of report outputs
235     * @param container the Message to add
236     * @param param the Parameter to add
237     *
238     */
239    void printMessageWithParam(int m, int n, CmsMessageContainer container, Object param);
240
241    /**
242     * Removes the report site root prefix from the absolute path in the resource name,
243     * that is adjusts the resource name for the report site root.<p>
244     *
245     * If the site root for this report has not been set,
246     * or the resource name does not start with the report site root,
247     * the name it is left untouched.<p>
248     *
249     * @param resourcename the resource name (full path)
250     *
251     * @return the resource name adjusted for the report site root
252     *
253     * @see org.opencms.file.CmsRequestContext#removeSiteRoot(String)
254     */
255    String removeSiteRoot(String resourcename);
256
257    /**
258     * Resets the runtime to 0 milliseconds.<p>
259     */
260    void resetRuntime();
261}