001// Copyright 2012 The Apache Software Foundation
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007//     http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package org.apache.tapestry5.services.compatibility;
016
017import org.apache.tapestry5.ComponentResources;
018
019/**
020 * Used to report deprecation warnings for components.
021 *
022 * @since 5.4
023 */
024public interface DeprecationWarning
025{
026
027    /**
028     * Used to identify a component parameter that has been deprecated. Typically, such parameters are simply
029     * ignored, but the message should be specific about this.
030     *
031     * @param resources
032     *         identifies the component, including its location
033     * @param parameterName
034     *         name of the deprecated parameter
035     * @param message
036     *         message to display; typically explains what action will be taken, such as simply ignoring the parameter entirely. This should clarify
037     *         the issue to the developer, guiding them towards resolving the deprecation, typically be eliminating
038     *         the parameter entirely.
039     */
040    void componentParameter(ComponentResources resources, String parameterName, String message);
041
042    /**
043     * The most common case: checks to see if the parameter name is bound and if so emits a warning that the parameter
044     * is ignored and will be removed.
045     *
046     * @param resources
047     *         identifies the component, including its location
048     * @param parameterNames
049     *         names of the deprecated parameters
050     */
051    void ignoredComponentParameters(ComponentResources resources, String... parameterNames);
052
053    /**
054     * Used to identify a specific parameter value that is no longer supported. The first time this combination of
055     * component, parameter name, and parameter value are provided, an error is logged against this service's
056     * logger, including the component type and complete id, name of parameter (but not the value), the message, and the location of
057     * the component.
058     *
059     * @param resources
060     *         identifies the component, including its location.
061     * @param parameterName
062     *         name of parameter containing illegal value.
063     * @param parameterValue
064     *         value that is not supported (typically, an enum type). May be null.
065     * @param message
066     *         message to display; typically explains that action will be taken, such as treating the value as an alternate value,
067     *         or simply ignoring the value. This should clarify the issue to the developer, guiding them towards resolving
068     *         the deprecation, by changing the value, or eliminating the use of the parameter entirely.
069     */
070    void componentParameterValue(ComponentResources resources, String parameterName, Object parameterValue, String message);
071}