<commit_before>RFC 0074: Support for class loading from class archives in the core
========================================================================
$Id$

@authors: kiesel
@created: Fri Sep 15 10:11:39 CEST 2006
@status: draft
@category: <core>

Scope of Change
---------------
Support for class loading and bootstrap class loading will be 
added to the core.
An application should be contained in a class archive so you only
need to supply lang.base.php and the archive file.

Rationale
---------
Deploying and maintaining an application can currently be done 
in two ways.

Subversion repository
~~~~~~~~~~~~~~~~~~~~~
Checkout the complete XP framework from the Subversion repository 
and updating the tree with Subversion update mechanism.
Tags have been created to achieve software consistency, but that 
also increased maintainance overhead. This approach required a recent 
version of Subversion installed on the system and network 
connectivity to the Subversion server.

Tarball repository
~~~~~~~~~~~~~~~~~~  
Unpacking a tar archive from an XP framework release, creating a
full source code tree in the target directory. While this reduces
software requirements to a "tar" installation, no simple update
mechanism exists.

To simplify shipment of applications written in XP, loading classes
from archives should be supported transparently by the uses() core
method.

Functionality
-------------
uses() will be changed to transparently support loading from class
archives. Support will include bootstrap loading, which means that
it cannot rely on any XP core classes being available at loading time.

The class loading algorithm
~~~~~~~~~~~~~~~~~~~~~~~~~~~
When a class should be loaded, each part of the include_path will be
checked, if it can provide the class to load depending on its own type. 

Directory include_path parts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Include_path parts which reference directories serve as base directory 
and uses() tries to load the class to load it from the file relative to 
the directory.

File include_path parts
~~~~~~~~~~~~~~~~~~~~~~~
Parts that reference files will be treated as class archives. Uses()
scrutinizes whether the archive provides the class and loads it from
there if it can.
If the file is no class archive, a fatal error will be raised.

If one part cannot provide a class, the next include_path part is being
checked. If all parts were unable to provide the class, a fatal error
is raised.

ClassLoaders
~~~~~~~~~~~~
A class which has been loaded by an ArchiveClassLoader will be associated
with the loading classloader by the mechanism described in rfc://0071.

Loading resources
~~~~~~~~~~~~~~~~~
Whenever a class loads other files "from the filesystem", relative to its
own location, it must use its associated classloader to fetch it. Ignoring
this rule cannot be detected but will lead to breakage of the class when
used after being loaded out of an archive.

The deprecated resource loading mechanism is:
<code>
  // Package net.xp_framework.rfc
  class Foo extends Object {
    function __construct() {
      $file= &new File(dirname(__FILE__).'/META-INF/mysettings.ini');
      $file->open(...);
      // ...
    }
  }
</code>

The new resource loading mechanism is:
<code>
  // Package net.xp_framework.rfc
  class Foo extends Object {
    function __construct() {
      $class= &$this->getClass();
      $cl= &$class->getClassLoader();
      
      // Resource path must reflect package name to conform with above
      // example
      $bytes= $cl->loadResource('net/xp_framework/rfc/META-INF/mysettings.ini');
      // ...
    }
  }
</code>


Security considerations
-----------------------
n/a

Speed impact
------------

Speed loss
~~~~~~~~~~
Class archives start with a header which contains metadata information 
about all contained files. As the header must be fully read to acquire
information about the archive, and the header size grows for each added
file, big archives will be slower than small archives.

Speed gain
~~~~~~~~~~
As the archive file only needs to be opened once, some fstat() system calls
will vanish, speeding up the loading process as a trade-off for the initially
mentioned speed loss.

[ TBD: Add benchmarks ]

Dependencies
------------
n/a

Related documents
-----------------

Comments
--------

<EOF>
<commit_msg>- add comment about archive filename extensions<commit_after>RFC 0074: Support for class loading from class archives in the core
========================================================================
$Id$

@authors: kiesel
@created: Fri Sep 15 10:11:39 CEST 2006
@status: draft
@category: <core>

Scope of Change
---------------
Support for class loading and bootstrap class loading will be 
added to the core.
An application should be contained in a class archive so you only
need to supply lang.base.php and the archive file.

Rationale
---------
Deploying and maintaining an application can currently be done 
in two ways.

Subversion repository
~~~~~~~~~~~~~~~~~~~~~
Checkout the complete XP framework from the Subversion repository 
and updating the tree with Subversion update mechanism.
Tags have been created to achieve software consistency, but that 
also increased maintainance overhead. This approach required a recent 
version of Subversion installed on the system and network 
connectivity to the Subversion server.

Tarball repository
~~~~~~~~~~~~~~~~~~  
Unpacking a tar archive from an XP framework release, creating a
full source code tree in the target directory. While this reduces
software requirements to a "tar" installation, no simple update
mechanism exists.

To simplify shipment of applications written in XP, loading classes
from archives should be supported transparently by the uses() core
method.

Functionality
-------------
uses() will be changed to transparently support loading from class
archives. Support will include bootstrap loading, which means that
it cannot rely on any XP core classes being available at loading time.

The class loading algorithm
~~~~~~~~~~~~~~~~~~~~~~~~~~~
When a class should be loaded, each part of the include_path will be
checked, if it can provide the class to load depending on its own type. 

Directory include_path parts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Include_path parts which reference directories serve as base directory 
and uses() tries to load the class to load it from the file relative to 
the directory.

File include_path parts
~~~~~~~~~~~~~~~~~~~~~~~
Parts that reference files will be treated as class archives. Uses()
scrutinizes whether the archive provides the class and loads it from
there if it can.
If the file is no class archive, a fatal error will be raised.

If one part cannot provide a class, the next include_path part is being
checked. If all parts were unable to provide the class, a fatal error
is raised.

ClassLoaders
~~~~~~~~~~~~
A class which has been loaded by an ArchiveClassLoader will be associated
with the loading classloader by the mechanism described in rfc://0071.

Loading resources
~~~~~~~~~~~~~~~~~
Whenever a class loads other files "from the filesystem", relative to its
own location, it must use its associated classloader to fetch it. Ignoring
this rule cannot be detected but will lead to breakage of the class when
used after being loaded out of an archive.

The deprecated resource loading mechanism is:
<code>
  // Package net.xp_framework.rfc
  class Foo extends Object {
    function __construct() {
      $file= &new File(dirname(__FILE__).'/META-INF/mysettings.ini');
      $file->open(...);
      // ...
    }
  }
</code>

The new resource loading mechanism is:
<code>
  // Package net.xp_framework.rfc
  class Foo extends Object {
    function __construct() {
      $class= &$this->getClass();
      $cl= &$class->getClassLoader();
      
      // Resource path must reflect the package name to conform with
      // above example
      $bytes= $cl->loadResource('net/xp_framework/rfc/META-INF/mysettings.ini');
      // ...
    }
  }
</code>


Security considerations
-----------------------
n/a

Speed impact
------------

Speed loss
~~~~~~~~~~
Class archives start with a header which contains metadata information 
about all contained files. As the header must be fully read to acquire
information about the archive, and the header size grows for each added
file, big archives will be slower than small archives.

Speed gain
~~~~~~~~~~
As the archive file only needs to be opened once, some fstat() system calls
will vanish, speeding up the loading process as a trade-off for the initially
mentioned speed loss.

[ TBD: Add benchmarks ]

Dependencies
------------
n/a

Related documents
-----------------

Comments
--------
- kiesel, Tue Sep 19 11:53:28 CEST 2006
  Currently, the classloader distinguished only between directories in the
  path and files in the path. Files will be treated as archives. To keep the
  option to have multiple different file formats later, we need to agree on
  a "standard" XP archive filename extension. There are several proposals:
    . .cca (as the package name)
    . .xar (XP archive)
    . .xpa (XP archive, proposed by George Aprozeanu)
    . .xpm (XP module, proposed by <NAME>)
    . .xpar (XP Archive)

<EOF>

{'fraction_non_alphanumeric': 0.12046491418640018, 'fraction_numerical': 0.005648490115142298, 'mean_word_length': 3.72396100564392, 'pattern_counts': {'":': 0, '<': 16, '<?xml version=': 0, '>': 24, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7414010', 'n_tokens_mistral': 2339, 'n_tokens_neox': 2197, 'n_words': 1217}