<?xml version="1.0"?>
<!--
    * Licensed to the Apache Software Foundation (ASF) under one
    * or more contributor license agreements.  See the NOTICE file
    * distributed with this work for additional information
    * regarding copyright ownership.  The ASF licenses this file
    * to you under the Apache License, Version 2.0 (the
    * "License"); you may not use this file except in compliance
    * with the License.  You may obtain a copy of the License at
    *
    *   http://www.apache.org/licenses/LICENSE-2.0
    *
    * Unless required by applicable law or agreed to in writing,
    * software distributed under the License is distributed on an
    * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    * KIND, either express or implied.  See the License for the
    * specific language governing permissions and limitations
    * under the License.
-->
<document>
  <properties>
    <title>Application areas</title>
  </properties>

  <body>
    <section name="Application areas">
      <p>
        There are many possible application areas for <font
              face="helvetica,arial">BCEL</font> ranging from class
        browsers, profilers, byte code optimizers, and compilers to
        sophisticated run-time analysis tools and extensions to the Java
        language.
      </p>

      <p>
        Compilers like the <a
              href="https://barat.sourceforge.net">Barat</a> compiler use <font
              face="helvetica,arial">BCEL</font> to implement a byte code
        generating back end. Other possible application areas are the
        static analysis of byte code or examining the run-time behavior of
        classes by inserting calls to profiling methods into the
        code. Further examples are extending Java with Eiffel-like
        assertions, automated delegation, or with the concepts of <a
              href="https://www.eclipse.org/aspectj/">Aspect-Oriented Programming</a>.<br/> A
        list of projects using <font face="helvetica,arial">BCEL</font> can
        be found <a href="../projects.html">here</a>.
      </p>

    <subsection name="Class loaders">
      <p>
        Class loaders are responsible for loading class files from the
        file system or other resources and passing the byte code to the
        Virtual Machine. A custom <tt>ClassLoader</tt> object may be used
        to intercept the standard procedure of loading a class, i.e.m  the
        system class loader, and perform some transformations before
        actually passing the byte code to the JVM.
      </p>

      <p>
        A  possible  scenario is  described  in <a href="#Figure 7">figure
        7</a>:
        During run-time the Virtual Machine requests a custom class loader
        to load a given class. But before the JVM actually sees the byte
        code, the class loader makes a "side-step" and performs some
        transformation to the class. To make sure that the modified byte
        code is still valid and does not violate any of the JVM's rules it
        is checked by the verifier before the JVM finally executes it.
      </p>

      <p align="center">
        <a name="Figure 7">
          <img src="../images/classloader.gif"/>
          <br/>
          Figure 7: Class loaders
        </a>
      </p>

      <p>
        Using class loaders is an elegant way of extending the Java
        Virtual Machine with new features without actually modifying it.
        This concept enables developers to use <em>load-time
        reflection</em> to implement their ideas as opposed to the static
        reflection supported by the <a
              href="https://docs.oracle.com/javase/8/docs/technotes/guides/reflection/index.html">Java
        Reflection API</a>. Load-time transformations supply the user with
        a new level of abstraction. They are not strictly tied to the static
        constraints of the original authors of the classes but may
        customize the applications with third-party code in order to
        benefit from new features. Such transformations may be executed on
        demand and neither interfere with other users, nor alter the
        original byte code. In fact, class loaders may even create classes
        <em>ad hoc</em> without loading a file at all.<br/> <font
              face="helvetica,arial">BCEL</font> has already builtin support for
        dynamically creating classes, an example is the ProxyCreator class.
      </p>

    </subsection>

    <subsection name="Example: Poor Man's Genericity">
      <p>
        The former "Poor Man's Genericity" project that extended Java with
        parameterized classes, for example, used <font
              face="helvetica,arial">BCEL</font> in two places to generate
        instances of parameterized classes: During compile-time (with the
        standard <tt>javac</tt> with some slightly changed classes) and at
        run-time using a custom class loader. The compiler puts some
        additional type information into class files (attributes) which is
        evaluated at load-time by the class loader. The class loader
        performs some transformations on the loaded class and passes them
        to the VM. The following algorithm illustrates how the load method
        of the class loader fulfills the request for a parameterized
        class, e.g., <tt>Stack&lt;String&gt;</tt>
      </p>

      <p>
        <ol type="1">
          <li> Search for class <tt>Stack</tt>, load it, and check for a
            certain class attribute containing additional type
            information. I.e.  the attribute defines the "real" name of the
            class, i.e., <tt>Stack&lt;A&gt;</tt>.</li>

          <li>Replace all occurrences and references to the formal type
            <tt>A</tt> with references to the actual type <tt>String</tt>. For
            example the method
          </li>

          <source>
            void push(A obj) { ... }
          </source>

          <p>
            becomes
          </p>

          <source>
            void push(String obj) { ... }
          </source>

          <li> Return the resulting class to the Virtual Machine.</li>
        </ol>
      </p>

    </subsection>
    </section>
  </body>
</document>
