Module: TreeHaver::Backends::Java

Defined in:
lib/tree_haver/backends/java.rb

Overview

Note:

Only available on JRuby

Java backend for JRuby using java-tree-sitter (jtreesitter)

This backend integrates with java-tree-sitter JARs on JRuby, leveraging JRuby’s native Java integration for optimal performance.

java-tree-sitter provides Java bindings to tree-sitter and supports:

  • Parsing source code into syntax trees

  • Incremental parsing via Parser.parse(Tree, String)

  • The Query API for pattern matching

  • Tree editing for incremental re-parsing

Installation

  1. Download the JAR from Maven Central: central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter

  2. Set the environment variable to point to the JAR directory: export TREE_SITTER_JAVA_JARS_DIR=/path/to/jars

  3. Use JRuby to run your code: jruby -e “require ‘tree_haver’; puts TreeHaver::Backends::Java.available?”

See Also:

Defined Under Namespace

Classes: Language, Node, Parser, Tree

Constant Summary collapse

JAVA_PACKAGE =

The Java package for java-tree-sitter

"io.github.treesitter.jtreesitter"

Class Method Summary collapse

Class Method Details

.add_jars_from_env! ⇒ void

This method returns an undefined value.

Attempt to append JARs from TREE_SITTER_JAVA_JARS_DIR to JRuby classpath and configure native library path from TREE_SITTER_RUNTIME_LIB

If the environment variable is set and points to a directory, all .jar files in that directory (recursively) are added to the JRuby classpath.

Examples:

ENV["TREE_SITTER_JAVA_JARS_DIR"] = "/path/to/java-tree-sitter/jars"
TreeHaver::Backends::Java.add_jars_from_env!



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/tree_haver/backends/java.rb', line 65

def add_jars_from_env!
  # :nocov:
  # This method requires JRuby and cannot be tested on MRI/CRuby.
  # JRuby-specific CI jobs would test this code.
  require "java"

  # Add JARs to classpath
  dir = ENV["TREE_SITTER_JAVA_JARS_DIR"]
  if dir && Dir.exist?(dir)
    Dir[File.join(dir, "**", "*.jar")].each do |jar|
      next if $CLASSPATH.include?(jar)
      $CLASSPATH << jar
    end
  end

  # Configure native library path for libtree-sitter
  # java-tree-sitter uses JNI and needs to find the native library
  configure_native_library_path!
  # :nocov:
rescue LoadError
  # ignore; not JRuby or Java bridge not available
end

.available? ⇒ Boolean

Check if the Java backend is available

Returns true if running on JRuby and java-tree-sitter classes can be loaded. Automatically attempts to load JARs from ENV if set.

Examples:

if TreeHaver::Backends::Java.available?
  puts "Java backend is ready"
end

Returns:

  • (Boolean) —

    true if Java backend is available



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/tree_haver/backends/java.rb', line 123

def available?
  return @loaded if @load_attempted
  @load_attempted = true
  @loaded = false
  @load_error = nil

  return false unless defined?(RUBY_ENGINE) && RUBY_ENGINE == "jruby"

  # :nocov:
  # Everything below requires JRuby and cannot be tested on MRI/CRuby.
  # JRuby-specific CI jobs would test this code.
  begin
    require "java"
  rescue LoadError
    @load_error = "JRuby java bridge not available"
    return false
  end

  # Optionally augment classpath and configure native library path
  add_jars_from_env!

  # Try to load the java-tree-sitter classes
  # Load Parser first as it doesn't trigger native library loading
  # Language class triggers native lib loading in its static initializer
  begin
    # These classes don't require native library initialization
    @java_classes[:Parser] = ::Java::IoGithubTreesitterJtreesitter::Parser
    @java_classes[:Tree] = ::Java::IoGithubTreesitterJtreesitter::Tree
    @java_classes[:Node] = ::Java::IoGithubTreesitterJtreesitter::Node
    @java_classes[:InputEdit] = ::Java::IoGithubTreesitterJtreesitter::InputEdit
    @java_classes[:Point] = ::Java::IoGithubTreesitterJtreesitter::Point

    # Language class may fail if native library isn't found - try it last
    # and provide a helpful error message
    begin
      @java_classes[:Language] = ::Java::IoGithubTreesitterJtreesitter::Language
    rescue NameError => e
      # Language failed but other classes loaded - native lib issue
      @load_error = "Language class failed to initialize (native library issue): #{e.message}"
      # Clear loaded classes since we can't fully function without Language
      @java_classes.clear
      return false
    end

    @loaded = true
  rescue NameError => e
    @load_error = "java-tree-sitter classes not found: #{e.message}"
    @loaded = false
  end

  @loaded
  # :nocov:
end

.capabilities ⇒ Hash{Symbol => Object}

Get capabilities supported by this backend

Examples:

TreeHaver::Backends::Java.capabilities
# => { backend: :java, parse: true, query: true, bytes_field: true, incremental: true }

Returns:

  • (Hash{Symbol => Object}) —

    capability map



209
210
211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/tree_haver/backends/java.rb', line 209

def capabilities
  # :nocov:
  # This method returns meaningful data only on JRuby when java-tree-sitter is available.
  return {} unless available?
  {
    backend: :java,
    parse: true,
    query: true, # java-tree-sitter supports the Query API
    bytes_field: true,
    incremental: true, # java-tree-sitter supports Parser.parse(Tree, String)
  }
  # :nocov:
end

.configure_native_library_path! ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Configure java.library.path to include the directory containing libtree-sitter



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/tree_haver/backends/java.rb', line 92

def configure_native_library_path!
  # :nocov:
  # This method requires JRuby and cannot be tested on MRI/CRuby.
  lib_path = ENV["TREE_SITTER_RUNTIME_LIB"]
  return unless lib_path && File.exist?(lib_path)

  lib_dir = File.dirname(lib_path)
  current_path = java.lang.System.getProperty("java.library.path") || ""

  unless current_path.include?(lib_dir)
    new_path = current_path.empty? ? lib_dir : "#{lib_dir}:#{current_path}"
    java.lang.System.setProperty("java.library.path", new_path)

    # Also set jna.library.path in case it uses JNA
    java.lang.System.setProperty("jna.library.path", new_path)
  end
  # :nocov:
rescue => _error
  # Ignore errors setting library path
end

.java_classes ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get the loaded Java classes

Returns:

  • (Hash) —

    the Java class references



199
200
201
 
# File 'lib/tree_haver/backends/java.rb', line 199

def java_classes
  @java_classes
end

.load_error ⇒ String?

Get the last load error message (for debugging)

Returns:

  • (String, nil) —

    the error message or nil if no error



180
181
182
 
# File 'lib/tree_haver/backends/java.rb', line 180

def load_error
  @load_error
end

.reset! ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Reset the load state (primarily for testing)



188
189
190
191
192
193
 
# File 'lib/tree_haver/backends/java.rb', line 188

def reset!
  @load_attempted = false
  @loaded = false
  @load_error = nil
  @java_classes = {}
end

.runtime_lookup ⇒ Object?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get the cached runtime library SymbolLookup

Returns:

  • (Object, nil) —

    the SymbolLookup for libtree-sitter.so



44
45
46
 
# File 'lib/tree_haver/backends/java.rb', line 44

def runtime_lookup
  @runtime_lookup
end

.runtime_lookup=(lookup) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Set the cached runtime library SymbolLookup

Parameters:

  • lookup (Object) —

    the SymbolLookup



51
52
53
 
# File 'lib/tree_haver/backends/java.rb', line 51

def runtime_lookup=(lookup)
  @runtime_lookup = lookup
end