1 /*
   2  * Copyright (c) 1995, 2017, 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 java.applet;
  27 
  28 import java.awt.Image;
  29 import java.awt.Graphics;
  30 import java.awt.image.ColorModel;
  31 import java.net.URL;
  32 import java.util.Enumeration;
  33 import java.io.InputStream;
  34 import java.io.IOException;
  35 import java.util.Iterator;
  36 
  37 /**
  38  * This interface corresponds to an applet's environment: the
  39  * document containing the applet and the other applets in the same
  40  * document.
  41  * <p>
  42  * The methods in this interface can be used by an applet to obtain
  43  * information about its environment.
  44  *
  45  * @author      Arthur van Hoff
  46  * @since       1.0
  47  *
  48  * @deprecated  The Applet API is deprecated. See the
  49  * <a href="package-summary.html"> java.applet package documentation</a>
  50  * for further information.
  51  */
  52 
  53 @Deprecated(since = "9")
  54 public interface AppletContext {
  55     /**
  56      * Creates an audio clip.
  57      *
  58      * @param   url   an absolute URL giving the location of the audio clip.
  59      * @return  the audio clip at the specified URL.
  60      */
  61     AudioClip getAudioClip(URL url);
  62 
  63     /**
  64      * Returns an {@code Image} object that can then be painted on
  65      * the screen. The {@code url} argument that is
  66      * passed as an argument must specify an absolute URL.
  67      * <p>
  68      * This method always returns immediately, whether or not the image
  69      * exists. When the applet attempts to draw the image on the screen,
  70      * the data will be loaded. The graphics primitives that draw the
  71      * image will incrementally paint on the screen.
  72      *
  73      * @param   url   an absolute URL giving the location of the image.
  74      * @return  the image at the specified URL.
  75      * @see     java.awt.Image
  76      */
  77     Image getImage(URL url);
  78 
  79     /**
  80      * Finds and returns the applet in the document represented by this
  81      * applet context with the given name. The name can be set in the
  82      * HTML tag by setting the {@code name} attribute.
  83      *
  84      * @param   name   an applet name.
  85      * @return  the applet with the given name, or {@code null} if
  86      *          not found.
  87      */
  88     Applet getApplet(String name);
  89 
  90     /**
  91      * Finds all the applets in the document represented by this applet
  92      * context.
  93      *
  94      * @return  an enumeration of all applets in the document represented by
  95      *          this applet context.
  96      */
  97     Enumeration<Applet> getApplets();
  98 
  99     /**
 100      * Requests that the browser or applet viewer show the Web page
 101      * indicated by the {@code url} argument. The browser or
 102      * applet viewer determines which window or frame to display the
 103      * Web page. This method may be ignored by applet contexts that
 104      * are not browsers.
 105      *
 106      * @param   url   an absolute URL giving the location of the document.
 107      */
 108     void showDocument(URL url);
 109 
 110     /**
 111      * Requests that the browser or applet viewer show the Web page
 112      * indicated by the {@code url} argument. The
 113      * {@code target} argument indicates in which HTML frame the
 114      * document is to be displayed.
 115      * The target argument is interpreted as follows:
 116      *
 117      * <table class="striped">
 118      * <caption>Target arguments and their descriptions</caption>
 119      * <thead>
 120      * <tr><th>Target Argument</th>
 121      * <th>Description</th></tr>
 122      * </thead>
 123      * <tbody>
 124      * <tr><td>{@code "_self"}  <td>Show in the window and frame that
 125      *                                   contain the applet.</tr>
 126      * <tr><td>{@code "_parent"}<td>Show in the applet's parent frame. If
 127      *                                   the applet's frame has no parent frame,
 128      *                                   acts the same as "_self".</tr>
 129      * <tr><td>{@code "_top"}   <td>Show in the top-level frame of the applet's
 130      *                                   window. If the applet's frame is the
 131      *                                   top-level frame, acts the same as "_self".</tr>
 132      * <tr><td>{@code "_blank"} <td>Show in a new, unnamed
 133      *                                   top-level window.</tr>
 134      * <tr><td><i>name</i><td>Show in the frame or window named <i>name</i>. If
 135      *                        a target named <i>name</i> does not already exist, a
 136      *                        new top-level window with the specified name is created,
 137      *                        and the document is shown there.</tr>
 138      * </tbody>
 139      * </table>
 140      * <p>
 141      * An applet viewer or browser is free to ignore {@code showDocument}.
 142      *
 143      * @param   url   an absolute URL giving the location of the document.
 144      * @param   target   a {@code String} indicating where to display
 145      *                   the page.
 146      */
 147     public void showDocument(URL url, String target);
 148 
 149     /**
 150      * Requests that the argument string be displayed in the
 151      * "status window". Many browsers and applet viewers
 152      * provide such a window, where the application can inform users of
 153      * its current state.
 154      *
 155      * @param   status   a string to display in the status window.
 156      */
 157     void showStatus(String status);
 158 
 159     /**
 160      * Associates the specified stream with the specified key in this
 161      * applet context. If the applet context previously contained a mapping
 162      * for this key, the old value is replaced.
 163      * <p>
 164      * For security reasons, mapping of streams and keys exists for each
 165      * codebase. In other words, applet from one codebase cannot access
 166      * the streams created by an applet from a different codebase
 167      *
 168      * @param key key with which the specified value is to be associated.
 169      * @param stream stream to be associated with the specified key. If this
 170      *               parameter is {@code null}, the specified key is removed
 171      *               in this applet context.
 172      * @throws IOException if the stream size exceeds a certain
 173      *         size limit. Size limit is decided by the implementor of this
 174      *         interface.
 175      * @since 1.4
 176      */
 177     public void setStream(String key, InputStream stream)throws IOException;
 178 
 179     /**
 180      * Returns the stream to which specified key is associated within this
 181      * applet context. Returns {@code null} if the applet context contains
 182      * no stream for this key.
 183      * <p>
 184      * For security reasons, mapping of streams and keys exists for each
 185      * codebase. In other words, applet from one codebase cannot access
 186      * the streams created by an applet from a different codebase
 187      *
 188      * @return the stream to which this applet context maps the key
 189      * @param key key whose associated stream is to be returned.
 190      * @since 1.4
 191      */
 192     public InputStream getStream(String key);
 193 
 194     /**
 195      * Finds all the keys of the streams in this applet context.
 196      * <p>
 197      * For security reasons, mapping of streams and keys exists for each
 198      * codebase. In other words, applet from one codebase cannot access
 199      * the streams created by an applet from a different codebase
 200      *
 201      * @return  an Iterator of all the names of the streams in this applet
 202      *          context.
 203      * @since 1.4
 204      */
 205     public Iterator<String> getStreamKeys();
 206 }