JAL-3763 refactored getCoveringMapping for virtual feature discovery
[jalview.git] / src / swingjs / api / JSUtilI.java
1 package swingjs.api;
2
3 import java.awt.Component;
4 import java.io.File;
5 import java.io.InputStream;
6 import java.net.URL;
7 import java.util.HashMap;
8 import java.util.Properties;
9
10 import swingjs.api.js.HTML5Applet;
11
12 public interface JSUtilI {
13
14   /**
15    * Indicate to SwingJS that the given file type is binary.
16    * 
17    * @param ext
18    */
19   void addBinaryFileType(String ext);
20
21   /**
22    * Indicate to SwingJS that we can load files using AJAX from the given
23    * domain, such as "www.stolaf.edu", because we know that CORS access has been
24    * provided.
25    * 
26    * @param domain
27    */
28   void addDirectDatabaseCall(String domain);
29
30   /**
31    * Cache or uncache data under the given path name.
32    * 
33    * @param path
34    * @param data
35    *          null to remove from the cache
36    */
37   void cachePathData(String path, Object data);
38
39   /**
40    * Get the HTML5 object corresponding to the specified Component, or the
41    * current thread if null.
42    * 
43    * @param c
44    *          the associated component, or null for the current thread
45    * @return HTML5 applet object
46    */
47   HTML5Applet getAppletForComponent(Component c);
48
49   /**
50    * Get an attribute applet.foo for the applet found using getApplet(null).
51    * 
52    * @param key
53    * @return
54    */
55   Object getAppletAttribute(String key);
56
57   /**
58    * Get the code base (swingjs/j2s, probably) for the applet found using
59    * getApplet(null).
60    * 
61    * @return
62    */
63   URL getCodeBase();
64
65   /**
66    * Get the document base (wherever the page is) for the applet found using
67    * getApplet(null).
68    * 
69    * @return
70    */
71
72   URL getDocumentBase();
73
74   /**
75    * Get an attribute from the div on the page that is associated with this
76    * frame, i.e. with id frame.getName() + "-div".
77    * 
78    * @param frame
79    * @param type
80    *          "node" or "dim"
81    * @return
82    */
83   Object getEmbeddedAttribute(Component frame, String type);
84
85   /**
86    * Get a file synchronously.
87    * 
88    * @param path
89    * @param asString
90    *          true for String; false for byte[]
91    * @return byte[] or String
92    */
93   Object getFile(String path, boolean asString);
94
95   /**
96    * Get the 秘bytes field associated with a file, but only if the File object
97    * itself has them attached, not downloading them.
98    * 
99    * @param f
100    * @return
101    */
102   byte[] getBytes(File f);
103
104   /**
105    * Retrieve a HashMap consisting of whatever the application wants, but
106    * guaranteed to be unique to this app context, that is, for the applet found
107    * using getApplet(null).
108    * 
109    * @param contextKey
110    * @return
111    */
112   HashMap<?, ?> getJSContext(Object contextKey);
113
114   /**
115    * Load a resource -- probably a core file -- if and only if a particular
116    * class has not been instantialized. We use a String here because if we used
117    * a .class object, that reference itself would simply load the class, and we
118    * want the core package to include that as well.
119    * 
120    * @param resourcePath
121    * @param className
122    */
123   void loadResourceIfClassUnknown(String resource, String className);
124
125   /**
126    * Read all applet.__Info properties for the applet found using
127    * getApplet(null) that start with the given prefix, such as "jalview_". A
128    * null prefix retrieves all properties. Note that non-string properties will
129    * be stringified.
130    * 
131    * @param prefix
132    *          an application prefix, or null for all properties
133    * @param p
134    *          properties to be appended to
135    */
136   void readInfoProperties(String prefix, Properties p);
137
138   /**
139    * Set an attribute for the applet found using getApplet(null). That is,
140    * applet[key] = val.
141    * 
142    * @param key
143    * @param val
144    */
145   void setAppletAttribute(String key, Object val);
146
147   /**
148    * Set an attribute of applet's Info map for the applet found using
149    * getApplet(null). That is, applet.__Info[key] = val.
150    * 
151    * @param infoKey
152    * @param val
153    */
154   void setAppletInfo(String infoKey, Object val);
155
156   /**
157    * Set the given File object's 秘bytes field from an InputStream or a byte[]
158    * array. If the file is a JSTempFile, then also cache those bytes.
159    * 
160    * @param f
161    * @param isOrBytes
162    *          BufferedInputStream, ByteArrayInputStream, FileInputStream, or
163    *          byte[]
164    * @return
165    */
166   boolean setFileBytes(File f, Object isOrBytes);
167
168   /**
169    * Same as setFileBytes, but also caches the data if it is a JSTempFile.
170    * 
171    * @param is
172    * @param outFile
173    * @return
174    */
175   boolean streamToFile(InputStream is, File outFile);
176
177   /**
178    * Switch the flag in SwingJS to use or not use the JavaScript Map object in
179    * Hashtable, HashMap, and HashSet. Default is enabled.
180    * 
181    */
182
183   void setJavaScriptMapObjectEnabled(boolean enabled);
184
185 }