/*

 * Copyright (c) 1995, 2017, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code 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.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code 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 in the LICENSE file that

 * accompanied this code).

 *

 * 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.applet;

import java.awt.Image;

import java.awt.Graphics;

import java.awt.image.ColorModel;

import java.net.URL;

import java.util.Enumeration;

import java.io.InputStream;

import java.io.IOException;

import java.util.Iterator;

/**

 * This interface corresponds to an applet's environment: the

 * document containing the applet and the other applets in the same

 * document.

 * <p>

 * The methods in this interface can be used by an applet to obtain

 * information about its environment.

 *

 * @author      Arthur van Hoff

 * @since       1.0

 *

 * @deprecated  The Applet API is deprecated. See the

 * <a href="package-summary.html"> java.applet package documentation</a>

 * for further information.

 */

@Deprecated(since = "9")

public interface AppletContext {

    /**

     * Creates an audio clip.

     *

     * @param   url   an absolute URL giving the location of the audio clip.

     * @return  the audio clip at the specified URL.

     */

    AudioClip getAudioClip(URL url);

    /**

     * Returns an {@code Image} object that can then be painted on

     * the screen. The {@code url} argument that is

     * passed as an argument must specify an absolute URL.

     * <p>

     * This method always returns immediately, whether or not the image

     * exists. When the applet attempts to draw the image on the screen,

     * the data will be loaded. The graphics primitives that draw the

     * image will incrementally paint on the screen.

     *

     * @param   url   an absolute URL giving the location of the image.

     * @return  the image at the specified URL.

     * @see     java.awt.Image

     */

    Image getImage(URL url);

    /**

     * Finds and returns the applet in the document represented by this

     * applet context with the given name. The name can be set in the

     * HTML tag by setting the {@code name} attribute.

     *

     * @param   name   an applet name.

     * @return  the applet with the given name, or {@code null} if

     *          not found.

     */

    Applet getApplet(String name);

    /**

     * Finds all the applets in the document represented by this applet

     * context.

     *

     * @return  an enumeration of all applets in the document represented by

     *          this applet context.

     */

    Enumeration<Applet> getApplets();

    /**

     * Requests that the browser or applet viewer show the Web page

     * indicated by the {@code url} argument. The browser or

     * applet viewer determines which window or frame to display the

     * Web page. This method may be ignored by applet contexts that

     * are not browsers.

     *

     * @param   url   an absolute URL giving the location of the document.

     */

    void showDocument(URL url);

    /**

     * Requests that the browser or applet viewer show the Web page

     * indicated by the {@code url} argument. The

     * {@code target} argument indicates in which HTML frame the

     * document is to be displayed.

     * The target argument is interpreted as follows:

     *

     * <table class="striped">

     * <caption>Target arguments and their descriptions</caption>

     * <thead>

     *   <tr>

     *     <th scope="col">Target Argument

     *     <th scope="col">Description

     * </thead>

     * <tbody>

     *   <tr>

     *     <th scope="row">{@code "_self"}

     *     <td>Show in the window and frame that contain the applet.

     *   <tr>

     *     <th scope="row">{@code "_parent"}

     *     <td>Show in the applet's parent frame. If the applet's frame has no

     *     parent frame, acts the same as "_self".

     *   <tr>

     *     <th scope="row">{@code "_top"}

     *     <td>Show in the top-level frame of the applet's window. If the

     *     applet's frame is the top-level frame, acts the same as "_self".

     *   <tr>

     *     <th scope="row">{@code "_blank"}

     *     <td>Show in a new, unnamed top-level window.

     *   <tr>

     *     <th scope="row"><i>name</i>

     *     <td>Show in the frame or window named <i>name</i>. If a target named

     *     <i>name</i> does not already exist, a new top-level window with the

     *     specified name is created, and the document is shown there.

     * </tbody>

     * </table>

     * <p>

     * An applet viewer or browser is free to ignore {@code showDocument}.

     *

     * @param   url   an absolute URL giving the location of the document.

     * @param   target   a {@code String} indicating where to display

     *                   the page.

     */

    public void showDocument(URL url, String target);

    /**

     * Requests that the argument string be displayed in the

     * "status window". Many browsers and applet viewers

     * provide such a window, where the application can inform users of

     * its current state.

     *

     * @param   status   a string to display in the status window.

     */

    void showStatus(String status);

    /**

     * Associates the specified stream with the specified key in this

     * applet context. If the applet context previously contained a mapping

     * for this key, the old value is replaced.

     * <p>

     * For security reasons, mapping of streams and keys exists for each

     * codebase. In other words, applet from one codebase cannot access

     * the streams created by an applet from a different codebase

     *

     * @param key key with which the specified value is to be associated.

     * @param stream stream to be associated with the specified key. If this

     *               parameter is {@code null}, the specified key is removed

     *               in this applet context.

     * @throws IOException if the stream size exceeds a certain

     *         size limit. Size limit is decided by the implementor of this

     *         interface.

     * @since 1.4

     */

    public void setStream(String key, InputStream stream)throws IOException;

    /**

     * Returns the stream to which specified key is associated within this

     * applet context. Returns {@code null} if the applet context contains

     * no stream for this key.

     * <p>

     * For security reasons, mapping of streams and keys exists for each

     * codebase. In other words, applet from one codebase cannot access

     * the streams created by an applet from a different codebase

     *

     * @return the stream to which this applet context maps the key

     * @param key key whose associated stream is to be returned.

     * @since 1.4

     */

    public InputStream getStream(String key);

    /**

     * Finds all the keys of the streams in this applet context.

     * <p>

     * For security reasons, mapping of streams and keys exists for each

     * codebase. In other words, applet from one codebase cannot access

     * the streams created by an applet from a different codebase

     *

     * @return  an Iterator of all the names of the streams in this applet

     *          context.

     * @since 1.4

     */

    public Iterator<String> getStreamKeys();

}