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