001: /*
002: * %W% %E%
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026: package com.sun.jump.module.download;
027:
028: import java.io.IOException;
029: import java.io.InputStream;
030: import java.net.URL;
031:
032: /**
033: * <code>JUMPDownloadDestination</code> provides the interface to
034: * receive the data that is downloaded by the <code>JUMPDownloadAction</code>.
035: * The <Code>start()</code> is called first before the download operation
036: * and if not exceptions are thrown by the method, then the
037: * <code>receive()</code> method is called one or more times as the
038: * downloading of data happens. Finally the <code>finish()</code> method
039: * is called if the data has been successfully downloaded and delivered to
040: * the destination or the <code>abort()</code> method is called if the
041: * download operation was aborted by the user or the system.
042: */
043: public interface JUMPDownloadDestination {
044: /**
045: * Notifies the destination the download is about to start.
046: *
047: * @param sourceURL source URL
048: * @param mimeType mime type of the object to be sent to
049: * this destination.
050: * @throws JUMPJUMPDownloadException is at implemntation's discretion
051: * to throw an JUMPJUMPDownloadException anything goes wrong. The download
052: * will be cancelled and this exception will be bubbled up.
053: * @throws IOException signal that there was an IO error.
054: */
055: public void start(URL sourceURL, String mimeType)
056: throws JUMPDownloadException, IOException;
057:
058: /**
059: * Requests this destination to receive a part of the object
060: * being downloaded.
061: *
062: * @param in The InputStream to read from
063: * @param desiredLength The number of bytes to receive
064: * @return the total number of bytes read, or <code>-1</code> is
065: * there is no more data because the end of the stream has been
066: * reached.
067: * @throws JUMPDJUMPDownloadExceptionis at implemntation's discretion
068: * to throw an JUMPDJUMPDownloadExceptionanything goes wrong. The download
069: * will be cancelled and this exception will be bubbled up.
070: * @throws IOException signal that there was an IO error.
071: */
072: public int receive(InputStream in, int desiredLength)
073: throws JUMPDownloadException, IOException;
074:
075: /**
076: * Notifies the destination that the object download is done. If the
077: * destination has successfully stored the data, it returns the URL
078: * where the destination has stored the application content.
079: *
080: * @return the URL of the application content that was downloaded.
081: * @throws JUMPJUMPDownloadException is at implemntation's discretion
082: * to throw an JUMPJUMPDownloadException anything goes wrong. The download
083: * will be cancelled and this exception will be bubbled up.
084: * @throws IOException signal that there was an IO error.
085: */
086: public URL finish() throws JUMPDownloadException, IOException;
087:
088: /**
089: * Notifies the destination that the object acquisition has
090: * failed or was stopped. There will be no more bits sent, and the
091: * {@link #finish()} method will not be called.
092: */
093: public void abort();
094:
095: /**
096: * Asks the destination what's the maximum buffer size should
097: * be used for downloading.
098: * @return maximum buffer size to be used for downloading, or 0,
099: * to let the implementation decide what's best.
100: * <br>
101: */
102: public int getMaxChunkSize();
103: }
|