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