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
static class	LoadService.LoadPathMethods
static class	LoadService.SuffixType

Field Summary

Fields

Modifier and Type	Field and Description
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	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
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(RubyString requireName)
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(java.lang.String baseName, java.lang.String loadName, LoadServiceResource resource)
protected void	debugLogFound(LoadServiceResource resource)
protected void	debugLogFound(java.lang.String what, java.lang.String msg)
protected void	debugLogTry(java.lang.String what, java.lang.String msg)
boolean	featureAlreadyLoaded(java.lang.String feature)
boolean	featureAlreadyLoaded(java.lang.String feature, java.lang.String[] loading)
protected LoadServiceResource	findFileInClasspath(java.lang.String name) this method uses the appropriate lookup strategy to find a file.
protected LibrarySearcher.FoundLibrary	findLibraryWithClassloaders(java.lang.String baseName, LoadService.SuffixType suffixType)
LoadServiceResource	getClassPathResource(java.lang.ClassLoader classLoader, java.lang.String name)
IRubyObject	getLoadedFeatures()
IRubyObject	getLoadPath()
protected java.lang.String	getLoadPathEntry(IRubyObject entry)
RubyModule	getWrapperSelf()
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	isJarfileLibrary(Library library, java.lang.String file)
protected static boolean	isRequireable(java.net.URL loc)
void	load(java.lang.String file, boolean wrap)
void	load(java.lang.String file, IRubyObject wrapWith)
void	loadFromClassLoader(java.lang.ClassLoader classLoader, java.lang.String file, boolean wrap)
void	provide(java.lang.String name)
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.
boolean	require(java.lang.String requireName)
protected java.lang.String	resolveLoadName(LoadServiceResource foundResource, java.lang.String previousPath)
protected LibrarySearcher.FoundLibrary	searchForLoad(java.lang.String file) Replaces findLibraryBySearchState but split off for load.
char	searchForRequire(java.lang.String file, LibrarySearcher.FoundLibrary[] path) Replaces findLibraryBySearchState but split off for require.
protected boolean	tryLoadingLibraryOrScript(Ruby runtime, Library library, java.lang.String searchFile)
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

jarFiles

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

runtime

protected final Ruby runtime

librarySearcher

protected LibrarySearcher librarySearcher

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

addPath

protected void addPath(java.lang.String path)

getWrapperSelf

public RubyModule getWrapperSelf()

load

public void load(java.lang.String file,
                 IRubyObject wrapWith)

load

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

loadFromClassLoader

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

require

public boolean require(java.lang.String requireName)

autoloadRequire

public boolean autoloadRequire(RubyString requireName)

warnCircularRequire

protected void warnCircularRequire(java.lang.String requireName)

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

isJarfileLibrary

protected boolean isJarfileLibrary(Library library,
                                   java.lang.String file)

tryLoadingLibraryOrScript

protected boolean tryLoadingLibraryOrScript(Ruby runtime,
                                            Library library,
                                            java.lang.String searchFile)

checkEmptyLoad

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

Throws:

RaiseException

debugLogTry

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

debugLogFound

protected final void debugLogFound(LoadServiceResource resource)

debugLogFound

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

searchForRequire

public char searchForRequire(java.lang.String file,
                             LibrarySearcher.FoundLibrary[] path)

Replaces findLibraryBySearchState but split off for require. Needed for OSGiLoadService to override.

searchForLoad

protected LibrarySearcher.FoundLibrary searchForLoad(java.lang.String file)

Replaces findLibraryBySearchState but split off for load. Needed for OSGiLoadService to override.

featureAlreadyLoaded

public boolean featureAlreadyLoaded(java.lang.String feature)

featureAlreadyLoaded

public boolean featureAlreadyLoaded(java.lang.String feature,
                                    java.lang.String[] loading)

findLibraryWithClassloaders

protected LibrarySearcher.FoundLibrary findLibraryWithClassloaders(java.lang.String baseName,
                                                                   LoadService.SuffixType suffixType)

createLibrary

protected Library createLibrary(java.lang.String baseName,
                                java.lang.String loadName,
                                LoadServiceResource resource)

getLoadPathEntry

protected java.lang.String getLoadPathEntry(IRubyObject entry)

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.

MRI: rb_find_file

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)