1. /*
  2. * @(#)AppletContext.java 1.31 04/05/05
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.applet;
  8. import java.awt.Image;
  9. import java.awt.Graphics;
  10. import java.awt.image.ColorModel;
  11. import java.net.URL;
  12. import java.util.Enumeration;
  13. import java.io.InputStream;
  14. import java.io.IOException;
  15. import java.util.Iterator;
  16. /**
  17. * This interface corresponds to an applet's environment: the
  18. * document containing the applet and the other applets in the same
  19. * document.
  20. * <p>
  21. * The methods in this interface can be used by an applet to obtain
  22. * information about its environment.
  23. *
  24. * @author Arthur van Hoff
  25. * @version 1.31, 05/05/04
  26. * @since JDK1.0
  27. */
  28. public interface AppletContext {
  29. /**
  30. * Creates an audio clip.
  31. *
  32. * @param url an absolute URL giving the location of the audio clip.
  33. * @return the audio clip at the specified URL.
  34. */
  35. AudioClip getAudioClip(URL url);
  36. /**
  37. * Returns an <code>Image</code> object that can then be painted on
  38. * the screen. The <code>url</code> argument<code> </code>that is
  39. * passed as an argument must specify an absolute URL.
  40. * <p>
  41. * This method always returns immediately, whether or not the image
  42. * exists. When the applet attempts to draw the image on the screen,
  43. * the data will be loaded. The graphics primitives that draw the
  44. * image will incrementally paint on the screen.
  45. *
  46. * @param url an absolute URL giving the location of the image.
  47. * @return the image at the specified URL.
  48. * @see java.awt.Image
  49. */
  50. Image getImage(URL url);
  51. /**
  52. * Finds and returns the applet in the document represented by this
  53. * applet context with the given name. The name can be set in the
  54. * HTML tag by setting the <code>name</code> attribute.
  55. *
  56. * @param name an applet name.
  57. * @return the applet with the given name, or <code>null</code> if
  58. * not found.
  59. */
  60. Applet getApplet(String name);
  61. /**
  62. * Finds all the applets in the document represented by this applet
  63. * context.
  64. *
  65. * @return an enumeration of all applets in the document represented by
  66. * this applet context.
  67. */
  68. Enumeration<Applet> getApplets();
  69. /**
  70. * Replaces the Web page currently being viewed with the given URL.
  71. * This method may be ignored by applet contexts that are not
  72. * browsers.
  73. *
  74. * @param url an absolute URL giving the location of the document.
  75. */
  76. void showDocument(URL url);
  77. /**
  78. * Requests that the browser or applet viewer show the Web page
  79. * indicated by the <code>url</code> argument. The
  80. * <code>target</code> argument indicates in which HTML frame the
  81. * document is to be displayed.
  82. * The target argument is interpreted as follows:
  83. * <p>
  84. * <center><table border="3" summary="Target arguments and their descriptions">
  85. * <tr><th>Target Argument</th><th>Description</th></tr>
  86. * <tr><td><code>"_self"</code> <td>Show in the window and frame that
  87. * contain the applet.</tr>
  88. * <tr><td><code>"_parent"</code><td>Show in the applet's parent frame. If
  89. * the applet's frame has no parent frame,
  90. * acts the same as "_self".</tr>
  91. * <tr><td><code>"_top"</code> <td>Show in the top-level frame of the applet's
  92. * window. If the applet's frame is the
  93. * top-level frame, acts the same as "_self".</tr>
  94. * <tr><td><code>"_blank"</code> <td>Show in a new, unnamed
  95. * top-level window.</tr>
  96. * <tr><td><i>name</i><td>Show in the frame or window named <i>name</i>. If
  97. * a target named <i>name</i> does not already exist, a
  98. * new top-level window with the specified name is created,
  99. * and the document is shown there.</tr>
  100. * </table> </center>
  101. * <p>
  102. * An applet viewer or browser is free to ignore <code>showDocument</code>.
  103. *
  104. * @param url an absolute URL giving the location of the document.
  105. * @param target a <code>String</code> indicating where to display
  106. * the page.
  107. */
  108. public void showDocument(URL url, String target);
  109. /**
  110. * Requests that the argument string be displayed in the
  111. * "status window". Many browsers and applet viewers
  112. * provide such a window, where the application can inform users of
  113. * its current state.
  114. *
  115. * @param status a string to display in the status window.
  116. */
  117. void showStatus(String status);
  118. /**
  119. * Associates the specified stream with the specified key in this
  120. * applet context. If the applet context previously contained a mapping
  121. * for this key, the old value is replaced.
  122. * <p>
  123. * For security reasons, mapping of streams and keys exists for each
  124. * codebase. In other words, applet from one codebase cannot access
  125. * the streams created by an applet from a different codebase
  126. * <p>
  127. * @param key key with which the specified value is to be associated.
  128. * @param stream stream to be associated with the specified key. If this
  129. * parameter is <code>null<code>, the specified key is removed
  130. * in this applet context.
  131. * @throws <code>IOException</code> if the stream size exceeds a certain
  132. * size limit. Size limit is decided by the implementor of this
  133. * interface.
  134. * @since JDK1.4
  135. */
  136. public void setStream(String key, InputStream stream)throws IOException;
  137. /**
  138. * Returns the stream to which specified key is associated within this
  139. * applet context. Returns <tt>null</tt> if the applet context contains
  140. * no stream for this key.
  141. * <p>
  142. * For security reasons, mapping of streams and keys exists for each
  143. * codebase. In other words, applet from one codebase cannot access
  144. * the streams created by an applet from a different codebase
  145. * <p>
  146. * @return the stream to which this applet context maps the key
  147. * @param key key whose associated stream is to be returned.
  148. * @since JDK1.4
  149. */
  150. public InputStream getStream(String key);
  151. /**
  152. * Finds all the keys of the streams in this applet context.
  153. * <p>
  154. * For security reasons, mapping of streams and keys exists for each
  155. * codebase. In other words, applet from one codebase cannot access
  156. * the streams created by an applet from a different codebase
  157. * <p>
  158. * @return an Iterator of all the names of the streams in this applet
  159. * context.
  160. * @since JDK1.4
  161. */
  162. public Iterator<String> getStreamKeys();
  163. }