org.graalvm.polyglot

Class Source.Builder

java.lang.Object

org.graalvm.polyglot.Source.Builder

Enclosing class:

Source

public class Source.Builder
extends Object

Represents a builder to build Source objects. To load a source from disk one can use:

File file = new File(dir, name);
assert name.endsWith(".java") : "Imagine proper file";

String language = Source.findLanguage(file);
Source source = Source.newBuilder(language, file).build();

assert file.getName().equals(source.getName());
assert file.getPath().equals(source.getPath());
assert file.toURI().equals(source.getURI());

To load source from a URL one can use:

URL resource = relativeClass.getResource("sample.js");
Source source = Source.newBuilder("js", resource)
                .build();
assert resource.toExternalForm().equals(source.getPath());
assert "sample.js".equals(source.getName());
assert resource.toURI().equals(source.getURI());

To create a source representing characters:

Source source = Source.newBuilder("js", "function() {\n"
    + "  return 'Hi';\n"
    + "}\n", "hi.js").buildLiteral();
assert "hi.js".equals(source.getName());

or read a source from a Reader:

Reader stream = new InputStreamReader(
                relativeClass.getResourceAsStream("sample.js")
);
Source source = Source.newBuilder("js", stream, "sample.js")
    .build();
assert "sample.js".equals(source.getName());

To create a source representing bytes:

byte[] bytes = new byte[] {/* Binary */};
Source source = Source.newBuilder("llvm",
                ByteSequence.create(bytes),
                "<literal>").buildLiteral();

Once your builder is configured, call Source.Builder.build() to perform the loading and construction of new Source.

Since:

19.0

Method Summary

Modifier and Type	Method and Description
Source	build() Uses configuration of this builder to create new Source object.
Source	buildLiteral() Uses configuration of this builder to create new Source object.
Source.Builder	cached(boolean cached) Enables or disables code caching for this source.
Source.Builder	content(ByteSequence bytes) Specifies byte based content of to-be-built Source.
Source.Builder	content(CharSequence characters) Specifies character based content of to-be-built Source.
Source.Builder	content(String code) Specifies content of to-be-built Source.
Source.Builder	encoding(Charset encoding) Assigns an encoding used to read the file content.
Source.Builder	interactive(boolean interactive) Marks the source as interactive.
Source.Builder	internal(boolean internal) Set whether this source has been marked as internal, meaning that it has been provided by the infrastructure, language implementation, or system library.
Source.Builder	mimeType(String mimeType) Explicitly assigns a MIME type to the to-be-built Source.
Source.Builder	name(String newName) Specifies a name to the to-be-built Source.
Source.Builder	uri(URI newUri) Assigns new URI to the to-be-created Source.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

name

public Source.Builder name(String newName)

Specifies a name to the to-be-built Source.

Parameters:

newName - name that replaces the previously given one. If set to null then "Unnamed" will be used.

Returns:

instance of this builder

Since:

19.0

content

public Source.Builder content(String code)

Specifies content of to-be-built Source. Using this method one can ignore the real content of a file or URL and use already read one, or completely different one. Example:

URL resource = relativeClass.getResource("sample.js");
Source source = Source.newBuilder("js", resource)
    .content("{}")
    .buildLiteral();
assert resource.toExternalForm().equals(source.getPath());
assert "sample.js".equals(source.getName());
assert resource.toExternalForm().equals(source.getURI().toString());
assert "{}".equals(source.getCharacters());

Parameters:

code - the code to be available via Source.getCharacters()

Returns:

instance of this builder

Since:

19.0

content

public Source.Builder content(CharSequence characters)

Specifies character based content of to-be-built Source. Using this method one can ignore the real content of a file or URL and use already read one, or completely different one. The given characters must not mutate after they were accessed for the first time. Example:

URL resource = relativeClass.getResource("sample.js");
Source source = Source.newBuilder("js", resource)
    .content("{}")
    .buildLiteral();
assert resource.toExternalForm().equals(source.getPath());
assert "sample.js".equals(source.getName());
assert resource.toExternalForm().equals(source.getURI().toString());
assert "{}".equals(source.getCharacters());

Parameters:

characters - the code to be available via Source.getCharacters()

Returns:

instance of this builder - which's Source.Builder.build() method no longer throws an IOException

Since:

19.0

content

public Source.Builder content(ByteSequence bytes)

Specifies byte based content of to-be-built Source. Using this method one can ignore the real content of a file or URL and use already read one, or completely different one. The given bytes must not mutate after they were accessed for the first time. Example:

URL resource = relativeClass.getResource("sample.js");
Source source = Source.newBuilder("js", resource)
    .content("{}")
    .buildLiteral();
assert resource.toExternalForm().equals(source.getPath());
assert "sample.js".equals(source.getName());
assert resource.toExternalForm().equals(source.getURI().toString());
assert "{}".equals(source.getCharacters());

Parameters:

bytes - the code to be available via Source.getBytes()

Returns:

instance of this builder - which's Source.Builder.build() method no longer throws an IOException

Since:

19.0

mimeType

public Source.Builder mimeType(String mimeType)

Explicitly assigns a MIME type to the to-be-built Source. If the MIME type is null then the default MIME type of the language will be used to interpret the source. If set explicitly then the language needs to support the MIME type in order to evaluate the source. If not null the MIME type is already verified containing no spaces and a '/' between group and sub-group. An example for a valid MIME type is: text/javascript.

The MIME type can be guessed by the system based on files or urls. If a source is binary based then the MIME type must also be a binary based MIME type. All MIME types starting with 'text/' will be interpreted as character based MIME types.

Parameters:

mimeType - the new mime type to be assigned, or null if default MIME type should be used.

Returns:

instance of this builder ready to create new source

Since:

19.0

See Also:

Language.getDefaultMimeType(), Language.getMimeTypes(), Source.findMimeType(File), Source.findMimeType(URL)

interactive

public Source.Builder interactive(boolean interactive)

Marks the source as interactive. Evaluation of interactive sources by an interactive language can use the Context output streams to print the result and read an input. However, non-interactive languages are expected to ignore the interactive property of sources and not use the polyglot engine streams. Any desired printing of the evaluated result provided by a non-interactive language needs to be handled by the caller. Calling of this method influences the result of Source.isInteractive().

Returns:

the instance of this builder

Since:

19.0

internal

public Source.Builder internal(boolean internal)

Set whether this source has been marked as internal, meaning that it has been provided by the infrastructure, language implementation, or system library. Internal sources are presumed to be irrelevant to guest language programmers, as well as possibly confusing and revealing of language implementation details.

On the other hand, tools should be free to make internal sources visible in (possibly privileged) modes that are useful for language implementors.

Returns:

the instance of this builder

Since:

19.0

cached

public Source.Builder cached(boolean cached)

Enables or disables code caching for this source. By default code caching is enabled. If true then the source does not require parsing every time this source is evaluated. If false then the source requires parsing every time the source is evaluated but does not remember any state. Disabling caching may be useful if the source is known to only be evaluated once.

If a source instance is no longer referenced by the client then all code caches will be freed automatically. Also, if the underlying context or engine is no longer referenced then cached code for evaluated sources will be freed automatically.

Returns:

instance of this builder ready to create new source

Since:

19.0

uri

public Source.Builder uri(URI newUri)

Assigns new URI to the to-be-created Source. Each source provides Source.getURI() as a persistent identification of its location. A default value for the method is deduced from the location or content, but one can change it by using this method

Parameters:

newUri - the URL to use instead of default one, cannot be null

Returns:

the instance of this builder

Since:

19.0

encoding

public Source.Builder encoding(Charset encoding)

Assigns an encoding used to read the file content. If the encoding is null then the file contained encoding information is used. If the file doesn't provide an encoding information the default UTF-8 encoding is used.

Parameters:

encoding - the new file encoding to be used for reading the content

Returns:

instance of this builder ready to create new source

Since:

19.0

build

public Source build()
             throws IOException

Uses configuration of this builder to create new Source object. The method throws an IOException if an error loading the source occurred.

Returns:

the source object

Throws:

IOException

Since:

19.0

buildLiteral

public Source buildLiteral()

Uses configuration of this builder to create new Source object. This method can only be used if the builder was created as string literal builder and otherwise throws an UnsupportedOperationException.

Returns:

the source object

Since:

19.0