Mercurial > hg > truffle

comparison truffle/com.oracle.truffle.api.vm/src/com/oracle/truffle/api/vm/PolyglotEngine.java @ 22325:414e82b9fc35

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Release 0.9 is out, let's remove deprecated elements from the API
author Jaroslav Tulach <jaroslav.tulach@oracle.com>
date Fri, 23 Oct 2015 20:23:00 +0200
parents 096e2c0fd2dc
children 1801b7f11c64
comparison
equal deleted inserted replaced
22324:ad67d348e361 22325:414e82b9fc35
23 * questions. 23 * questions.
24 */ 24 */
25 package com.oracle.truffle.api.vm; 25 package com.oracle.truffle.api.vm;
26 26
27 import java.io.Closeable; 27 import java.io.Closeable;
28 import java.io.File;
29 import java.io.IOException; 28 import java.io.IOException;
30 import java.io.InputStream; 29 import java.io.InputStream;
31 import java.io.InterruptedIOException; 30 import java.io.InterruptedIOException;
32 import java.io.OutputStream; 31 import java.io.OutputStream;
33 import java.io.Reader;
34 import java.io.Writer;
35 import java.net.URI;
36 import java.net.URL;
37 import java.net.URLConnection;
38 import java.nio.file.Files;
39 import java.util.ArrayList; 32 import java.util.ArrayList;
40 import java.util.Arrays; 33 import java.util.Arrays;
41 import java.util.Collections; 34 import java.util.Collections;
42 import java.util.HashMap; 35 import java.util.HashMap;
43 import java.util.HashSet; 36 import java.util.HashSet;
92 * Use {@link #buildNew()} to create new isolated portal ready for execution of various languages. 85 * Use {@link #buildNew()} to create new isolated portal ready for execution of various languages.
93 * All the languages in a single portal see each other exported global symbols and can cooperate. 86 * All the languages in a single portal see each other exported global symbols and can cooperate.
94 * Use {@link #buildNew()} multiple times to create different, isolated portal environment 87 * Use {@link #buildNew()} multiple times to create different, isolated portal environment
95 * completely separated from each other. 88 * completely separated from each other.
96 * <p> 89 * <p>
97 * Once instantiated use {@link #eval(java.net.URI)} with a reference to a file or URL or directly 90 * Once instantiated use {@link #eval(com.oracle.truffle.api.source.Source)} with a reference to a
98 * pass code snippet into the virtual machine via {@link #eval(java.lang.String, java.lang.String)}. 91 * file or URL or directly pass code snippet into the virtual machine via
99 * Support for individual languages is initialized on demand - e.g. once a file of certain MIME type 92 * {@link #eval(com.oracle.truffle.api.source.Source)}. Support for individual languages is
100 * is about to be processed, its appropriate engine (if found), is initialized. Once an engine gets 93 * initialized on demand - e.g. once a file of certain MIME type is about to be processed, its
101 * initialized, it remains so, until the virtual machine isn't garbage collected. 94 * appropriate engine (if found), is initialized. Once an engine gets initialized, it remains so,
95 * until the virtual machine isn't garbage collected.
102 * <p> 96 * <p>
103 * The engine is single-threaded and tries to enforce that. It records the thread it has been 97 * The engine is single-threaded and tries to enforce that. It records the thread it has been
104 * {@link Builder#build() created} by and checks that all subsequent calls are coming from the same 98 * {@link Builder#build() created} by and checks that all subsequent calls are coming from the same
105 * thread. There is 1:1 mapping between {@link PolyglotEngine} and a thread that can tell it what to 99 * thread. There is 1:1 mapping between {@link PolyglotEngine} and a thread that can tell it what to
106 * do. 100 * do.
182 * .{@link Builder#build() build()}; 176 * .{@link Builder#build() build()};
183 * </pre> 177 * </pre>
184 * 178 *
185 * It searches for {@link Registration languages registered} in the system class loader and 179 * It searches for {@link Registration languages registered} in the system class loader and
186 * makes them available for later evaluation via 180 * makes them available for later evaluation via
187 * {@link #eval(java.lang.String, java.lang.String)} methods. 181 * {@link #eval(com.oracle.truffle.api.source.Source)} method.
188 * 182 *
189 * @return new, isolated virtual machine with pre-registered languages 183 * @return new, isolated virtual machine with pre-registered languages
190 */ 184 */
191 public static PolyglotEngine.Builder buildNew() { 185 public static PolyglotEngine.Builder buildNew() {
192 // making Builder non-static inner class is a 186 // making Builder non-static inner class is a
230 out = os; 224 out = os;
231 return this; 225 return this;
232 } 226 }
233 227
234 /** 228 /**
235 * @deprecated does nothing
236 */
237 @Deprecated
238 @SuppressWarnings("unused")
239 public Builder stdOut(Writer w) {
240 return this;
241 }
242
243 /**
244 * Changes the error output for languages running in <em>to be created</em> 229 * Changes the error output for languages running in <em>to be created</em>
245 * {@link PolyglotEngine virtual machine}. The default is to use {@link System#err}. 230 * {@link PolyglotEngine virtual machine}. The default is to use {@link System#err}.
246 * 231 *
247 * @param os the stream to use as output 232 * @param os the stream to use as output
248 * @return instance of this builder 233 * @return instance of this builder
251 err = os; 236 err = os;
252 return this; 237 return this;
253 } 238 }
254 239
255 /** 240 /**
256 * @deprecated does nothing
257 */
258 @Deprecated
259 @SuppressWarnings("unused")
260 public Builder stdErr(Writer w) {
261 return this;
262 }
263
264 /**
265 * Changes the default input for languages running in <em>to be created</em> 241 * Changes the default input for languages running in <em>to be created</em>
266 * {@link PolyglotEngine virtual machine}. The default is to use {@link System#in}. 242 * {@link PolyglotEngine virtual machine}. The default is to use {@link System#in}.
267 * 243 *
268 * @param is the stream to use as input 244 * @param is the stream to use as input
269 * @return instance of this builder 245 * @return instance of this builder
270 */ 246 */
271 public Builder setIn(InputStream is) { 247 public Builder setIn(InputStream is) {
272 in = is; 248 in = is;
273 return this;
274 }
275
276 /**
277 * @deprecated does nothing
278 */
279 @Deprecated
280 @SuppressWarnings("unused")
281 public Builder stdIn(Reader r) {
282 return this; 249 return this;
283 } 250 }
284 251
285 /** 252 /**
286 * Registers another instance of {@link EventConsumer} into the to be created 253 * Registers another instance of {@link EventConsumer} into the to be created
368 * @return an immutable map with keys being MIME types and values the {@link Language 335 * @return an immutable map with keys being MIME types and values the {@link Language
369 * descriptions} of associated languages 336 * descriptions} of associated languages
370 */ 337 */
371 public Map<String, ? extends Language> getLanguages() { 338 public Map<String, ? extends Language> getLanguages() {
372 return Collections.unmodifiableMap(langs); 339 return Collections.unmodifiableMap(langs);
373 }
374
375 /**
376 * Evaluates file located on a given URL. Is equivalent to loading the content of a file and
377 * executing it via {@link #eval(java.lang.String, java.lang.String)} with a MIME type guess
378 * based on the file's extension and/or content.
379 *
380 * @param location the location of a file to execute
381 * @return result of a processing the file, possibly <code>null</code>
382 * @throws IOException exception to signal I/O problems or problems with processing the file's
383 * content
384 * @deprecated use {@link #eval(com.oracle.truffle.api.source.Source)}
385 */
386 @Deprecated
387 public Object eval(URI location) throws IOException {
388 checkThread();
389 Source s;
390 String mimeType;
391 if (location.getScheme().equals("file")) {
392 File file = new File(location);
393 s = Source.fromFileName(file.getPath(), true);
394 mimeType = Files.probeContentType(file.toPath());
395 } else {
396 URL url = location.toURL();
397 s = Source.fromURL(url, location.toString());
398 URLConnection conn = url.openConnection();
399 mimeType = conn.getContentType();
400 }
401 Language l = langs.get(mimeType);
402 if (l == null) {
403 throw new IOException("No language for " + location + " with MIME type " + mimeType + " found. Supported types: " + langs.keySet());
404 }
405 return eval(l, s).get();
406 }
407
408 /**
409 * Evaluates code snippet. Chooses a language registered for a given MIME type (throws
410 * {@link IOException} if there is none). And passes the specified code to it for execution.
411 *
412 * @param mimeType MIME type of the code snippet - chooses the right language
413 * @param reader the source of code snippet to execute
414 * @return result of an execution, possibly <code>null</code>
415 * @throws IOException thrown to signal errors while processing the code
416 * @deprecated use {@link #eval(com.oracle.truffle.api.source.Source)}
417 */
418 @Deprecated
419 public Object eval(String mimeType, Reader reader) throws IOException {
420 checkThread();
421 Language l = langs.get(mimeType);
422 if (l == null) {
423 throw new IOException("No language for MIME type " + mimeType + " found. Supported types: " + langs.keySet());
424 }
425 return eval(l, Source.fromReader(reader, mimeType)).get();
426 }
427
428 /**
429 * Evaluates code snippet. Chooses a language registered for a given MIME type (throws
430 * {@link IOException} if there is none). And passes the specified code to it for execution.
431 *
432 * @param mimeType MIME type of the code snippet - chooses the right language
433 * @param code the code snippet to execute
434 * @return result of an execution, possibly <code>null</code>
435 * @throws IOException thrown to signal errors while processing the code
436 * @deprecated use {@link #eval(com.oracle.truffle.api.source.Source)}
437 */
438 @Deprecated
439 public Object eval(String mimeType, String code) throws IOException {
440 checkThread();
441 Language l = langs.get(mimeType);
442 if (l == null) {
443 throw new IOException("No language for MIME type " + mimeType + " found. Supported types: " + langs.keySet());
444 }
445 return eval(l, Source.fromText(code, mimeType)).get();
446 } 340 }
447 341
448 /** 342 /**
449 * Evaluates provided source. Chooses language registered for a particular 343 * Evaluates provided source. Chooses language registered for a particular
450 * {@link Source#getMimeType() MIME type} (throws {@link IOException} if there is none). The 344 * {@link Source#getMimeType() MIME type} (throws {@link IOException} if there is none). The
574 } 468 }
575 } 469 }
576 470
577 /** 471 /**
578 * Looks global symbol provided by one of initialized languages up. First of all execute your 472 * Looks global symbol provided by one of initialized languages up. First of all execute your
579 * program via one of your {@link #eval(java.lang.String, java.lang.String)} and then look 473 * program via one of your {@link #eval(com.oracle.truffle.api.source.Source)} and then look
580 * expected symbol up using this method. 474 * expected symbol up using this method.
581 * <p> 475 * <p>
582 * The names of the symbols are language dependent, but for example the Java language bindings 476 * The names of the symbols are language dependent, but for example the Java language bindings
583 * follow the specification for method references: 477 * follow the specification for method references:
584 * <ul> 478 * <ul>
858 * information into a descriptor inside of the language's JAR file. When a new 752 * information into a descriptor inside of the language's JAR file. When a new
859 * {@link PolyglotEngine} is created, it reads all available descriptors and creates 753 * {@link PolyglotEngine} is created, it reads all available descriptors and creates
860 * {@link Language} objects to represent them. One can obtain a {@link #getName() name} or list 754 * {@link Language} objects to represent them. One can obtain a {@link #getName() name} or list
861 * of supported {@link #getMimeTypes() MIME types} for each language. The actual language 755 * of supported {@link #getMimeTypes() MIME types} for each language. The actual language
862 * implementation is not initialized until 756 * implementation is not initialized until
863 * {@link PolyglotEngine#eval(java.lang.String, java.lang.String) a code is evaluated} in it. 757 * {@link PolyglotEngine#eval(com.oracle.truffle.api.source.Source) a code is evaluated} in it.
864 */ 758 */
865 public class Language { 759 public class Language {
866 private final LanguageCache info; 760 private final LanguageCache info;
867 private TruffleLanguage.Env env; 761 private TruffleLanguage.Env env;
868 762
924 818
925 Object[] res = {SPI.languageGlobal(getEnv(true)), null}; 819 Object[] res = {SPI.languageGlobal(getEnv(true)), null};
926 return res[0] == null ? null : new Value(new TruffleLanguage[]{info.getImpl(true)}, res, null); 820 return res[0] == null ? null : new Value(new TruffleLanguage[]{info.getImpl(true)}, res, null);
927 } 821 }
928 822
929 /**
930 * @deprecated concatenate {@link #getName()} and {@link #getVersion()} the way you want.
931 */
932 @Deprecated
933 public String getShortName() {
934 return getName() + "(" + getVersion() + ")";
935 }
936
937 TruffleLanguage<?> getImpl(boolean create) { 823 TruffleLanguage<?> getImpl(boolean create) {
938 getEnv(create); 824 getEnv(create);
939 TruffleLanguage<?> impl = info.getImpl(false); 825 TruffleLanguage<?> impl = info.getImpl(false);
940 return impl; 826 return impl;
941 } 827 }
947 return env; 833 return env;
948 } 834 }
949 835
950 @Override 836 @Override
951 public String toString() { 837 public String toString() {
952 return "[" + getShortName() + " for " + getMimeTypes() + "]"; 838 return "[" + getName() + "@ " + getVersion() + " for " + getMimeTypes() + "]";
953 } 839 }
954 } // end of Language 840 } // end of Language
955 841
956 // 842 //
957 // Accessor helper methods 843 // Accessor helper methods