1 /*******************************************************************************

     2  * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     3  * All rights reserved. This program and the accompanying materials

     4  * are made available under the terms of the Eclipse Public License v1.0

     5  * which accompanies this distribution, and is available at

     6  * http://www.eclipse.org/legal/epl-v10.html

     7  *

     8  * Contributors:

     9  *     Nokia Corporation - initial implementation

    10  *******************************************************************************/

    11 

    12 #ifndef _JNI_UTILS_H_

    13 #define _JNI_UTILS_H_

    14 

    15 #include <QObject>

    16 #include <QRect>

    17 #include <QPoint>

    18 #include <QStringList>

    19 #include <QStack>

    20 #include <QPointer>

    21 #include <jni.h>

    22 

    23 template<class T>

    24 class QStack;

    25 

    26 namespace Java { namespace GFX {

    27 class ImageDataWrapper;

    28 class PaletteDataWrapper;

    29 class Image;

    30 class GfxException;

    31 }}

    32 

    33 namespace Java { namespace eSWT {

    34 

    35 class ExecExceptionHandler;

    36 

    37 typedef QPointer<QObject> QObjectPtr;

    38 typedef QStack<QObjectPtr> PtrStack;

    39 typedef QStack<ExecExceptionHandler*> ExecStack;

    40 

    41 class JniUtils : public QObject {

    42     Q_OBJECT

    43 

    44 public:

    45     /**

    46      * The constructor.

    47      * @param aEnv The JNI environment pointer of the Qt GUI thread.

    48      * @param aDisplay Local ref to the Java Display instance, JniUtils will create a global ref

    49      */

    50     JniUtils(JNIEnv* aEnv, jobject aDisplay);

    51 

    52     /**

    53      * The destructor.

    54      */

    55     virtual ~JniUtils();

    56 

    57     /**

    58      * Calls eventProcess Java method of the active Display instance. 

    59      * Can only be called in the UI thread. 

    60      * @param aQObject Target QObject of the QEvent

    61      * @param aQEventType Type of the QEvent

    62      * @param aN Event type specific integer arguments

    63      * @param aString Event type specific string argument

    64      * @return True if the event should be canceled.

    65      */

    66     bool eventProcess(const QObject* aQObject, const int& aQEventType,

    67                       const int& a1 = 0, const int& a2 = 0, const int& a3 = 0,

    68                       const int& a4 = 0, const int& a5 = 0,

    69                       const jstring aString = NULL);

    70 

    71     /**

    72      * Calls eventProcess Java method based on the given jobject and jmethodID.

    73      * Can only be called in the UI thread. 

    74      * @param aObject The Java object instance for the method call.

    75      * @param aMethodID The Java methodID for the method call.

    76      * @param ... Parameters to pass to the Java method.

    77      * @return True if the event should be canceled.

    78      */

    79     bool eventProcess(jobject aObject, const jmethodID aMethodID,

    80             const int& aQObject, const int& aQEventType, const int& a1,

    81             const int& a2, const int& a3, const int& a4, const int& a5,

    82             const jstring aString);

    83 

    84     /**

    85      * Query if the jobject is the Display of the process.

    86      * Can only be called in the UI thread. 

    87      * @param aObject jobject to compare to the Display.

    88      * @return true if given jobject is the Display

    89      */

    90     bool isDisplay(jobject aObject);

    91 

    92     /**

    93      * This must be called before entering an event loop. E.g. dialogs and

    94      * menus need to call this before calling exec(). This will handle closing

    95      * the dialog or menu properly in case a Java exception is thrown while in

    96      * exec(). Call to enterExec must always be paired with leaveExec.

    97      * @param aObject the object that exec will be called on.

    98      */

    99     void enterExec(QObject* aObject);

   100 

   101     /**

   102      * This must be called after exiting an event loop. It must be preceded by

   103      * enterExec.

   104      */

   105     void leaveExec();

   106 

   107     /**

   108      * Creates a Java Rectangle from the given QRect.

   109      * @param aEnv JNI environment for the thread

   110      * @param aRect The QRect to use.

   111      * @return A Java Rectangle object reference. Never NULL.

   112      * @exception std::bad_alloc

   113      */

   114     jobject NewJavaRectangle(JNIEnv* aEnv, const QRect& aRect);

   115 

   116     /**

   117      * Creates a Java Point from the given QSize.

   118      * @param aEnv JNI environment for the thread

   119      * @param aSize The QSize object ot use.

   120      * @return A Java Point object reference.

   121      * @exception std::bad_alloc

   122      */

   123     jobject NewJavaPoint(JNIEnv* aEnv, const QSize& aSize);

   124 

   125     /**

   126      * Creates a Java Point from the given QPoint.

   127      * @param aEnv JNI environment for the thread

   128      * @param aPoint The QPoint object ot use.

   129      * @return A Java Point object reference.

   130      * @exception std::bad_alloc

   131      */

   132     jobject NewJavaPoint(JNIEnv* aEnv, const QPoint& aPoint);

   133 

   134     /**

   135      * Creates a QString from the given Java string.

   136      * @param aEnv JNI environment for the thread

   137      * @param The Java String to use.

   138      * @return A QString object.

   139      * @exception std::bad_alloc

   140      */

   141     QString JavaStringToQString(JNIEnv* aEnv, jstring aJavaString);

   142 

   143     /**

   144      * Creates a Java string from the given QString.

   145      * @param aEnv JNI environment for the thread

   146      * @param aQString The QString object to use.

   147      * @return A Java string.

   148      * @exception std::bad_alloc

   149      */

   150     jstring QStringToJavaString(JNIEnv* aEnv, const QString& aQString);

   151 

   152     /**

   153      * Creates a new Java integer array from the given native int array.

   154      * @param aEnv JNI environment for the thread

   155      * @param aArray Native primitive integer array.

   156      * @param aItemCount Number of items to read from the array starting from the first item.

   157      * @return A Java integer array.

   158      * @exception std::bad_alloc

   159      */

   160     jintArray NewJavaIntArray(JNIEnv* aEnv, int* aArray, const int& aItemCount);

   161 

   162     /**

   163      * Creates a new Java string array from the given QStringList.

   164      * @param aEnv JNI environment for the thread

   165      * @param aStrList QStringList.

   166      * @return A Java object array.

   167      * @exception std::bad_alloc or std::bad_typeid

   168      */

   169     jobjectArray NewJavaStringArray(JNIEnv* aEnv, const QStringList& aStrList);

   170 

   171     /**

   172      * Creates a QStringList from the given Java string array .

   173      * @param aEnv JNI environment for the thread

   174      * @param aObjectArray jobjectArray.

   175      * @return A QStringList

   176      */

   177     QStringList JavaStringArrayToQStringList(JNIEnv* aEnv, jobjectArray aObjectArray);

   178 

   179     /**

   180      * Creates a new Java byte array from the given QByteArray.

   181      * @param aEnv JNI environment for the thread

   182      * @param aArray QByteArray.

   183      * @return A Java byte array.

   184      * @exception std::bad_alloc

   185      */

   186     jbyteArray NewJavaByteArray(JNIEnv* aEnv, const QByteArray& aArray);

   187 

   188     /**

   189      * Creates a QByteArray from the given Java byte array.

   190      * @param aEnv JNI environment for the thread

   191      * @param Java byte array.

   192      * @return A QByteArray object.

   193      * @exception std::bad_alloc

   194      */

   195     QByteArray JavaByteArrayToQByteArray(JNIEnv* aEnv, jbyteArray aByteArray);

   196 

   197     /**

   198      * Throws an SWT error exception from the current JNI call.

   199      * Note that after this call the JVM is handling the exception and further Java execution is not

   200      * possible until the exception has been caught by the JVM.

   201      * @param aEnv JNI environment for the thread

   202      * @param aError The SWT error code to throw.

   203      */

   204     void Throw(JNIEnv* aEnv, const int& aError);

   205     

   206     /**

   207      * Throws a custom Java exception from the current JNI call. 

   208      * Note that after this call the JVM is handling the exception and further Java execution is not 

   209      * possible until the exception has been caught by the JVM. 

   210      * @param aEnv JNI environment for the thread

   211      * @param aException The GfxException containing error code and error description.

   212      */

   213     void Throw(JNIEnv* aEnv, Java::GFX::GfxException& aException);

   214 

   215     /**

   216      * Returns a Java object instance method ID based of on the given method name and signature.

   217      * @param aEnv JNI environment for the thread

   218      * @param aObject The Java object instance.

   219      * @param aMethodName The name of the Java method.

   220      * @param aMethodSignature The JNI signature of the Java method.

   221      * @return JNI method id of the method or NULL if unsuccessful.

   222      */

   223     jmethodID FindJavaMethodID(JNIEnv* aEnv, jobject aObject, const char* aMethodName,

   224             const char* aMethodSignature);

   225 

   226     /**

   227      * Returns the number of currently active (maybe nested) calls to event 

   228      * processing functions. I.e. calls to functions that might lead to 

   229      * callbacks to Java event listeners. Used to defer the desruction of 

   230      * QApplication to the point where all nested events loops have exited. 

   231      */

   232     int javaCallbackCount();

   233 

   234     /**

   235      * Copies a region of a Java integer array to a pre-allocated primitive int

   236      * buffer. 

   237      * @param aEnv JNI environment for the thread

   238      * @param aArray The source Java array

   239      * @param aStart The copy operation start index in the source array

   240      * @param aLength The number of elements to be copied

   241      * @param aBuffer The pre-allocated destination buffer

   242      * @exception std::bad_alloc

   243      */

   244     void GetJavaIntArrayRegionToIntArray(JNIEnv* aEnv, jintArray aArray, jsize aStart, jsize aLength, int* aBuffer);

   245     

   246     /**

   247      * Copies contents of a primitive integer buffer to a region of a Java 

   248      * integer array. 

   249      * @param aEnv JNI environment for the thread

   250      * @param aArray The target Java array

   251      * @param aStart The copy operation start index in the target Java array

   252      * @param aLength The number of elements to be copied

   253      * @param aBuffer The native primitive type source buffer

   254      * @exception std::bad_alloc

   255      */

   256     void SetJavaIntArrayRegionFromIntArray(JNIEnv* aEnv, jintArray aArray, jsize aStart, jsize aLength, int* aBuffer);

   257     

   258     /**

   259      * Copies a region of a Java byte array to a pre-allocated primitive char

   260      * buffer. 

   261      * @param aEnv JNI environment for the thread

   262      * @param aArray The source Java array

   263      * @param aStart The copy operation start index in the source array

   264      * @param aLength The number of elements to be copied

   265      * @param aBuffer The pre-allocated destination buffer

   266      * @exception std::bad_alloc

   267      */

   268     void GetJavaByteArrayRegionToCharArray(JNIEnv* aEnv, jbyteArray aArray, jsize aStart, jsize aLength, char* aBuffer);

   269     

   270     /**

   271      * Copies contents of a primitive integer buffer to a region of a Java 

   272      * integer array. 

   273      * @param aEnv JNI environment for the thread

   274      * @param aArray The target Java array

   275      * @param aStart The copy operation start index in the target Java array

   276      * @param aLength The number of elements to be copied

   277      * @param aBuffer The native primitive type source buffer

   278      * @exception std::bad_alloc

   279      */

   280     void SetJavaByteArrayRegionFromCharArray(JNIEnv* aEnv, jbyteArray aArray, jsize aStart, jsize aLength, char* aBuffer);

   281     

   282     /**

   283      * Copies a region of a Java short array to a pre-allocated primitive short

   284      * buffer. 

   285      * @param aEnv JNI environment for the thread

   286      * @param aArray The source Java array

   287      * @param aStart The copy operation start index in the source array

   288      * @param aLength The number of elements to be copied

   289      * @param aBuffer The pre-allocated destination buffer

   290      * @exception std::bad_alloc

   291      */

   292     void GetJavaShortArrayRegionToShortArray(JNIEnv* aEnv, jshortArray aArray, jsize aStart, jsize aLength, short* aBuffer);

   293     

   294     /**

   295      * Copies contents of a primitive short buffer to a region of a Java 

   296      * short array. 

   297      * @param aEnv JNI environment for the thread

   298      * @param aArray The target Java array

   299      * @param aStart The copy operation start index in the target Java array

   300      * @param aLength The number of elements to be copied

   301      * @param aBuffer The native primitive type source buffer

   302      * @exception std::bad_alloc

   303      */

   304     void SetJavaShortArrayRegionFromShortArray(JNIEnv* aEnv, jshortArray aArray, jsize aStart, jsize aLength, short* aBuffer);

   305     

   306     /**

   307      * Creates java side image data object based on the given native side 

   308      * image data object.

   309      * @param aEnv JNI environment for the thread

   310      * @param aImageData The native image data object

   311      * @return Java side image data object

   312      */

   313     jobject CreateJavaImageData(JNIEnv* aEnv, Java::GFX::ImageDataWrapper& aImageData);

   314 

   315     /**

   316      * Creates java side palette data object based on the given native side 

   317      * palette data object.

   318      * @param aEnv JNI environment for the thread

   319      * @param aPaletteData The native palette data object

   320      * @return Java side palette data object

   321      */

   322     jobject CreateJavaPaletteData(JNIEnv* aEnv, Java::GFX::PaletteDataWrapper& aPaletteData);

   323 

   324     /**

   325      * Creates a native image object based on the given image data object.

   326      * @param aEnv JNI environment for the thread

   327      * @param aJavaImageData Java side image data object

   328      * @return Native image object

   329      */

   330     Java::GFX::Image* CreateImage(JNIEnv* aEnv, jobject& aJavaImageData);

   331 

   332     /**

   333      * Checks if in terms of event processing the object can be deleted. Used 

   334      * to prevent objects from getting deleted inside their event listeners. 

   335      * @param aPtrToDelete Pointer to the deletion candidate object. 

   336      * @return True if the object can be deleted. 

   337      */

   338     bool safeToDelete(QObject* aPtrToDelete);

   339 

   340 private:

   341     JniUtils() {};

   342 

   343     /**

   344      * Creates a native palette data object based on the given palette data object.

   345      * @param aEnv JNI environment

   346      * @param aJavaPaletteData Java side image data object

   347      * @return Native image object

   348      */

   349     Java::GFX::PaletteDataWrapper* CreatePaletteData(JNIEnv* aEnv, jobject& aJavaPaletteData);

   350     

   351     /**

   352      * Converts GfxException error code to java exception class string.

   353      * @param aErrorCode The Gfx error code to throw. 

   354      */

   355     const char* resolveException(int aErrorCode);

   356     

   357     /**

   358      * Checks recursively if the object is a child of the other object. 

   359      * @param aChild The child candidate.

   360      * @param aParent The candidate parent object whose children are searched. 

   361      * @returns True if aParent equals aChild or aChild is one of the children. 

   362      */

   363     bool isSameOrChild(const QObject* aChild, const QObject* aParent) const;

   364 

   365     /**

   366      * Private helper class that can be created on stack to safely update the 

   367      * number of recursive callbacks and the list of objects currently in

   368      * their event or signal handler. 

   369      */

   370     class JavaCallbackCounter

   371     {

   372     public:

   373         JavaCallbackCounter(PtrStack& aStack, QObject* aObject)

   374             : mStack(aStack)

   375         { 

   376             QObjectPtr ptr = aObject;

   377             mStack.push(ptr);

   378         }

   379         virtual ~JavaCallbackCounter()

   380         { 

   381             mStack.pop();

   382         }

   383     private:

   384         PtrStack& mStack;

   385     };

   386 

   387     JNIEnv*     mUIThreadJniEnv;

   388     jobject     mDisplay;

   389     jclass*     mJclasses;

   390     jmethodID*  mJmethodIds;

   391     ExecStack   mExecStack;

   392     PtrStack    mObjectsBeingHandled;

   393 };

   394 

   395 }}

   396 

   397 #endif // _JNI_UTILS_H_