lucene-pylucene-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From va...@apache.org
Subject svn commit: r935415 - /lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/readme.xml
Date Sun, 18 Apr 2010 21:19:48 GMT
Author: vajda
Date: Sun Apr 18 21:19:47 2010
New Revision: 935415

URL: http://svn.apache.org/viewvc?rev=935415&view=rev
Log:
   - added paragraph about Java generics handling

Modified:
    lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/readme.xml

Modified: lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/readme.xml
URL: http://svn.apache.org/viewvc/lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/readme.xml?rev=935415&r1=935414&r2=935415&view=diff
==============================================================================
--- lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/readme.xml (original)
+++ lucene/pylucene/site/src/documentation/content/xdocs/jcc/documentation/readme.xml Sun
Apr 18 21:19:47 2010
@@ -391,9 +391,9 @@
       <p>
 	Many Java APIs are declared to return types that are less specific
 	than the types actually returned. In Java 1.5, this is worked around
-	with annotations. JCC does not heed annotations at the moment. A
-	Java API declared to return <code>Object</code> will wrap objects as
-	such.
+	with type parameters. JCC generates code to heed type parameters
+	unless the <code>--no-generics</code> is used. See next section for
+	details on Java generics support.
       </p>
       <p>
 	In C++, casting the object into its actual type is supported via the
@@ -415,6 +415,63 @@
         print booleanQuery.getClauses()
       </source>
     </section>
+    <section id="generics">
+      <title>Handling generic classes</title>
+      <p>
+	Java 1.5 added support for parameterized types. JCC generates code
+	to heed type parameters unless the <code>--no-generics</code>
+	command line parameter is used. Java type parameterization is a
+	runtime feature. There is only one class used for all its
+	parameterizations. Similarly, JCC wrapper objects all use the same
+	class but store type parameterizations on instances and make them
+	accessible as a tuple via the <code>parameters_</code> variable.
+      </p>
+      <p>
+	For example, an <code>ArrayList&lt;Document&gt;</code> instance,
+	has <code>(&lt;type 'Document'&gt;,)</code>
+	for <code>parameters_</code> and its <code>get()</code> method uses
+	that type parameter to wrap its return values.
+      </p>
+      <p>
+	To allocate an instance of a generic Java class with specific type
+	parameters use the <code>of_()</code> method. This method accepts
+	one or more Python classes to use as type parameters. For
+	example, <code>java.util.ArrayList&lt;E&gt;</code> is declared to
+	accept one type parameter. Its wrapper's <code>of_()</code>
+	hence accepts one parameter, a Python class, to use as type
+	parameter for the return type of its <code>get()</code> method, among
+	others: 
+      </p>
+      <source>
+	>>> a = ArrayList().of_(Document)
+	>>> a
+        &lt;ArrayList: []&gt;
+	>>> a.parameters_
+	(&lt;type 'Document'&gt;,)
+        >>> a.add(Document())
+        True
+        >>> a.get(0)
+        &lt;Document: Document&lt;&gt;&gt;
+      </source>
+      <p>
+	The use of type parameters is, of course, optional. A generic Java
+	class can still be used as before, without type parameters.
+	Downcasting from <code>Object</code> is then necessary:  
+      </p>
+      <source>
+	>>> a = ArrayList()
+	>>> a
+        &lt;ArrayList: []&gt;
+	>>> a.parameters_
+	(None,)
+        >>> a.add(Document())
+        True
+        >>> a.get(0)
+        &lt;Object: Document&lt;&gt;&gt;
+        >>> Document.cast_(a.get(0))
+        &lt;Document: Document&lt;&gt;&gt;
+      </source>
+    </section>
     <section id="arrays">
       <title>Handling arrays</title>
       <p>



Mime
View raw message