com.oracle.truffle.api.source

Class Source.Builder<E1 extends Exception,E2 extends Exception,E3 extends Exception>

java.lang.Object

com.oracle.truffle.api.source.Source.Builder<E1,E2,E3>

Type Parameters:

E1 - the (checked) exception that one should expect when calling Source.Builder.build() method - usually an IOException, sometimes none.

E2 - either a MissingMIMETypeException to signal that one has to call Source.Builder.mimeType(java.lang.String) or a RuntimeException to signal everything seems to be OK

E3 - either a MissingNameException to signal that one has to call Source.Builder.name(java.lang.String) or a RuntimeException to signal everything seems to be OK

Enclosing class:

Source

public final class Source.Builder<E1 extends Exception,E2 extends Exception,E3 extends Exception>
extends Object

Allows one to specify additional attribute before creating new Source instance. One can specify Source.Builder.name(java.lang.String), Source.Builder.mimeType(java.lang.String), Source.Builder.content(java.lang.String) and/or whether a Source is internal or not. To load a source from disk one can use:

File file = new File(dir, name);
assert name.endsWith(".java") : "Imagine 'c:\\sources\\Example.java' file";

Source source = Source.newBuilder(file).build();

assert file.getName().equals(source.getName());
assert file.getPath().equals(source.getPath());
assert file.toURI().equals(source.getURI());
assert "text/x-java".equals(source.getMimeType());

To load source from a URL one can use:

URL resource = relativeClass.getResource("sample.js");
Source source = Source.newBuilder(resource)
    .name("sample.js")
    .build();
assert resource.toExternalForm().equals(source.getPath());
assert "sample.js".equals(source.getName());
assert "application/javascript".equals(source.getMimeType());
assert resource.toURI().equals(source.getURI());

To create a source representing text in a string use:

Source source = Source.newBuilder("function() {\n"
    + "  return 'Hi';\n"
    + "}\n")
    .name("hi.js")
    .mimeType("application/javascript")
    .build();
assert "hi.js".equals(source.getName());
assert "application/javascript".equals(source.getMimeType());

or read a source from a Reader:

Reader stream = new InputStreamReader(
                relativeClass.getResourceAsStream("sample.js")
);
Source source = Source.newBuilder(stream)
    .name("sample.js")
    .mimeType("application/javascript")
    .build();
assert "sample.js".equals(source.getName());
assert "application/javascript".equals(source.getMimeType());

The system does all it can to guarantee that newly created source has a MIME type assigned. In some situations the mime type can be guessed, in others it has to be explicitly specified via the Source.Builder.mimeType(java.lang.String) method. Once your builder is configured, call Source.Builder.build() to perform the loading and construction of new Source.

Since:

0.15

Method Summary

Modifier and Type	Method and Description
Source	build() Uses configuration of this builder to create new Source object.
Source.Builder<RuntimeException,E2,E3>	content(String code) Specifies content of to-be-built Source.
Source.Builder<E1,E2,E3>	interactive() Marks the source as interactive.
Source.Builder<E1,E2,E3>	internal() Marks the source as internal.
Source.Builder<E1,RuntimeException,E3>	mimeType(String newMimeType) Explicitly assignes a MIME type to the to-be-built Source.
Source.Builder<E1,E2,RuntimeException>	name(String newName) Gives a new name to the to-be-built Source.
Source.Builder<E1,E2,E3>	uri(URI ownUri) Assigns new URI to the to-be-created Source.

Methods inherited from class java.lang.Object

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

Method Detail

name

public Source.Builder<E1,E2,RuntimeException> name(String newName)

Gives a new name to the to-be-built Source.

Parameters:

newName - name that replaces the previously given one, cannot be null

Returns:

instance of this builder

Since:

0.15

mimeType

public Source.Builder<E1,RuntimeException,E3> mimeType(String newMimeType)

Explicitly assignes a MIME type to the to-be-built Source. This method returns the builder parametrized with Source type parameter to signal to the compiler that it is safe to call Source.Builder.build() method and create an instance of a Source. Example:

Source source = Source.newBuilder("function() {\n"
    + "  return 'Hi';\n"
    + "}\n")
    .name("hi.js")
    .mimeType("application/javascript")
    .build();
assert "hi.js".equals(source.getName());
assert "application/javascript".equals(source.getMimeType());

Parameters:

newMimeType - the new mime type to be assigned

Returns:

instance of this builder ready to create new source

Since:

0.15

internal

public Source.Builder<E1,E2,E3> internal()

Marks the source as internal. Internal sources are those that aren't created by user, but rather inherently present by the language system. Calling this method influences result of create Source.isInternal()

Returns:

the instance of this builder

Since:

0.15

interactive

public Source.Builder<E1,E2,E3> interactive()

Marks the source as interactive. Evaluation of interactive sources by an interactive language can use the PolyglotEngine 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:

0.21

uri

public Source.Builder<E1,E2,E3> uri(URI ownUri)

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:

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

Returns:

the instance of this builder

Since:

0.15

content

public Source.Builder<RuntimeException,E2,E3> 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(resource)
    .name("sample.js")
    .content("{}")
    .build();
assert resource.toExternalForm().equals(source.getPath());
assert "sample.js".equals(source.getName());
assert "application/javascript".equals(source.getMimeType());
assert resource.toExternalForm().equals(source.getURI().toString());
assert "{}".equals(source.getCode());

Parameters:

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

Returns:

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

Since:

0.15

build

public Source build()
             throws E1 extends Exception,
                    E2 extends Exception,
                    E3 extends Exception

Uses configuration of this builder to create new Source object. The return value is parametrized to ensure your code doesn't compile until you specify a MIME type:

• either via file related methods like Source.newBuilder(java.io.File) that can guess the MIME type
• or directly via Source.Builder.mimeType(java.lang.String) method on this builder

This method may throw an exception - especially when dealing with files (e.g. Source.newBuilder(java.net.URL), Source.newBuilder(java.io.File) or Source.newBuilder(java.io.Reader) this method may throw IOException that one needs to deal with. In case of other building styles (like Source.newBuilder(java.lang.String) one doesn't need to capture any exception when calling this method.

Returns:

the source object

Throws:

E1 - exception if something went wrong while creating the source

E2 - eliminate this exception by calling Source.Builder.mimeType(java.lang.String)

E3 - eliminate this exception by calling Source.Builder.name(java.lang.String)

E1 extends Exception

Since:

0.15