Source (GraalVM SDK Java API Reference)

java.lang.Object
- org.graalvm.polyglot.Source

```
public final class Source
extends Object
```
Representation of a source code unit and its contents that can be evaluated in an execution context. Each source is associated with the the ID of the language.
From a file on disk
Each file is represented as a canonical object, indexed by the absolute, canonical path name of the file. File content is read eagerly and may be optionally cached. Sample usage:
```
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());
```
The starting point is Source.newBuilder(String, java.io.File) method.
Read from an URL
One can read remote or in JAR resources using the Source.newBuilder(String, java.net.URL) factory:
```
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());
```
Each URL source is represented as a canonical object, indexed by the URL. Contents are read eagerly once the Source.Builder.build() method is called.
Source from a literal text
An anonymous immutable code snippet can be created from a string via the Source.newBuilder(String, java.lang.CharSequence, String) factory method:
```
Source source = Source.newBuilder("js", "function() {\n"
    + "  return 'Hi';\n"
    + "}\n", "hi.js").buildLiteral();
assert "hi.js".equals(source.getName());
```
Reading from a stream
If one has a Reader one can convert its content into a Source via Source.newBuilder(String, java.io.Reader, String) method:
```
Reader stream = new InputStreamReader(
                relativeClass.getResourceAsStream("sample.js")
);
Source source = Source.newBuilder("js", stream, "sample.js")
    .build();
assert "sample.js".equals(source.getName());
```
the content is read eagerly once the Source.Builder.build() method is called.
Reading from bytes
Sources can be created from bytes. Please note that all character related methods will throw an UnsupportedOperationException if that is the case.
```
byte[] bytes = new byte[] {/* Binary */};
Source source = Source.newBuilder("llvm",
                ByteSequence.create(bytes),
                "<literal>").buildLiteral();
```
Attributes
The source object can be associated with various attributes like Source.getName() and Source.getURI(), Source.getMimeType() and these are immutable. The system makes the best effort to derive values of these attributes from the location and/or content of the Source object. However, to give the user that creates the source control over these attributes, the API offers an way to alter values of these attributes.
Character and byte based Sources
A source is byte or character based, or none of those when no content is specified. For literal sources it depends on whether the byte or character based factory method was used. When the source was loaded from a file or url then the default MIME type of the provided language will be used to determine whether bytes or characters should be loaded. The behavior can be customized by specifying a MIME type or content explicitly. If the specified or inferred MIME type starts with 'text/ or the MIME types is null then it will be interpreted as character based, otherwise byte based.
Since:

19.0

See Also:

To evaluate sources., To detect a language using a File, To detect a language using an URL., To detect a MIME type using a File., To detect a MIME type using an URL.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

class Source.Builder
Represents a builder to build Source objects.

Nested Classes
Modifier and Type	Class and Description
`class`	`Source.Builder` Represents a builder to build `Source` objects.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static Source`	`create(String language, CharSequence source)` Shortcut for creating a source object from a language and char sequence.
`boolean`	`equals(Object obj)`
`static String`	`findLanguage(File file)` Returns the id of the first language that supports evaluating the probed mime type of a given `file`.
`static String`	`findLanguage(String mimeType)` Returns the first installed language that supports evaluating sources for a given MIME type.
`static String`	`findLanguage(URL url)` Returns the id of the first language that supports evaluating the probed mime type of a given `URL`.
`static String`	`findMimeType(File file)` Returns the probed MIME type for a given file, or `null` if no MIME type could be resolved.
`static String`	`findMimeType(URL url)` Returns the probed MIME type for a given url, or `null` if no MIME type could be resolved.
`ByteSequence`	`getBytes()` Returns the bytes of the source if it is a `byte based source`.
`CharSequence`	`getCharacters()` Returns all characters of the source.
`CharSequence`	`getCharacters(int lineNumber)` Gets the text (not including a possible terminating newline) in a (1-based) numbered line.
`int`	`getColumnNumber(int offset)` Given a 0-based character offset, return the 1-based number of the column at the position.
`String`	`getLanguage()` Returns the language this source created with.
`int`	`getLength()` Gets the number of characters or bytes of the source.
`int`	`getLineCount()` The number of text lines of a character based source, including empty lines; characters at the end of the source without a terminating newline count as a line.
`int`	`getLineLength(int lineNumber)` The number of characters (not counting a possible terminating newline) in a (1-based) numbered line.
`int`	`getLineNumber(int offset)` Given a 0-based character offset, return the 1-based number of the line that includes the position.
`int`	`getLineStartOffset(int lineNumber)` Given a 1-based line number, return the 0-based offset of the first character in the line.
`String`	`getMimeType()` Returns the MIME type that is associated with this source.
`String`	`getName()` Returns the name of this resource holding a guest language program.
`String`	`getPath()` The fully qualified name of the source.
`Reader`	`getReader()` Returns a new reader that reads from the `characters` provided by this source.
`URI`	`getURI()` Get the URI of the source.
`URL`	`getURL()` The URL if the source is retrieved via URL.
`boolean`	`hasBytes()` Returns `true` if this source represents a byte based source, else `false`.
`boolean`	`hasCharacters()` Returns `true` if this source represents a character based source, else `false`.
`int`	`hashCode()`
`boolean`	`isInteractive()` Check whether this source has been marked as interactive.
`boolean`	`isInternal()` Gets whether this source has been marked as internal, meaning that it has been provided by the infrastructure, language implementation, or system library.
`static Source.Builder`	`newBuilder(String language, ByteSequence bytes, String name)` Creates a new byte based literal source from a byte sequence.
`static Source.Builder`	`newBuilder(String language, CharSequence characters, String name)` Creates a new character based literal source from a character sequence.
`static Source.Builder`	`newBuilder(String language, File file)` Creates a new file based source builder from a given file.
`static Source.Builder`	`newBuilder(String language, Reader source, String name)` Creates new character based literal source from a reader.
`static Source.Builder`	`newBuilder(String language, URL url)` Creates a new URL based source builder from a given URL.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - getLanguage
```
public String getLanguage()
```
    Returns the language this source created with. The string returned matches the id of the language.
    
    Since:
    
    19.0
  - getName
```
public String getName()
```
    Returns the name of this resource holding a guest language program. An example would be the name of a guest language source code file. Name is supposed to be shorter than Source.getPath().
    
    Returns:
    
    the name of the guest language program
    
    Since:
    
    19.0
    
    See Also:
    
    Source.Builder.name(String)
  - getPath
```
public String getPath()
```
    The fully qualified name of the source. In case this source originates from a File, then the path is the normalized, canonical path for absolute files, or the relative path otherwise. If the source originates from an URL, then it's the path component of the URL.
    
    Since:
    
    19.0
  - getURL
```
public URL getURL()
```
    The URL if the source is retrieved via URL.
    
    Returns:
    
    URL or null
    
    Since:
    
    19.0
  - getURI
```
public URI getURI()
```
    Get the URI of the source. Every source has an associated URI, which can be used as a persistent identification of the source. The URI returned by this method should be as unique as possible, yet it can happen that different sources return the same Source.getURI() - for example when content of a file on a disk changes and is re-loaded.
    
    Returns:
    
    a URI, never null
    
    Since:
    
    19.0
  - isInteractive
```
public boolean isInteractive()
```
    Check whether this source has been marked as interactive. Interactive sources are provided by an entity which is able to interactively read output and provide an input during the source execution; that can be a user I/O through an interactive shell for instance.
    One can specify whether a source is interactive when building it.
    
    Returns:
    
    whether this source is marked as interactive
    
    Since:
    
    19.0
  - isInternal
```
public boolean isInternal()
```
    Gets 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.
    One can specify whether a source is internal when building it.
    
    Returns:
    
    whether this source is marked as internal
    
    Since:
    
    19.0
  - getReader
```
public Reader getReader()
```
    Returns a new reader that reads from the characters provided by this source.
    
    Throws:
    
    UnsupportedOperationException - if this source cannot contain characters.
    
    Since:
    
    19.0
  - getLength
```
public int getLength()
```
    Gets the number of characters or bytes of the source.
    
    Since:
    
    19.0
  - getCharacters
```
public CharSequence getCharacters()
```
    Returns all characters of the source.
    
    Throws:
    
    UnsupportedOperationException - if this source cannot contain characters.
    
    Since:
    
    19.0
  - getMimeType
```
public String getMimeType()
```
    Returns the MIME type that is associated with this source. Sources have a null MIME type by default. 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
    
    Returns:
    
    MIME type of this source or null, if not explicitly set.
    
    Since:
    
    19.0
    
    See Also:
    
    Language.getDefaultMimeType(), Language.getMimeTypes(), Source.findMimeType(File), Source.findMimeType(URL)
  - getCharacters
```
public CharSequence getCharacters(int lineNumber)
```
    Gets the text (not including a possible terminating newline) in a (1-based) numbered line. Causes the contents of this source to be loaded if they are loaded lazily.
    
    Throws:
    
    UnsupportedOperationException - if this source cannot contain characters.
    
    Since:
    
    19.0
    
    See Also:
    
    Source.hasCharacters()
  - getBytes
```
public ByteSequence getBytes()
```
    Returns the bytes of the source if it is a byte based source.
    
    Throws:
    
    UnsupportedOperationException - if this source cannot contain bytes .
    
    Since:
    
    19.0
    
    See Also:
    
    Source.hasBytes()
  - hasCharacters
```
public boolean hasCharacters()
```
    Returns true if this source represents a character based source, else false. A source is either a byte based, a character based, or with no content, but never both byte and character based at the same time.
    The following methods are only supported if Source.hasCharacters() is true:
    Since:
    
    19.0
  - hasBytes
```
public boolean hasBytes()
```
    Returns true if this source represents a byte based source, else false. A source is either a byte based, a character based, or with no content, but never both byte and character based at the same time.
    The method Source.getBytes() is only supported if this method returns true.
    
    Since:
    
    19.0
    
    See Also:
    
    Source.getBytes()
  - getLineCount
```
public int getLineCount()
```
    The number of text lines of a character based source, including empty lines; characters at the end of the source without a terminating newline count as a line. Causes the contents of this source to be loaded if they are loaded lazily.
    
    Throws:
    
    UnsupportedOperationException - if this source cannot contain characters.
    
    Since:
    
    19.0
  - getLineNumber
```
public int getLineNumber(int offset)
                  throws IllegalArgumentException
```
    Given a 0-based character offset, return the 1-based number of the line that includes the position. Causes the contents of this source to be loaded if they are loaded lazily.
    
    Throws:
    
    UnsupportedOperationException - if this source cannot contain characters.
    
    IllegalArgumentException - if the offset is outside the text contents
    
    Since:
    
    19.0
  - getColumnNumber
```
public int getColumnNumber(int offset)
                    throws IllegalArgumentException
```
    Given a 0-based character offset, return the 1-based number of the column at the position. Causes the contents of this source to be loaded if they are loaded lazily.
    
    Throws:
    
    UnsupportedOperationException - if this source cannot contain characters.
    
    IllegalArgumentException - if the offset is outside the text contents
    
    Since:
    
    19.0
  - getLineStartOffset
```
public int getLineStartOffset(int lineNumber)
                       throws IllegalArgumentException
```
    Given a 1-based line number, return the 0-based offset of the first character in the line.
    
    Throws:
    
    UnsupportedOperationException - if this source cannot contain characters.
    
    IllegalArgumentException - if there is no such line in the text
    
    Since:
    
    19.0
  - getLineLength
```
public int getLineLength(int lineNumber)
                  throws IllegalArgumentException
```
    The number of characters (not counting a possible terminating newline) in a (1-based) numbered line. Causes the contents of this source to be loaded if they are loaded lazily.
    
    Throws:
    
    UnsupportedOperationException - if this source cannot contain characters.
    
    IllegalArgumentException - if there is no such line in the text
    
    Since:
    
    19.0
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
    
    Since:
    
    19.0
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
    
    Since:
    
    19.0
  - equals
```
public boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object
    
    Since:
    
    19.0
  - newBuilder
```
public static Source.Builder newBuilder(String language,
                                        CharSequence characters,
                                        String name)
```
    Creates a new character based literal source from a character sequence. The given characters must not mutate after they were accessed for the first time.
    Use this method for sources that do originate from a literal. For file or URL sources use the appropriate builder constructor and Source.Builder.content(CharSequence).
    Example usage:
```
Source source = Source.newBuilder("js", "function() {\n"
    + "  return 'Hi';\n"
    + "}\n", "hi.js").buildLiteral();
assert "hi.js".equals(source.getName());
```
    Parameters:
    
    language - the language id, must not be null
    
    characters - the character sequence or string, must not be null
    
    name - the name of the source, if null then "Unnamed" will be used as name.
    
    Since:
    
    19.0
  - newBuilder
```
public static Source.Builder newBuilder(String language,
                                        ByteSequence bytes,
                                        String name)
```
    Creates a new byte based literal source from a byte sequence. The given bytes must not mutate after they were accessed for the first time.
    Use this method for sources that do originate from a literal. For file or URL sources use the appropriate builder constructor and Source.Builder.content(CharSequence).
    Example usage:
```
byte[] bytes = new byte[] {/* Binary */};
Source source = Source.newBuilder("llvm",
                ByteSequence.create(bytes),
                "<literal>").buildLiteral();
```
    Parameters:
    
    language - the language id, must not be null
    
    bytes - the byte sequence or string, must not be null
    
    name - the name of the source, if null then "Unnamed" will be used as name.
    
    Since:
    
    19.0
  - newBuilder
```
public static Source.Builder newBuilder(String language,
                                        File file)
```
    Creates a new file based source builder from a given file. A file based source is either interpreted as binary or character source depending on the default MIME type of the language, the contents or the specified MIME type. A language may be detected from an existing file using Source.findLanguage(File).
    Example usage:
```
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());
```
    Parameters:
    
    language - the language id, must not be null
    
    file - the file to use, must not be null
    
    Since:
    
    19.0
  - newBuilder
```
public static Source.Builder newBuilder(String language,
                                        URL url)
```
    Creates a new URL based source builder from a given URL. A URL based source is either interpreted as binary or character source depending on the default MIME type of the language, the contents or the specified MIME type. A language may be detected from an existing file using Source.findLanguage(URL).
    Example usage:
```
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());
```
    Parameters:
    
    language - the language id, must not be null
    
    url - the URL to use and load, must not be null
    
    Since:
    
    19.0
  - newBuilder
```
public static Source.Builder newBuilder(String language,
                                        Reader source,
                                        String name)
```
    Creates new character based literal source from a reader.
    Use this method for sources that do originate from a literal. For file or URL sources use the appropriate builder constructor and Source.Builder.content(CharSequence).
    Example usage:
```
Reader stream = new InputStreamReader(
                relativeClass.getResourceAsStream("sample.js")
);
Source source = Source.newBuilder("js", stream, "sample.js")
    .build();
assert "sample.js".equals(source.getName());
```
    Since:
    
    19.0
  - create
```
public static Source create(String language,
                            CharSequence source)
```
    Shortcut for creating a source object from a language and char sequence. The given characters must not mutate after they were accessed for the first time.
    Use for sources that do not come from a file, or URL. If they do, use the appropriate builder and Source.Builder.content(CharSequence).
    
    Since:
    
    19.0
  - findLanguage
```
public static String findLanguage(File file)
                           throws IOException
```
    Returns the id of the first language that supports evaluating the probed mime type of a given file. This method is a shortcut for: String mimeType = Source.findMimeType(file); return mimeType != null ? Source.findLanguage(mimeType) : null;
    Parameters:
    
    file - the file to find the first language for
    
    Throws:
    
    IOException - if an error opening the file occurred.
    
    Since:
    
    19.0
    
    See Also:
    
    Source.findMimeType(URL), Source.findLanguage(String)
  - findLanguage
```
public static String findLanguage(URL url)
                           throws IOException
```
    Returns the id of the first language that supports evaluating the probed mime type of a given URL. This method is a shortcut for: String mimeType = Source.findMimeType(url); return mimeType != null ? Source.findLanguage(mimeType) : null;
    Parameters:
    
    url - the url to find the first language for
    
    Throws:
    
    IOException - if an error opening the url occurred.
    
    Since:
    
    19.0
    
    See Also:
    
    Source.findMimeType(URL), Source.findLanguage(String)
  - findMimeType
```
public static String findMimeType(File file)
                           throws IOException
```
    Returns the probed MIME type for a given file, or null if no MIME type could be resolved. Typically the MIME type is identified using the file extension and/or using its contents. Probing the MIME type of an File may require to opening the file.
    
    Throws:
    
    IOException - if an error opening the file occurred.
    
    Since:
    
    19.0
    
    See Also:
    
    Source.findLanguage(File)
  - findMimeType
```
public static String findMimeType(URL url)
                           throws IOException
```
    Returns the probed MIME type for a given url, or null if no MIME type could be resolved. Typically the MIME type is identified using the file extension, connection meta-data and/or using it contents. Returns null if the language of the given file could not be detected. Probing the language of an URL may require to open a new URL connection.
    
    Throws:
    
    IOException - if an error opening the url occurred.
    
    Since:
    
    19.0
    
    See Also:
    
    Source.findLanguage(URL)
  - findLanguage
```
public static String findLanguage(String mimeType)
```
    Returns the first installed language that supports evaluating sources for a given MIME type. Returns null if no language was found that supports a given MIME type. The languages are queried in the same order as returned by Engine.getLanguages(). Mime-types don't adhere to the MIME type format will return null.
    
    Since:
    
    19.0

Class Source

From a file on disk

Read from an URL

Source from a literal text

Reading from a stream

Reading from bytes

Attributes

Character and byte based Sources

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getLanguage

getName

getPath

getURL

getURI

isInteractive

isInternal

getReader

getLength

getCharacters

getMimeType

getCharacters

getBytes

hasCharacters

hasBytes

getLineCount

getLineNumber

getColumnNumber

getLineStartOffset

getLineLength

toString

hashCode

equals

newBuilder

newBuilder

newBuilder

newBuilder

newBuilder

create

findLanguage

findLanguage

findMimeType

findMimeType

findLanguage