jar-dependencies 0.6.0.pre3-java

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 92976e67d21610e137cef159d14a61f57c0c1b9c2215425d6165ebc0be0ff492
+  data.tar.gz: f1d11f3d54f78e14fde342fe99758821c2ce5726348d979d5e87d151a2b2b329
+SHA512:
+  metadata.gz: c157385bf7ca957c668ff6d603aebe9059ab2f80ac04c106a03e3ec0867e4c842ae8eade15275adc57ee5482dea6f1223ec4390c61884642dc795cfce76bf4eb
+  data.tar.gz: 05a38e3355d651c13de3eb4b5aafa11f6505929675000bdbf3f3686cd87d7d5d899afa2d977f41fe84ca55d5f0c1b2d89ff001d8dc399cb9185f7c9448a4036a

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2014 Christian Meier
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Mavenfile

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+gemfile
+
+plugin_repository id: :mavengems, url: 'mavengem:https://rubygems.org'
+
+jruby_plugin(:minitest, minispecDirectory: 'specs/*_spec.rb') do
+  execute_goals(:spec)
+end
+
+properties('jruby.versions' => ['${jruby.version}'].join(','),
+           # just lock the version
+           'bundler.version' => '2.5.11',
+           'jruby.version' => '9.4.8.0',
+           'jruby.plugins.version' => '3.0.6',
+           'push.skip' => true)
+
+#plugin :invoker, '1.8' do
+#  execute_goals(:install, :run,
+#                id: 'integration-tests',
+#                projectsDirectory: 'integration',
+#                streamLogs: true,
+#                goals: ['install'],
+#                preBuildHookScript: 'setup.bsh',
+#                postBuildHookScript: 'verify.bsh',
+#                cloneProjectsTo: '${project.build.directory}',
+#                properties: { 'jar-dependencies.version' => '${project.version}',
+#                              # use an old jruby with old ruby-maven here
+#                              'jruby.version' => '${jruby.version}',
+#                              'jruby.plugins.version' => '${jruby.plugins.version}',
+#                              'bundler.version' => '${bundler.version}', })
+#end
+
+distribution_management do
+  repository id: :ossrh, url: 'https://oss.sonatype.org/service/local/staging/deploy/maven2/'
+end
+
+profile id: :skip do
+  properties 'maven.test.skip' => true, 'invoker.skip' => true
+end
+
+profile id: :release do
+  properties 'maven.test.skip' => true, 'invoker.skip' => true, 'push.skip' => false
+
+  build do
+    default_goal :deploy
+  end
+end

data/Rakefile

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+task default: [:specs]
+
+require 'bundler/gem_tasks'
+require 'rake/clean'
+
+begin
+  require 'rubocop/rake_task'
+  RuboCop::RakeTask.new
+rescue LoadError
+  # RuboCop not available; skip defining the task
+end
+
+desc 'run specs'
+task :specs do
+  $LOAD_PATH << 'specs'
+
+  Dir['specs/*_spec.rb'].each do |f|
+    require File.basename(f.sub(/.rb$/, ''))
+  end
+end
+
+require_relative 'lib/jars/mima/version'
+
+MIMA_VERSION = Jars::Mima::MIMA_VERSION
+SLF4J_VERSION = Jars::Mima::SLF4J_VERSION
+MIMA_JARS = Jars::Mima::JARS
+MIMA_DIR = Jars::Mima::MIMA_DIR
+
+MIMA_JARS.each_key { |jar| CLEAN.include(File.join(MIMA_DIR, jar)) }
+
+desc 'download Mima (and dependent SLF4J) jars'
+task :download_jars do
+  require 'fileutils'
+  require 'open-uri'
+  require 'digest/sha1'
+
+  FileUtils.mkdir_p(MIMA_DIR)
+
+  MIMA_JARS.each do |filename, info|
+    target = File.join(MIMA_DIR, filename)
+    if File.exist?(target)
+      verify_checksum(target, info[:sha1])
+      puts "  exists: #{target}"
+      next
+    end
+
+    puts "  downloading #{filename}..."
+    URI.open(info[:url]) do |remote| # rubocop:disable Security/Open
+      File.binwrite(target, remote.read)
+    end
+    verify_checksum(target, info[:sha1])
+    puts "  saved: #{target}"
+  end
+end
+
+def verify_checksum(path, expected_sha1)
+  actual = Digest::SHA1.file(path).hexdigest
+  return if actual == expected_sha1
+
+  File.delete(path)
+  raise "SHA-1 mismatch for #{path}:\n  " \
+        "expected: #{expected_sha1}\n  " \
+        "actual:   #{actual}"
+end

data/Readme.md

@@ -0,0 +1,225 @@
+# jar-dependencies
+
+[![Gem Version](https://img.shields.io/gem/v/jar-dependencies)](https://rubygems.org/gems/jar-dependencies)
+[![Build Status](https://github.com/jruby/jar-dependencies/actions/workflows/main.yml/badge.svg)](https://github.com/jruby/jar-dependencies/actions/workflows/main.yml?query=branch%3Amaster)
+
+Add gem dependencies for jar files to ruby gems.
+
+## Getting control back over your jar
+
+jar dependencies are declared in the gemspec of the gem using the same notation
+as [JBundler](https://github.com/jruby/jbundler).
+
+When using `require_jar` to load the jar into JRuby's classloader a version conflict
+will be detected and only **ONE** jar gets loaded.
+**jbundler** allows to select the version suitable for you application.
+
+Most maven-artifacts do **NOT** use versions ranges but depend on a concrete version.
+In such cases **jbundler** can always **overwrite** any such version.
+
+
+## Vendoring your jars before packing the jar
+
+Add the following to your *Rakefile*:
+
+```ruby
+require 'jars/installer'
+task :install_jars do
+  Jars::Installer.vendor_jars!
+end
+```
+
+This will install (download) the dependent jars into **JARS_HOME** and create a
+file **lib/my_gem_jars.rb**, which will be an enumeration of `require_jars`
+statements to load all the jars.
+The **vendor_jars** task will copy them into the **lib** directory of the gem.
+
+The location where jars are cached is per default **$HOME/.m2/repository** the
+same default as Maven uses to cache downloaded jar-artifacts.
+It respects **$HOME/.m2/settings.xml** from Maven with mirror and other settings
+or the environment variable **JARS_HOME**.
+
+**IMPORTANT**: Make sure that jar-dependencies is only a **development dependency**
+of your gem. If it is a runtime dependency the require_jars file will be overwritten
+during installation.
+
+
+## Reduce the download and reuse the jars from maven local repository
+
+If you do not want to vendor jars into a gem then **jar-dependency** gem can vendor
+them when you install the gem. In that case do not use
+`Jars::Installer.install_jars` from the above rake tasks.
+
+**NOTE**: Recent JRuby comes with **jar-dependencies** as default gem, for older
+versions for the feature to work you need to gem install **jar-dependencies** first
+and for bundler need to use the **bundle-with-jars** command instead.
+
+**IMPORTANT**: Make sure that jar-dependencies is a **runtime dependency** of your
+gem so the require_jars file will be overwritten during installation with the
+"correct" versions of the jars.
+
+
+## For development you do not need to vendor the jars at all
+
+Set the environment variable
+
+```shell
+export JARS_VENDOR=false
+```
+
+to tell the jar_installer not vendor any jars, but only create the file with the
+`require_jar` statements. This `require_jars` method will find the jar inside the
+maven local repository and load it from there.
+
+
+## Some drawbacks
+
+ * First you need to install the jar-dependency gem with its development dependencies installed (then ruby-maven gets installed as well)
+ * Bundler does not install the jar-dependencies (unless JRuby adds the gem as default gem)
+ * You need ruby-maven doing the job of dependency resolution and downloading them. gems not part of <http://rubygems.org> will not work currently
+
+
+## JARs other than from maven-central
+
+By default all jars need to come from maven-central (<search.maven.org>), in order
+to use jars from any other repo you need to add it into your Maven *settings.xml*
+and configure it in a way that works without an interactive prompt (username +
+passwords needs to be part of the settings.xml file).
+
+**NOTE:** Gems depending on jars other then maven-central will **NOT** work when
+they get published on rubygems.org since the user of those gems will not have the
+right settings.xml to allow them to access the jar dependencies.
+
+
+## Examples
+
+An [example with rspec and all](example/Readme.md) walks you through setup and
+shows how development works and shows what happens during installation.
+
+There are some more examples with the various [project setups for gems and application](examples/README.md).
+This includes using proper Maven for the project or ruby-maven with rake or
+the rake-compiler in conjunction with jar-dependencies.
+
+# Lock down versions
+
+Whenever there are version ranges for jar dependencies it is advisable to lock down the versions of dependencies.
+For the jar dependencies inside the gemspec declaration this can be done with:
+
+```shell
+lock_jars
+```
+
+This is also working in **any** project which uses a gem with
+jar-dependencies. It also uses a Jarfile if present. See the [sinatra
+application from the examples](examples/sinatra-app/having-jarfile-and-gems-with-jar-dependencies/).
+
+This means for a project using bundler and jar-dependencies the setup is
+
+```shell
+bundle install
+lock_jars
+```
+
+This will install both gems and jars for the project.
+
+Update a specific version is done with (use only the artifact_id)
+
+```shell
+lock_jars --update slf4j-api
+```
+
+And look at the dependencies tree
+
+```shell
+lock_jars --tree
+```
+
+As `lock_jars` uses ruby-maven to resolve the jar dependencies.
+Since jar-dependencies does not declare ruby-maven as runtime dependency
+(you just not need ruby-maven during runtime only when you want to
+setup the project it is needed) it is advicable to have it as
+development dependency in your Gemfile.
+
+# Proxy and mirror setup
+
+Proxies and mirrors can be set up by the usual configuration of maven itself: [settings.xml](https://maven.apache.org/settings.html) - see the mirrors and proxy sections.
+
+As jar-dependencies does only deal with jar and all jars need to come from maven central, it is only neccessary to mirror maven-central. An example of such a [settings-example.xml](setting.xml is here).
+
+You also can add such a settings.xml to your project which jar-dependencies will use instad of the default maven locations. This allows to have a per-project configuration and also removes the need to users of your Ruby project to dive into maven in case you have company policy to use a local mirror for gem and jar artifacts.
+
+jar-dependencies itself uses maven **only** for the jars and all gems are managed by RubyGems or Bundler or your favourite management tool. So any proxy/mirror settings which should affect gems need to be done in those tools.
+
+# Gradle, Maven, etc
+
+Dependency management frameworks like gradle (via jruby-gradle-plugin) or maven (via jruby-maven-plugins) can also use gem artifacts retrieved from rubygems.org.
+
+Each of these tools (including jar-dependencies) does the dependency
+resolution slightly different and in rare cases can produce different
+outcomes. But overall each tool can manage both jars and gems and
+their transitive dependencies.
+
+Popular gems like jrjackson or nokogiri do not declare their jars in
+the gemspec files and just load the bundle jars into jruby
+classloader, can easily create problems as the jackson and
+xalan/xerces libraries used by those gems are popular ones in the Java world.
+
+# Troubleshooting
+
+Jar dependency resolution uses the bundled Mima resolver. To get more
+insight into jar-dependencies progress and warnings, enable verbose output:
+
+```shell
+JARS_VERBOSE=true bundle install
+JARS_VERBOSE=true gem install some_gem
+```
+
+
+For Ruby-side debug diagnostics, including backtraces for suppressed setup
+errors and jar loading decisions, enable debug output:
+
+```shell
+JARS_DEBUG=true bundle install
+JARS_DEBUG=true gem install some_gem
+```
+
+# Configuration
+
+<table border='1'>
+<tr>
+<td>ENV</td><td>java system property</td><td>default</td><td>description</td>
+</tr>
+<tr>
+<td><tt>JARS_DEBUG</tt></td><td>jars.debug</td><td>false</td><td>if set to true it will produce Ruby-side debug diagnostics and implies verbose output</td>
+</tr>
+<tr>
+<td><tt>JARS_VERBOSE</tt></td><td>jars.verbose</td><td>false</td><td>if set to true it will produce some extra resolver output</td>
+</tr>
+<tr>
+<td><tt>JARS_HOME</tt></td><td>jars.home</td><td>$HOME/.m2/repository</td><td>filesystem location where to store the jar files and some metadata</td>
+</tr>
+<tr>
+<td><tt>JARS_MAVEN_SETTINGS</tt></td><td>jars.maven.settings</td><td>$HOME/.m2/settings.xml</td><td>setting.xml for maven to use</td>
+</tr>
+<tr>
+<td><tt>JARS_VENDOR</tt></td><td>jars.vendor</td><td>true</td><td>set to true means that the jars will be stored in JARS_HOME only</td>
+</tr>
+<tr>
+<td><tt>JARS_SKIP</tt></td><td>jars.skip</td><td>true</td><td>do **NOT** install jar dependencies at all</td>
+</tr>
+</table>
+
+# Motivation
+
+In 2014, while tools such as [https://github.com/arrigonialberto86/ruby-band](https://github.com/arrigonialberto86/ruby-band) used [jbundler](https://github.com/jruby/jbundler) to manage their there was no easy or formal way to 
+- find out which JARs were added to the JRuby classloader
+- to manage JRuby projects with Maven
+- to build Java/JRuby gem extensions with [rake-compiler](https://github.com/luislavena/rake-compiler/issues/87).
+
+With JRuby 9000 it was the right time to get jar dependencies "right".
+
+# Developing
+
+You must have the latest ruby-maven installed in your local JRuby.
+
+./mvnw install will build the gem and run integration tests

data/exe/lock_jars

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'jar_dependencies'
+require 'optparse'
+options = {}
+optparse = OptionParser.new do |opts|
+  opts.banner = "Usage: #{File.basename(__FILE__)} [options]"
+
+  opts.separator ''
+  opts.separator 'Options:'
+  opts.separator ''
+
+  opts.on('-v', '--verbose', 'Output more information') do |t|
+    options[:verbose] = t
+  end
+
+  opts.on('-d', '--debug', 'Output debug information') do |t|
+    options[:debug] = t
+  end
+
+  opts.on('-f', '--force', 'Force creation of Jars.lock') do |t|
+    options[:force] = t
+  end
+
+  opts.on('-t', '--tree', 'Show dependency tree') do |t|
+    options[:tree] = t
+  end
+
+  opts.on('-u', '--update JAR_COORDINATE',
+          'Resolves given dependency and use latest version. ' \
+          'JAR_COORDINATE is either artifact_id or group_id:artifact_id') do |u|
+    options[:update] = u
+  end
+
+  opts.on('--vendor-dir DIRECTORY', 'Vendor directory where to copy the installed jars.' \
+                                    'add this directory to $LOAD_PATH or set JARS_HOME respectively.') do |dir|
+    options[:vendor_dir] = dir
+  end
+
+  opts.on('-h', '--help', 'Display this screen') do
+    puts opts
+    exit
+  end
+
+  opts.separator ''
+  opts.separator 'THIS IS A EXPERIMETAL FEATURE !!!'
+  opts.separator ''
+  opts.separator '* load jars "Jars.lock" from current working directory: `Jars.require_jars_lock!`'
+  opts.separator '* classpath features: see `Jars::Classpath'
+end
+optparse.parse!
+
+Jars.lock_down(debug: options.delete(:debug), verbose: options.delete(:verbose), **options)

data/jar-dependencies.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+File.expand_path('lib', File.dirname(__FILE__)).tap do |lib|
+  $LOAD_PATH.unshift lib unless $LOAD_PATH.include?(lib)
+end
+
+require 'jars/version'
+require 'jars/mima/version'
+
+Gem::Specification.new do |s|
+  s.name = 'jar-dependencies'
+
+  s.version = Jars::VERSION
+  s.platform = 'java'
+
+  s.author = 'christian meier'
+  s.email = ['mkristian@web.de']
+  s.summary = 'manage jar dependencies for gems'
+  s.homepage = 'https://github.com/jruby/jar-dependencies'
+
+  s.bindir = 'exe'
+  s.executables = ['lock_jars']
+
+  s.license = 'MIT'
+
+  s.files = Dir['{lib}/**/*'] + %w[Mavenfile Rakefile Readme.md jar-dependencies.gemspec MIT-LICENSE]
+  # explicitly require the jars
+  s.files += Jars::Mima::JARS.each_key.map { File.join(Jars::Mima::MIMA_DIR, _1) }
+
+  s.description = <<~TEXT
+    manage jar dependencies for gems and keep track which jar was already
+    loaded using maven artifact coordinates. it warns on version conflicts and
+    loads only ONE jar assuming the first one is compatible to the second one
+    otherwise your project needs to lock down the right version by providing a
+    Jars.lock file.
+  TEXT
+
+  s.required_ruby_version = '>= 2.6'
+
+  s.metadata['rubygems_mfa_required'] = 'true'
+end

data/lib/jar-dependencies.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+#
+# Copyright (C) 2014 Christian Meier
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+
+require 'jar_dependencies'