Maven goals

The build goal is used to send builds to the Codename One build server. It also supports a few local build targets, such as ios-source, which generates an Xcode project, and android-source which generates an Android Gradle project.

This goal is bound to the package phase of the Codename One application project archetype (cn1app-archetype), so you don’t need to run this directly.

This goal generates a legacy.cn1lib file. It’s bound to the package phase of cn1lib-archetype projects so you will never need to run this goal directly.

This will output the cn1lib file inside the common/target directory of the root multimodule maven project.

Checks API usage in the project’s "common" module to ensure that it doesn’t use any classes or methods that aren’t supported by Codename One.

This goal is bound to the process-classes phase of both Codename One application project archetype (cn1app-archetype) projects and Codename One library project archetype (cn1lib-archetype) projects, so you shouldn’t ever need to run this goal directly.

Compiles the project’s CSS files, generating a theme.res file which is placed in the build/classes directory.

This goal is bound to the process-classes phase of Codename One application project archetype (cn1app-archetype) projects, so you shouldn’t need to run this goal directly.

Generates a Maven project using the Codename One application project archetype (cn1app-archetype) as a basis, and applying an optional project template. This goal can also be used to migrate legacy Codename One Ant-based Application projects into maven.

This goal shouldn’t be run inside an existing Maven project directory. It will output a project into a directory named after the artifactId parameter.

Because there is no existing project, you will need to provide the full maven path to the goal:

In the above example, assuming all went well, it would output your project into a directory named myapp.

When providing an Ant-based Codename One application project as the sourceProject parameter, this goal will generate an equivalent Maven project to the Ant project, with the same settings and sources.

See Migrating an existing project for examples using this goal to migrate an existing project into Maven.

When using a Codename One application project archetype (cn1app-archetype) maven project as the sourceProject parameter, the project will be treated project template, and perform some basic processing of the source files as necessary convert the template into a real project. This includes replacing all occurrences of ${mainName} and ${packageName} in project sources with the value of the mainName and packageName parameters provided on the command-line.

Any occurrences of mainName and packagePath in file or directory names will be swapped with the values of mainName and packagePath (which is automatically derived from packageName by substituting '.' with file separators).

The (optional) secret sauce that differentiates a regular Maven project from a Maven project template is the existence of a generate-app-project.rpf file in the root project directory. This file is in rich property file format, and allows you to define a minimal amount of configuration details that the generate-app-project goal needs to convert the template into a real project.

This file may contain the following properties:

As a fuller example of a project template, see the generate-app-project.rpf file in the bare-bones Kotlin app template.

This is the template that’s used in Codename One initializr for the Bare-bones Kotlin project.

Clones the current project as a new project with a different groupId, artifactId, packageName, and mainName. Resulting project will be made available in the common/target/generated-sources/cn1-cloned-projects directory.

In the above example, assuming all went well, it would output your project into a directory named myapp.

The create-gui-form goal will generate a GUI form that can be edited in the GUI builder.

Basic Usage Example

The above example will generate a GUIBuilder form with the provided class name. It effectively generates two files:

You can then open the GUI builder to edit this form using the cn1:guibuilder goal:

Generates a Maven cn1lib project (using the cn1lib-archetype) given an ANT cn1lib project as a template.

This is to assist in migrating Ant projects to Maven projects. This won’t make any changes to the source Ant project. It generates a new project using the Codename One library project archetype (cn1lib-archetype) and copies all files and configuration from the source project, into the new project.

Suppose you have an Ant Codename One library project at /path/to/MyLegacyAntLibraryProject and you want to convert it to a Maven project.

You can run the generate-cn1lib-project goal as follows:

Some notes about this command as shown above:

If all goes well, you should find a new maven project generated in the "your-maven-lib" directory (named after the artifactId that you specified).

To test that the project was generated successfully, try opening the resulting project in your IDE or run its "install" goal on the command-line.

For example:

After running the "install" command, you should be able to add your library as a dependency to a Codename One application project archetype (cn1app-archetype) project using the following dependency:

See Codename One libraries for more information about the resulting maven library project.

Generates the bootstrapping wrapper class for the Java SE desktop app. This is used by the Java SE module of Codename One application project archetype (cn1app-archetype) projects.

You shouldn’t need to call this goal directly.

Generates Java sources from the Codename One GUI builder files. This goal is bound to the process-sources phase of Codename One application project archetype (cn1app-archetype) projects, so you should never need to run this goal explicitly.

Generates stub implementations for all native interfaces defined in the project. This won’t overwrite any existing implementations that may exist.

You should run this goal explicitly after you create a native interface in your class.

See the Codename One Developer guide section on native interfaces for more information on creating native interfaces.

Suppose you’ve created a native interface as the Java interface com.mycompany.myapp.MyNative, as described in the example in native interfaces.

After creating this (and possibly other) native interfaces in your project, run the generate-native-interfaces Maven goal as follows:

By default this generates Java/Objective-C stubs. You can optionally include Swift and Kotlin stubs (both off by default):

This will generate the following files (if they don’t exist yet).

Open and edit these files to implement your native interface methods as desired.

Generates a typed Codename One client from an OpenAPI 3.x JSON specification. Writes one @Mapped record (Java 17+) or class (Java 8 target) per components.schemas entry and one @RestClient-annotated interface per OpenAPI tag. The generated files land in common/src/main/java so the project owns the contract; the matching networking implementation is emitted into common/target/generated-sources by the build-time annotation processor so the project source stays clean.

The mojo is paired with the existing process-annotations pipeline: identical schemas across operations collapse to one record/class, and operationIds become interface methods that resolve at runtime via a com.codename1.io.rest.RestClients registry populated by the generated bootstrap class (the same splice pattern as @Mapped mappers).

Configuration:

The listings in this section are the goal’s own output, generated from a Swagger Petstore specification cut down to the pet, store and user tags. That spec is in the repository at docs/demos/common/src/main/snippets/developer-guide/appendix-goal-generate-openapi-petstore.json, so you can run the goal against it and compare. The committed copies carry a license header and the tag:: markers this guide includes them by; strip those two additions and the rest is exactly what the goal wrote.

One @RestClient interface per tag and one model per schema land under common/src/main/java:

Tag.java is missing from that list on purpose. The Petstore declares Tag and Category with the same two properties, and identical shapes collapse to one record, so Pet.tags() comes back typed as a list of Category. Give the two schemas different shapes if you want them to stay separate classes.

Each @RestClient interface method is annotated with the HTTP verb and path; parameters are annotated @Path / @Query / @Header / @Body so the processor knows how to assemble the Rest call. The emitted method shape:

The model type referenced by the generated API is emitted into the generated model package:

Model types are emitted as fully qualified names (the API interface lives in <basePackage> and models under <basePackage>.model) so the generator never needs to track imports or worry about collisions between an API class name and a same-named model.

Call sites use the static factory:

The <Tag>ApiImpl class that actually performs the HTTP call lives in target/generated-sources — the project source never references it directly. The build server probes the project zip for the generated cn1app.RestClientBootstrap and splices the registry wiring in, mirroring the existing cn1app.MapperBootstrap pattern.

Generates a typed Codename One gRPC-Web client from a proto3 .proto specification. Writes one @ProtoMessage record (Java 17+) or class (Java 8 target) per message, one @ProtoEnum enum per enum, and one @GrpcClient-annotated interface per service. The generated files land in common/src/main/java so the project owns the contract; the matching protobuf codec and gRPC-Web call site are emitted into common/target/generated-sources by the build-time annotation processors so the project source stays clean.

The mojo is paired with the existing process-annotations pipeline: @ProtoMessage triggers per-class binary protobuf codec generation and a cn1app.ProtoBootstrap registration entry; @GrpcClient triggers per-interface <Service>GrpcImpl generation chained through com.codename1.io.grpc.GrpcWeb.invokeUnary(…​) and a cn1app.GrpcClientBootstrap that wires everything to the com.codename1.io.grpc.GrpcClients registry (same splice pattern as @Mapped mappers).

Configuration:

For a helloworld.proto declaring message HelloRequest, message HelloReply, enum Mood, and service Greeter { rpc SayHello(HelloRequest) returns (HelloReply); }, the goal emits under common/src/main/java:

Each @ProtoMessage carries one @ProtoField(tag = N) per field; scalar fields use the default varint wire kind, sint32 / sint64 use wireType = ProtoField.WireKind.SINT, and fixed32 / fixed64 / sfixed32 / sfixed64 use wireType = ProtoField.WireKind.FIXED. Renamed fields (e.g. snake_case → camelCase) carry the original proto name via the optional name attribute so introspection tooling can recover it.

The @GrpcClient interface looks like:

Call sites use the static factory:

The <Service>GrpcImpl class that actually performs the gRPC-Web POST lives in target/generated-sources — the project source never references it directly. The build server probes the project zip for cn1app.ProtoBootstrap and cn1app.GrpcClientBootstrap and splices the registry wiring in, mirroring the existing cn1app.MapperBootstrap pattern.

The runtime speaks gRPC-Web binary (application/grpc-web+proto) over HTTP/1.1, which is the standard mobile / browser variant of gRPC supported by Envoy, the official grpcweb Go proxy, and the gRPC-Web filter in modern gRPC server implementations. Plain HTTP/2 gRPC requires trailers that ConnectionRequest doesn’t expose; gRPC-Web carries grpc-status in a synthetic trailer frame in the response body instead.

A successful call:

Generates a typed Codename One GraphQL client from a GraphQL SDL schema, optionally driven by a set of operation documents. Writes one @Mapped record (Java 17+) or class (Java 8 target) per response shape and input type, a Java enum per GraphQL enum, and one @GraphQLClient-annotated interface carrying one method per operation. The generated files land in common/src/main/java so the project owns the contract; the matching client implementation and JSON mappers are emitted into common/target/generated-sources by the build-time annotation processors so the project source stays clean.

The mojo is paired with the existing process-annotations pipeline: the generated @Mapped types trigger per-class JSON mapper generation and a cn1app.MapperBootstrap entry, while @GraphQLClient triggers per-interface <Name>Impl generation chained through com.codename1.io.graphql.GraphQL.execute(…​) (queries and mutations) or com.codename1.io.graphql.GraphQL.subscribe(…​) (subscriptions), plus a cn1app.GraphQLClientBootstrap that wires everything to the com.codename1.io.graphql.GraphQLClients registry (same splice pattern as @Mapped mappers and @GrpcClient clients).

Configuration:

Unlike OpenAPI paths or gRPC service methods, a GraphQL schema doesn’t enumerate the operations a client wants — the client chooses which fields to select. The goal therefore supports two modes:

For a Star Wars schema and an operations.graphql declaring query HeroName, mutation AddReview, and subscription OnReview, the goal emits under common/src/main/java:

GraphQL enums map to a generated Java enum in response types, input types, and method variables alike — the JSON mapper binds enums by their name(). Built-in scalars map to their boxed Java type (Int → Integer, Float → Double, Boolean → Boolean, String / ID → String); custom scalars fall back to String.

The @GraphQLClient interface looks like:

Call sites use the static factory. Queries and mutations report through an OnComplete<GraphQLResponse<T>>:

A subscription returns a GraphQLSubscription handle whose cancel() ends the stream:

The <Name>Impl class that performs the request lives in target/generated-sources — the project source never references it directly. The build server probes the project zip for cn1app.GraphQLClientBootstrap and splices the registry wiring in, mirroring the existing cn1app.MapperBootstrap pattern.

Queries and mutations are sent as an HTTP POST to the endpoint with a JSON body {"query":…​,"operationName":…​,"variables":{…​}} and a Content-Type: application/json header. The response envelope ({"data":…​,"errors":[…​]}) is parsed into a typed GraphQLResponse<T>; because a GraphQL response can carry both data and errors, GraphQLResponse exposes getData() and getErrors() independently and isOk() reports whether the errors array was empty.

Subscriptions run over a WebSocket using the graphql-transport-ws protocol (offered via the Sec-WebSocket-Protocol handshake header): the client sends connection_init, waits for connection_ack, sends a subscribe message carrying the operation, and maps each next payload’s data to T before delivering it to the handler. The WebSocket endpoint defaults to the query endpoint with its scheme rewritten to ws / wss; pass a ws:// / wss:// URL to of(…​) to override it. All handler callbacks are dispatched on the EDT.

The guibuilder goal opens the Codename One GUI builder to edit a specified GUIBuilder form.

This will open the GUI builder to edit the form whose class is com.example.MyForm.

The generate-archetype mojo will generate a new archetype maven project based on an existing archetype project. It’s designed to ease the maintenance of several similar archetypes which differ in some dependencies or default project source code. It takes as input a template file which references the base archetype project and specifies what to customize.

Example Usage

Here is a sample template file:

Notice that the above template is velocity template for a Java file. It will be used as the source code for the main class in the resulting project. It’s a velocity template because maven’s archetype:generate goal will process it to replace properties such as package and the main class name.

Installs/Updates Codename One into the user’s home directory. This goal is automatically run if a Maven build is attempted and it detects that Codename One isn’t yet installed (in the $HOME/.codenameone) directory.

Installs a legacy cn1lib file as a dependency in this application project.

See Adding project dependencies for fuller coverage of project dependencies.

This will generate a Maven pom project for this lib inside the "cn1libs" directory, and it will add a dependency inside the common/pom.xml file.

If you need to remove the cn1lib later (that is, revert an installation), you can remove the <dependency> tag that was added to the common/pom.xml file for the cn1lib.

You can also remove the directory that was created inside the cn1libs folder for this cn1lib - but this step isn’t necessary.

Opens the legacy Codename One designer app to edit the project "theme.res" file.

This will open the Codename One designer.

Sets up some properties and environment variables required for the Codename One simulator to run properly.

This goal is bound to the initialize phase of the Java SE module of the Codename One application project archetype (cn1app-archetype) and shouldn’t be executed directly.

Downloads and opens the standalone Codename One Settings editor bound to the current Maven project. The editor manages basic project properties, build hints, and extensions.

See Appendix D, Codename One Settings

Runs Codename One unit tests.

This goal is bound to the test phase of Codename One application project archetype (cn1app-archetype) projects, so that running it directly isn’t necessary. If you build a cn1app-archetype project using:

or

Then this goal will be executed automatically.

Updates Codename One. This updates tools that live inside $HOME/.codenameone, such as the GUI builder, and tries to update the cn1.version and cn1.plugin.version properties in the project’s pom.xml. The standalone Settings editor is resolved from Maven using cn1.plugin.version when you run mvn cn1:settings.

Parameters

See Updating Codename One for more information about updating Codename One.