Javatrans Java-to-C++ mapping

Chris Greenhalg, 2006-03-29; last updated 2007-05-30

Introduction

This document describes some aspects of Javatrans' mapping from Java to C++.

Primitive types

The following tables lists the Java primitive types, the C++ macro used in the generated C++ code and the actual types used on Windows and Symbian. (see ../src.cpp/include/java_platform.h)

Java type	Description	C++ Macro	Windows type	Unix type	Symbian type
boolean	true/false	JAVA_BOOLEAN	bool	bool	TBool
byte	8 bit signed int	JAVA_BYTE	char	char	TInt8
short	16 bit signed int	JAVA_SHORT	short	short	TInt16
int	32 bit signed int	JAVA_INT	int	int	TInt32
long	64 bit signed int	JAVA_LONG	long long	long long	TInt64
char	16 bit signed int and unicode character	JAVA_CHAR	_TCHAR[*]	wchar_t	TText
float	32 bit float	JAVA_FLOAT	float	float	TReal32
double	64 bit float	JAVA_DOUBLE	double	double	TReal64

[*] _TCHAR compiles to char or WCHAR depending on wether _UNICODE is defined - it should be.

Strings

As a direct translation from Java, all application strings will be instances of (hand-crafter) class java_lang_String, which is an immutable string. Internally, the strings are currently:

on Windows: const TCHAR*
on Symbian: const TDescC&
on Unix: const JAVA_CHAR* (const wchar_t*)

To facilitate cross-platform coding with strings the following macros are defined:

STRING_LITERAL(NAME,STRING) - defines NAME as a (static) immutable native string variable, with value given by the (double-quoted) STRING.
STRING_LIT(STRING) - allows (double-quoted) STRING to be used inline as a string constant value (but note that on Symbian although the string text is constant the wrapper instance generated by which macro is NOT - use STRING_LITERAL if a reference to it could persist outside of its immediate scope.)
STRING_COMPARE(S1,S2) - is strcmp(S1,S2) on windows. wcscmp(S1,S2) on Unix or S1.Compare(S2) on Symbian.

Classes

To maintain compatibility with Symbian C++ there can be no multiple inheritance. Consequently, interface classes cannot derive from java_lang_Object. To work-around this a set of common virtual methods are defined in java_lang_Object and also in all interface classes which support casting to java_lang_Object and to specific classes. However, this means that built-in C++ coercions typically do not work.

Exceptions

Because of the class mapping checking the class compatibility of exception classes cannot be done by the C++ compiler, but must be done by explicit run-time tests. Consequently, ANSI C++ exceptions cannot use the mapped Java exception classes directly. In addition, Symbian does not have standard ANSI exception handling, but its own more restricted system (only int values can be thrown). Consequently, exception handling is handled in a cross-platform manner using the following macros (shown in a typical example):

int myfunction(int arg1) JAVA_THROWS2(java_lang_RuntimeException,me_MyException) {
  JavaPtr<me_MyException> ex = new me_MyException();
  ex->init(arg1);
  JAVA_THROW(ex);
}
int myfunction2(int arg1) JAVA_THROWS1(java_lang_RuntimeException) {
  JAVA_TRY
    myfunction(arg1);
  JAVA_END_TRY
  JAVA_CATCH(me_MyException, me) 
    JAVA_LOG(STRING_LIT("bang!"));
  JAVA_END_CATCH
  JAVA_CHECK_HANDLED
}

Other cross-platform variations and macros

Symbian has no native 64-bit integer; TInt64 is a C++ class. It does not have predefined coercion operators to/from int, nor does it have bit-wise logical operators defined. Consequently these are provided by macros defined in ../src.cpp/include/java_platform.h.

Macros are defined for DLL import/export of functions, JAVA_IMPORT and JAVA_EXPORT, and inserted into all generated code, anticipating that it will be placed in a DLL. For libraries <libraryname>_IMPORT is used to specify import and is #defined as JAVA_EXPORT or JAVA_IMPORT according to whether the header file is included from a file within the library or outside it..

Other cross platform and/or placeholder macros defined and used in the generated code are:

JAVA_LOG(ARG) - output a text message
JAVA_ERROR(ARG) - signal a (major) error

Global variables (class static fields)

Symbian does not generally allow mutable global variables. The translation process therefore collects static (class) fields into a single (per-library) data-structure, which is initialised on a per-application basis under Symbian (process-wide on Windows). The fields are accessed via the macro:

GLOBAL_FIELD(CLASSNAME,FIELDNAME) - defined in ../src.cpp/include/java_global.h

The following macros are also generated, but are defined to have no effect - they simple serve as documentation in the class file(s) of the existence of global fields in the generated globals.inc file(see Javatrans_introduction.html):

DECLARE_GLOBAL_FIELD(TYPE,FIELDNAME)
DEFINE_GLOBAL_FIELD(TYPE,CLASSNAME,FIELDNAME)

Known issues

See Javatrans_introduction.html

Change log

2007-05-30

added classes & exceptions sections; added unix type mappings; updated windows char type

2006-05-04

updates to reflect library-based organisation and include directory

2006-03-29

This document created.