Package org.graalvm.polyglot

Class Source

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 newBuilder(String, java.io.File) method.

Read from a URL

One can read remote or in JAR resources using the 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 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 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 getName() and getURI(), 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:

  • Method Details

    • 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 getPath().
      Returns:
      the name of the guest language program
      Since:
      19.0
      See Also:

    • 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 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

    • getInputStream

      @Deprecated(since="19.0") public InputStream getInputStream()
      Deprecated.
      use getReader(), getCharacters() or getBytes() instead. The implementation is inefficient and can not distinguish byte and character based sources.
      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:

    • 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:

    • 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:

    • 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 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 getBytes() is only supported if this method returns true.

      Since:
      19.0
      See Also:

    • 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:
      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 findLanguage(File). 
       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 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). 

       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
      See Also:

    • 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:

    • 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:

    • 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:

    • 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 a URL may require to open a new URL connection.
      Throws:
      IOException - if an error opening the url occurred.
      Since:
      19.0
      See Also:

    • 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