pas2jni: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		# Overview
2	2
3	3		The pas2jni utility generates a JNI (Java Native Interface) bridge for a Pascal code. Then the Pascal code (including classes and other advanced features) can be easily used in Java programs on various platforms, including [[Android]].
4	4
5	5		For example you can do the following in Java:
6	6
7	7		``` java
8	8		import pas.classes.*;
9	9
10	10		...
11	11
12	12		TStringList sl = TStringList.Create();
13	13		sl.Add("Hello.");
14	14		String s = sl.getStrings(0);
15	15		sl.Free();
16	16
17	17		...
18	18		```
19	19
20	20		The following Pascal features are supported by pas2jni:
21	21
22	22		- function/procedure;
23	23		- var/out parameters;
24	24		- class;
25	25		- interface;
26	26		- object;
27	27		- record;
28	28		- property;
29	29		- constant;
30	30		- enum;
31	31		- set (32 elements maximum);
32	32		- TGuid type;
33	33		- pointer type;
34	34		- string types;
35	35		- all numeric types;
36	36		- method pointer;
37	37		- array (limited support: setters/getters for array elements).
38	38
39	39		USUPPORTED features:
40	40
41	41		- array (full support);
42	42		- set (with 32+ elements);
43	43		- procedure pointer (Not possible to implement. To workaround this limitation create a procedure handler in your Pascal code and call a method pointer declared in some global Pascal class. Then you can assign this method pointer from a Java code).
44	44
45	45		Shared libraries, generated by pas2jni were tested with Java on Windows and Android. It should work on other systems as well.
46	46
47	47		# How to use
48	48
49	49		pas2jni uses the [[PPUDump]] utility included with Free Pascal Compiler to read unit interfaces. Therefore your Pascal code must be first compiled with FPC. When your units are compiled, you can run pas2jni. You need to specify a list of main units and units search path. When you specify a main unit, all its interface declarations will be available in Java. For linked units only used declarations will be available. You can fine tune included/excluded declaration using `-I` and `-E` command line options.
50	50
51	51		The basic invocation of pas2jni:
52	52
53		-	~~`pas2jni myunit -U/path/to/my/units;/path/to/FPC/units/*`~~
	53	+	```text
	54	+	pas2jni myunit -U/path/to/my/units;/path/to/FPC/units/*
	55	+	```
54	56
55	57		Here you specify myunit as the main unit and provide path to your compiled units and FPC compiled units.
56	58
57	59		After successfull run of pas2jni you will get the following output files:
58	60
59	61		- file `myunitjni.pas` - a generated library unit to be compiled to a shared library. It will contain all your Pascal code to be used from Java.
60	62		- folder `pas` - generated Java package `pas` to be used in your Java program. Interface to each Pascal unit is placed to a separate Java public class.
61	63
62	64		Note: You need to use ppudump of the same version as the FPC compiler. Use the `-D` switch to specify correct ppudump if it is not in `PATH`.
63	65
64	66		# Custom handlers
65	67
66	68		It is possible to define the following custom handlers in your Pascal code.
67	69
68	70		`procedure JNI_OnException;`
69	71
70	72		- It is called when an unhandled Pascal exception occurs. For example, you can log a stack back trace in this handler.
71	73
72	74		Custom handlers must be public and defined in one of the main units specified when calling pas2jni.
73	75
74	76		# Coding tips
75	77
76	78		## Setting handlers (method pointers) in a Java code.
77	79
78	80		For example there is the following class and event handler in your Pascal code:
79	81
80	82		``` pascal
81	83		type TMyClass = class
82	84		//...
83	85		property OnChange: TNotifyEvent;
84	86		//...
85	87		end;
86	88		```
87	89
88	90		In Java code, you add the event handler in a usual Java way:
89	91
90	92		``` java
91	93		// Create an instance of TMyClass
92	94		TMyClass myClass = TMyClass.Create();
93	95
94	96		// Set the event handler
95	97		myClass.setOnChange(
96	98		new TNotifyEvent() {
97	99		protected void Execute(TObject Sender) {
98	100		// The handler code
99	101		}
100	102		}
101	103		);
102	104
103	105		// Work with myClass
104	106		// ...
105	107		// ...
106	108
107	109		// Remove the handler to avoid memory leak
108	110		myClass.setOnChange(null);
109	111		// Free the object
110	112		myClass.Free();
111	113		```
112	114
113	115		NOTE: If you are setting handlers (method pointers) for short living objects, it is needed to explicitly remove the handlers before the object destruction by setting the null handler. Otherwise you will reach the active handlers limit (10000 handlers) and your application will crash.
114	116
115	117		## Type casting
116	118
117	119		In some cases type casting for generated Java classes does not work as expected. For example, the following code will not compile:
118	120
119	121		``` java
120	122		contnrs.TObjectList objList = contnrs.TObjectList.Create();
121	123		classes.TList list = objList;
122	124		```
123	125
124	126		Though `TObjectList` is inherited from `TList` and similar code works in Pascal, the generated Java classes use a bit different class hierarchy in this case. An intermediate class `__TList` is used and `TList` is not ancestor for `TObjectList` anymore. The `__TList` class is needed to handle method reintroducing, which is allowed in Pascal, but not allowed in Java.
125	127
126	128		You need to use the following type casting trick in such case:
127	129
128	130		``` java
129	131		classes.TList list = new classes.TList(objList);
130	132		```
131	133
132	134		The same type casting method is used to cast a pointer to an object:
133	135
134	136		``` java
135	137		// Create a list
136	138		classes.TList list = classes.TList.Create();
137	139		// Get a pointer to the list
138	140		long pList = system.Pointer(list);
139	141		// Type cast the pointer to the new TObject variable
140	142		system.TObject list2 = new system.TObject(pList);
141	143		```
142	144
143	145		## Passing Java objects to Pascal code
144	146
145	147		In some cases it is needed to pass native Java objects to your Pascal code and handle them directly using JNI functions. For example, you can pass a Java array to your Pascal code to perform some quick processing of the array's data.
146	148
147	149		To do that you need to use a specially defined type `TJavaObject`. Use this type for function parameters to indicate that this parameter expect a Java object without any special processing.
148	150
149	151		Also it is needed a pointer to the JNI environment in order to call JNI functions. Just add a parameter of type `PJNIEnv` to access the JNI environment using this parameter.
150	152
151	153		Here an example:
152	154
153	155		``` pascal
154	156		// Define a special type TJavaObject. The declaration must be exactly as shown here
155	157		type
156	158		TJavaObject = type jobject;
157	159
158	160		// Define your procedure
159	161		procedure HandleJavaObject(env: PJNIEnv; obj: TJavaObject; myParam: longint);
160	162		begin
161	163		// Work with native Java object 'obj' using JNI functions accessible via 'env'.
162	164		// ...
163	165		end;
164	166		```
165	167
166	168		You will get the following generated declaration in Java for this procedure:
167	169
168	170		``` java
169	171		public native static void HandleJavaObject(Object obj, int myParam);
170	172		```
171	173
172	174		# Command line options
173	175
174	176		Usage: pas2jni [options] <unit> [<unit2> <unit3> ...]
175	177
176	178		Options:
177	179		-U<path> - Unit search path, semicolon delimited. Wildcards are allowed.
178	180		-L<name> - Set output library name.
179	181		-P<name> - Set Java package name.
180	182		-O<path> - Set output path for Pascal files.
181	183		-J<path> - Set output path for Java files.
182	184		-D<prog> - Set full path to the "ppudump" program.
183	185		-I<list> - Include the list of specified objects in the output. The list is
184	186		semicolon delimited. To read the list from a file use -I@<file>
185	187		-E<list> - Exclude the list of specified objects from the output. The list is
186	188		semicolon delimited. To read the list from a file use -E@<file>
187	189		-? - Show this help information.
188	190
189	191		---
190	192		From the Free Pascal wiki, page "pas2jni", as it stood on 2020-01-29 after a change by Yurysidorov, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
191	193		Category: FPC
192	194		Category: Utilities

Back to history