doc/jcc/documentation/readme.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <head>
   4 <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <meta content="Apache Forrest" name="Generator">
   6 <meta name="Forrest-version" content="0.8">
   7 <meta name="Forrest-skin-name" content="pelt">
   8 <title>JCC Features</title>
   9 <link type="text/css" href="../../skin/basic.css" rel="stylesheet">
  10 <link media="screen" type="text/css" href="../../skin/screen.css" rel="stylesheet">
  11 <link media="print" type="text/css" href="../../skin/print.css" rel="stylesheet">
  12 <link type="text/css" href="../../skin/profile.css" rel="stylesheet">
  13 <script src="../../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../../skin/fontsize.js" language="javascript" type="text/javascript"></script>
  14 <link rel="shortcut icon" href="../../">
  15 </head>
  16 <body onload="init()">
  17 <script type="text/javascript">ndeSetTextSize();</script>
  18 <div id="top">
  19 <!--+
  20     |breadtrail
  21     +-->
  22 <div class="breadtrail">
  23 <a href="http://www.apache.org/">apache</a> &gt; <a href="http://lucene.apache.org/">lucene</a><script src="../../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
  24 </div>
  25 <!--+
  26     |header
  27     +-->
  28 <div class="header">
  29 <!--+
  30     |start group logo
  31     +-->
  32 <div class="grouplogo">
  33 <a href="http://lucene.apache.org/"><img class="logoImage" alt="Lucene" src="../../images/lucene_green_150.gif" title="Lucene Description"></a>
  34 </div>
  35 <!--+
  36     |end group logo
  37     +-->
  38 <!--+
  39     |start Project Logo
  40     +-->
  41 <div class="projectlogoA1">
  42 <a href="http://lucene.apache.org/pylucene/"><img class="logoImage" alt="PyLucene" src="../../images/project.png" title="PyLucene Description"></a>
  43 </div>
  44 <!--+
  45     |end Project Logo
  46     +-->
  47 <!--+
  48     |start Tabs
  49     +-->
  50 <ul id="tabs">
  51 <li>
  52 <a class="unselected" href="../../index.html">PyLucene</a>
  53 </li>
  54 <li class="current">
  55 <a class="selected" href="../../jcc/index.html">JCC</a>
  56 </li>
  57 </ul>
  58 <!--+
  59     |end Tabs
  60     +-->
  61 </div>
  62 </div>
  63 <div id="main">
  64 <div id="publishedStrip">
  65 <!--+
  66     |start Subtabs
  67     +-->
  68 <div id="level2tabs"></div>
  69 <!--+
  70     |end Endtabs
  71     +-->
  72 <script type="text/javascript"><!--
  73 document.write("Last Published: " + document.lastModified);
  74 //  --></script>
  75 </div>
  76 <!--+
  77     |breadtrail
  78     +-->
  79 <div class="breadtrail">
  80
  81              &nbsp;
  82            </div>
  83 <!--+
  84     |start Menu, mainarea
  85     +-->
  86 <!--+
  87     |start Menu
  88     +-->
  89 <div id="menu">
  90 <div onclick="SwitchMenu('menu_selected_1.1', '../../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../../skin/images/chapter_open.gif');">JCC</div>
  91 <div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
  92 <div onclick="SwitchMenu('menu_1.1.1', '../../skin/')" id="menu_1.1.1Title" class="menutitle">About</div>
  93 <div id="menu_1.1.1" class="menuitemgroup">
  94 <div class="menuitem">
  95 <a href="../../jcc/index.html" title="Welcome to JCC">Index</a>
  96 </div>
  97 </div>
  98 <div onclick="SwitchMenu('menu_selected_1.1.2', '../../skin/')" id="menu_selected_1.1.2Title" class="menutitle" style="background-image: url('../../skin/images/chapter_open.gif');">Documentation</div>
  99 <div id="menu_selected_1.1.2" class="selectedmenuitemgroup" style="display: block;">
 100 <div class="menuitem">
 101 <a href="../../jcc/documentation/install.html">Installation</a>
 102 </div>
 103 <div class="menupage">
 104 <div class="menupagetitle">Features</div>
 105 </div>
 106 <div class="menuitem">
 107 <a href="../../jcc/documentation/javadoc/index.html">Javadoc</a>
 108 </div>
 109 </div>
 110 </div>
 111 <div id="credit"></div>
 112 <div id="roundbottom">
 113 <img style="display: none" class="corner" height="15" width="15" alt="" src="../../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
 114 <!--+
 115   |alternative credits
 116   +-->
 117 <div id="credit2"></div>
 118 </div>
 119 <!--+
 120     |end Menu
 121     +-->
 122 <!--+
 123     |start content
 124     +-->
 125 <div id="content">
 126 <div title="Portable Document Format" class="pdflink">
 127 <a class="dida" href="readme.pdf"><img alt="PDF -icon" src="../../skin/images/pdfdoc.gif" class="skin"><br>
 128         PDF</a>
 129 </div>
 130 <h1>JCC Features</h1>
 131 <div id="minitoc-area">
 132 <ul class="minitoc">
 133 <li>
 134 <a href="#install">Installing JCC</a>
 135 </li>
 136 <li>
 137 <a href="#invoking">Invoking JCC</a>
 138 </li>
 139 <li>
 140 <a href="#use">Generating C++ and Python wrappers with JCC</a>
 141 </li>
 142 <li>
 143 <a href="#classpath">Classpath considerations</a>
 144 </li>
 145 <li>
 146 <a href="#setuptools">Using distutils vs setuptools</a>
 147 </li>
 148 <li>
 149 <a href="#egg">Distributing an egg</a>
 150 </li>
 151 <li>
 152 <a href="#api">JCC's runtime API functions</a>
 153 </li>
 154 <li>
 155 <a href="#casting">Type casting and instance checks</a>
 156 </li>
 157 <li>
 158 <a href="#generics">Handling generic classes</a>
 159 </li>
 160 <li>
 161 <a href="#arrays">Handling arrays</a>
 162 </li>
 163 <li>
 164 <a href="#exceptions">Exception reporting</a>
 165 </li>
 166 <li>
 167 <a href="#extensions">Writing Java class extensions in Python</a>
 168 </li>
 169 <li>
 170 <a href="#embedding">Embedding a Python VM in a Java VM</a>
 171 </li>
 172 <li>
 173 <a href="#python">Pythonic protocols</a>
 174 </li>
 175 </ul>
 176 </div>
 177
 178 <div class="warning">
 179 <div class="label">Warning</div>
 180 <div class="content">
 181       Before calling any PyLucene API that requires the Java VM, start it by
 182       calling <span class="codefrag">initVM(classpath, ...)</span>. More about this function
 183       in <a href="#api">here</a>.
 184     </div>
 185 </div>
 186
 187 <a name="N10017"></a><a name="install"></a>
 188 <h2 class="boxed">Installing JCC</h2>
 189 <div class="section">
 190 <p>
 191         JCC is a Python extension written in Python and C++. It requires a
 192         Java Runtime Environment (JRE) to operate as it uses Java's
 193         reflection APIs to do its work. It is built and installed
 194         via <span class="codefrag">distutils</span> or <span class="codefrag">setuptools</span>.
 195       </p>
 196 <p>
 197         See <a href="../../jcc/documentation/install.html">installation</a> for more
 198         information and operating system specific notes.
 199       </p>
 200 </div>
 201
 202 <a name="N1002E"></a><a name="invoking"></a>
 203 <h2 class="boxed">Invoking JCC</h2>
 204 <div class="section">
 205 <p>
 206         JCC is installed as a package and how to invoke it depends on the
 207         Python version used:
 208       </p>
 209 <ul>
 210
 211 <li>python 2.7: <span class="codefrag">python -m jcc</span>
 212 </li>
 213
 214 <li>python 2.6: <span class="codefrag">python -m jcc.__main__</span>
 215 </li>
 216
 217 <li>python 2.5: <span class="codefrag">python -m jcc</span>
 218 </li>
 219
 220 <li>python 2.4:
 221           <ul>
 222
 223 <li>no setuptools: <span class="codefrag">python </span><em><span class="codefrag">site-packages</span></em><span class="codefrag">/jcc/__init__.py</span>
 224 </li>
 225
 226 <li>with setuptools: <span class="codefrag">python </span><em><span class="codefrag">site-packages</span></em>/<em><span class="codefrag">jcc egg directory</span></em><span class="codefrag">/jcc/__init__.py</span>
 227 </li>
 228
 229 </ul>
 230
 231 </li>
 232
 233 <li>python 2.3: <span class="codefrag">python </span><em><span class="codefrag">site-packages</span></em>/<em><span class="codefrag">jcc egg directory</span></em><span class="codefrag">/jcc/__init__.py</span>
 234 </li>
 235
 236 </ul>
 237 </div>
 238
 239 <a name="N10076"></a><a name="use"></a>
 240 <h2 class="boxed">Generating C++ and Python wrappers with JCC</h2>
 241 <div class="section">
 242 <p>
 243         JCC started as a C++ code generator for hiding the gory details of
 244         accessing methods and fields on Java classes via
 245         Java's <a href="http://java.sun.com/j2se/1.5.0/docs/guide/jni/spec/invocation.html">Native Invocation Interface</a>.
 246         These C++ wrappers make it possible to access a Java object as if it
 247         was a regular C++ object very much like GCJ's
 248         <a href="http://gcc.gnu.org/onlinedocs/gcj/About-CNI.html">CNI
 249         interface</a>.
 250       </p>
 251 <p>
 252         It then became apparent that JCC could also generate the C++
 253         wrappers for making these classes available to Python. Every class
 254         that gets thus wrapped becomes a
 255         <a href="http://docs.python.org/ext/defining-new-types.html">CPython
 256         type</a>.
 257       </p>
 258 <p>
 259         JCC generates wrappers for all public classes that are requested by
 260         name on the command line or via the <span class="codefrag">--jar</span> command line
 261         argument. It generates wrapper methods for all public methods and
 262         fields on these classes whose return type and parameter types are
 263         found in one of the following ways:
 264       </p>
 265 <ul>
 266
 267 <li>
 268           the type is one of the requested classes
 269         </li>
 270
 271 <li>
 272           the type is one of the requested classes' superclass or implemented
 273           interfaces
 274         </li>
 275
 276 <li>
 277           the type is available from one of the packages listed via the
 278           <span class="codefrag">--package</span> command line argument
 279         </li>
 280
 281 </ul>
 282 <p>
 283         Overloaded methods are supported and are selected at runtime on the
 284         basis of the type and number of arguments passed in.
 285       </p>
 286 <p>
 287         JCC does not generate wrappers for methods or fields which don't
 288         satisfy these requirements. Thus, JCC can avoid generating code for
 289         runaway transitive closures of type dependencies.
 290       </p>
 291 <p>
 292         JCC generates property accessors for a property
 293         called <em><span class="codefrag">field</span></em> when it finds Java methods
 294         named <span class="codefrag">set</span><em><span class="codefrag">Field</span></em><span class="codefrag">(value)</span>,
 295         <span class="codefrag">get</span><em><span class="codefrag">Field</span></em><span class="codefrag">()</span> or
 296         <span class="codefrag">is</span><em><span class="codefrag">Field</span></em><span class="codefrag">()</span>.
 297       </p>
 298 <p>
 299         The C++ wrappers are declared in a C++ namespace structure that
 300         mirrors the Java classes' Java packages. The Python types are
 301         declared in a flat namespace at the top level of the resulting
 302         Python extension module.
 303       </p>
 304 <p>
 305         JCC's command-line arguments are best illustrated via the PyLucene
 306         example:
 307       </p>
 308 <pre class="code">
 309     $ python -m jcc           # run JCC to wrap
 310         --jar lucene.jar      # all public classes in the lucene jar file
 311         --jar analyzers.jar   # and the lucene analyzers contrib package
 312         --jar snowball.jar    # and the snowball contrib package
 313         --jar highlighter.jar # and the highlighter contrib package
 314         --jar regex.jar       # and the regex search contrib package
 315         --jar queries.jar     # and the queries contrib package
 316         --jar extensions.jar  # and the Python extensions package
 317         --package java.lang   # including all dependencies found in the
 318                               # java.lang package
 319         --package java.util   # and the java.util package
 320         --package java.io     # and the java.io package
 321           java.lang.System    # and to explicitely wrap java.lang.System
 322           java.lang.Runtime   # as well as java.lang.Runtime
 323           java.lang.Boolean   # and java.lang.Boolean
 324           java.lang.Byte      # and java.lang.Byte
 325           java.lang.Character # and java.lang.Character
 326           java.lang.Integer   # and java.lang.Integer
 327           java.lang.Short     # and java.lang.Short
 328           java.lang.Long      # and java.lang.Long
 329           java.lang.Double    # and java.lang.Double
 330           java.lang.Float     # and java.lang.Float
 331           java.text.SimpleDateFormat
 332                               # and java.text.SimpleDateFormat
 333           java.io.StringReader
 334                               # and java.io.StringReader
 335           java.io.InputStreamReader
 336                               # and java.io.InputStreamReader
 337           java.io.FileInputStream
 338                               # and java.io.FileInputStream
 339           java.util.Arrays    # and java.util.Arrays
 340         --exclude org.apache.lucene.queryParser.Token
 341                               # while explicitely not wrapping
 342                               # org.apache.lucene.queryParser.Token
 343         --exclude org.apache.lucene.queryParser.TokenMgrError
 344                               # nor org.apache.lucene.queryParser.TokenMgrError
 345         --exclude org.apache.lucene.queryParser.ParseException
 346                               # nor.apache.lucene.queryParser.ParseException
 347         --python lucene       # generating Python wrappers into a module
 348                               # called lucene
 349         --version 2.4.0       # giving the Python extension egg version 2.4.0
 350         --mapping org.apache.lucene.document.Document
 351                   'get:(Ljava/lang/String;)Ljava/lang/String;'
 352                               # asking for a Python mapping protocol wrapper
 353                               # for get access on the Document class by
 354                               # calling its get method
 355         --mapping java.util.Properties
 356                   'getProperty:(Ljava/lang/String;)Ljava/lang/String;'
 357                               # asking for a Python mapping protocol wrapper
 358                               # for get access on the Properties class by
 359                               # calling its getProperty method
 360         --sequence org.apache.lucene.search.Hits
 361                    'length:()I'
 362                    'doc:(I)Lorg/apache/lucene/document/Document;'
 363                               # asking for a Python sequence protocol wrapper
 364                               # for length and get access on the Hits class by
 365                               # calling its length and doc methods
 366         --files 2             # generating all C++ classes into about 2 .cpp
 367                               # files
 368         --build               # and finally compiling the generated C++ code
 369                               # into a Python egg via setuptools - when
 370                               # installed - or a regular Python extension via
 371                               # distutils or setuptools otherwise
 372         --module collections.py
 373                               # copying the collections.py module into the egg
 374         --install             # installing it into Python's site-packages
 375                               # directory.
 376       </pre>
 377 <p>
 378         There are limits to both how many files can fit on the command line
 379         and how large a C++ file the C++ compiler can handle. By default,
 380         JCC generates one large C++ file containing the source code for all
 381         wrapper classes.
 382       </p>
 383 <p>
 384         Using the <span class="codefrag">--files</span> command line argument, this behaviour
 385         can be tuned to workaround various limits:<br>
 386         for example:
 387       </p>
 388 <ul>
 389
 390 <li>
 391           to break up the large wrapper class file into about 2 files:<br>
 392
 393 <span class="codefrag">--files 2</span>
 394
 395 </li>
 396
 397 <li>
 398           to break up the large wrapper class file into about 10 files:<br>
 399
 400 <span class="codefrag"> --files 10</span>
 401
 402 </li>
 403
 404 <li>
 405           to generate one C++ file per Java class wrapped:<br>
 406
 407 <span class="codefrag">--files separate</span>
 408
 409 </li>
 410
 411 </ul>
 412 <p>
 413         The <span class="codefrag">--prefix</span> and <span class="codefrag">--root</span> arguments are
 414         passed through to <span class="codefrag">distutils</span>' <span class="codefrag">setup()</span>.
 415       </p>
 416 </div>
 417
 418 <a name="N10108"></a><a name="classpath"></a>
 419 <h2 class="boxed">Classpath considerations</h2>
 420 <div class="section">
 421 <p>
 422         When generating wrappers for Python, the JAR files passed to JCC
 423         via <span class="codefrag">--jar</span> are copied into the resulting Python extension
 424         egg as resources and added to the extension
 425         module's <span class="codefrag">CLASSPATH</span> variable. Classes or JAR files that
 426         are required by the classes contained in the argument JAR files need
 427         to be made findable via JCC's <span class="codefrag">--classpath</span> command line
 428         argument. At runtime, these need to be appended to the
 429         extension's <span class="codefrag">CLASSPATH</span> variable before starting the VM
 430         with <span class="codefrag">initVM(CLASSPATH)</span>.
 431       </p>
 432 <p>
 433         To have such required jar files also automatically copied into
 434         resulting Python extension egg and added to the classpath at build
 435         and runtime, use the <span class="codefrag">--include</span> option. This option
 436         works like the <span class="codefrag">--jar</span> option except that no wrappers are
 437         generated for the classes contained in them unless they're
 438         explicitely named on the command line.
 439       </p>
 440 <p>
 441         When more than one JCC-built extension module is going to be used in
 442         the same Python VM and these extension modules share Java classes,
 443         only one extension module should be generated with wrappers for these
 444         shared classes. The other extension modules must be built by importing
 445         the one with the shared classes by using the <span class="codefrag">--import</span>
 446         command line parameter. This ensures that only one copy of the
 447         wrappers for the shared classes are generated and that they are
 448         compatible among all extension modules sharing them.
 449       </p>
 450 </div>
 451
 452 <a name="N10130"></a><a name="setuptools"></a>
 453 <h2 class="boxed">Using distutils vs setuptools</h2>
 454 <div class="section">
 455 <p>
 456         By default, when building a Python extension,
 457         if <span class="codefrag">setuptools</span> is found to be installed, it is used
 458         over <span class="codefrag">distutils</span>. If you want to force the use
 459         of <span class="codefrag">distutils</span> over <span class="codefrag">setuptools</span>, use
 460         the <span class="codefrag">--use-distutils</span> command line argument.
 461       </p>
 462 </div>
 463
 464 <a name="N1014E"></a><a name="egg"></a>
 465 <h2 class="boxed">Distributing an egg</h2>
 466 <div class="section">
 467 <p>
 468         The <span class="codefrag">--bdist</span> option can be used to ask JCC to
 469         invoke <span class="codefrag">distutils</span> with <span class="codefrag">bdist</span>
 470         or <span class="codefrag">setuptools</span>
 471         with <span class="codefrag">bdist_egg</span>. If <span class="codefrag">setuptools</span> is used,
 472         the resulting egg has to be installed with the
 473         <a href="http://peak.telecommunity.com/DevCenter/EasyInstall"><span class="codefrag">easy_install</span></a>
 474         installer which is normally part of a Python installation that
 475         includes <span class="codefrag">setuptools</span>.
 476       </p>
 477 </div>
 478
 479 <a name="N10172"></a><a name="api"></a>
 480 <h2 class="boxed">JCC's runtime API functions</h2>
 481 <div class="section">
 482 <p>
 483         JCC includes a small runtime component that is compiled into any
 484         Python extension it produces.
 485       </p>
 486 <p>
 487         This runtime component makes it possible to manage the Java VM from
 488         Python. Because a Java VM can be configured with a myriad of
 489         options, it is not automatically started when the resulting Python
 490         extension module is loaded into the Python interpreter.
 491       </p>
 492 <p>
 493         Instead, the <span class="codefrag">initVM()</span> function must be called from the
 494         main thread before using any of the wrapped classes. It takes the
 495         following keyword arguments:
 496       </p>
 497 <ul>
 498
 499 <li>
 500
 501 <span class="codefrag">classpath</span>
 502 <br>
 503           A string containing one or more directories or jar files for the
 504           Java VM to search for classes. Every Python extension produced by
 505           JCC exports a <span class="codefrag">CLASSPATH</span> variable that is hardcoded to
 506           the jar files that it was produced from. A copy of each jar file
 507           is installed as a resource file with the extension when JCC is
 508           invoked with the <span class="codefrag">--install</span> command line argument.
 509           This parameter is optional and defaults to the
 510           <span class="codefrag">CLASSPATH</span> string exported by the module
 511           <span class="codefrag">initVM</span> is imported from.
 512           <pre class="code">
 513             &gt;&gt;&gt; import lucene
 514             &gt;&gt;&gt; lucene.initVM(classpath=lucene.CLASSPATH)
 515           </pre>
 516
 517 </li>
 518
 519 <li>
 520
 521 <span class="codefrag">initialheap</span>
 522 <br>
 523           The initial amount of Java heap to start the Java VM with. This
 524           argument is a string that follows the same syntax as the
 525           similar <span class="codefrag">-Xms</span> java command line argument.
 526           <pre class="code">
 527             &gt;&gt;&gt; import lucene
 528             &gt;&gt;&gt; lucene.initVM(initialheap='32m')
 529             &gt;&gt;&gt; lucene.Runtime.getRuntime().totalMemory()
 530             33357824L
 531           </pre>
 532
 533 </li>
 534
 535 <li>
 536
 537 <span class="codefrag">maxheap</span>
 538 <br>
 539           The maximum amount of Java heap that could become available to the
 540           Java VM. This argument is a string that follows the same syntax as
 541           the similar <span class="codefrag">-Xmx</span> java command line argument.
 542         </li>
 543
 544 <li>
 545
 546 <span class="codefrag">maxstack</span>
 547 <br>
 548           The maximum amount of stack space that available to the Java
 549           VM. This argument is a string that follows the same syntax as the
 550           similar <span class="codefrag">-Xss</span> java command line argument.
 551         </li>
 552
 553 <li>
 554
 555 <span class="codefrag">vmargs</span>
 556 <br>
 557           A string of comma separated additional options to pass to the VM
 558           startup rountine. These are passed through as-is. For example:
 559           <pre class="code">
 560             &gt;&gt;&gt; import lucene
 561             &gt;&gt;&gt; lucene.initVM(vmargs='-Xcheck:jni,-verbose:jni,-verbose:gc')
 562           </pre>
 563
 564 </li>
 565
 566 </ul>
 567 <p>
 568         The <span class="codefrag">initVM()</span> and <span class="codefrag">getVMEnv()</span> functions
 569         return a JCCEnv object that has a few utility methods on it:
 570       </p>
 571 <ul>
 572
 573 <li>
 574
 575 <span class="codefrag">attachCurrentThread(name, asDaemon)</span>
 576 <br>
 577           Before a thread created in Python or elsewhere but not in the Java
 578           VM can be used with the Java VM, this method needs to be
 579           invoked. The two arguments it takes are optional and
 580           self-explanatory.
 581         </li>
 582
 583 <li>
 584
 585 <span class="codefrag">detachCurrentThread()</span>
 586           The opposite of <span class="codefrag">attachCurrentThread()</span>. This method
 587           should be used with extreme caution as Python's and java VM's
 588           garbage collectors may use a thread detached too early causing a
 589           system crash. The utility of this method seems dubious at the
 590           moment.
 591         </li>
 592
 593 </ul>
 594 <p>
 595         There are several differences between JNI's <span class="codefrag">findClass()</span>
 596         and Java's <span class="codefrag">Class.forName()</span>:
 597       </p>
 598 <ul>
 599
 600 <li>
 601           className is a '/' separated string of names
 602         </li>
 603
 604 <li>
 605           the class loaders are different, <span class="codefrag">findClass()</span> may find
 606           classes that <span class="codefrag">Class.forName()</span> won't.
 607         </li>
 608
 609 </ul>
 610 <p>
 611         For example:
 612       </p>
 613 <pre class="code">
 614         &gt;&gt;&gt; from lucene import *
 615         &gt;&gt;&gt; initVM(CLASSPATH)
 616         &gt;&gt;&gt; findClass('org/apache/lucene/document/Document')
 617         &lt;Class: class org.apache.lucene.document.Document&gt;
 618         &gt;&gt;&gt; Class.forName('org.apache.lucene.document.Document')
 619         Traceback (most recent call last):
 620           File "&lt;stdin&gt;", line 1, in &lt;module&gt;
 621         lucene.JavaError: java.lang.ClassNotFoundException:
 622                           org/apache/lucene/document/Document
 623         &gt;&gt;&gt; Class.forName('java.lang.Object')
 624         &lt;Class: class java.lang.Object&gt;
 625       </pre>
 626 </div>
 627
 628 <a name="N10207"></a><a name="casting"></a>
 629 <h2 class="boxed">Type casting and instance checks</h2>
 630 <div class="section">
 631 <p>
 632         Many Java APIs are declared to return types that are less specific
 633         than the types actually returned. In Java 1.5, this is worked around
 634         with type parameters. JCC generates code to heed type parameters
 635         unless the <span class="codefrag">--no-generics</span> is used. See next section for
 636         details on Java generics support.
 637       </p>
 638 <p>
 639         In C++, casting the object into its actual type is supported via the
 640         regular C casting operator.
 641       </p>
 642 <p>
 643         In Python each wrapped class has a class method
 644         called <span class="codefrag">cast_</span> that implements the same functionality.
 645       </p>
 646 <p>
 647         Similarly, each wrapped class has a class method
 648         called <span class="codefrag">instance_</span> that tests whether the wrapped java
 649         instance is of the given type. For example:
 650       </p>
 651 <pre class="code">
 652         if BooleanQuery.instance_(query):
 653             booleanQuery = BooleanQuery.cast_(query)
 654
 655         print booleanQuery.getClauses()
 656       </pre>
 657 </div>
 658
 659 <a name="N10227"></a><a name="generics"></a>
 660 <h2 class="boxed">Handling generic classes</h2>
 661 <div class="section">
 662 <p>
 663         Java 1.5 added support for parameterized types. JCC generates code
 664         to heed type parameters unless the <span class="codefrag">--no-generics</span>
 665         command line parameter is used. Java type parameterization is a
 666         runtime feature. The same class is used for all its
 667         parameterizations. Similarly, JCC wrapper objects all use the same
 668         class but store type parameterizations on instances and make them
 669         accessible as a tuple via the <span class="codefrag">parameters_</span> property.
 670       </p>
 671 <p>
 672         For example, an <span class="codefrag">ArrayList&lt;Document&gt;</span> instance,
 673         has <span class="codefrag">(&lt;type 'Document'&gt;,)</span>
 674         for <span class="codefrag">parameters_</span> and its <span class="codefrag">get()</span> method uses
 675         that type parameter to wrap its return values.
 676       </p>
 677 <p>
 678         To allocate an instance of a generic Java class with specific type
 679         parameters use the <span class="codefrag">of_()</span> method. This method accepts
 680         one or more Python wrapper classes to use as type parameters. For
 681         example, <span class="codefrag">java.util.ArrayList&lt;E&gt;</span> is declared to
 682         accept one type parameter. Its wrapper's <span class="codefrag">of_()</span> method
 683         hence accepts one parameter, a Python class, to use as type
 684         parameter for the return type of its <span class="codefrag">get()</span> method, among
 685         others:
 686       </p>
 687 <pre class="code">
 688         &gt;&gt;&gt; a = ArrayList().of_(Document)
 689         &gt;&gt;&gt; a
 690         &lt;ArrayList: []&gt;
 691         &gt;&gt;&gt; a.parameters_
 692         (&lt;type 'Document'&gt;,)
 693         &gt;&gt;&gt; a.add(Document())
 694         True
 695         &gt;&gt;&gt; a.get(0)
 696         &lt;Document: Document&lt;&gt;&gt;
 697       </pre>
 698 <p>
 699         The use of type parameters is, of course, optional. A generic Java
 700         class can still be used as before, without type parameters.
 701         Downcasting from <span class="codefrag">Object</span> is then necessary:
 702       </p>
 703 <pre class="code">
 704         &gt;&gt;&gt; a = ArrayList()
 705         &gt;&gt;&gt; a
 706         &lt;ArrayList: []&gt;
 707         &gt;&gt;&gt; a.parameters_
 708         (None,)
 709         &gt;&gt;&gt; a.add(Document())
 710         True
 711         &gt;&gt;&gt; a.get(0)
 712         &lt;Object: Document&lt;&gt;&gt;
 713         &gt;&gt;&gt; Document.cast_(a.get(0))
 714         &lt;Document: Document&lt;&gt;&gt;
 715       </pre>
 716 </div>
 717
 718 <a name="N10263"></a><a name="arrays"></a>
 719 <h2 class="boxed">Handling arrays</h2>
 720 <div class="section">
 721 <p>
 722         Java arrays are wrapped with a C++ JArray
 723         template. The <span class="codefrag">[]</span> is available for read
 724         access. This template, <span class="codefrag">JArray&lt;T&gt;</span>, accomodates all
 725         java primitive types, <span class="codefrag">jstring</span>, <span class="codefrag">jobject</span> and
 726         wrapper class arrays.
 727       </p>
 728 <p>
 729         Java arrays are returned to Python in a <span class="codefrag">JArray</span> wrapper
 730         instance that implements the Python sequence protocol. It is
 731         possible to change an array's elements but not to change an array's
 732         size.
 733       </p>
 734 <p>
 735         To convert a char array to a Python string use
 736         a <span class="codefrag">''.join(array)</span> construct.
 737       </p>
 738 <p>
 739         Any Java method expecting an array can be called with the corresponding
 740         sequence object from python.
 741       </p>
 742 <p>
 743         To instantiate a Java array from Python, use one of the following
 744         forms:
 745       </p>
 746 <pre class="code">
 747         &gt;&gt;&gt; array = JArray('int')(size)
 748         # the resulting Java int array is initialized with zeroes
 749
 750         &gt;&gt;&gt; array = JArray('int')(sequence)
 751         # the sequence must only contain ints
 752         # the resulting Java int array contains the ints in the sequence
 753       </pre>
 754 <p>
 755         Instead of <span class="codefrag">'int'</span>, you may also use one
 756         of <span class="codefrag">'object'</span>, <span class="codefrag">'string'</span>, <span class="codefrag">'bool'</span>,
 757         <span class="codefrag">'byte'</span>, <span class="codefrag">'char'</span>, <span class="codefrag">'double'</span>,
 758         <span class="codefrag">'float'</span>, <span class="codefrag">'long'</span> and <span class="codefrag">'short'</span>
 759         to create an array of the corresponding type.
 760       </p>
 761 <p>
 762         Because there is only one wrapper class for object arrays,
 763         the <span class="codefrag">JArray('object')</span> type's constructor takes a second
 764         argument denoting the class of the object elements. This argument is
 765         optional and defaults to <span class="codefrag">Object</span>.
 766       </p>
 767 <p>
 768         As with the <span class="codefrag">Object</span> types, the <span class="codefrag">JArray</span> types
 769         also include a <span class="codefrag">cast_</span> method. This method becomes useful
 770         when the array returned to Python is wrapped as a
 771         plain <span class="codefrag">Object</span>. This is the case, for example, with
 772         nested arrays since there is no distinct Python type for every
 773         different java object array class - all java object arrays are
 774         wrapped by <span class="codefrag">JArray('object')</span>. For example:
 775       </p>
 776 <pre class="code">
 777         # cast obj to an array of ints
 778         &gt;&gt;&gt; JArray('int').cast_(obj)
 779         # cast obj to an array of Document
 780         &gt;&gt;&gt; JArray('object').cast_(obj, Document)
 781       </pre>
 782 <p>
 783         In both cases, the java type of obj must be compatible with the
 784         array type it is being cast to.
 785       </p>
 786 <pre class="code">
 787         # using nested array:
 788
 789         &gt;&gt;&gt; d = JArray('object')(1, Document)
 790         &gt;&gt;&gt; d[0] = Document()
 791         &gt;&gt;&gt; d
 792         JArray&lt;object&gt;[&lt;Document: Document&lt;&gt;&gt;]
 793         &gt;&gt;&gt; d[0]
 794         &lt;Document: Document&lt;&gt;&gt;
 795         &gt;&gt;&gt; a = JArray('object')(2)
 796         &gt;&gt;&gt; a[0] = d
 797         &gt;&gt;&gt; a[1] = JArray('int')([0, 1, 2])
 798         &gt;&gt;&gt; a
 799         JArray&lt;object&gt;[&lt;Object: [Lorg.apache.lucene.document.Document;@694f12&gt;, &lt;Object: [I@234265&gt;]
 800         &gt;&gt;&gt; a[0]
 801         &lt;Object: [Lorg.apache.lucene.document.Document;@694f12&gt;
 802         &gt;&gt;&gt; a[1]
 803         &lt;Object: [I@234265&gt;
 804         &gt;&gt;&gt; JArray('object').cast_(a[0])[0]
 805         &lt;Object: Document&lt;&gt;&gt;
 806         &gt;&gt;&gt; JArray('object').cast_(a[0], Document)[0]
 807         &lt;Document: Document&lt;&gt;&gt;
 808         &gt;&gt;&gt; JArray('int').cast_(a[1])
 809         JArray&lt;int&gt;[0, 1, 2]
 810         &gt;&gt;&gt; JArray('int').cast_(a[1])[0]
 811         0
 812       </pre>
 813 <p>
 814         To verify that a Java object is of a given array type, use
 815         the <span class="codefrag">instance_()</span> method available on the array
 816         type. This is not the same as verifying that it is assignable with
 817         elements of a given type. For example, using the arrays created
 818         above:
 819       </p>
 820 <pre class="code">
 821         # is d array of Object ? are d's elements of type Object ?
 822         &gt;&gt;&gt; JArray('object').instance_(d)
 823         True
 824
 825         # can it receive Object instances ?
 826         &gt;&gt;&gt; JArray('object').assignable_(d)
 827         False
 828
 829         # is it array of Document ? are d's elements of type Document ?
 830         &gt;&gt;&gt; JArray('object').instance_(d, Document)
 831         True
 832
 833         # is it array of Class ? are d's elements of type Class ?
 834         &gt;&gt;&gt; JArray('object').instance_(d, Class)
 835         False
 836
 837         # can it receive Document instances ?
 838         &gt;&gt;&gt; JArray('object').assignable_(d, Document)
 839         True
 840       </pre>
 841 </div>
 842
 843 <a name="N102E0"></a><a name="exceptions"></a>
 844 <h2 class="boxed">Exception reporting</h2>
 845 <div class="section">
 846 <p>
 847         Exceptions that occur in the Java VM and that escape to C++ are
 848         reported as a <span class="codefrag">javaError</span> C++ exception. When using
 849         Python wrappers, the C++ exceptions are handled and reported with
 850         Python exceptions. When using C++ only, failure to handle the
 851         exception in your C++ code will cause the process to crash.
 852       </p>
 853 <p>
 854         Exceptions that occur in the Java VM and that escape to the Python
 855         VM are reported with a <span class="codefrag">JavaError</span> python exception
 856         object. The <span class="codefrag">getJavaException()</span> method can be called
 857         on <span class="codefrag">JavaError</span> objects to obtain the original java
 858         exception object wrapped as any other Java object. This Java object
 859         can be used to obtain a Java stack trace for the error, for example.
 860       </p>
 861 <p>
 862         Exceptions that occur in the Python VM and that escape to the Java
 863         VM, as for example can happen in Python extensions (see topic below)
 864         are reported to the Java VM as a <span class="codefrag">RuntimeException</span> or as
 865         a <span class="codefrag">PythonException</span> when using shared
 866         mode. See <a href="../../jcc/documentation/install.html">installation
 867         instructions</a> for more information about shared mode.
 868       </p>
 869 </div>
 870
 871 <a name="N10306"></a><a name="extensions"></a>
 872 <h2 class="boxed">Writing Java class extensions in Python</h2>
 873 <div class="section">
 874 <p>
 875         JCC makes it relatively easy to extend a Java class from
 876         Python. This is done via an intermediary class written in Java that
 877         implements a special method called <span class="codefrag">pythonExtension()</span>
 878         and that declares a number of native methods that are to be
 879         implemented by the actual Python extension.
 880       </p>
 881 <p>
 882         When JCC sees these special extension java classes it generates the
 883         C++ code implementing the native methods they declare. These native
 884         methods call the corresponding Python method implementations passing
 885         in parameters and returning the result to the Java VM caller.
 886       </p>
 887 <p>
 888         For example, to implement a Lucene analyzer in Python, one would
 889         implement first such an extension class in Java:
 890       </p>
 891 <pre class="code">
 892     package org.apache.pylucene.analysis;
 893
 894     import org.apache.lucene.analysis.Analyzer;
 895     import org.apache.lucene.analysis.TokenStream;
 896     import java.io.Reader;
 897
 898     public class PythonAnalyzer extends Analyzer {
 899         private long pythonObject;
 900
 901         public PythonAnalyzer()
 902         {
 903         }
 904
 905         public void pythonExtension(long pythonObject)
 906         {
 907             this.pythonObject = pythonObject;
 908         }
 909         public long pythonExtension()
 910         {
 911             return this.pythonObject;
 912         }
 913
 914         public void finalize()
 915             throws Throwable
 916         {
 917             pythonDecRef();
 918         }
 919
 920         public native void pythonDecRef();
 921         public native TokenStream tokenStream(String fieldName, Reader reader);
 922     }
 923       </pre>
 924 <p>
 925         The <span class="codefrag">pythonExtension()</span> methods is what makes this class
 926         recognized as an extension class by JCC. They should be included
 927         verbatim as above along with the declaration of
 928         the <span class="codefrag">pythonObject</span> instance variable.
 929       </p>
 930 <p>
 931         The implementation of the native <span class="codefrag">pythonDecRef()</span> method
 932         is generated by JCC and is necessary because it seems
 933         that <span class="codefrag">finalize()</span> cannot itself be native. Since an
 934         extension class wraps the Python instance object it's going to be
 935         calling methods on, its ref count needs to be decremented when this
 936         Java wrapper class disappears. A declaration
 937         for <span class="codefrag">pythonDecRef()</span> and a <span class="codefrag">finalize()</span>
 938         implementation should always be included verbatim as above.
 939       </p>
 940 <p>
 941         Really, the only non boilerplate user input is the constructor of the
 942         class and the other native methods, <span class="codefrag">tokenStream()</span> in
 943         the example above.
 944       </p>
 945 <p>
 946         The corresponding Python class(es) are implemented as follows:
 947       </p>
 948 <pre class="code">
 949         class _analyzer(PythonAnalyzer):
 950             def tokenStream(_self, fieldName, reader):
 951                 class _tokenStream(PythonTokenStream):
 952                     def __init__(self_):
 953                         super(_tokenStream, self_).__init__()
 954                         self_.TOKENS = ["1", "2", "3", "4", "5"]
 955                         self_.INCREMENTS = [1, 2, 1, 0, 1]
 956                         self_.i = 0
 957                         self_.posIncrAtt = self_.addAttribute(PositionIncrementAttribute.class_)
 958                         self_.termAtt = self_.addAttribute(TermAttribute.class_)
 959                         self_.offsetAtt = self_.addAttribute(OffsetAttribute.class_)
 960                     def incrementToken(self_):
 961                         if self_.i == len(self_.TOKENS):
 962                             return False
 963                         self_.termAtt.setTermBuffer(self_.TOKENS[self_.i])
 964                         self_.offsetAtt.setOffset(self_.i, self_.i)
 965                         self_.posIncrAtt.setPositionIncrement(self_.INCREMENTS[self_.i])
 966                         self_.i += 1
 967                         return True
 968                     def end(self_):
 969                         pass
 970                     def reset(self_):
 971                         pass
 972                     def close(self_):
 973                         pass
 974                 return _tokenStream()
 975       </pre>
 976 <p>
 977         When an <span class="codefrag">__init__()</span> is declared, <span class="codefrag">super()</span>
 978         must be called or else the Java wrapper class will not know about
 979         the Python instance it needs to invoke.
 980       </p>
 981 <p>
 982         When a java extension class declares native methods for which there
 983         are public or protected equivalents available on the parent class,
 984         JCC generates code that makes it possible to
 985         call <span class="codefrag">super()</span> on these methods from Python as well.
 986       </p>
 987 <p>
 988         There are a number of extension examples available in PyLucene's test
 989         <a href="http://svn.apache.org/viewcvs.cgi/lucene/pylucene/trunk/test">suite</a>
 990         and <a href="../../documentation/readme.html">samples</a>.
 991       </p>
 992 </div>
 993
 994 <a name="N1035C"></a><a name="embedding"></a>
 995 <h2 class="boxed">Embedding a Python VM in a Java VM</h2>
 996 <div class="section">
 997 <p>
 998         Using the same techniques used when writing a Python extension of a
 999         Java class, JCC may also be used to embed a Python VM in a Java VM.
1000         Following are the steps and constraints to follow to achieve this:
1001       </p>
1002 <ul>
1003
1004 <li>
1005           JCC must be built in shared mode.  See
1006           <a href="../../jcc/documentation/install.html">installation
1007           instructions</a> for more information about shared mode.
1008           Note that for this use on Mac OS X, JCC must also be built
1009           with the link flags <span class="codefrag">"-framework", "Python"</span> in
1010           the <span class="codefrag">LFLAGS</span> value.
1011         </li>
1012
1013 <li>
1014           As described in the previous section, define one or more Java
1015           classes to be "extended" from Python to provide the
1016           implementations of the native methods declared on them. Instances
1017           of these classes implement the bridges into the Python VM from
1018           Java.
1019         </li>
1020
1021 <li>
1022           The <span class="codefrag">org.apache.jcc.PythonVM</span> Java class is going be
1023           used from the Java VM's main thread to initialize the embedded
1024           Python VM. This class is installed inside the JCC egg under the
1025           <span class="codefrag">jcc/classes</span> directory and the full path to this
1026           directory must be on the Java <span class="codefrag">CLASSPATH</span>.
1027         </li>
1028
1029 <li>
1030           The JCC egg directory contains the JCC shared runtime library - not
1031           the JCC Python extension shared library - but a library
1032           called <span class="codefrag">libjcc.dylib</span> on Mac OS X,
1033           <span class="codefrag">libjcc.so</span> on Linux or <span class="codefrag">jcc.dll</span> on Windows.
1034           This directory must be added to the Java VM's shared library path
1035           via the <span class="codefrag">-Djava.library.path</span> command line parameter.
1036         </li>
1037
1038 <li>
1039           In the Java VM's main thread, initialize the Python VM by
1040           calling its static <span class="codefrag">start()</span> method passing it a
1041           Python program name string and optional start-up arguments
1042           in a string array that will be made accessible in Python via
1043           <span class="codefrag">sys.argv</span>.  Note that the program name string is
1044           purely informational, and is not used by the
1045           <span class="codefrag">start()</span> code other than to initialize that
1046           Python variable.  This method returns the singleton PythonVM
1047           instance to be used in this Java VM. <span class="codefrag">start()</span>
1048           may be called multiple times; it will always return the same
1049           singleton instance.  This instance may also be retrieved at any
1050           later time via the static <span class="codefrag">get()</span> method defined
1051           on the <span class="codefrag">org.apache.jcc.PythonVM</span> class.
1052         </li>
1053
1054 <li>
1055           Any Java VM thread that is going to be calling into the Python VM
1056           should start with acquiring a reference to the Python thread state
1057           object by calling <span class="codefrag">acquireThreadState()</span> method on the
1058           Python VM instance. It should then release the Python thread state
1059           before terminating by calling <span class="codefrag">releaseThreadState()</span>.
1060           Calling these methods is optional but strongly recommended as it
1061           ensures that Python is not creating and throwing away a thread
1062           state everytime the Python VM is entered and exited from a given
1063           Java VM thread.
1064         </li>
1065
1066 <li>
1067           Any Java VM thread may instantiate a Python object for which an
1068           extension class was defined in Java as described in the previous
1069           section by calling the <span class="codefrag">instantiate()</span> method on the
1070           PythonVM instance. This method takes two string parameters, the
1071           name of the Python module and the name of the Python class to
1072           import and instantiate from it. The <span class="codefrag">__init__()</span>
1073           constructor on this class must be callable without any parameters
1074           and, if defined, must call <span class="codefrag">super()</span> in order to
1075           initialize the Java side. The <span class="codefrag">instantiate()</span> method is
1076           declared to return <span class="codefrag">java.lang.Object</span> but the return
1077           value is actually an instance of the Java extension class used and
1078           must be downcast to it.
1079         </li>
1080
1081 </ul>
1082 </div>
1083
1084 <a name="N103C4"></a><a name="python"></a>
1085 <h2 class="boxed">Pythonic protocols</h2>
1086 <div class="section">
1087 <p>
1088         When generating wrappers for Python, JCC attempts to detect which
1089         classes can be made iterable:
1090       </p>
1091 <ul>
1092
1093 <li>
1094           When a class declares to
1095           implement <span class="codefrag">java.lang.Iterable</span>, JCC makes it iterable
1096           from Python.
1097         </li>
1098
1099 <li>
1100           When a Java class declares a method called <span class="codefrag">next()</span>
1101           with no arguments returning an object type, this class is made
1102           iterable. Its <span class="codefrag">next()</span> method is assumed to terminate
1103           iteration by returning <span class="codefrag">null</span>.
1104         </li>
1105
1106 </ul>
1107 <p>
1108         JCC generates a Python mapping get method for a class when requested
1109         to do so via the <span class="codefrag">--mapping</span> command line option which
1110         takes two arguments, the class to generate the mapping get for and
1111         the Java method to use. The method is specified with its name
1112         followed by ':' and its Java
1113         <a href="http://java.sun.com/j2se/1.5.0/docs/guide/jni/spec/types.html#wp16432">signature</a>.
1114       </p>
1115 <p>
1116       For example, <span class="codefrag">System.getProperties()['java.class.path']</span> is
1117       made possible by:
1118       </p>
1119 <pre class="code">
1120         --mapping java.util.Properties
1121                   'getProperty:(Ljava/lang/String;)Ljava/lang/String;'
1122                               # asking for a Python mapping protocol wrapper
1123                               # for get access on the Properties class by
1124                               # calling its getProperty method
1125       </pre>
1126 <p>
1127         JCC generates Python sequence length and get methods for a class
1128         when requested to do so via the <span class="codefrag">--sequence</span> command line
1129         option which takes three arguments, the class to generate the
1130         sequence length and get for and the two java methods to use. The
1131         methods are specified with their name followed by ':' and their Java
1132         <a href="http://java.sun.com/j2se/1.5.0/docs/guide/jni/spec/types.html#wp16432">signature</a>. For example:
1133       </p>
1134 <pre class="code">
1135       for i in xrange(len(hits)):
1136           doc = hits[i]
1137           ...
1138       </pre>
1139 <p>
1140         is made possible by:
1141       </p>
1142 <pre class="code">
1143         --sequence org.apache.lucene.search.Hits
1144                    'length:()I'
1145                    'doc:(I)Lorg/apache/lucene/document/Document;'
1146       </pre>
1147 </div>
1148
1149 </div>
1150 <!--+
1151     |end content
1152     +-->
1153 <div class="clearboth">&nbsp;</div>
1154 </div>
1155 <div id="footer">
1156 <!--+
1157     |start bottomstrip
1158     +-->
1159 <div class="lastmodified">
1160 <script type="text/javascript"><!--
1161 document.write("Last Published: " + document.lastModified);
1162 //  --></script>
1163 </div>
1164 <div class="copyright">
1165         Copyright &copy;
1166          2009-2011 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
1167 </div>
1168 <!--+
1169     |end bottomstrip
1170     +-->
1171 </div>
1172 </body>
1173 </html>