DOCSEARCHbyAlgolia
Submit Docs

jcefmaven

repository·master·Indexed 43 days ago

https://github.com/jcefmaven/jcefmaven

Maven artifacts for the Java Chromium Embedded Framework (JCEF), enabling developers to embed a Chromium browser into Java 8+ applications. It manages complex native dependencies via Maven or Gradle and provides the CefAppBuilder for configuring CefApp instances, including support for off-screen rendering (OSR) and custom download mirrors.

Tokens
1.5K
Snippets
5
Records
7
Agent score
5%

What's inside jcefmaven

  1. Install jcefmaven via Maven or Gradle

    master

    To use jcefmaven in your project, add it as a dependency using your preferred build tool. By default, this includes the base jcef library and jogl. On the first run, the native binaries will be downloaded and extracted automatically.

    If you prefer to bundle the natives to avoid downloading them at runtime, you must manually include the specific native artifacts for your target platform from Maven Central. Note that each bundle is approximately 100MB, so it is recommended to include only one bundle per build and export one build per platform.

    <dependency>
    <groupId>me.friwi</groupId>
    <artifactId>jcefmaven</artifactId>
    <version>146.0.10</version>
</dependency>
    implementation 'me.friwi:jcefmaven:146.0.10'

  2. Initialize JCEF using CefAppBuilder

    master

    To start using JCEF, use the CefAppBuilder to configure and build a CefApp instance. The builder allows you to set the installation directory, progress handlers, JCEF arguments, and windowless rendering (OSR) settings.

    Important: Do not use CefApp.addAppHandler(...) directly, as this will break functionality on MacOSX. Instead, use builder.setAppHandler(...) with a MavenCefAppHandlerAdapter.

    //Create a new CefAppBuilder instance
CefAppBuilder builder = new CefAppBuilder();

//Configure the builder instance
bulder.setInstallDir(new File("jcef-bundle")); //Default
bulder.setProgressHandler(new ConsoleProgressHandler()); //Default
bulder.addJcefArgs("--disable-gpu"); //Just an example
bulder.getCefSettings().windowless_rendering_enabled = true; //Default - select OSR mode

//Set an app handler. Do not use CefApp.addAppHandler(...), it will break your code on MacOSX!
bulder.setAppHandler(new MavenCefAppHandlerAdapter(){...});

//Build a CefApp instance using the configuration above
CefApp app = builder.build();

  3. Configure JVM flags for JDK 16+ and MacOSX

    master

    If you are running on JDK 16 or later, or if you are using MacOSX, you must add specific JVM flags to your execution environment to allow access to internal modules.

    # For MacOSX
--add-opens java.desktop/sun.awt=ALL-UNNAMED
--add-opens java.desktop/sun.lwawt=ALL-UNNAMED
--add-opens java.desktop/sun.lwawt.macosx=ALL-UNNAMED

# To use OSR (off-screen render) mode (JOGL flags)
--add-exports java.base/java.lang=ALL-UNNAMED
--add-exports java.desktop/sun.awt=ALL-UNNAMED
--add-exports java.desktop/sun.java2d=ALL-UNNAMED

  4. Configure custom download mirrors

    master
    If you need to use custom download mirrors for the native artifacts, use the getMirrors() and setMirrors(Collection<String>) methods on the CefAppBuilder. By default, it uses the project's GitHub repository and the central Maven repository.

  5. Get current platform and version information

    master

    You can programmatically determine the current operating system or retrieve version information for the build and the JCEF instance.

    //Get the current platform (e.g., to disable OSR on win-arm64)
EnumPlatform platform = EnumPlatform.getCurrentPlatform();
EnumOS os = platform.getOs();

//Provides build version data. Requires build_meta.json to be on classpath.
CefBuildInfo buildInfo = CefBuildInfo.fromClasspath();

//Provides JCEF version data. You can call this after initialization.
CefVersion cefVersion = cefApp.getVersion();

  6. Run artifact generation via Docker Compose

    master

    You can use the generate-artifacts service defined in docker-compose.yml to run the artifact generation process within a container. This service builds from the local Dockerfile and executes the ./scripts/generate_maven_builds.sh script.

    To use this service, you must provide two environment variables to the command:

    1. ${BUILD_META_URL}: The URL for build metadata.
    2. ${MVN_VERSION}: The Maven version to be used.

    The generated artifacts are mapped from the container's /jcefout directory to the local ./out directory via a volume.

    services:
  generate-artifacts:
    container_name: generate-artifacts
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ./out:/jcefout
    command: "./scripts/generate_maven_builds.sh ${BUILD_META_URL} ${MVN_VERSION}"

  7. Limitations and Requirements

    master

    Requirements

    • Java 8 or later

    Limitations

    • win-arm64: No OSR (Off-Screen Rendering) mode is supported because jogamp is unavailable.
    • App Handlers: Never use CefApp.addAppHandler(...). Always use builder.setAppHandler(...) with a MavenCefAppHandlerAdapter to ensure MacOSX compatibility.