warbler_updated 2.1.0

data/README.rdoc

@@ -0,0 +1,280 @@
+= Warbler {<img src="https://badge.fury.io/rb/warbler.svg" alt="Gem Version" />}[http://badge.fury.io/rb/warbler] {<img src="https://github.com/jruby/warbler/actions/workflows/ci.yml/badge.svg" alt="Build Status" />}[https://github.com/jruby/warbler/actions/workflows/ci.yml]
+
+Warbler is a gem to make a Java jar or war file out of any Ruby, Rails or Rack
+application. Warbler provides a minimal, flexible, Ruby-like way to bundle up
+all of your application files for deployment to a Java environment.
+
+Warbler provides a sane set of out-of-the box defaults that should allow most
+Ruby applications to assemble and Just Work.
+
+Version 2.x of Warbler supports versions of JRuby from 9.2.0.0 and up.
+
+Version 1.4.x of Warbler supports versions of JRuby up to 1.7.x. The {1.x-dev branch}[https://github.com/jruby/warbler/tree/1.x-dev] is the working code for this.
+
+== Getting Started
+
+1. Install the gem: <tt>gem install warbler</tt>.
+
+2. Run warbler in the top directory of your application: <tt>warble</tt>.
+
+3. Choose one:
+
+* For a web project, deploy your +myapp.war+ file to your favorite Java application server.
+
+* For a standalone applications, just run it: <tt>java -jar myapp.jar</tt>.
+
+== Usage
+
+Warbler's +warble+ command is just a small wrapper around Rake with internally
+defined tasks.
+
+    $ warble -T
+    warble compiled    # Feature: precompile all Ruby files
+    warble config      # Generate a configuration file to customize your archive
+    warble executable  # Feature: make an executable archive (runnable + an emb...
+    warble gemjar      # Feature: package gem repository inside a jar
+    warble pluginize   # Install Warbler tasks in your Rails application
+    warble runnable    # Feature: make a runnable archive (e.g. java -jar rails...
+    warble version     # Display version of Warbler
+    warble war         # Create the project war file
+    warble war:clean   # Remove the project war file
+    warble war:debug   # Dump diagnostic information
+
+
+Type <tt>warble</tt> to create the jar or war file.
+
+== Features
+
+Warbler "features" are small Rake tasks that run before the creation of the war
+file and make manipulations to the archive structure. For instance, the
++executable+ feature makes your war file capable of running on its own,
+without a servlet container (using an embedded web server) :
+
+    warble executable war
+
+You can either add features to the warbler command line:
+
+    warble FEATURE war
+
+or configure them in <tt>config/warble.rb</tt> to always be used.
+
+   config.features = %w(FEATURE)
+
+Currently, the following features are available :
+
+* +gemjar+: This bundles all gems into a single gem file to reduce the
+  number of files in the .war. This is mostly useful for Google
+  AppEngine where the number of files per application has a limit.
+  (Note: not applicable for jar-based applications.)
+* +runnable+: This makes a (standard Java) runnable .war archive thus you can
+  execute binary bundled (gem) commands e.g. "rake". You should use the -S
+  switch to specify the binary followed by any arguments in takes e.g.
+  <tt>java -jar myrailsapp.war -S rake db:migrate</tt>.
+* +executable+: This bundles an embedded web server into the .war so that it
+  can either be deployed into a traditional java web server or run as a
+  standalone application using <tt>java -jar myapp.war</tt>.
+  (Note: jar-based applications are executable by default.)
+* +compiled+: This uses +jrubyc+ to precompile all .rb files in your application
+  to .class files and includes those in the .war instead of the Ruby sources.
+  NOTE: The war file will still contain .rb files, but they will be short stubs
+  containing the following code : <tt>load __FILE__.sub(/\.rb$/, '.class')</tt>
+
+Features may form the basis for a third-party plugin system (in the future)
+if there is demand.
+
+NOTE: Feature tasks must be included in the same command invocation and
+inserted before the +war+ task in order to take effect. For example,
+<tt>warble compiled; warble war</tt> does not compile and obfuscate +.rb+
+sources because the second invocation of +warble+ does not run the +compiled+
+feature and creates a basic war with the sources included, make sure you run :
+
+    warble compiled war
+
+or, if it's important that the war always be compiled, use the option above to
+put the feature in your <tt>config/warble.rb</tt>.
+
+== .war or .jar?
+
+War-based projects are for Rails, Merb, or Rack-based web applications.
+They usually contain a +config/environment.rb+ file, a +config/init.rb+ file,
+or a +config.ru+ file.
+The presence of these files are used to determine if the project is a web
+application, and thus a Java EE compatible war file is built for the project.
+
+Jar-based projects are for standalone Ruby applications. Usually a Ruby
+application has a launcher script in the +bin+ directory and Ruby code
+in the <tt>lib</tt> directory. Warbler packages the application so that
+<tt>java -jar myapp.jar</tt> runs the launcher script.
+
+== Jar Files
+
+=== Gem Specification Files
+
+If your project has a <tt>.gemspec</tt> file in the top directory, it will be
+used to configure the project's dependencies, launcher script, require paths,
+and the files to be included in the archive. For best results make sure your
+gemspec specifies all of the following attributes:
+
+* +executables+
+* +require_paths+
+* runtime dependencies added with +add_dependency+
+
+If your project do not have a <tt>.gemspec</tt>, Warbler will attempt to guess
+the launcher from the contents of the <tt>bin</tt> directory and use the
+<tt>lib</tt> directory as the lone require path. All files in the project
+will be included in the archive.
+
+=== Bundler
+
+Applications that use Bundler[http://gembundler.com/], detected via presence of
+a +Gemfile+, will have the gems packaged up into the archive along with the
+Gemfile. The Bundler groups named ":development", ":test" and ":assets" will be
+excluded by default, unless you specify with <tt>config.bundle_without</tt> in
++config/warble.rb+.
+
+Warbler supports Bundler for gems and git repositories, but not for plain path
+components. Warbler will warn when a +:path+ component is found in the +Gemfile+
+and will refuse to include it in the archive.
+
+=== JBundler (experimental)
+
+Applications that use JBundler[http://github.com/mkristian/jbundler], detected
+via presence of a +Jarfile+, will have the jars packaged up into the archive. the JBundler gem is **not** needed for runtime since all jars are already part of the classloader.
+
+== War Files
+
+=== Rails applications
+
+Rails applications are detected automatically and configured appropriately.
+The following items are set up for you:
+
+* Your application runs in the +production+ environment by default.
+  Change it in +config/warble.rb+ (see below).
+* The Rails gem is packaged if you haven't vendored Rails (Rails <= 2.x).
+* Other gems configured in Rails.configuration.gems are packaged (2.1 - 2.3)
+* Multi-thread-safe execution (as introduced in Rails 2.2) is detected and
+  runtime pooling is disabled.
+
+=== Other Rack Applications
+
+If you have a +config.ru+ file in the top directory or one of the immediate
+subdirectories of your application, it will be included and used as the rackup
+script for your Rack-based application. You will probably need to specify
+framework and application gems in +config/warble.rb+ unless you're using Bundler
+to manage your gems. <tt>ENV['RACK_ENV']</tt> will be set to +production+.
+
+See {the examples in the jruby-rack project}[http://github.com/jruby/jruby-rack/tree/master/examples/]
+of how to configure Warbler to package Camping and Sinatra apps.
+
+=== Configuration Notes
+
+* Warbler will load the +environment+ Rake task in a Rails application to try
+  to detect some configuration. If you don't have database access in the
+  environment where you package your application, you may wish to set
+  <tt>Warbler.framework_detection = false</tt> at the top of +config.rb+.
+  In this case you may need to specify additional details such as booter, gems
+  and other settings that would normally be gleaned from the app configuration.
+* Is it possible to more generally detect what gems an application uses?
+  <tt>Gem.loaded_specs</tt> is available, but the application needs to be
+  loaded first before its contents are reliable.
+
+== Custom Configuration
+
+If the default settings are not appropriate for your application, you can
+customize Warbler's behavior. To customize files, libraries, and gems included
+in the .war file, you'll need a config/warble.rb file. There a two ways of
+doing this. With the gem, simply run
+
+    warble config
+
+Finally, edit the +config/warble.rb+ to your taste. The generated file is
+fully-documented with the available options and default values.
+
+=== Archive Layout
+
+The default configuration puts application files (+app+, +config+, +lib+,
++log+, +vendor+, +tmp+) under the .war file's +WEB-INF+ directory, and files in
++public+ in the root of the .war file. Any Java .jar files stored in lib will
+automatically be placed in +WEB-INF/lib+ for placement on the web app's
+class-path.
+
+=== web.xml
+
+Java web applications are configured mainly through this file, and Warbler
+creates a suitable default file for you for use. However, if you need to
+customize it in any way, you have two options.
+
+1. If you just want a static web.xml file whose contents you manually
+   control, you may unzip the one generated for you in
+   <tt>yourapp.war:WEB-INF/web.xml</tt> to <tt>config/web.xml</tt> and
+   modify as needed. It will be copied into subsequent copies of the
+   war file for you.
+2. If you want to inject some dynamic information into the file, copy
+   the <tt>WARBLER_HOME/web.xml.erb</tt> to
+   <tt>config/web.xml.erb</tt>. Its contents will be evaluated for you
+   and put in the webapp. Note that you can also pass arbitrary
+   properties to the ERb template by setting
+   <tt>config.webxml.customkey</tt> values in your
+   <tt>config/warble.rb</tt> file.
+
+For more information on configuration, see Warbler::Config.
+
+== Rakefile Integration
+
+If you'd like to control Warbler from your own project's +Rakefile+,
+simply add the following code somewhere in the +Rakefile+ :
+
+    require 'warbler'
+    Warbler::Task.new
+
+If you're using Bundler, you'll want to add Warbler to your +Gemfile+ :
+
+    group :development do
+      gem "warbler", :require => false
+    end
+
+Now you should be able to invoke <tt>rake war</tt> to create your war file.
+
+== Troubleshooting
+
+If Warbler isn't packaging the files you were expecting, use the +war:debug+
+task to give you more insight into what's going on.
+
+If you think you found a bug, please file one at
+https://github.com/jruby/warbler/issues.
+
+== Source
+
+You can get the Warbler source using Git, in any of the following ways:
+
+   git clone git://github.com/jruby/warbler.git
+
+You can also download a tarball of Warbler source at
+https://github.com/jruby/warbler/archive/master.zip.
+
+== Development
+
+You can develop Warbler with any implementation of Ruby. To write Warbler code
+and run specs, you need to have Bundler installed and run <tt>bundle</tt> once.
+
+After that, simply run <tt>rake</tt>.
+
+=== Integration Tests
+
+There are a few integration tests in the `integration` directory that build WAR file
+with Warbler, and run some basic smoke tests against them.  You can run these like so:
+
+    cd integration
+    mvn verify
+
+You'll need to have Maven >= 3.1.1 installed, of course: http://maven.apache.org/
+
+== License
+
+Warbler is provided under the terms of the MIT license.
+
+Warbler (c) 2013-2018 The JRuby Team
+
+Warbler (c) 2010-2012 Engine Yard, Inc.
+
+Warbler (c) 2007-2009 Sun Microsystems, Inc.

data/Rakefile

@@ -0,0 +1,63 @@
+#-*- mode: ruby -*-
+#--
+# Copyright (c) 2010-2012 Engine Yard, Inc.
+# Copyright (c) 2007-2009 Sun Microsystems, Inc.
+# This source code is available under the MIT license.
+# See the file LICENSE.txt for details.
+#++
+
+begin
+  require 'bundler'
+rescue LoadError
+  warn "\nPlease `gem install bundler' and run `bundle install' to ensure you have all dependencies.\n\n"
+else
+  require 'bundler/gem_helper'
+  Bundler::GemHelper.install_tasks :dir => File.dirname(__FILE__)
+end
+
+require 'rake/clean'
+CLEAN << "pkg" << "doc" << Dir['integration/**/target']
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = ['--color', "--format documentation"]
+end
+
+task :default => :spec
+
+# use Mavenfile to define :jar task
+require 'maven/ruby/maven'
+mvn = Maven::Ruby::Maven.new
+if defined?(JRUBY_VERSION) && !JRUBY_VERSION.start_with?('9.0')
+  mvn.inherit_jruby_version
+end
+
+desc 'compile java sources and build jar'
+task :jar do
+  mvn.prepare_package
+end
+
+desc 'run some integration test'
+task :integration do
+  mvn.verify
+end
+
+desc 'generate the pom.xml from the Mavenfile'
+task :pom do
+  mvn.validate('-Dpolyglot.dump.pom=pom.xml')
+end
+
+# Make sure jar gets compiled before the gem is built
+task :build => :jar
+
+require 'rdoc/task'
+RDoc::Task.new(:docs) do |rd|
+  gemspec = Gem::Specification.load(File.expand_path('warbler.gemspec', File.dirname(__FILE__)))
+  rd.rdoc_dir = "doc"
+  rd.rdoc_files.include("README.rdoc", "History.txt", "LICENSE.txt")
+  rd.rdoc_files += gemspec.require_paths
+  rd.options << '--title' << "#{gemspec.name}-#{gemspec.version} Documentation"
+  rd.options += gemspec.rdoc_options
+end
+
+task :release => :docs

data/bin/warble

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+#
+#--
+# Copyright (c) 2010-2011 Engine Yard, Inc.
+# Copyright (c) 2007-2009 Sun Microsystems, Inc.
+# This source code is available under the MIT license.
+# See the file LICENSE.txt for details.
+#++
+
+require 'warbler'
+Warbler::Application.run

data/ext/JarMain.java

@@ -0,0 +1,334 @@
+/**
+ * Copyright (c) 2010-2012 Engine Yard, Inc.
+ * Copyright (c) 2007-2009 Sun Microsystems, Inc.
+ * This source code is available under the MIT license.
+ * See the file LICENSE.txt for details.
+ */
+
+import java.io.File;
+import java.io.IOException;
+import java.io.FileOutputStream;
+import java.io.InputStream;
+import java.io.PrintStream;
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.net.URI;
+import java.net.URISyntaxException;
+import java.net.URL;
+import java.net.URLClassLoader;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Enumeration;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.jar.JarEntry;
+import java.util.jar.JarFile;
+
+public class JarMain implements Runnable {
+
+    static final String MAIN = '/' + JarMain.class.getName().replace('.', '/') + ".class";
+
+    protected final String[] args;
+    protected final String archive;
+    private final String path;
+
+    protected File extractRoot;
+
+    protected URLClassLoader classLoader;
+
+    JarMain(String[] args) {
+        this.args = args;
+        URL mainClass = getClass().getResource(MAIN);
+        URI uri;
+        File file;
+
+        try {
+            this.path = mainClass.toURI().getSchemeSpecificPart();
+            uri = new URI(this.path.replace("!" + MAIN, ""));
+        }
+        catch (URISyntaxException e) {
+            throw new RuntimeException(e);
+        }
+
+        archive = new File(uri.getPath()).getAbsolutePath();
+
+        Runtime.getRuntime().addShutdownHook(new Thread(this));
+    }
+
+    protected URL[] extractArchive() throws Exception {
+        final JarFile jarFile = new JarFile(archive);
+        try {
+            Map<String, JarEntry> jarNames = new HashMap<String, JarEntry>();
+            for (Enumeration<JarEntry> e = jarFile.entries(); e.hasMoreElements(); ) {
+                JarEntry entry = e.nextElement();
+                String extractPath = getExtractEntryPath(entry);
+                if ( extractPath != null ) jarNames.put(extractPath, entry);
+            }
+
+            extractRoot = File.createTempFile("jruby", "extract");
+            extractRoot.delete(); extractRoot.mkdirs();
+
+            final List<URL> urls = new ArrayList<URL>(jarNames.size());
+            for (Map.Entry<String, JarEntry> e : jarNames.entrySet()) {
+                URL entryURL = extractEntry(e.getValue(), e.getKey());
+                if (entryURL != null) urls.add( entryURL );
+            }
+            return urls.toArray(new URL[urls.size()]);
+        }
+        finally {
+            jarFile.close();
+        }
+    }
+
+    protected String getExtractEntryPath(final JarEntry entry) {
+        final String name = entry.getName();
+        if ( name.startsWith("META-INF/lib") && name.endsWith(".jar") ) {
+            return name.substring(name.lastIndexOf('/') + 1);
+        }
+        return null; // do not extract entry
+    }
+
+    protected URL extractEntry(final JarEntry entry, final String path) throws Exception {
+        final File file = new File(extractRoot, path);
+        if ( entry.isDirectory() ) {
+            file.mkdirs();
+            return null;
+        }
+        final String entryPath = entryPath(entry.getName());
+        final InputStream entryStream;
+        try {
+            entryStream = new URI("jar", entryPath, null).toURL().openStream();
+        }
+        catch (IllegalArgumentException e) {
+            // TODO gems '%' file name "encoding" ?!
+            debug("failed to open jar:" + entryPath + " skipping entry: " + entry.getName(), e);
+            return null;
+        }
+        final File parent = file.getParentFile();
+        if ( parent != null ) parent.mkdirs();
+        FileOutputStream outStream = new FileOutputStream(file);
+        final byte[] buf = new byte[65536];
+        try {
+            int bytesRead;
+            while ((bytesRead = entryStream.read(buf)) != -1) {
+                outStream.write(buf, 0, bytesRead);
+            }
+        }
+        finally {
+            entryStream.close();
+            outStream.close();
+            file.deleteOnExit();
+        }
+        // if (false) debug(entry.getName() + " extracted to " + file.getPath());
+        return file.toURI().toURL();
+    }
+
+    protected String entryPath(String name) {
+        if ( ! name.startsWith("/") ) name = "/" + name;
+        return path.replace(MAIN, name);
+    }
+
+    protected Object newScriptingContainer(final URL[] jars) throws Exception {
+        setSystemProperty("org.jruby.embed.class.path", "");
+        classLoader = new URLClassLoader(jars);
+        Class scriptingContainerClass = Class.forName("org.jruby.embed.ScriptingContainer", true, classLoader);
+        Object scriptingContainer = scriptingContainerClass.newInstance();
+        debug("scripting container class loader urls: " + Arrays.toString(jars));
+        invokeMethod(scriptingContainer, "setArgv", (Object) args);
+        invokeMethod(scriptingContainer, "setClassLoader", new Class[] { ClassLoader.class }, classLoader);
+        return scriptingContainer;
+    }
+
+    protected int launchJRuby(final URL[] jars) throws Exception {
+        final Object scriptingContainer = newScriptingContainer(jars);
+        debug("invoking " + archive + " with: " + Arrays.deepToString(args));
+        Object outcome = invokeMethod(scriptingContainer, "runScriptlet", launchScript());
+        return ( outcome instanceof Number ) ? ( (Number) outcome ).intValue() : 0;
+    }
+
+    protected String launchScript() {
+        return
+        "begin\n" +
+        "  require 'META-INF/init.rb'\n" +
+        "  require 'META-INF/main.rb'\n" +
+        "  0\n" +
+        "rescue SystemExit => e\n" +
+        "  e.status\n" +
+        "end";
+    }
+
+    protected int start() throws Exception {
+        final URL[] jars = extractArchive();
+        return launchJRuby(jars);
+    }
+
+    protected void debug(String msg) {
+        debug(msg, null);
+    }
+
+    protected void debug(String msg, Throwable t) {
+        if ( isDebug() ) System.out.println(msg);
+        if ( isDebug() && t != null ) t.printStackTrace(System.out);
+    }
+
+    protected static void debug(Throwable t) {
+        debug(t, System.out);
+    }
+
+    private static void debug(Throwable t, PrintStream out) {
+        if ( isDebug() ) t.printStackTrace(out);
+    }
+
+    protected void warn(String msg) {
+        System.out.println("WARNING: " + msg);
+    }
+
+    protected static void error(Throwable t) {
+        error(t.toString(), t);
+    }
+
+    protected static void error(String msg, Throwable t) {
+        System.err.println("ERROR: " + msg);
+        debug(t, System.err);
+    }
+
+    protected void delete(File f) {
+        try {
+          if (f.isDirectory() && !isSymlink(f)) {
+              File[] children = f.listFiles();
+              for (int i = 0; i < children.length; i++) {
+                  delete(children[i]);
+              }
+          }
+          f.delete();
+        }
+        catch (IOException e) { error(e); }
+    }
+
+    protected boolean isSymlink(File file) throws IOException {
+        if (file == null) throw new NullPointerException("File must not be null");
+        final File canonical;
+        if ( file.getParent() == null ) canonical = file;
+        else {
+            File parentDir = file.getParentFile().getCanonicalFile();
+            canonical = new File(parentDir, file.getName());
+        }
+        return ! canonical.getCanonicalFile().equals( canonical.getAbsoluteFile() );
+    }
+
+    public void run() {
+        // If the URLClassLoader isn't closed, on Windows, temp JARs won't be cleaned up
+        try {
+            invokeMethod(classLoader, "close");
+        }
+        catch (NoSuchMethodException e) { } // We're not being run on Java >= 7
+        catch (Exception e) { error(e); }
+
+        if ( extractRoot != null ) delete(extractRoot);
+    }
+
+    public static void main(String[] args) {
+        doStart(new JarMain(args));
+    }
+
+    protected static void doStart(final JarMain main) {
+        int exit;
+        try {
+            exit = main.start();
+        }
+        catch (Exception e) {
+            Throwable t = e;
+            while ( t.getCause() != null && t.getCause() != t ) {
+                t = t.getCause();
+            }
+            error(e.toString(), t);
+            exit = 1;
+        }
+        try {
+            if ( isSystemExitEnabled() ) System.exit(exit);
+        }
+        catch (SecurityException e) {
+            debug(e);
+        }
+    }
+
+    protected static Object invokeMethod(final Object self, final String name, final Object... args)
+        throws NoSuchMethodException, IllegalAccessException, Exception {
+
+        final Class[] signature = new Class[args.length];
+        for ( int i = 0; i < args.length; i++ ) signature[i] = args[i].getClass();
+        return invokeMethod(self, name, signature, args);
+    }
+
+    protected static Object invokeMethod(final Object self, final String name, final Class[] signature, final Object... args)
+        throws NoSuchMethodException, IllegalAccessException, Exception {
+        Method method = self.getClass().getDeclaredMethod(name, signature);
+        try {
+            return method.invoke(self, args);
+        }
+        catch (InvocationTargetException e) {
+            Throwable target = e.getTargetException();
+            if (target instanceof Exception) {
+                throw (Exception) target;
+            }
+            throw e;
+        }
+    }
+
+    private static final boolean debug;
+    static {
+        debug = Boolean.parseBoolean( getSystemProperty("warbler.debug", "false") );
+    }
+
+    static boolean isDebug() { return debug; }
+
+    /**
+     * if warbler.skip_system_exit system property is defined, we will not
+     * call System.exit in the normal flow. System.exit can cause problems
+     * for wrappers like procrun
+     */
+    private static boolean isSystemExitEnabled(){
+        return getSystemProperty("warbler.skip_system_exit") == null; //omission enables System.exit use
+    }
+
+    static String getSystemProperty(final String name) {
+        return getSystemProperty(name, null);
+    }
+
+    static String getSystemProperty(final String name, final String defaultValue) {
+        try {
+            return System.getProperty(name, defaultValue);
+        }
+        catch (SecurityException e) {
+            return defaultValue;
+        }
+    }
+
+    static boolean setSystemProperty(final String name, final String value) {
+        try {
+            System.setProperty(name, value);
+            return true;
+        }
+        catch (SecurityException e) {
+            return false;
+        }
+    }
+
+    static String getENV(final String name) {
+        return getENV(name, null);
+    }
+
+    static String getENV(final String name, final String defaultValue) {
+        try {
+            if ( System.getenv().containsKey(name) ) {
+                return System.getenv().get(name);
+            }
+            return defaultValue;
+        }
+        catch (SecurityException e) {
+            return defaultValue;
+        }
+    }
+
+}