Sophie: jace-1.1.1-6.mga5 noarch

jace-1.1.1-6.mga5.noarch.rpm


<html>

  <title> Jace Developer's Guide - Peer Classes </title>

  <body>
    <font face="Verdana" size="-1">

    <table width="100%">
      <tr>
        <td bgcolor="#EEEEEE" align="right">
          <font size="+2">
            <b>Chapter 4</b>
          </font>
        </td>
      </tr>
      <tr>
        <td align="right"> 
          <font size="+2">
            <b>Peer Classes</b>
          </font>
        </td>
      </tr>
    </table>

    <br><br>


    <table bgcolor="#EEEEEE" width="100%"> <tr> <td> Peer To Peer </td> </tr> </table>

    <p>
    Jace's C++ Peers are the yin to Jace's C++ Proxies' yang. Whereas the purpose of a C++ Proxy is to provide developers with easy access to a matching Java class from C++, the purpose of a C++ Peer is to provide developers with the capability to easily implement the native methods of a matching Java class.
    </p>
    
    <p>
    As an example of Peers, consider the Java AWT Peer classes (Frame, Button, Choice, List, etc...). Each of these Peer classes has a corresponding native Peer class. When the Java Peer class is instantiated, it also instantiates the native Peer. When a native method is called on the Java Peer, the method call is passed onto the native Peer. When the Java Peer is destroyed (through a call to dispose() or a similar deallocation method), the native Peer is also destroyed.
    </p>
    
    <p>
    Rather then delve deeply into the well known design pattern of Peer classes, I highly suggest that if you're not yet familiar with them, you read Section 9 of <a href="http://java.sun.com/docs/books/jni/index.html">The Java Native Interface</a>. <a href="http://developer.java.sun.com/developer/JDCTechTips/2001/tt0612.html#tip2">This JDC tech tip</a> is also a good tutorial on Peer classes.
    </p>

    With that background out of the way, I can now explain how Jace makes it easy to implement Peer classes. You just follow this simple recipe:
    
    <ol>
      <li> Write your Java Peer class as you normally would any other class. Make sure the methods that you want to implement in your native Peer are declared as native in your Java Peer. <br><br> </li>

      <li> Use the tool, PeerEnhancer, to enhance your Java Peer class to include all of the boilerplate Java Peer code you'd normally have to write by hand. The PeerEnhancer works by using <a href="http://jakarta.apache.org/bcel/index.html">BCEL</a> to enhance the bytecode of your Java Peer class file to include new code, methods, and data. Once your Java Peer class has been enhanced, it will do several new things: <br><br>

        <ul>
          <li> Load your native shared library upon class initialization of the Java Peer. <br><br> </li>
          <li> Create and store a matching native Peer when the Java Peer is constructed. <br><br> </li>
          <li> Destroy the matching native Peer when the Java Peer is garbage collected or when its deallocation method is called. <br><br> </li>
        </ul>

      </li>

      <li> Use the tool, PeerGenerator to generate the boilerplate native Peer code for you.
           The PeerGenerator will generate several files: <br><br>

        <ul>
          <li> A C++ header file which contains the declaration of your native C++ Peer class. This class contains the declarations for all of the Java Peer's fields and methods. <br><br> </li>
          <li> A C++ source file which contains the Jace implementation of all of the fields and methods declared in the C++ header file - except for the native methods. You will implement the native methods with your own code, and you have easy access to all of the Java Peer's fields and methods. <br><br> </li>
          <li> A C++ source file which contains all of the code required to map between the JNI native method calls and calls to the C++ Peer class. This is how calls from the JVM get translated to calls on your native C++ Peer. <br><br> </li>
        </ul>

      </li>

      <li> Implement the native methods declared in the C++ Peer header. It's trivial to implement these methods, because they are declared totally in terms of C++ Proxy classes. Both the arguments and the return value are C++ Proxy classes. You can even throw C++ proxy exceptions, which Jace will catch and rethrow to the JVM as real Java exceptions. <br><br> </li>

      <li> Use the tool, AutoProxy to generate the necessary C++ Proxy classes. It will automatically generate all C++ Proxy classes that are required to implement your native Peer. <br><br> </li>

      <li> You're all done. Compile your code and take it for a spin. <br><br> </li>

    </ol>

    <br><br>

    <table width="100%">
      <tr>
        <td align="right">
          <a href="guide3.html">Previous</a>
          <a href="guide5.html">Next</a>
        </td>
      </tr>
    </table>

    <br><br>

  <br><br>
  <br><br>
  <br><br>
  <br><br>
  <br><br>
  <br><br>
  <br><br>
  <br><br>

    </font>

  </body>
</html>