001// Licensed under the Apache License, Version 2.0 (the "License");
002// you may not use this file except in compliance with the License.
003// You may obtain a copy of the License at
004//
005//     http://www.apache.org/licenses/LICENSE-2.0
006//
007// Unless required by applicable law or agreed to in writing, software
008// distributed under the License is distributed on an "AS IS" BASIS,
009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
010// See the License for the specific language governing permissions and
011// limitations under the License.
012
013package org.apache.tapestry5.services;
014
015/**
016 * Interface implemented by a page used for reporting exceptions.
017 *
018 * Alternately,  implemented by services to report request handling exceptions. This is invoked <em>before</em> the exception report page is rendered.
019 * The default implementation converts the exception into a well formatted text file, with content similar to the default
020 * {@link org.apache.tapestry5.corelib.pages.ExceptionReport} page, and stores this file on the file system.
021 *
022 * Exception report files are stored beneath a root directory, with intermediate folders for the day (e.g., "2014-06-02"), hour, and minute.
023 *
024 * Directories are created as necessary; however, there is nothing in place to delete these exceptions reports.
025 *
026 * @see org.apache.tapestry5.SymbolConstants#EXCEPTION_REPORTS_DIR
027 * @see org.apache.tapestry5.services.RequestExceptionHandler
028 * @see org.apache.tapestry5.services.ExceptionReportWriter
029 */
030public interface ExceptionReporter
031{
032    /**
033     * Used to communicate to the page what exception is to be reported.
034     *
035     * @param exception
036     *         runtime exception thrown during processing of the request
037     */
038    void reportException(Throwable exception);
039}