LockJar
LockJar manages Java Jars for Ruby. Powered by Naether to create a frankenstein of Bundler and Maven. A Jarfile (example) is used to generate a Jarfile.lock that contains all the resolved jar dependencies. The Jarfile.lock can be used to populate the classpath.
LockJar can:
- Be used directly in MRI 2.x and JRuby 1.7, 9.0
- From the command line
- Triggered from a Gem install
- Integrated into Buildr
- Integrated into Bundler
https://github.com/mguymon/lock_jar
Install
gem install lock_jar
Ruby Usage
JRuby is natively supported. Ruby 2.x uses Rjb to proxy over JNI.
Jarfile
A Jarfile is a simple file using a Ruby DSL for defining a project's dependencies using the following methods:
- local_repo(path): Set the local Maven repository, this were dependencies are downloaded to.
- remote_repo(url): Add additional url of remote Maven repository.
- group(groups): Set the group for nested jar or pom. A single or Array of groups can be set.
- jar(notations, opts = {}): Add Jar dependency in artifact notation, artifact:group:version as the bare minimum. A single or Array of notations can be passed. Default group is default, can be specified by setting opts = { :group => ['group_name'] }
- local(path): Add a local path to a Jar
-
pom(pom_path, opts = {}): Add a local Maven pom, default is to load dependencies for
runtime
andcompile
scopes. To select the scopes to be loaded from the pom, set the opts = { :scopes => ['test'] } - without_default_maven_repo: Do not use the default maven repo.
Example Jarfile
repository 'http://repository.jboss.org/nexus/content/groups/public-jboss'
// Default group is default
jar "org.apache.mina:mina-core:2.0.4"
local 'spec/fixtures/naether-0.13.0.jar'
group 'runtime' do
jar 'org.apache.tomcat:servlet-api:jar:6.0.35'
end
group 'test' do
jar 'junit:junit:jar:4.12', :group => 'test'
end
Resolving dependencies
LockJar.lock(*args): Using a Jarfile, creates a lock file. Depending on the type of arg, a different configuration is set.
-
[String] will set the Jarfile path, e.g.
'/somewhere/Jarfile.different'
. Default jarfile is'Jarfile'
-
[Hash] will set the options, e.g.
{ :local_repo => 'path' }
- :download [Boolean] if true, will download jars to local repo. Defaults to true.
-
:local_repo [String] sets the local repo path. Defaults to
ENV['M2_REPO']
or'~/.m2/repository'
-
:lockfile [String] sets the Jarfile.lock path. Default lockfile is
'Jarfile.lock'
.
When the Jarfile is locked, the transitive dependencies are resolved and saved to the Jarfile.lock file.
Example of locking a Jarfile to a Jarfile.lock
LockJar.lock
Default Remote Repository
LockJar uses Naether's default remote repository, http://repo1.maven.org/maven2/.
Jarfile.lock pior to 0.12.0 did not write the default remote repository. As of version 0.12.0, only repositories in the Jarfile.lock are used. This means older Jarfile.lock will need to be updated to include the default maven repo if they rely on it.
Jarfile.lock
The Jarfile.lock generated is a YAML file containing information on how to handle the classpath for grouped dependencies and their nested transitive dependencies.
The Jarfile.lock
---
version: 0.7.0
groups:
default:
dependencies:
- ch.qos.logback:logback-classic:jar:0.9.24
- ch.qos.logback:logback-core:jar:0.9.24
- com.metapossum:metapossum-scanner:jar:1.0
- com.tobedevoured.modelcitizen:core:jar:0.8.1
- commons-beanutils:commons-beanutils:jar:1.8.3
- commons-io:commons-io:jar:1.4
- commons-lang:commons-lang:jar:2.6
- commons-logging:commons-logging:jar:1.1.1
- junit:junit:jar:4.7
- org.apache.mina:mina-core:jar:2.0.4
- org.slf4j:slf4j-api:jar:1.6.1
artifacts:
- jar:org.apache.mina:mina-core:jar:2.0.4:
transitive:
org.slf4j:slf4j-api:jar:1.6.1: {}
- pom:spec/pom.xml:
scopes:
- runtime
- compile
transitive:
com.metapossum:metapossum-scanner:jar:1.0:
junit:junit:jar:4.7: {}
commons-io:commons-io:jar:1.4: {}
commons-beanutils:commons-beanutils:jar:1.8.3:
commons-logging:commons-logging:jar:1.1.1: {}
ch.qos.logback:logback-classic:jar:0.9.24:
ch.qos.logback:logback-core:jar:0.9.24: {}
commons-lang:commons-lang:jar:2.6: {}
development:
dependencies:
- com.typesafe:config:jar:0.5.0
artifacts:
- jar:com.typesafe:config:jar:0.5.0:
transitive: {}
test:
dependencies:
- junit:junit:jar:4.12
- org.hamcrest:hamcrest-core:jar:1.1
artifacts:
- jar:junit:junit:jar:4.12:
transitive:
org.hamcrest:hamcrest-core:jar:1.1: {}
...
Accessing Jars
LockJar.install(*args): Download Jars in the Jarfile.lock
-
[String] will set the Jarfile.lock path, e.g.
'Better.lock'
. Default lock file is'Jarfile.lock'
. -
[Array] will set the groups, e.g.
['compile','test']
. Defaults group is default. -
[Hash] will set the options, e.g.
{ :local_repo => 'path' }
-
:local_repo [String] sets the local repo path. Defaults to
ENV['M2_REPO']
or'~/.m2/repository'
-
:local_repo [String] sets the local repo path. Defaults to
LockJar.list(*args): Lists all dependencies as notations for groups from the Jarfile.lock. Depending on the type of arg, a different configuration is set.
-
[String] will set the Jarfile.lock path, e.g.
'Better.lock'
. Default lock file is'Jarfile.lock'
. -
[Array] will set the groups, e.g.
['default', 'runtime']
. Defaults group is default. -
[Hash] will set the options, e.g.
{ :local_repo => 'path' }
-
:local_repo [String] sets the local repo path. Defaults to
ENV['M2_REPO']
or'~/.m2/repository'
- :local_paths [Boolean] converts the notations to paths of jars in the local repo
-
:resolve [Boolean] to
true
will make transitive dependences resolve before returning list of jars. Setting tofalse
will list dependencies, excluding transitive dependencies.
-
:local_repo [String] sets the local repo path. Defaults to
LockJar.load(*args): Loads all dependencies to the classpath for groups from the Jarfile.lock. Default group is default. Default lock file is Jarfile.lock.
-
[String] will set the Jarfile.lock, e.g.
'Better.lock'
-
[Array] will set the groups, e.g.
['default', 'runtime']
-
[Hash] will set the options, e.g.
{ :local_repo => 'path' }
- :local_repo [String] sets the local repo path
- :resolve [Boolean] to true will make transitive dependences resolve before loading to classpath
Once a Jarfile.lock is generated, you can list all resolved jars by
jars = LockJar.list
or directly load all Jars into the classpath
jars = LockJar.load
Do not forget, if you change your Jarfile, you have to re-generate the Jarfile.lock.
See also loading Jars into a custom ClassLoader.
Shortcuts
Skipping the Jarfile
You can skip the Jarfile and Jarfile.lock to directly play with dependencies by passing a block to LockJar.lock, LockJar.list, and LockJar.load
Lock without a Jarfile
LockJar.lock do
jar 'org.eclipse.jetty:example-jetty-embedded:jar:8.1.2.v20120308'
end
List without a Jarfile.lock
LockJar.list do
jar 'org.eclipse.jetty:example-jetty-embedded:jar:8.1.2.v20120308'
end
Load without a Jarfile.lock
LockJar.load do
jar 'org.eclipse.jetty:example-jetty-embedded:jar:8.1.2.v20120308'
end
Since you skipped the locking part, mostly likely you will need to resolve the dependences in the block, just pass the :resolve => true option to enable dependency resolution (also works for LockJar.list).
LockJar.load(:resolve => true) do
jar 'org.eclipse.jetty:example-jetty-embedded:jar:8.1.2.v20120308'
end
Command line
There is a simple command line helper. You can lock a Jarfile with the following command
lockjar lock
List jars in a Jarfile.lock with
lockjar list
Download all jars in a Jarfile.lock with
lockjar install
lockjar --help will give you list of all commands and their options.
Gem Integration
Installing Jars with a Gem
LockJar can be triggered when a Gem is installed by using a Gem extension of type Rakefile. The cavaet is the task to install the jars must be the default for the Rakefile.
A Gem spec with Rakefile extension:
Gem::Specification.new do |s|
s.extensions = ["Rakefile"]
end
Rakefile with default to install Jars using LockJar:
task :default => :prepare
task :prepare do
require 'lock_jar'
# get jarfile relative the gem dir
lockfile = File.expand_path("../Jarfile.lock", __FILE__)
LockJar.install(lockfile)
end
Work around for Rakefile default
The downside of using the Gem extension Rakefile is it requires the default to
point at the task to download the jars (from the example Rakefile,
task :default => :prepare
). To get around this, I used a Rakefile called
PostInstallRakefile to handle the task :prepare
. When packaging the gem, PostInstallRakefile is
renamed to Rakefile
.
Manually installing Jars
Instead of rely in a Rakefile to install Jars when the Gem is installed, Jars can be manually installed. The following
Ruby needs to be called before calling LockJar.load
. Only Jars that are missing are downloaded.
#get jarfile relative the gem dir
lockfile = File.expand_path("../Jarfile.lock", __FILE__)
# Download any missing Jars
LockJar.install(lockfile)
Loading
With the Jars installed, loading the classpath for the Gem is simple. As part of the load process for the Gem (an entry file that is required, etc) use the following:
#get jarfile relative the gem dir
lockfile = File.expand_path("../Jarfile.lock", __FILE__)
# Loads the ClassPath with Jars from the lockfile
LockJar.load(lockfile)
See also loading Jars into a custom ClassLoader.
Authentication
LockJar supports authentication to repository by passing in credentials from a .lockjar
file. The YAML file contains a username and passwords per repository, for example:
repositories:
'https://some.fancy.doman/maven':
username: 'user1'
password: 'the_pass'
The order of precedence for locating the .lockjar
file is the ENV['LOCKJAR_CONFIG']
, current working directory, and last the user's home directory.
Buildr Integration
LockJar integrates with Buildr using an Addon. This allows the Jarfile to be defined directly into a buildfile. A global LockJar definition can be set and is inherited to all projects. Each project may have its own LockJar definition. A lock file is generated per project based on the project name.
A new Buildr task is added to generate the lockfile for all projects
buildr lock_jar:lock
and a task per project to generate the lockfile for a single project
buildr <app>:<project>:lock_jar:lock
In a project, you can access an Array of notations using the lock_jars method, accepts same parameters as LockJar.list
lock_jars()
The default group dependencies are automatically added to the classpath for compiling. The test group dependencies are automatically added to the classpath for tests. Do not forget, if you change the LockJar definitions, you have to rerun the lock_jar:lock task.
Example
Sample buildfile with LockJar
require 'lock_jar/buildr'
# app definition, inherited into all projects
lock_jar do
group 'test' do
jar 'junit:junit:jar:4.12'
end
end
define 'app' do
define 'project1' do
lock_jar do
jar "org.apache.mina:mina-core:2.0.4"
end
end
define 'project2' do
lock_jar do
pom 'pom.xml'
end
end
end
Generated the following lock files using lock_jar:lock
- project1.lock - contains junit and mina jars.
- project2.lock - contains junit and pom.xml jars.
Bundler Integration
LockJar patches Bundler
to allow creation of a Jarfile.lock when Bundler calls install
and update
. To enable this support, add this exit callback your Gemfile
@@check ||= at_exit do
require 'lock_jar/bundler'
LockJar::Bundler.lock!
end
You can optionally create a Jarfile that will automatically be included when you bundle install
or bundle update
. Otherwise
Gems with a Jarfile will be merge to generate a Jarfile.lock.
Bundler to LockJar groups
LockJar will merge the dependencies from the default
and runtime
group of a Gem's Jarfile. These will be placed in the
lockfile under Gem's corresponding Bundler group. For example, the following Gemfile:
group :development do
gem 'solr_sail', '~>0.1.0'
end
Would produce the follow Jarfile.lock excerpt:
---
version: 0.7.0
merged:
- gem:solr_sail:gems/solr_sail-0.1.0-java/Jarfile
groups:
default:
dependencies: []
artifacts: []
development:
dependencies:
- ch.qos.logback:logback-classic:jar:1.0.6
- ch.qos.logback:logback-core:jar:1.0.6
- com.google.guava:guava:jar:r05
Since solr_sail
is defined in the Gemfile's development
group, the corresponding Jarfile.lock dependencies are also under the development
group.
License
Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.