1 /*
   2  * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.imageio.event;
  27 
  28 import java.util.EventListener;
  29 import javax.imageio.ImageReader;
  30 
  31 /**
  32  * An interface used by {@code ImageReader} implementations to
  33  * notify callers of their image and thumbnail reading methods of
  34  * progress.
  35  *
  36  * <p> This interface receives general indications of decoding
  37  * progress (via the {@code imageProgress} and
  38  * {@code thumbnailProgress} methods), and events indicating when
  39  * an entire image has been updated (via the
  40  * {@code imageStarted}, {@code imageComplete},
  41  * {@code thumbnailStarted} and {@code thumbnailComplete}
  42  * methods).  Applications that wish to be informed of pixel updates
  43  * as they happen (for example, during progressive decoding), should
  44  * provide an {@code IIOReadUpdateListener}.
  45  *
  46  * @see IIOReadUpdateListener
  47  * @see javax.imageio.ImageReader#addIIOReadProgressListener
  48  * @see javax.imageio.ImageReader#removeIIOReadProgressListener
  49  *
  50  */
  51 public interface IIOReadProgressListener extends EventListener {
  52 
  53     /**
  54      * Reports that a sequence of read operations is beginning.
  55      * {@code ImageReader} implementations are required to call
  56      * this method exactly once from their
  57      * {@code readAll(Iterator)} method.
  58      *
  59      * @param source the {@code ImageReader} object calling this method.
  60      * @param minIndex the index of the first image to be read.
  61      */
  62     void sequenceStarted(ImageReader source, int minIndex);
  63 
  64     /**
  65      * Reports that a sequence of read operations has completed.
  66      * {@code ImageReader} implementations are required to call
  67      * this method exactly once from their
  68      * {@code readAll(Iterator)} method.
  69      *
  70      * @param source the {@code ImageReader} object calling this method.
  71      */
  72     void sequenceComplete(ImageReader source);
  73 
  74     /**
  75      * Reports that an image read operation is beginning.  All
  76      * {@code ImageReader} implementations are required to call
  77      * this method exactly once when beginning an image read
  78      * operation.
  79      *
  80      * @param source the {@code ImageReader} object calling this method.
  81      * @param imageIndex the index of the image being read within its
  82      * containing input file or stream.
  83      */
  84     void imageStarted(ImageReader source, int imageIndex);
  85 
  86     /**
  87      * Reports the approximate degree of completion of the current
  88      * {@code read} call of the associated
  89      * {@code ImageReader}.
  90      *
  91      * <p> The degree of completion is expressed as a percentage
  92      * varying from {@code 0.0F} to {@code 100.0F}.  The
  93      * percentage should ideally be calculated in terms of the
  94      * remaining time to completion, but it is usually more practical
  95      * to use a more well-defined metric such as pixels decoded or
  96      * portion of input stream consumed.  In any case, a sequence of
  97      * calls to this method during a given read operation should
  98      * supply a monotonically increasing sequence of percentage
  99      * values.  It is not necessary to supply the exact values
 100      * {@code 0} and {@code 100}, as these may be inferred
 101      * by the callee from other methods.
 102      *
 103      * <p> Each particular {@code ImageReader} implementation may
 104      * call this method at whatever frequency it desires.  A rule of
 105      * thumb is to call it around each 5 percent mark.
 106      *
 107      * @param source the {@code ImageReader} object calling this method.
 108      * @param percentageDone the approximate percentage of decoding that
 109      * has been completed.
 110      */
 111     void imageProgress(ImageReader source, float percentageDone);
 112 
 113     /**
 114      * Reports that the current image read operation has completed.
 115      * All {@code ImageReader} implementations are required to
 116      * call this method exactly once upon completion of each image
 117      * read operation.
 118      *
 119      * @param source the {@code ImageReader} object calling this
 120      * method.
 121      */
 122     void imageComplete(ImageReader source);
 123 
 124     /**
 125      * Reports that a thumbnail read operation is beginning.  All
 126      * {@code ImageReader} implementations are required to call
 127      * this method exactly once when beginning a thumbnail read
 128      * operation.
 129      *
 130      * @param source the {@code ImageReader} object calling this method.
 131      * @param imageIndex the index of the image being read within its
 132      * containing input file or stream.
 133      * @param thumbnailIndex the index of the thumbnail being read.
 134      */
 135     void thumbnailStarted(ImageReader source,
 136                           int imageIndex, int thumbnailIndex);
 137 
 138     /**
 139      * Reports the approximate degree of completion of the current
 140      * {@code getThumbnail} call within the associated
 141      * {@code ImageReader}.  The semantics are identical to those
 142      * of {@code imageProgress}.
 143      *
 144      * @param source the {@code ImageReader} object calling this method.
 145      * @param percentageDone the approximate percentage of decoding that
 146      * has been completed.
 147      */
 148     void thumbnailProgress(ImageReader source, float percentageDone);
 149 
 150     /**
 151      * Reports that a thumbnail read operation has completed.  All
 152      * {@code ImageReader} implementations are required to call
 153      * this method exactly once upon completion of each thumbnail read
 154      * operation.
 155      *
 156      * @param source the {@code ImageReader} object calling this
 157      * method.
 158      */
 159     void thumbnailComplete(ImageReader source);
 160 
 161     /**
 162      * Reports that a read has been aborted via the reader's
 163      * {@code abort} method.  No further notifications will be
 164      * given.
 165      *
 166      * @param source the {@code ImageReader} object calling this
 167      * method.
 168      */
 169     void readAborted(ImageReader source);
 170 }
--- EOF ---