org.w3c.dom.events.ProgressEvent Maven / Gradle / Ivy
/*
* Portions Copyright 2000-2008 Sun Microsystems, Inc. All Rights
* Reserved. Use is subject to license terms.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License version
* 2 only, as published by the Free Software Foundation.
*
* This program 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
* General Public License version 2 for more details (a copy is
* included at /legal/license.txt).
*
* You should have received a copy of the GNU General Public License
* version 2 along with this work; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 or visit www.sun.com if you need additional
* information or have any questions.
*/
/*
* Copyright (c) 2006 World Wide Web Consortium,
*
* (Massachusetts Institute of Technology, European Research Consortium for
* Informatics and Mathematics, Keio University). All Rights Reserved. This
* work is distributed under the W3C(r) Software License [1] 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.
*
* [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
*/
package org.w3c.dom.events;
/**
* A progress event occurs when the user agent makes progress in some data
* transfer operation, such as loading a resource from the web via
* XMLHttpRequest.
*
*
Note: This interface has not yet been accepted for
* inclusion in the W3C DOM 3 Event specification. It may be removed from the
* JSR 280 specification or added to a different namespace in a
* subsequent version of the specification.
*
* Other specifications which have a
* use case for these events should define when ProgressEvent events
* are dispatched.
*
*
* - The user agent must dispatch a
start event when a
* relevant operation has begun.
* - The user agent may dispatch one or
* more
progress events while a network operation is taking
* place.
* - If the operation fails to complete the user agent must
* dispatch either an
error event, if the failure to complete
* was due to an error (such as a timeout, or network error), or an
* abort event if the operation was deliberately cancelled
* (e.g. by user interaction or through a script call).
* - If the operation successfully completes, the user agent must
* dispatch a
load event.
*
* In short, there must be at least one start event, followed by
* zero or more progress events, followed by one event which may be
* any of error, abort or load, according
* to the outcome of the operation.
*
* Event definitions
*
* The following events are defined in this specification
*
*
*
* Name
* Description
* How many?
* When?
*
*
* loadstartThe operation has begun
* once
* Must be dispatched first
*
*
* progressThe operation is in progress
* zero or more
* May be dispatched zero or more times after a loadstart
* event, before any of error, abort or load events are dispatched
*
*
* errorThe operation failed to complete, e.g. as a result of a network
* error
* never or once
* Exactly one of these must be
* dispatched
*
*
* abortThe operation was cancelled, e.g. as a result of user
* interaction
* never or once
*
*
* loadThe operation successfully completed
* never or once
*
*
*
*
* These events must not bubble, and must not be
* cancelable.
*
* These events trigger event listeners attached on Element
* nodes for that event and on the capture and target phases.
*
*
No default action is defined for these events.
*
* These events are in the null namespace. Two kinds of
* initialization methods are provided: one in which the namespace is
* required (and must be null) and one which assigns the
* null namespace automatically, This specification does
* not recommend use of one method over the other, and authors may choose
* whichever method suits them better for any given usage.
*
*/
public interface ProgressEvent extends Event {
/**
* Specifies whether the total size of the transfer is known.
*/
public boolean getLengthComputable();
/**
* Specifies the number of bytes downloaded since the beginning of the
* download. This refers to the content, excluding headers and overhead
* from the transaction,
* and where there is a content-encoding or transfer-encoding refers
* to the number of bytes to be transferred, i.e. with the relevant
* encodings applied. For more details on HTTP see [RFC2616].
*/
public int getLoaded();
/**
* Specifies the expected total number of bytes of the content
* transferred in the operation. Where the size of the transfer is for
* some reason unknown, the value of this attribute must be zero.
*/
public int getTotal();
/**
* The initProgressEvent method is used to initialize the value of a
* progress event created through the DocumentEvent interface.
* If this method is called multiple times, the final invocation takes
* precedence .
*
* @param typeArg
* This must be one of loadstart,
* progress, error, abort,
* load. If it is not one of those values then this
* specification does not define the resulting event.
* @param canBubbleArg
* This must be false. Where a
* value of true is passed, implementations
* must override that and change the value to
* false.
* @param cancelableArg
* This must be false. Where a
* value of true is passed, implementations
* must override that and change the value to
* false.
* @param lengthComputableArg
* If the implementation has reliable information about
* the value of total, then this should be true.
* If the implementation does not have reliable information about
* the value of total, this should be false.
* @param loadedArg
* Specifies the total number of bytes already loaded. If this value
* is not a non-negative number,
* the implementation must change it to zero.
* @param totalArg
* Specifies the total number of bytes to be
* loaded. If lengthComputable is false,
* this must be zero. If any other parameter is passed, and
* lengthComputable is false, the implementation
* must override this and set the value to zero. If
* lengthComputable is true, and the value
* of this parameter is not a non-negative number, the implementation
* must set lengthComputable to false
* and the value of total to zero.
*/
public void initProgressEvent(String typeArg,
boolean canBubbleArg,
boolean cancelableArg,
boolean lengthComputableArg,
int loadedArg,
int totalArg);
/**
* The initProgressEventNS method is used to initialize the value of a
* namespaced progress event created through the DocumentEvent interface.
* This method may only be called before the progress event has been
* dispatched via the dispatchEvent method, though it may be called
* multiple times during that phase if necessary. If called multiple
* times, the final invocation takes precedence.
*
* @param namespaceURIArg
* Specifies the URI for the namespace of the event.
* For all events defined in this specification, the
* value of this parameter is null.
* @param typeArg
* This must be one of loadstart,
* progress, error,
* abort, load. If it is not one
* of those values then this specification does not define
* the resulting event.
* @param canBubbleArg
* This must be false. Where a
* value of true is passed, implementations
* must override that and change the value to
* false.
* @param cancelableArg
* This must be false. Where a
* value of true is passed, implementations
* must override that and change the value to
* false.
* @param lengthComputableArg
* If the implementation has reliable information about
* the value of total, then this should be true. If the
* implementation does not have reliable information about
* the value of total, this should be false.
* @param loadedArg
* This parameter specifies the total number of bytes
* already loaded.
* If this value is not a non-negative number, the implementation
* must change it to zero.
* @param totalArg
* This specifies the total number of bytes to be
* loaded. If lengthComputable is false,
* this must be zero. If any other parameter is passed,
* and lengthComputable is false, the
* implementation must override this and set the value to
* zero. If lengthComputable is true, and
* the value of this parameter is not a non-negative number, the
* implementation must set lengthComputable
* to false and the value of total to zero.
*
*/
public void initProgressEventNS(String namespaceURIArg,
String typeArg,
boolean canBubbleArg,
boolean cancelableArg,
boolean lengthComputableArg,
int loadedArg,
int totalArg);
}