xp-framework/rfc — Issue #121: Class loading revamp
Author: thekid
Created: 2011-10-17 15:56:32+00:00
State: closed
Labels: framework, implemented

Scope of Change
====
- There will be one ClassLoader for each element in the include path.
- Every class will have a classloader associated with it.
- The deprecated overloaded variant of ClassLoader::defineClass() will
be removed.
- uses() wrappers will be removed.

Rationale
====
- Consistent API
- Makes xp-framework/rfc #37 possible (fully qualified class names)
- Makes xp-framework/rfc #117 possible (package reflection)

Functionality
====

Overview
----
Consider the following include_path (wrapped for better readability)

```
.;
C:\cygwin\home\thekid\devel\xp\trunk\skeleton;
C:\cygwin\home\thekid\lib\xp-com.a9-5.4.1.xar

```
This will now create three different classloader instances:

* FileSystemClassLoader (.)
* FileSystemClassLoader (C:\cygwin\home\thekid\devel\xp\trunk\skeleton)
* ArchiveClassLoader (C:\cygwin\home\thekid\lib\xp-com.a9-5.4.1.xar)

The default classloader, which can be retrieved by invoking

```php

```
can be asked for a class by using its loadClass() method. This method
will ask all registered classloaders (see list from above) for the class
and will load it from the first class loader whose providesClass() method
returns TRUE.

uses()
----
The uses() function will use the default classloader instead of re-providing
the class loading functionality itself. One exception is the bootstrapping
process: Here, a minimalistic version is used. This version differs from the
rest of the classloading source in the following:

* It will bail when classes cannot be found
* It only supports loading from filesystem and xar archives

Bootstrapping
----
The bootstrapping process starts after lang.base.php has been processed
and the core classes are loaded. The core classes are the following:

```
lang.Generic
lang.Object
lang.StackTraceElement
lang.Throwable
lang.Error
lang.XPException
lang.Type
lang.reflect.Argument
lang.reflect.Routine
lang.reflect.Method
lang.reflect.Field
lang.reflect.Constructor
lang.reflect.Modifiers
lang.reflect.Package
lang.XPClass
lang.NullPointerException
lang.IllegalAccessException
lang.IllegalArgumentException
lang.IllegalStateException
lang.FormatException
lang.ClassNotFoundException
lang.IClassLoader
lang.FileSystemClassLoader
lang.DynamicClassLoader
lang.archive.ArchiveReader
lang.archive.ArchiveClassLoader
lang.ClassLoader

```
During the bootstrap process, classes are loaded by xp::loadClass0().
After that, the lang.ClassLoader (delegating to the registered loaders
as described above) takes over control by registering loaders as follows:

```php

```
Note: From that point on, uses() will no longer bail but throw
lang.ClassNotFoundExceptions.

include_path
----
PHP's include_path setting is parsed once at startup and is available in
xp::$registry['classpath'] from that point on. Changes to the include_path
occuring later on are not considered.

If your are using sourcecode to add to the include_path by manipulating
the ini setting via ini_set() or set_include_path(), you need to refactor
that as follows:

```php

```

uses() wrappers
----
The syntactical additions to the uses() function described in xp-framework/rfc #22
will be deprecated with this RFC. The problem with them are that where
a class is loaded from is hardcoded in the sourcecode rather than made
"configurable" via the include_path setting or exchangeable at runtime
by registering new classloaders.

```
TODO: Replacement example

```

Dynamically created classes
----
Previously, dynamically created classes did not have a classloader.
Classes created by ClassLoader::getDefault()->defineClass() and by
newinstance() now have a classloader, lang.DynamicClassLoader.

Security considerations
====
n/a

Speed impact
====
A bit faster, slightly increased memory usage.

Dependencies
====
Note:

```
This will bump the minor version number (-> 5.5.0)

```
- uses() wrappers deprecation
- defineClass() old api deprecation

Related documents
====
- http://experiments.xp-framework.net/?arena,classloaders
The new classloading API

- http://xp-framework.info/xml/xp.en_US/news/view?174
XP Blog: "Different XP framework classloading implementations compared"