/*
* Geotoolkit.org - An Open Source Java GIS Toolkit
* http://www.geotoolkit.org
*
* (C) 2010-2012, Open Source Geospatial Foundation (OSGeo)
* (C) 2010-2012, Geomatys
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation;
* version 2.1 of the License.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*/
package org.geotoolkit.image.io;
import java.util.logging.Logger;
import java.util.logging.LogRecord;
import javax.imageio.event.IIOReadWarningListener;
import javax.imageio.event.IIOWriteWarningListener;
import org.apache.sis.util.Localized;
import org.apache.sis.util.logging.Logging;
/**
* Interface for objects that may produce warnings for recoverable failures. The warnings
* are encapsulated in {@link LogRecord} objects and given to the {@link #warningOccurred
* warningOccurred} method. The (sometime indirect) result of a call to {@code warningOccurred}
* is one of the following choices:
*
* <ol>
* <li><p>If there is at least one listener ({@link IIOReadWarningListener} or
* {@link IIOWriteWarningListener}) is reachable directly or indirectly, then
* the logging message is given to those listeners.</p></li>
*
* <li><p>Otherwise the record is logged using the {@link #LOGGER} declared in this interface.</p></li>
* </ol>
*
* In many cases the {@code warningOccured} method delegates its work to an other
* {@code WarningProducer} until an {@code ImageReader} or {@code ImageWriter} is
* found. For example the chain of delegations can be as below:
* <p>
* <ol>
* <li>{@link org.geotoolkit.image.io.metadata.ReferencingBuilder}</li>
* <li>{@link org.geotoolkit.image.io.metadata.MetadataNodeParser#warningOccurred(LogRecord)}</li>
* <li>{@link org.geotoolkit.image.io.metadata.SpatialMetadata#warningOccurred(LogRecord)}</li>
* <li>{@link org.geotoolkit.image.io.SpatialImageReader#warningOccurred(LogRecord)}</li>
* <li>{@link javax.imageio.ImageReader#processWarningOccurred(String)}</li>
* <li>{@link javax.imageio.event.IIOReadWarningListener#warningOccurred(ImageReader, String)}</li>
* </ol>
*
* {@section Localization}
* Warnings are localized for a {@linkplain java.util.Locale locale} typically inferred from
* the image reader or writer. The locale can be specified by a call to the {@code setLocale}
* method defined in the {@link javax.imageio.ImageReader} or {@link javax.imageio.ImageWriter}
* class.
*
* @author Martin Desruisseaux (Geomatys)
* @version 3.08
*
* @see SpatialImageReader#warningOccurred(LogRecord)
* @see SpatialImageWriter#warningOccurred(LogRecord)
* @see org.geotoolkit.image.io.metadata.SpatialMetadata#warningOccurred(LogRecord)
* @see org.geotoolkit.image.io.metadata.MetadataNodeParser#warningOccurred(LogRecord)
*
* @since 3.08
* @module
*/
public interface WarningProducer extends Localized {
/**
* The logger to use as a fallback when no warning listener can be reach.
*/
Logger LOGGER = Logging.getLogger("org.geotoolkit.image.io");
/**
* Invoked when a warning occurred. This method is typically invoked by the class implementing
* this {@code WarningProducer} interface. However it can also be invoked by other classes that
* forward their warnings, like below:
*
* <blockquote>
* {@link org.geotoolkit.image.io.metadata.ReferencingBuilder} →
* {@link org.geotoolkit.image.io.metadata.MetadataNodeParser} →
* {@link org.geotoolkit.image.io.metadata.SpatialMetadata} →
* ({@link SpatialImageReader} or {@link SpatialImageWriter})
* </blockquote>
*
* This method is public for allowing such forwarding.
*
* @param record The warning that occurred.
* @return {@code true} if the message has been sent to at least one warning listener,
* or {@code false} if it has been sent to the logging system as a fallback.
*/
boolean warningOccurred(LogRecord record);
}