org.jruby.runtime.load

Class LoadService

java.lang.Object

org.jruby.runtime.load.LoadService

Direct Known Subclasses:

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

Author:

jpetersen

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.
class	LoadService.NormalSearcher Deprecated.
class	LoadService.ScriptClassSearcher Deprecated.
static class	LoadService.SearchState
class	LoadService.SourceBailoutSearcher Deprecated.
static class	LoadService.SuffixType

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Map<java.lang.String,Library>	builtinLibraries Deprecated.
protected static java.util.regex.Pattern	extensionPattern
protected java.util.Map<java.lang.String,java.util.jar.JarFile>	jarFiles
protected org.jruby.runtime.load.LibrarySearcher	librarySearcher
protected StringArraySet	loadedFeatures
protected RubyArray	loadedFeaturesDup
protected RubyArray	loadPath
protected Ruby	runtime
protected static java.util.regex.Pattern	sourcePattern

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) Deprecated.
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) Deprecated.
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.
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.
protected 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.
java.util.List<java.lang.String>	getBuiltinLibraries() Deprecated.
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<java.lang.String> 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)
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)
void	provide(java.lang.String shortName, java.lang.String fullName)
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) Deprecated.
void	removeInternalLoadedFeature(java.lang.String name)
boolean	require(java.lang.String requireName)
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.
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

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

jarFiles

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

runtime

protected final Ruby runtime

librarySearcher

protected final org.jruby.runtime.load.LibrarySearcher librarySearcher

builtinLibraries

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

Deprecated.

Constructor Detail

LoadService

public LoadService(Ruby runtime)

Method Detail

init

public void init(java.util.List<java.lang.String> 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

provide

public void provide(java.lang.String shortName,
                    java.lang.String fullName)

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)

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()

removeInternalLoadedFeature

public void removeInternalLoadedFeature(java.lang.String name)

featureAlreadyLoaded

public 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)

buildClassName

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

Deprecated.

checkEmptyLoad

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

Throws:

RaiseException

debugLogTry

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

Deprecated.

debugLogFound

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

Deprecated.

debugLogFound

@Deprecated
protected final void debugLogFound(LoadServiceResource resource)

Deprecated.

findLibraryBySearchState

protected 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)

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

public 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:

resolveLoadName

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

getFileName

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

addBuiltinLibrary

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

Deprecated.

removeBuiltinLibrary

@Deprecated
public void removeBuiltinLibrary(java.lang.String name)

Deprecated.

getBuiltinLibraries

@Deprecated
public java.util.List<java.lang.String> getBuiltinLibraries()

Deprecated.