jcc/java/org/apache/jcc/PythonVM.java

   1 /* ====================================================================
   2  *   Licensed under the Apache License, Version 2.0 (the "License");
   3  *   you may not use this file except in compliance with the License.
   4  *   You may obtain a copy of the License at
   5  *
   6  *       http://www.apache.org/licenses/LICENSE-2.0
   7  *
   8  *   Unless required by applicable law or agreed to in writing, software
   9  *   distributed under the License is distributed on an "AS IS" BASIS,
  10  *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  11  *   See the License for the specific language governing permissions and
  12  *   limitations under the License.
  13  * ====================================================================
  14  */
  15
  16 package org.apache.jcc;
  17
  18
  19 public class PythonVM {
  20     static protected PythonVM vm;
  21
  22     static {
  23         System.loadLibrary("jcc");
  24     }
  25
  26     /**
  27      * Start the embedded Python interpreter.  The specified
  28      * program name and args are set into the Python variable sys.argv.
  29      * This returns an instance of the Python VM; it may be called
  30      * multiple times, and will return the same VM instance each time.
  31      *
  32      * @param programName the name of the Python program, typically
  33      * /usr/bin/python.  This is informational; the program is not
  34      * actually executed.
  35      * @param args additional arguments to be put into sys.argv.
  36      * @return a singleton instance of PythonVM
  37      */
  38     static public PythonVM start(String programName, String[] args)
  39     {
  40         if (vm == null)
  41         {
  42             vm = new PythonVM();
  43             vm.init(programName, args);
  44         }
  45
  46         return vm;
  47     }
  48
  49     /**
  50      * Start the embedded Python interpreter.  The specified
  51      * program name is set into the Python variable sys.argv[0].
  52      * This returns an instance of the Python VM; it may be called
  53      * multiple times, and will return the same VM instance each time.
  54      *
  55      * @param programName the name of the Python program, typically
  56      * /usr/bin/python.  This is informational; the program is not
  57      * actually executed.
  58      * @return a singleton instance of PythonVM
  59      */
  60     static public PythonVM start(String programName)
  61     {
  62         return start(programName, null);
  63     }
  64
  65     /**
  66      * Obtain the PythonVM instance, or null if the Python VM
  67      * has not yet been started.
  68      *
  69      * @return a singleton instance of PythonVM, or null
  70      */
  71     static public PythonVM get()
  72     {
  73         return vm;
  74     }
  75
  76     protected PythonVM()
  77     {
  78     }
  79
  80     protected native void init(String programName, String[] args);
  81
  82     /**
  83      * Instantiate the specified Python class, and return the instance.
  84      *
  85      * @param moduleName the Python module the class is defined in
  86      * @param className the Python class to instantiate.
  87      * @return a handle on the Python instance.
  88      */
  89     public native Object instantiate(String moduleName, String className)
  90         throws PythonException;
  91
  92     /**
  93      * Bump the Python thread state counter.  Every thread should
  94      * do this before calling into Python, to prevent the Python
  95      * thread state from being inadvertently collected (and causing loss
  96      * of thread-local variables)
  97      *
  98      * @return the Python thread state counter.  A return value less
  99      * than zero signals an error.
 100      */
 101     public native int acquireThreadState();
 102
 103     /**
 104      * Release the Python thread state counter.  Every thread that has
 105      * called acquireThreadState() should call this before
 106      * terminating.
 107      *
 108      * @return the Python thread state counter.  A return value less
 109      * than zero signals an error.
 110      */
 111     public native int releaseThreadState();
 112 }