0
# Type System and Signatures
1

2
PyJNIus provides a comprehensive type system for generating JNI method signatures and handling type conversions between Python and Java. This system enables precise type specification for manual class definitions and supports automatic type conversion.
3

4
## Capabilities
5

6
### Signature Generation
7

8
Functions for creating JNI method signatures from Python type specifications.
9

10
```python { .api }
11
def signature(returns: type, takes: list) -> str:
12
    """
13
    Generate JNI method signature string from return and parameter types.
14
    
15
    Args:
16
        returns: Return type (primitive, JavaClass, or array type)
17
        takes: List of parameter types
18
        
19
    Returns:
20
        JNI signature string (e.g., '(Ljava/lang/String;I)V')
21
    """
22

23
def with_signature(returns: type, takes: list) -> callable:
24
    """
25
    Decorator that generates signature and applies java_method decorator.
26
    
27
    Args:
28
        returns: Return type specification  
29
        takes: List of parameter type specifications
30
        
31
    Returns:
32
        Decorator function that applies java_method with generated signature
33
    """
34
```
35

36
**Usage Examples:**
37

38
```python
39
from jnius import signature, JavaClass, jint, jvoid
40
from jnius import autoclass
41

42
String = autoclass('java.lang.String')
43

44
# Generate signatures for different method types
45
sig1 = signature(jvoid, [])  # '()V' - no parameters, void return
46
sig2 = signature(jint, [])   # '()I' - no parameters, int return  
47
sig3 = signature(String, [jint])  # '(I)Ljava/lang/String;' - int parameter, String return
48
sig4 = signature(jvoid, [String, jint])  # '(Ljava/lang/String;I)V' - String and int parameters
49

50
# Use with manual class definition
51
from jnius import JavaClass, MetaJavaClass, JavaMethod
52

53
class MyClass(JavaClass, metaclass=MetaJavaClass):
54
    __javaclass__ = 'com/example/MyClass'
55
    
56
    # Using generated signatures
57
    processData = JavaMethod(signature(String, [String, jint]))
58
    getValue = JavaMethod(signature(jint, []))
59
```
60

61
### Primitive Type Specifiers
62

63
Type specifiers for Java primitive types used in signature generation.
64

65
```python { .api }
66
jboolean: type  # Java boolean type specifier
67
jbyte: type     # Java byte type specifier  
68
jchar: type     # Java char type specifier
69
jdouble: type   # Java double type specifier
70
jfloat: type    # Java float type specifier
71
jint: type      # Java int type specifier
72
jlong: type     # Java long type specifier
73
jshort: type    # Java short type specifier
74
jvoid: type     # Java void type specifier
75
```
76

77
**JNI Signature Mapping:**
78

79
- `jboolean` → `Z`
80
- `jbyte` → `B` 
81
- `jchar` → `C`
82
- `jdouble` → `D`
83
- `jfloat` → `F`
84
- `jint` → `I`
85
- `jlong` → `J`
86
- `jshort` → `S`
87
- `jvoid` → `V`
88

89
### Array Type Specifier
90

91
Function for creating array type specifiers from element types.
92

93
```python { .api }
94
def JArray(of_type: type) -> type:
95
    """
96
    Create array type specifier for signature generation.
97
    
98
    Args:
99
        of_type: Element type (primitive, JavaClass, or nested array)
100
        
101
    Returns:
102
        Array type specifier for use in signatures
103
    """
104
```
105

106
**Usage Examples:**
107

108
```python
109
from jnius import JArray, jint, jdouble, signature, autoclass
110

111
String = autoclass('java.lang.String')
112

113
# Array type specifiers
114
int_array = JArray(jint)        # int[] → [I
115
double_array = JArray(jdouble)   # double[] → [D
116
string_array = JArray(String)    # String[] → [Ljava/lang/String;
117

118
# Multi-dimensional arrays
119
int_matrix = JArray(JArray(jint))  # int[][] → [[I
120

121
# Using in signatures
122
array_method_sig = signature(jvoid, [int_array])  # '([I)V'
123
matrix_method_sig = signature(int_matrix, [])     # '()[[I'
124

125
# Manual class with array methods
126
class ArrayProcessor(JavaClass, metaclass=MetaJavaClass):
127
    __javaclass__ = 'com/example/ArrayProcessor'
128
    
129
    processIntArray = JavaMethod(signature(jvoid, [int_array]))
130
    getStringArray = JavaMethod(signature(string_array, []))
131
    createMatrix = JavaMethod(signature(int_matrix, [jint, jint]))
132
```
133

134
### Signature Decorator
135

136
Alternative decorator that uses type specifications instead of raw JNI signatures.
137

138
```python { .api }
139
@with_signature(returns, takes)
140
def method_name(self, ...): ...
141
```
142

143
**Usage Examples:**
144

145
```python
146
from jnius import PythonJavaClass, MetaJavaClass, with_signature
147
from jnius import jint, jvoid, autoclass
148

149
String = autoclass('java.lang.String')
150

151
class Calculator(PythonJavaClass, metaclass=MetaJavaClass):
152
    __javaclass__ = 'com/example/Calculator'
153
    
154
    @with_signature(jint, [jint, jint])
155
    def add(self, a, b):
156
        pass  # Automatically gets signature '(II)I'
157
    
158
    @with_signature(jvoid, [String])
159
    def setName(self, name):
160
        pass  # Automatically gets signature '(Ljava/lang/String;)V'
161
    
162
    @with_signature(String, [])
163
    def getName(self):
164
        pass  # Automatically gets signature '()Ljava/lang/String;'
165

166
# Usage
167
calc = Calculator()
168
result = calc.add(5, 3)  # 8
169
calc.setName('MyCalculator')
170
name = calc.getName()    # 'MyCalculator'
171
```
172

173
### Internal Type Processing
174

175
Internal functions used by the signature system for type analysis.
176

177
```python { .api }
178
def _jni_type_spec(jclass: type) -> str:
179
    """
180
    Generate JNI type specification string for a given type.
181
    
182
    Args:
183
        jclass: Type to analyze (JavaClass, primitive, or array)
184
        
185
    Returns:
186
        JNI type specification string
187
        
188
    Note:
189
        Internal function used by signature generation system.
190
    """
191

192
def get_signature(cls_tp) -> str:
193
    """
194
    Convert a Java Class type to its JNI signature string.
195
    
196
    Args:
197
        cls_tp: Java Class object or type
198
        
199
    Returns:
200
        JNI signature string for the class
201
        
202
    Note:
203
        Used by reflection system for type analysis.
204
    """
205
```
206

207
This function handles the conversion between Python type objects and JNI type specification strings:
208

209
- JavaClass subclasses → `L<classname>;` format
210
- Primitive type specifiers → Single character codes
211
- Array types → `[<element_type>` format
212

213
### Type Conversion Behavior
214

215
PyJNIus automatically handles type conversion between Python and Java:
216

217
**Python to Java:**
218
- `bool` → `boolean`
219
- `int` → `int`, `long`, `byte`, `short` (based on range)
220
- `float` → `double`, `float`
221
- `str` → `String`
222
- `list` → Java arrays (when appropriate)
223
- `dict` → `Map` implementations (when appropriate)
224

225
**Java to Python:**
226
- Java primitives → Corresponding Python types
227
- Java strings → Python strings
228
- Java arrays → Python lists (when accessed)
229
- Java collections → Python-like objects with protocol support
230

231
**Manual Control:**
232
For precise control over type conversion, use explicit type specifications in signatures and cast functions for runtime type conversion.