org.jruby.runtime.load

Class LoadService

java.lang.Object

org.jruby.runtime.load.LoadService

Direct Known Subclasses:

LoadService19, OSGiLoadService

public class LoadService
extends java.lang.Object

How require works in JRuby

When requiring a name from Ruby, JRuby will first remove any file extension it knows about, thereby making it possible to use this string to see if JRuby has already loaded the name in question. If a .rb extension is specified, JRuby will only try those extensions when searching. If a .so, .o, .dll, or .jar extension is specified, JRuby will only try .so or .jar when searching. Otherwise, JRuby goes through the known suffixes (.rb, .rb.ast.ser, .so, and .jar) and tries to find a library with this name. The process for finding a library follows this order for all searchable extensions:

1. First, check if the name starts with 'jar:', then the path points to a jar-file resource which is returned.
2. Second, try searching for the file in the current dir
3. Then JRuby looks through the load path trying these variants:
   1. See if the current load path entry starts with 'jar:', if so check if this jar-file contains the name
   2. Otherwise JRuby tries to construct a path by combining the entry and the current working directy, and then see if a file with the correct name can be reached from this point.
4. If all these fail, try to load the name as a resource from classloader resources, using the bare name as well as the load path entries
5. When we get to this state, the normal JRuby loading has failed. At this stage JRuby tries to load Java native extensions, by following this process:
   1. First it checks that we haven't already found a library. If we found a library of type JarredScript, the method continues.
   2. The first step is translating the name given into a valid Java Extension class name. First it splits the string into each path segment, and then makes all but the last downcased. After this it takes the last entry, removes all underscores and capitalizes each part separated by underscores. It then joins everything together and tacks on a 'Service' at the end. Lastly, it removes all leading dots, to make it a valid Java FWCN.
   3. If the previous library was of type JarredScript, we try to add the jar-file to the classpath
   4. Now JRuby tries to instantiate the class with the name constructed. If this works, we return a ClassExtensionLibrary. Otherwise, the old library is put back in place, if there was one.
6. When all separate methods have been tried and there was no result, a LoadError will be raised.
7. Otherwise, the name will be added to the loaded features, and the library loaded

How to make a class that can get required by JRuby

First, decide on what name should be used to require the extension. In this purely hypothetical example, this name will be 'active_record/connection_adapters/jdbc_adapter'. Then create the class name for this require-name, by looking at the guidelines above. Our class should be named active_record.connection_adapters.JdbcAdapterService, and implement one of the library-interfaces. The easiest one is BasicLibraryService, where you define the basicLoad-method, which will get called when your library should be loaded.

The next step is to either put your compiled class on JRuby's classpath, or package the class/es inside a jar-file. To package into a jar-file, we first create the file, then rename it to jdbc_adapter.jar. Then we put this jar-file in the directory active_record/connection_adapters somewhere in JRuby's load path. For example, copying jdbc_adapter.jar into JRUBY_HOME/lib/ruby/site_ruby/1.8/active_record/connection_adapters will make everything work. If you've packaged your extension inside a RubyGem, write a setub.rb-script that copies the jar-file to this place.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	LoadService.BailoutSearcher Deprecated.
class	LoadService.ClassLoaderSearcher Deprecated.
class	LoadService.ExtensionSearcher Deprecated.
static interface	LoadService.LoadSearcher Deprecated.
private static class	LoadService.LoadTimer
class	LoadService.NormalSearcher Deprecated.
private class	LoadService.RequireLocks
private static class	LoadService.RequireState
class	LoadService.ScriptClassSearcher Deprecated.
static class	LoadService.SearchState
class	LoadService.SourceBailoutSearcher Deprecated.
static class	LoadService.SuffixType
private static class	LoadService.TracingLoadTimer

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Map<java.lang.String,Library>	builtinLibraries
protected static java.util.regex.Pattern	extensionPattern
protected java.util.Map<java.lang.String,java.util.jar.JarFile>	jarFiles
protected LibrarySearcher	librarySearcher
protected StringArraySet	loadedFeatures
protected RubyArray	loadedFeaturesDup
private java.util.Map<java.lang.String,java.lang.String>	loadedFeaturesIndex
protected RubyArray	loadPath
private LoadService.LoadTimer	loadTimer
private static Logger	LOG
protected LoadService.RequireLocks	requireLocks
protected Ruby	runtime
protected java.util.List<LoadService.LoadSearcher>	searchers
protected static java.util.regex.Pattern	sourcePattern
private static java.util.regex.Pattern	URI_PATTERN

Constructor Summary

Constructors

Constructor and Description
LoadService(Ruby runtime)

Method Summary

Modifier and Type	Method and Description
void	addBuiltinLibrary(java.lang.String name, Library library)
protected void	addFeatureToIndex(java.lang.String shortName, java.lang.String name)
protected void	addLoadedFeature(java.lang.String name) Deprecated.
protected void	addLoadedFeature(java.lang.String shortName, java.lang.String name)
protected void	addPath(java.lang.String path)
void	addPaths(java.util.List<java.lang.String> additionalDirectories) Add additional directories to the load path.
void	addPaths(java.lang.String... additionalDirectories) Add additional directories to the load path.
boolean	autoloadRequire(java.lang.String requireName)
protected java.lang.String	buildClassName(java.lang.String className)
protected void	checkEmptyLoad(java.lang.String file)
static java.lang.String	classpathFilenameFromURL(java.lang.String name, java.net.URL loc, boolean isClasspathScheme) Given a URL to a classloader resource, build an appropriate load string.
protected Library	createLibrary(LoadService.SearchState state, LoadServiceResource resource) Deprecated.
protected void	debugLogFound(LoadServiceResource resource) Deprecated.
protected void	debugLogFound(java.lang.String what, java.lang.String msg) Deprecated.
protected void	debugLogTry(java.lang.String what, java.lang.String msg) Deprecated.
private java.lang.String	expandRelativeJarPath(java.lang.String path)
protected boolean	featureAlreadyLoaded(java.lang.String name)
protected Library	findBuiltinLibrary(LoadService.SearchState state, java.lang.String baseName, LoadService.SuffixType suffixType) Deprecated.
LoadService.SearchState	findFileForLoad(java.lang.String file)
protected LoadServiceResource	findFileInClasspath(java.lang.String name) this method uses the appropriate lookup strategy to find a file.
private Library	findLibraryBySearchState(LoadService.SearchState state)
protected Library	findLibraryWithClassloaders(LoadService.SearchState state, java.lang.String baseName, LoadService.SuffixType suffixType)
protected Library	findLibraryWithoutCWD(LoadService.SearchState state, java.lang.String baseName, LoadService.SuffixType suffixType) Deprecated.
protected LoadServiceResource	getClassPathResource(java.lang.ClassLoader classLoader, java.lang.String name)
protected java.lang.String	getFileName(JRubyFile file, java.lang.String namePlusSuffix)
java.util.jar.JarFile	getJarFile(java.lang.String jarFileName)
IRubyObject	getLoadedFeatures()
IRubyObject	getLoadPath()
protected java.lang.String	getLoadPathEntry(IRubyObject entry)
void	init(java.util.List prependDirectories) Called to initialize the load path with a set of optional prepended directories and then the standard set of dirs.
protected boolean	isFeatureInIndex(java.lang.String shortName)
private boolean	isFeaturesIndexUpToDate()
protected boolean	isJarfileLibrary(LoadService.SearchState state, java.lang.String file)
protected static boolean	isRequireable(java.net.URL loc)
void	load(java.lang.String file, boolean wrap)
void	loadFromClassLoader(java.lang.ClassLoader classLoader, java.lang.String file, boolean wrap)
protected boolean	loadPathLooksLikeClasspathURL(java.lang.String loadPathEntry)
protected boolean	loadPathLooksLikeJarURL(java.lang.String loadPathEntry)
private static RaiseException	newLoadErrorFromThrowable(Ruby runtime, java.lang.String file, java.lang.Throwable t)
static void	reflectedLoad(Ruby runtime, java.lang.String libraryName, java.lang.String className, java.lang.ClassLoader classLoader, boolean wrap) Load the org.jruby.runtime.load.Library implementation specified by className.
void	removeBuiltinLibrary(java.lang.String name)
void	removeInternalLoadedFeature(java.lang.String name)
boolean	require(java.lang.String requireName)
private LoadService.RequireState	requireCommon(java.lang.String file, boolean circularRequireWarning)
protected void	reraiseRaiseExceptions(java.lang.Throwable e)
protected java.lang.String	resolveLoadName(LoadServiceResource foundResource, java.lang.String previousPath)
boolean	smartLoad(java.lang.String file) Deprecated.
private java.lang.String[]	splitJarUrl(java.lang.String loadPathEntry)
protected boolean	tryLoadingLibraryOrScript(Ruby runtime, LoadService.SearchState state)
protected LoadServiceResource	tryResourceAsIs(java.lang.String namePlusSuffix) Deprecated.
protected LoadServiceResource	tryResourceAsIs(java.lang.String namePlusSuffix, java.lang.String debugName) Deprecated.
protected LoadServiceResource	tryResourceFromCWD(LoadService.SearchState state, java.lang.String baseName, LoadService.SuffixType suffixType) Deprecated.
protected LoadServiceResource	tryResourceFromDotSlash(LoadService.SearchState state, java.lang.String baseName, LoadService.SuffixType suffixType) Deprecated.
protected LoadServiceResource	tryResourceFromHome(LoadService.SearchState state, java.lang.String baseName, LoadService.SuffixType suffixType) Deprecated.
protected LoadServiceResource	tryResourceFromJarURL(LoadService.SearchState state, java.lang.String baseName, LoadService.SuffixType suffixType) Deprecated.
protected LoadServiceResource	tryResourceFromJarURLWithLoadPath(java.lang.String namePlusSuffix, java.lang.String loadPathEntry) Deprecated.
protected LoadServiceResource	tryResourceFromLoadPath(java.lang.String namePlusSuffix, java.lang.String loadPathEntry) Deprecated.
protected LoadServiceResource	tryResourceFromLoadPathOrURL(LoadService.SearchState state, java.lang.String baseName, LoadService.SuffixType suffixType) Deprecated.
protected void	warnCircularRequire(java.lang.String requireName)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOG

private static final Logger LOG

loadTimer

private final LoadService.LoadTimer loadTimer

sourcePattern

protected static final java.util.regex.Pattern sourcePattern

extensionPattern

protected static final java.util.regex.Pattern extensionPattern

loadPath

protected RubyArray loadPath

loadedFeatures

protected StringArraySet loadedFeatures

loadedFeaturesDup

protected RubyArray loadedFeaturesDup

loadedFeaturesIndex

private final java.util.Map<java.lang.String,java.lang.String> loadedFeaturesIndex

builtinLibraries

protected final java.util.Map<java.lang.String,Library> builtinLibraries

jarFiles

protected final java.util.Map<java.lang.String,java.util.jar.JarFile> jarFiles

runtime

protected final Ruby runtime

librarySearcher

protected final LibrarySearcher librarySearcher

requireLocks

protected final LoadService.RequireLocks requireLocks

searchers

protected final java.util.List<LoadService.LoadSearcher> searchers

URI_PATTERN

private static final java.util.regex.Pattern URI_PATTERN

Constructor Detail

LoadService

public LoadService(Ruby runtime)

Method Detail

init

public void init(java.util.List prependDirectories)

Called to initialize the load path with a set of optional prepended directories and then the standard set of dirs. This should only be called once, at load time, since it wipes out loaded features.

Parameters:

prependDirectories -

addPaths

public void addPaths(java.util.List<java.lang.String> additionalDirectories)

Add additional directories to the load path.

Parameters:

additionalDirectories - a List of additional dirs to append to the load path

addPaths

public void addPaths(java.lang.String... additionalDirectories)

Add additional directories to the load path.

Parameters:

additionalDirectories - an array of additional dirs to append to the load path

isFeatureInIndex

protected boolean isFeatureInIndex(java.lang.String shortName)

addLoadedFeature

@Deprecated
protected void addLoadedFeature(java.lang.String name)

Deprecated.

addLoadedFeature

protected void addLoadedFeature(java.lang.String shortName,
                                java.lang.String name)

addFeatureToIndex

protected void addFeatureToIndex(java.lang.String shortName,
                                 java.lang.String name)

addPath

protected void addPath(java.lang.String path)

load

public void load(java.lang.String file,
                 boolean wrap)

loadFromClassLoader

public void loadFromClassLoader(java.lang.ClassLoader classLoader,
                                java.lang.String file,
                                boolean wrap)

findFileForLoad

public LoadService.SearchState findFileForLoad(java.lang.String file)

require

public boolean require(java.lang.String requireName)

autoloadRequire

public boolean autoloadRequire(java.lang.String requireName)

requireCommon

private LoadService.RequireState requireCommon(java.lang.String file,
                                               boolean circularRequireWarning)

warnCircularRequire

protected void warnCircularRequire(java.lang.String requireName)

smartLoad

@Deprecated
public boolean smartLoad(java.lang.String file)

Deprecated.

This method did require the specified file without getting a lock. Now we offer safe version only. Use require(String) instead.

reflectedLoad

public static void reflectedLoad(Ruby runtime,
                                 java.lang.String libraryName,
                                 java.lang.String className,
                                 java.lang.ClassLoader classLoader,
                                 boolean wrap)

Load the org.jruby.runtime.load.Library implementation specified by className. The purpose of using this method is to avoid having static references to the given library class, thereby avoiding the additional classloading when the library is not in use.

Parameters:

runtime - The runtime in which to load

libraryName - The name of the library, to use for error messages

className - The class of the library

classLoader - The classloader to use to load it

wrap - Whether to wrap top-level in an anonymous module

getLoadPath

public IRubyObject getLoadPath()

getLoadedFeatures

public IRubyObject getLoadedFeatures()

addBuiltinLibrary

public void addBuiltinLibrary(java.lang.String name,
                              Library library)

removeBuiltinLibrary

public void removeBuiltinLibrary(java.lang.String name)

removeInternalLoadedFeature

public void removeInternalLoadedFeature(java.lang.String name)

isFeaturesIndexUpToDate

private boolean isFeaturesIndexUpToDate()

featureAlreadyLoaded

protected boolean featureAlreadyLoaded(java.lang.String name)

isJarfileLibrary

protected boolean isJarfileLibrary(LoadService.SearchState state,
                                   java.lang.String file)

reraiseRaiseExceptions

protected void reraiseRaiseExceptions(java.lang.Throwable e)
                               throws RaiseException

Throws:

RaiseException

tryLoadingLibraryOrScript

protected boolean tryLoadingLibraryOrScript(Ruby runtime,
                                            LoadService.SearchState state)

newLoadErrorFromThrowable

private static RaiseException newLoadErrorFromThrowable(Ruby runtime,
                                                        java.lang.String file,
                                                        java.lang.Throwable t)

buildClassName

protected java.lang.String buildClassName(java.lang.String className)

checkEmptyLoad

protected void checkEmptyLoad(java.lang.String file)
                       throws RaiseException

Throws:

RaiseException

debugLogTry

@Deprecated
protected void debugLogTry(java.lang.String what,
                                       java.lang.String msg)

Deprecated.

debugLogFound

@Deprecated
protected void debugLogFound(java.lang.String what,
                                         java.lang.String msg)

Deprecated.

debugLogFound

@Deprecated
protected void debugLogFound(LoadServiceResource resource)

Deprecated.

findLibraryBySearchState

private Library findLibraryBySearchState(LoadService.SearchState state)

findBuiltinLibrary

@Deprecated
protected Library findBuiltinLibrary(LoadService.SearchState state,
                                                 java.lang.String baseName,
                                                 LoadService.SuffixType suffixType)

Deprecated.

findLibraryWithoutCWD

@Deprecated
protected Library findLibraryWithoutCWD(LoadService.SearchState state,
                                                    java.lang.String baseName,
                                                    LoadService.SuffixType suffixType)

Deprecated.

findLibraryWithClassloaders

protected Library findLibraryWithClassloaders(LoadService.SearchState state,
                                              java.lang.String baseName,
                                              LoadService.SuffixType suffixType)

createLibrary

@Deprecated
protected Library createLibrary(LoadService.SearchState state,
                                            LoadServiceResource resource)

Deprecated.

tryResourceFromCWD

@Deprecated
protected LoadServiceResource tryResourceFromCWD(LoadService.SearchState state,
                                                             java.lang.String baseName,
                                                             LoadService.SuffixType suffixType)
                                                      throws RaiseException

Deprecated.

Throws:

RaiseException

tryResourceFromDotSlash

@Deprecated
protected LoadServiceResource tryResourceFromDotSlash(LoadService.SearchState state,
                                                                  java.lang.String baseName,
                                                                  LoadService.SuffixType suffixType)
                                                           throws RaiseException

Deprecated.

Try loading the resource from the current dir by appending suffixes and passing it to tryResourceAsIs to have the ./ replaced by CWD.

Throws:

RaiseException

tryResourceFromHome

@Deprecated
protected LoadServiceResource tryResourceFromHome(LoadService.SearchState state,
                                                              java.lang.String baseName,
                                                              LoadService.SuffixType suffixType)
                                                       throws RaiseException

Deprecated.

Throws:

RaiseException

tryResourceFromJarURL

@Deprecated
protected LoadServiceResource tryResourceFromJarURL(LoadService.SearchState state,
                                                                java.lang.String baseName,
                                                                LoadService.SuffixType suffixType)

Deprecated.

tryResourceFromLoadPathOrURL

@Deprecated
protected LoadServiceResource tryResourceFromLoadPathOrURL(LoadService.SearchState state,
                                                                       java.lang.String baseName,
                                                                       LoadService.SuffixType suffixType)

Deprecated.

getLoadPathEntry

protected java.lang.String getLoadPathEntry(IRubyObject entry)

tryResourceFromJarURLWithLoadPath

@Deprecated
protected LoadServiceResource tryResourceFromJarURLWithLoadPath(java.lang.String namePlusSuffix,
                                                                            java.lang.String loadPathEntry)

Deprecated.

getJarFile

public java.util.jar.JarFile getJarFile(java.lang.String jarFileName)

loadPathLooksLikeJarURL

protected boolean loadPathLooksLikeJarURL(java.lang.String loadPathEntry)

loadPathLooksLikeClasspathURL

protected boolean loadPathLooksLikeClasspathURL(java.lang.String loadPathEntry)

splitJarUrl

private java.lang.String[] splitJarUrl(java.lang.String loadPathEntry)

tryResourceFromLoadPath

@Deprecated
protected LoadServiceResource tryResourceFromLoadPath(java.lang.String namePlusSuffix,
                                                                  java.lang.String loadPathEntry)
                                                           throws RaiseException

Deprecated.

Throws:

RaiseException

tryResourceAsIs

@Deprecated
protected LoadServiceResource tryResourceAsIs(java.lang.String namePlusSuffix)
                                                   throws RaiseException

Deprecated.

Throws:

RaiseException

tryResourceAsIs

@Deprecated
protected LoadServiceResource tryResourceAsIs(java.lang.String namePlusSuffix,
                                                          java.lang.String debugName)
                                                   throws RaiseException

Deprecated.

Throws:

RaiseException

findFileInClasspath

protected LoadServiceResource findFileInClasspath(java.lang.String name)

this method uses the appropriate lookup strategy to find a file. It is used by Kernel#require.

Parameters:

name - the file to find, this is a path name

Returns:

the correct file

isRequireable

protected static boolean isRequireable(java.net.URL loc)

getClassPathResource

protected LoadServiceResource getClassPathResource(java.lang.ClassLoader classLoader,
                                                   java.lang.String name)

classpathFilenameFromURL

public static java.lang.String classpathFilenameFromURL(java.lang.String name,
                                                        java.net.URL loc,
                                                        boolean isClasspathScheme)

Given a URL to a classloader resource, build an appropriate load string.

Parameters:

name - the original filename requested

loc - the URL to the resource

isClasspathScheme - whether we're using the classpath: sceheme

Returns:

expandRelativeJarPath

private java.lang.String expandRelativeJarPath(java.lang.String path)

resolveLoadName

protected java.lang.String resolveLoadName(LoadServiceResource foundResource,
                                           java.lang.String previousPath)

getFileName

protected java.lang.String getFileName(JRubyFile file,
                                       java.lang.String namePlusSuffix)