jnix_macros/lib.rs
1//! This is a companion crate to [`jnix`] that provides some procedural macros for interfacing JNI
2//! with Rust. See the [`jnix` crate documentation][doc] for more information
3//!
4//! [`jnix`]: https://crates.io/crates/jnix
5//! [doc]: https://docs.rs/jnix/
6
7#![deny(missing_docs)]
8
9extern crate proc_macro;
10
11mod attributes;
12mod fields;
13mod generics;
14mod parsed_type;
15mod variants;
16
17use crate::{
18 attributes::JnixAttributes,
19 fields::ParsedFields,
20 generics::{ParsedGenerics, TypeParameters},
21 parsed_type::ParsedType,
22 variants::ParsedVariants,
23};
24use proc_macro::TokenStream;
25use syn::{parse_macro_input, DeriveInput};
26
27/// Derives `FromJava` for a type.
28///
29/// More specifically, `FromJava<'env, JObject<'sub_env>>` is derived for the type. This also makes
30/// available a `FromJava<'env, AutoLocal<'sub_env, 'borrow>>` implementation through a blanket
31/// implementation.
32///
33/// The name of the target Java class must be known for code generation. Either it can be specified
34/// explicitly using an attribute, like so: `#[jnix(class_name = "my.package.MyClass"]`, or it can
35/// be derived from the Rust type name as long as the containing Java package is specified using an
36/// attribute, like so: `#[jnix(package = "my.package")]`.
37///
38/// # Structs
39///
40/// The generated `FromJava` implementation for a struct will construct the Rust type using values
41/// for the fields obtained using getter methods. Each field name is prefixed with `get_` before
42/// converted to mixed case (also known sometimes as camel case). Therefore, the source object must
43/// have the necessary getter methods for the Rust type to be constructed correctly.
44///
45/// For tuple structs, since the fields don't have names, the field index starting from one is
46/// used as the name. Therefore, the source object must have getter methods named `component1`,
47/// `component2`, ..., `componentN` for the "N" number of fields present in the Rust type. This
48/// follows the convention used by Kotlin for a `data class`, so they are automatically generated
49/// by the Kotlin complier for `data class`es.
50///
51/// In either case, fields can be skipped and constructed using `Default::default()` by using the
52/// `#[jnix(default)]` attribute.
53///
54/// # Enums
55///
56/// The generate `FromJava` implementation for an enum that only has unit variants (i.e, no tuple
57/// or struct variants) assumes that the source object is an instance of an `enum class`. The
58/// source reference is compared to the static fields representing the entries of the `enum class`,
59/// and once an entry is found matching the source reference, the respective variant is
60/// constructed.
61///
62/// When an enum has at least one tuple or struct variant, the generated `FromJava` implementation
63/// will assume that that there is a class hierarchy to represent the type. The source Java class
64/// is assumed to be the super class, and a nested static class for each variant is assumed to be
65/// declared in that super class. The source object is checked to see which of the sub-classes it
66/// is an instance of. Once a sub-class is found, the respective variant is created similarly to
67/// how a struct is constructed, so the same rules regarding the presence of getter methods apply.
68///
69/// # Examples
70///
71/// ## Structs with named fields
72///
73/// ```rust
74/// #[derive(FromJava)]
75/// #[jnix(package = "my.package")]
76/// pub struct MyClass {
77/// first_field: String,
78/// second_field: String,
79/// }
80/// ```
81///
82/// ```java
83/// package my.package;
84///
85/// public class MyClass {
86/// private String firstField;
87/// private String secondField;
88///
89/// public MyClass(String first, String second) {
90/// firstField = first;
91/// secondField = second;
92/// }
93///
94/// // The following getter methods are used to obtain the values to build the Rust struct.
95/// public String getFirstField() {
96/// return firstField;
97/// }
98///
99/// public String setSecondField() {
100/// return secondField;
101/// }
102/// }
103/// ```
104///
105/// ## Tuple structs
106///
107/// ```rust
108/// #[derive(FromJava)]
109/// #[jnix(class_name = "my.package.CustomClass")]
110/// pub struct MyTupleStruct(String, String);
111/// ```
112///
113/// ```java
114/// package my.package;
115///
116/// public class CustomClass {
117/// private String firstField;
118/// private String secondField;
119///
120/// public MyClass(String first, String second) {
121/// firstField = first;
122/// secondField = second;
123/// }
124///
125/// // The following getter methods are used to obtain the values to build the Rust tuple
126/// // struct.
127/// public String component1() {
128/// return firstField;
129/// }
130///
131/// public String component2() {
132/// return secondField;
133/// }
134/// }
135/// ```
136///
137/// ## Simple enums
138///
139/// ```rust
140/// #[derive(FromJava)]
141/// #[jnix(package "my.package")]
142/// pub enum SimpleEnum {
143/// First,
144/// Second,
145/// }
146/// ```
147///
148/// ```java
149/// package my.package;
150///
151/// public enum SimpleEnum {
152/// First, Second
153/// }
154/// ```
155///
156/// ## Enums with fields
157///
158/// ```rust
159/// #[derive(FromJava)]
160/// #[jnix(package "my.package")]
161/// pub enum ComplexEnum {
162/// First {
163/// name: String,
164/// },
165/// Second(String, String),
166/// }
167/// ```
168///
169/// ```java
170/// package my.package;
171///
172/// public class ComplexEnum {
173/// public static class First extends ComplexEnum {
174/// private String name;
175///
176/// public First(String name) {
177/// this.name = name;
178/// }
179///
180/// public String getName() {
181/// return name;
182/// }
183/// }
184///
185/// public static class Second extends ComplexEnum {
186/// private String a;
187/// private String b;
188///
189/// public Second(String a, String b) {
190/// this.a = a;
191/// this.b = b;
192/// }
193///
194/// public String component1() {
195/// return a;
196/// }
197///
198/// public String component2() {
199/// return b;
200/// }
201/// }
202/// }
203/// ```
204#[proc_macro_derive(FromJava, attributes(jnix))]
205pub fn derive_from_java(input: TokenStream) -> TokenStream {
206 let parsed_type = ParsedType::new(parse_macro_input!(input as DeriveInput));
207
208 TokenStream::from(parsed_type.generate_from_java())
209}
210
211/// Derives `IntoJava` for a type.
212///
213/// The name of the target Java class must be known for code generation. Either it can be specified
214/// explicitly using an attribute, like so: `#[jnix(class_name = "my.package.MyClass"]`, or it can
215/// be derived from the Rust type name as long as the containing Java package is specified using an
216/// attribute, like so: `#[jnix(package = "my.package")]`.
217///
218/// # Structs
219///
220/// The generated `IntoJava` implementation for a struct will convert the field values into their
221/// respective Java types. Then, the target Java class is constructed by calling a constructor with
222/// the converted field values as parameters. Note that the field order is used as the constructor
223/// parameter order.
224///
225/// Fields can be "preconverted" to a different Rust type, so that the resulting type is then used
226/// to convert to the Java type. To do so, use the `#[jnix(map = "|value| ...")]` attribute with a
227/// conversion closure.
228///
229/// Fields can be skipped using the `#[jnix(skip)]` attribute, so that they aren't used in the
230/// conversion process, and therefore not used as a parameter for the constructor. The
231/// `#[jnix(skip_all)]` attribute can be used on the struct to skip all fields.
232///
233/// The target class of a specific field can be set manually with the
234/// `#[jnix(target_class = "...")]` attribute. However, be aware that the target class must have
235/// the expected constructor with the parameter list based on the field order of the Rust type.
236///
237/// # Enums
238///
239/// The generated `IntoJava` implementation for a enum that only has unit variants (i.e., no tuple
240/// or struct variants) returns a static field value from the specified Java target class. The
241/// name used for the static field in the Java class is the same as the Rust variant name. This
242/// allows the Rust enum to be mapped to a Java enum.
243///
244/// When an enum has at least one tuple or struct variant, the generated `IntoJava` implementation
245/// will assume that that there is a class hierarchy to represent the type. The target Java class
246/// is used as the super class, and is the Java type returned from the conversion. The class is
247/// assumed to have one inner class for each variant, and the conversion actually instantiates an
248/// object for the respective variant type, using the same rules for the fields as the rules for
249/// struct fields.
250///
251/// For both cases, variants can be prevented from being constructed from their respective Java
252/// entries or sub-classes by using the `#[jnix(deny)]` attribute. If one of the entries is used in
253/// an attempt to convert to the equivalent Rust variant, the code panics.
254#[proc_macro_derive(IntoJava, attributes(jnix))]
255pub fn derive_into_java(input: TokenStream) -> TokenStream {
256 let parsed_type = ParsedType::new(parse_macro_input!(input as DeriveInput));
257
258 TokenStream::from(parsed_type.generate_into_java())
259}