Build-time POJO annotation frameworks: JSON/XML mapping, component binding, SQLite ORM

CodenameOne/src/com/codename1/annotations/Bind.java

@@ -0,0 +1,90 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codename1.annotations;
+
+import com.codename1.binding.BindAttr;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/// Pairs a `@Bindable` field with the component it should mirror.
+///
+/// `name` is the value the target component returns from
+/// `Component#getName()`. `attr` picks the attribute to write: text, UIID,
+/// selected state, visible / hidden, the icon name, or the component name
+/// itself.
+///
+/// One-way bindings push from the model to the component on
+/// `Binders.bind`. Two-way bindings additionally listen for user input on
+/// text fields, text areas, and check boxes so changes flow back into the
+/// model.
+///
+/// #### Accessor resolution
+///
+/// The annotation processor decides how to read and write the field in
+/// this order:
+///
+/// 1. **Explicit accessor names** -- `@Bind(getter="getX", setter="setX")`.
+///    Use this when the JavaBeans naming convention doesn't match (a
+///    fluent setter, a renamed boolean, ...).
+/// 2. **JavaBeans accessors** when both `getter` and `setter` are blank:
+///    `getFoo()` / `isFoo()` for the getter, `setFoo(T)` for the setter.
+///    Detected from the project's compiled bytecode -- no runtime
+///    reflection.
+/// 3. **Direct public-field access** as a last resort. The processor
+///    fails the build with a clear error when the field is private and
+///    no usable accessor exists.
+///
+/// For two-way bindings the build-time processor instruments the resolved
+/// setter to call `Binders.notifyChanged(this)` at every return point.
+/// Application code can mutate the model through the setter from anywhere
+/// and the bound component refreshes automatically; see
+/// `Annotation-Component-Binding.asciidoc` for the loop-guard details.
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.FIELD)
+public @interface Bind {
+    /// `Component#getName()` of the target component.
+    String name();
+
+    /// Which property of the component the field mirrors. Default: `TEXT`.
+    BindAttr attr() default BindAttr.TEXT;
+
+    /// When false the binding is one-way (model -> component only).
+    /// Default `true` for `TEXT` against editable components and for
+    /// `SELECTED`; for all other attributes the binding is implicitly
+    /// one-way regardless of this flag.
+    boolean twoWay() default true;
+
+    /// Explicit getter method name. Default: empty -- the processor uses
+    /// JavaBeans `get<Field>` / `is<Field>` discovery, then falls back to
+    /// direct public-field access.
+    String getter() default "";
+
+    /// Explicit setter method name. Default: empty -- the processor uses
+    /// JavaBeans `set<Field>` discovery, then falls back to direct
+    /// public-field assignment. The resolved setter (whether explicit or
+    /// detected) is instrumented for two-way bindings.
+    String setter() default "";
+}

CodenameOne/src/com/codename1/annotations/Bindable.java

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codename1.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/// Marks a POJO or `PropertyBusinessObject` as a target for the component
+/// binding processor. The Codename One Maven plugin generates a `Binder` next
+/// to the class that copies the marked fields into the matching components of
+/// a `Container` -- and back, for two-way bindings against `TextField`,
+/// `TextArea`, `CheckBox`, and friends.
+///
+/// ```java
+/// @Bindable
+/// public class LoginModel {
+///     @Bind(name="userField", attr=BindAttr.TEXT)
+///     public Property<String, LoginModel> user = new Property<>("user");
+///
+///     @Bind(name="rememberMe", attr=BindAttr.SELECTED)
+///     public boolean remember;
+/// }
+///
+/// LoginModel model = new LoginModel();
+/// Binders.bind(model, form);
+/// // user types into userField -- model.user.get() observes the change
+/// // model.user.set("alice") -- userField re-renders with the new text
+/// ```
+///
+/// Lookup happens through `Component#getComponentForm().findByName(name)` so
+/// the form's GUI builder names line up with the model field names.
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.TYPE)
+public @interface Bindable {
+}

CodenameOne/src/com/codename1/annotations/Column.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codename1.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/// Renames or constrains an `@Entity` field's column. Optional -- when absent,
+/// the column name defaults to the field name and the type is inferred from
+/// the Java field type (`String -> TEXT`, `int/long -> INTEGER`,
+/// `float/double -> REAL`, `boolean -> INTEGER`, `byte[] -> BLOB`,
+/// `java.util.Date -> INTEGER`).
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.FIELD)
+public @interface Column {
+    /// Column name. Defaults to the field name when blank.
+    String name() default "";
+
+    /// When false the column gets a `NOT NULL` constraint at table-create time.
+    boolean nullable() default true;
+
+    /// Optional explicit SQL type. Use the SQLite type names (`TEXT`,
+    /// `INTEGER`, `REAL`, `BLOB`, `NUMERIC`). When blank the processor infers
+    /// the type from the field's Java type.
+    String type() default "";
+}

CodenameOne/src/com/codename1/annotations/DbTransient.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codename1.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/// Excludes an `@Entity` field from the generated table. Useful for computed
+/// fields, caches, or fields shared only with the JSON / XML projection.
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.FIELD)
+public @interface DbTransient {
+}

CodenameOne/src/com/codename1/annotations/Entity.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codename1.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/// Marks a POJO or `PropertyBusinessObject` as a target for the SQLite ORM
+/// processor.
+///
+/// At build time the Codename One Maven plugin generates a reflection-free
+/// `Dao` next to the class with `createTable`, `insert`, `update`, `delete`,
+/// `findById`, `findAll`, and `find(where, params)` methods. Application code
+/// reaches the generated dao through `com.codename1.orm.EntityManager`:
+///
+/// ```java
+/// @Entity(table="users")
+/// public class User {
+///     @Id(autoIncrement=true) public long id;
+///     @Column(name="full_name") public String name;
+///     public int age;
+/// }
+///
+/// EntityManager em = EntityManager.open("MyDB");
+/// Dao<User> users = em.dao(User.class);
+/// users.createTable();
+/// users.insert(new User());
+/// ```
+///
+/// The dao uses the same prepared-statement protocol as the existing
+/// `com.codename1.db.Database`; no `Class.forName` lookups, so the binding
+/// survives ParparVM rename / R8 obfuscation in shipped builds.
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.TYPE)
+public @interface Entity {
+    /// SQL table name. Defaults to the simple class name when blank.
+    String table() default "";
+}

CodenameOne/src/com/codename1/annotations/Id.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codename1.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/// Designates the primary-key field of an `@Entity`. Exactly one field per
+/// entity must carry `@Id`. The field type may be `long`, `int`, `String`, or
+/// a `Property` wrapper of one of those.
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.FIELD)
+public @interface Id {
+    /// When true (the default) the underlying column is declared
+    /// `INTEGER PRIMARY KEY AUTOINCREMENT`. Set false when the application
+    /// assigns its own keys (UUIDs, server-issued ids, ...).
+    boolean autoIncrement() default true;
+}

CodenameOne/src/com/codename1/annotations/JsonIgnore.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codename1.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/// Excludes a `@Mapped` field from the JSON projection. The same field still
+/// participates in XML mapping unless `@XmlTransient` is also present.
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.FIELD)
+public @interface JsonIgnore {
+}