[Jpeergen-cvs] web-site documentation.html,1.1,1.2 index.html,1.2,1.3 overview.html,1.1,1.2
Status: Beta
Brought to you by:
pspeed
Menu
▾
▴
[Jpeergen-cvs] web-site documentation.html,1.1,1.2 index.html,1.2,1.3 overview.html,1.1,1.2
|
From: <ps...@us...> - 2004-08-16 06:43:26
|
Update of /cvsroot/jpeergen/web-site In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv9585 Modified Files: documentation.html index.html overview.html Log Message: Added content to the documentation page. A few other tweaks here and there. Index: documentation.html =================================================================== RCS file: /cvsroot/jpeergen/web-site/documentation.html,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** documentation.html 16 Aug 2004 05:02:54 -0000 1.1 --- documentation.html 16 Aug 2004 06:43:16 -0000 1.2 *************** *** 23,32 **** <h1>Documentation</h1> ! <p>Under construction</p> <h3>Java Class Considerations</h3> <h3>Running the doclet</h3> <br><br><br> <hr> --- 23,222 ---- <h1>Documentation</h1> ! <p>In order to generate the C++ code for a Java object the class must ! meet a few simple requirements. After that, JPeerGen can be run as a javadoc ! doclet from the command line or within an ANT build script.</p> ! ! <p>Table of contents:</p> ! <ul> ! <li>Java Class Considerations</li> ! <ul> ! <li>The <code>peer</code> attribute ! <li>The <code>peer.return.jni</code> attribute ! </ul> ! <li>Running the doclet</li> ! <ul> ! <li>Doclet options ! </ul> ! <li>Running the doclet in ANT</li> ! </ul> <h3>Java Class Considerations</h3> + <p>There are two "modes" under which a class can be peered: fully peered + and staticly peered. A fully peered class is one that has a related C++ + instance for every Java instance. These instances can then interact back + and forth. A staticly peered class is one where the Java class only has + static native methods and/or the C++ class only needs to call static peered + methods on the Java class.</p> + + <h4>The <code>peer</code> attribute</h4> + + <p>In order to facilitate the relationship between a fully peered object + and its C++ counterpart, the Java class is required to implement a peer + attribute.</p> + + <code>private long peer;</code> + + <p>The binding code will store the pointer to the C++ instance in this + attribute and use it for later peer lookups. It is important that the + java code not modify this value in any way.</p> + + <p>This is only required if full peering is desired. Classes that only + have static native or peered methods need not have this attribute.</p> + + <h4>The <code>@peered</code> javadoc tag</h4> + + <p>The <code>@peered</code> javadoc tag is used to designate reverse + peering. Any method with this tag defined in its javadoc will have + bindings generated for it that make the method easier to call from C++ + code.</p> + + <p>Example method declaration:</p> + <code><pre> + public class MyObject { + private long peer; + + /** + * Method for doing something on this object. + * @peered + */ + public int doSomething( String s ) { + // Do something with s + } + } + </pre></code> + + <p>This will cause a C++ binding to be generated with the following + signature:</p> + + <code><pre> + int MyObject::doSomething( std:string s ); + </pre></code> + + <p>Native code can then call that method directly without worrying about + the raw JNI details or string conversion issues, etc..</p> + + <h4>The <code>@peered.return.jni</code> javadoc tag</h4> + + <p>This is an alternate way to designate reverse peering that specifies + that the return type should not be converted. By default, if a Java method + returns an instance of the Java class as a return value then the C++ binding + will automatically convert that value.</p> + + <p>In some cases, this is not desirable. For example, the native code + may need to work directly with the JNI jobject value. Another case is when + the class isn't fully peered. The current version of JPeerGen will attempt + to generate a conversion even though the peer lookup will fail.</p> + + <p>Example method declaration:</p> + <code><pre> + public class MyObject { + + /** + * Method for doing something on this object. + * @peered.return.jni + */ + public static MyObject doSomething( String s ) { + // Do something with s + } + } + </pre></code> + + <p>This will cause a C++ binding to be generated with the following + signature:</p> + + <code><pre> + static jobject MyObject::doSomething( std:string s ); + </pre></code> + + <p>It is then up to the native code to deal with the jobject value directly.</p> + <h3>Running the doclet</h3> + <p>JPeerGen needs to be run as a doclet from within javadoc. Following is + an example of running the JPeerGen doclet:</p> + + <code><pre> + javadoc -private -doclet org.progeeks.jni.PeerDoclet src\foo\MyObject.java + </pre></code> + + <p>The above will generate the various C++ files needed to peer the MyObject + class and place them into the current directory.</p> + + <p>Source file lists can be specified in all of the usual javadoc ways and all + of the non-doclet-specific options on javadoc can be brought to use to specify + the doclet classpath, etc.. More on this topic can be read in the javadoc + documentation.</p> + + <p>Note: it is a good idea to only pass classes to javadoc that actually have + some form of peering required. JPeerGen will do its best to determine whether + or not an object should be peered, but passing the whole source tree can cause + problems if there are Java classes that have native methods that JPeerGen should + not be dealing with.</p> + + <h4>Doclet Options</h4> + <p>The JPeerGen doclet defines several options the can be used to customize + output. These are as follows:</p> + + <table border="1"> + <tr> + <td><b>Option</b></td> + <td><b>Description</b></td> + </tr> + <tr> + <td>-d <directory></td> + <td>Sets the destination directory for all generated files.<br><br> + <b>Example:</b> + <code><pre>javadoc -private -doclet org.progeeks.jni.PeerDoclet <b>-d src/jni</b> src\foo\MyObject.java</pre></code> + Causes generated C++ files to go into the src/jni sub-directory. + </td> + </tr> + <tr> + <td>-overwrite</td> + <td>Causes files that would normally not be overwritten to be overwritten. + <br><font color="red">Use this option with caution since it will wipe out any + customizations done to the C++ code.</font></td> + </tr> + <tr> + <td>-save</td> + <td>Instead of skipping files that would overwrite a user-modifiable file, + this option causes the file to be created with the .new extension.<br><br> + </td> + </tr> + <tr> + <td>-exclude <comma separated class list></td> + <td>Sets a list of classes to exclude from generation. The value is a comma + separated list of fully qualified class names.<br><br> + <b>Example:</b> + <code><pre>javadoc -private -doclet org.progeeks.jni.PeerDoclet <b>-exclude foo.MyOtherObject</b> src\foo\*.java</pre></code> + Causes all classes in the foo package to be passed through JPeerGen except + for the foo.MyOtherObject class. + </td> + </tr> + </table> + + + <h3>Running the doclet in ANT</h3> + + <p>Following is a simple example of running the JPeerGen doclet within + an ANT build file using ANT's built-in "javadoc" task:</p> + + <code><pre> + <javadoc private="true" sourcepath="src/java" + sourcefiles="foo/MyObject.java,foo/MyOtherObject.java" > + <doclet name="org.progeeks.jni.PeerDoclet" > + <param name="-d" value="src/jni" /> + <param name="-save" /> + </doclet> + </javadoc> + </pre></code> + + <p>The above task definition will generate any necessary C++ peer files + for the classes foo.MyObject and foo.MyOtherObject located in the + src/java directory. The generated files will be put into src/jni. + If any existing user-modifiable files already exist, new versions will + be generated with the .new extension tacked on.</p> + + <br><br><br> <hr> Index: index.html =================================================================== RCS file: /cvsroot/jpeergen/web-site/index.html,v retrieving revision 1.2 retrieving revision 1.3 diff -C2 -d -r1.2 -r1.3 *** index.html 16 Aug 2004 05:02:54 -0000 1.2 --- index.html 16 Aug 2004 06:43:16 -0000 1.3 *************** *** 20,24 **** </td><td><image src="images/Blank.gif" height="1" width="10" /></td><td> ! <image src="images/JPeerGen-Logo.png" /> <p>Helping bridge the Java->C++ gap.</p> --- 20,24 ---- </td><td><image src="images/Blank.gif" height="1" width="10" /></td><td> ! <a href="http://jpeergen.sf.net/"><image src="images/JPeerGen-Logo.png" border="0" /></a> <p>Helping bridge the Java->C++ gap.</p> Index: overview.html =================================================================== RCS file: /cvsroot/jpeergen/web-site/overview.html,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** overview.html 16 Aug 2004 05:02:54 -0000 1.1 --- overview.html 16 Aug 2004 06:43:16 -0000 1.2 *************** *** 92,95 **** --- 92,126 ---- </table> + <h3>Best Usage Patterns</h3> + + <p>It is important to note that the binding interaction is not free. In addition to the + normal JNI overhead, JPeerGen adds some casting and one or two extra calls in the + chain. Furthermore, a current limitation of the system is that C++ objects are not + cleaned up properly when the Java object is garbage collected. (Though, users can + implement this manually with a native terminate method.)<p> + + <p>This means that JPeerGen is best used in coarse-grained situations like native + services or other facade-like objects. These are both long-lived and usually do + enough work on their own to justify the small bits of call overhead that are added.</p> + + <h3>Future Improvements</h3> + + <p>On the books is better handling for array types and the ability for cross-peered + objects to be automatically converted.</p> + + <p>Currently, the generator can only pass array types down as jobjects. This is + something I'd like to add despite the overhead the array copying would cause. It's + just to convenient to ignore.</p> + + <p>Also, right now the only peered object that can be auto-converted is the one + for which the generator is currently running. So if a native method on MyObject + takes a MyObject instance as a parameter, it will be automitcally converted to + the MyObjectPeer on the C++ side. However, if a native method on MyObject takes + a MyOtherObject instance as a parameter, it will not be converted even if + MyOtherObject is also a peered object. JPeerGen already knows about all of the + classes that were passed to the doclet, so this should be a trivial enough change. However, the + type conversion code needs a major refactoring first so this will have to wait for + the 2.0 cycle.</p> + <br><br><br> <hr> |
