src/swingjs/api/JSUtilI.java

   1 package swingjs.api;
   2
   3 import java.awt.Component;
   4 import java.io.File;
   5 import java.io.IOException;
   6 import java.io.InputStream;
   7 import java.io.OutputStream;
   8 import java.net.URL;
   9 import java.util.HashMap;
  10 import java.util.Map;
  11 import java.util.Properties;
  12 import java.util.function.Function;
  13 import java.util.zip.ZipEntry;
  14 import java.util.zip.ZipInputStream;
  15
  16 import javax.swing.JComponent;
  17
  18 import swingjs.api.js.HTML5Applet;
  19
  20 public interface JSUtilI
  21 {
  22
  23         /**
  24          * The HTML5 canvas delivers [r g b a r g b a ...] which is not a Java option.
  25          * The closest Java option is TYPE_4BYTE_ABGR, but that is not quite what we
  26          * need. SwingJS decodes TYPE_4BYTE_HTML5 as TYPE_4BYTE_RGBA"
  27          *
  28          * ColorSpace cs = ColorSpace.getInstance(ColorSpace.CS_sRGB);
  29          *
  30          * int[] nBits = { 8, 8, 8, 8 };
  31          *
  32          * int[] bOffs = { 0, 1, 2, 3 };
  33          *
  34          * colorModel = new ComponentColorModel(cs, nBits, true, false,
  35          * Transparency.TRANSLUCENT, DataBuffer.TYPE_BYTE);
  36          *
  37          * raster = Raster.createInterleavedRaster(DataBuffer.TYPE_BYTE, width, height,
  38          * width * 4, 4, bOffs, null);
  39          *
  40          * Note, however, that this buffer type should only be used for direct buffer access
  41          * using
  42          *
  43          *
  44          *
  45          */
  46         public static final int TYPE_4BYTE_HTML5 = -6;
  47
  48         /**
  49          * The HTML5 VIDEO element wrapped in a BufferedImage.
  50          *
  51          * To be extended to allow video capture?
  52          */
  53         public static final int TYPE_HTML5_VIDEO = Integer.MIN_VALUE;
  54
  55         /**
  56          * Indicate to SwingJS that the given file type is binary.
  57          *
  58          * @param ext
  59          */
  60         void addBinaryFileType(String ext);
  61
  62         /**
  63          * Indicate to SwingJS that we can load files using AJAX from the given domain,
  64          * such as "www.stolaf.edu", because we know that CORS access has been provided.
  65          *
  66          * @param domain
  67          */
  68         void addDirectDatabaseCall(String domain);
  69
  70         /**
  71          * Cache or uncache data under the given path name.
  72          *
  73          * @param path
  74          * @param data null to remove from the cache
  75          */
  76         void cachePathData(String path, Object data);
  77
  78         /**
  79          * Get the HTML5 object corresponding to the specified Component, or the current thread if null.
  80          *
  81          * @param c  the associated component, or null for the current thread
  82          * @return HTML5 applet object
  83          */
  84         HTML5Applet getAppletForComponent(Component c);
  85
  86         /**
  87          * Get an attribute applet.foo for the applet found using getApplet(null).
  88          *
  89          * @param key
  90          * @return
  91          */
  92         Object getAppletAttribute(String key);
  93
  94
  95         /**
  96          * Get the applet's __Info map or an attribute of that map for the applet found using
  97          * getApplet(null). That is, applet.__Info or applet.__Info[InfoKey].
  98          *
  99          * @param infoKey if null, return the full __Info map
 100          */
 101         Object getAppletInfo(String infoKey);
 102
 103         /**
 104          * Get the code base (swingjs/j2s, probably) for the applet found using
 105          * getApplet(null).
 106          *
 107          * @return
 108          */
 109         URL getCodeBase();
 110
 111         /**
 112          * Get the document base (wherever the page is) for the applet found using
 113          * getApplet(null).
 114          *
 115          * @return
 116          */
 117
 118         URL getDocumentBase();
 119
 120         /**
 121          * Get an attribute from the div on the page that is associated with this frame,
 122          * i.e. with id frame.getName() + "-div".
 123          *
 124          * @param frame
 125          * @param type  "node" or "dim"
 126          * @return
 127          */
 128         Object getEmbeddedAttribute(Component frame, String type);
 129
 130         /**
 131          * Get a file synchronously.
 132          *
 133          * @param path
 134          * @param asString true for String; false for byte[]
 135          * @return byte[] or String
 136          */
 137         Object getFile(String path, boolean asString);
 138
 139         /**
 140          * Get the 秘bytes field associated with a file, but only if the File object itself has
 141          * them attached, not downloading them.
 142          *
 143          * @param f
 144          * @return
 145          */
 146         byte[] getBytes(File f);
 147
 148         /**
 149          * Retrieve a HashMap consisting of whatever the application wants, but
 150          * guaranteed to be unique to this app context, that is, for the applet found using
 151          * getApplet(null).
 152          *
 153          * @param contextKey
 154          * @return
 155          */
 156         HashMap<?, ?> getJSContext(Object contextKey);
 157
 158         /**
 159          * Load a resource -- probably a core file -- if and only if a particular class
 160          * has not been instantialized. We use a String here because if we used a .class
 161          * object, that reference itself would simply load the class, and we want the
 162          * core package to include that as well.
 163          *
 164          * @param resourcePath
 165          * @param className
 166          */
 167         void loadResourceIfClassUnknown(String resource, String className);
 168
 169         /**
 170          * Read all applet.__Info properties  for the applet found using
 171          * getApplet(null) that start with the given prefix, such as "jalview_".
 172          * A null prefix retrieves all properties. Note that non-string properties will be
 173          * stringified.
 174          *
 175          * @param prefix an application prefix, or null for all properties
 176          * @param p      properties to be appended to
 177          */
 178         void readInfoProperties(String prefix, Properties p);
 179
 180         /**
 181          * Set an attribute for the applet found using
 182          * getApplet(null). That is, applet[key] = val.
 183          *
 184          * @param key
 185          * @param val
 186          */
 187         void setAppletAttribute(String key, Object val);
 188
 189         /**
 190          * Set an attribute of applet's Info map for the applet found using
 191          * getApplet(null). That is, applet.__Info[key] = val.
 192          *
 193          * @param infoKey
 194          * @param val
 195          */
 196         void setAppletInfo(String infoKey, Object val);
 197
 198         /**
 199          * Set the given File object's 秘bytes field from an InputStream or a byte[] array.
 200          * If the file is a JSTempFile, then also cache those bytes.
 201          *
 202          * @param f
 203          * @param isOrBytes BufferedInputStream, ByteArrayInputStream, FileInputStream, or byte[]
 204          * @return
 205          */
 206         boolean setFileBytes(File f, Object isOrBytes);
 207
 208         /**
 209          * Set the given URL object's _streamData field from an InputStream or a byte[] array.
 210          *
 211          * @param f
 212          * @param isOrBytes BufferedInputStream, ByteArrayInputStream, FileInputStream, or byte[]
 213          * @return
 214          */
 215         boolean setURLBytes(URL url, Object isOrBytes);
 216
 217         /**
 218          * Same as setFileBytes.
 219          *
 220          * @param is
 221          * @param outFile
 222          * @return
 223          */
 224         boolean streamToFile(InputStream is, File outFile);
 225
 226           /**
 227            * Switch the flag in SwingJS to use or not use the JavaScript Map object in
 228            * Hashtable, HashMap, and HashSet. Default is enabled.
 229            *       *
 230            */
 231         void setJavaScriptMapObjectEnabled(boolean enabled);
 232
 233
 234         /**
 235          * Open a URL in a browser tab.
 236          *
 237          * @param url
 238          * @param target null or specific tab, such as "_blank"
 239          */
 240         void displayURL(String url, String target);
 241
 242         /**
 243          * Retrieve cached bytes for a path (with unnormalized name)
 244          * from J2S._javaFileCache.
 245          *
 246          * @param path
 247          *
 248          * @return byte[] or null
 249          */
 250         byte[] getCachedBytes(String path);
 251
 252         /**
 253          * Attach cached bytes to a file-like object, including URL,
 254          * or anything having a 秘bytes field (File, URI, Path)
 255          * from J2S._javaFileCache. That is, allow two such objects
 256          * to share the same underlying byte[ ] array.
 257          *
 258          *
 259          * @param URLorURIorFile
 260          * @return byte[] or null
 261          */
 262         byte[] addJSCachedBytes(Object URLorURIorFile);
 263
 264         /**
 265          * Seek an open ZipInputStream to the supplied ZipEntry, if possible.
 266          *
 267          * @param zis the ZipInputStream
 268          * @param ze  the ZipEntry
 269          * @return the length of this entry, or -1 if, for whatever reason, this was not possible
 270          */
 271         long seekZipEntry(ZipInputStream zis, ZipEntry ze);
 272
 273         /**
 274          * Retrieve the byte array associated with a ZipEntry.
 275          *
 276          * @param ze
 277          * @return
 278          */
 279         byte[] getZipBytes(ZipEntry ze);
 280
 281         /**
 282          * Java 9 method to read all (remaining) bytes from an InputStream. In SwingJS,
 283          * this may just create a new reference to an underlying Int8Array without
 284          * copying it.
 285          *
 286          * @param zis
 287          * @return
 288          * @throws IOException
 289          */
 290         byte[] readAllBytes(InputStream zis) throws IOException;
 291
 292         /**
 293          * Java 9 method to transfer all (remaining) bytes from an InputStream to an OutputStream.
 294          *
 295          * @param is
 296          * @param out
 297          * @return
 298          * @throws IOException
 299          */
 300         long transferTo(InputStream is, OutputStream out) throws IOException;
 301
 302         /**
 303          * Retrieve any bytes already attached to this URL.
 304          *
 305          * @param url
 306          * @return
 307          */
 308         byte[] getURLBytes(URL url);
 309
 310         /**
 311          * Set a message in the lower-left-hand corner SwingJS status block.
 312          *
 313          * @param msg
 314          * @param doFadeOut
 315          */
 316         void showStatus(String msg, boolean doFadeOut);
 317
 318         /**
 319          * Asynchronously retrieve the byte[] for a URL.
 320          *
 321          * @param url
 322          * @param whenDone
 323          */
 324         void getURLBytesAsync(URL url, Function<byte[], Void> whenDone);
 325
 326         /**
 327          * Experimental method to completely disable a Swing Component's user interface.
 328          *
 329          * @param jc
 330          * @param enabled
 331          */
 332         void setUIEnabled(JComponent jc, boolean enabled);
 333
 334
 335         /**
 336          * Play an audio
 337          * @param buffer
 338          * @param format a javax.sound.sampled.AudioFormat
 339          * @throws Exception
 340          */
 341         void playAudio(byte[] buffer, Object format) throws Exception;
 342
 343         /**
 344          * For either an applet or an application, get the ORIGINAL __Info as a Map that
 345          * has a full set up lower-case keys along with whatever non-all-lower-case keys
 346          * provided at start-up.
 347          *
 348          * @return
 349          */
 350         Map<String, Object> getAppletInfoAsMap();
 351
 352
 353   void setAppClass(Object j);
 354
 355 }