From 028083561b40d8ca615e793cd21f585feb972071 Mon Sep 17 00:00:00 2001 From: Jose Date: Mon, 9 Oct 2023 19:30:01 +0200 Subject: [PATCH] Rework Java & Java Compat README files (#1538) --- README.md | 4 +- java-compat/BUILDING.md | 249 +++++++++++++++++++++++++ java-compat/README.md | 361 +++++++++++------------------------ java/BUILDING.md | 317 +++++++++++++++++++++++++++++++ java/README.md | 403 +++++++++------------------------------- 5 files changed, 770 insertions(+), 564 deletions(-) create mode 100644 java-compat/BUILDING.md create mode 100644 java/BUILDING.md diff --git a/README.md b/README.md index ddc180f28d5..6be10c96c8e 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,7 @@ server; neither side knows the programming language used by the other side. ## Complete solution with a uniform API The Ice framework provides everything you need to build networked applications: + - RPCs with a compact binary [protocol][protocol] over a variety of network transports (TCP, UDP, WebSocket, Bluetooth...) - Secure communications ([IceSSL][icessl]) @@ -84,7 +85,7 @@ languages. ## Building Ice from source -[C++](cpp/BUILDING.md) | [C#](csharp/BUILDING.md) | [Java](java) | [JavaScript/TypeScript](js) | [MATLAB](matlab) | [Objective-C](objective-c) | [PHP](php) | [Python](python) | [Ruby](ruby) | [Swift](swift) +[C++](cpp/BUILDING.md) | [C#](csharp/BUILDING.md) | [Java](java/BUILDING.md) | [Java Compat](java-compat/BUILDING.md) | [JavaScript/TypeScript](js) | [MATLAB](matlab) | [Objective-C](objective-c) | [PHP](php) | [Python](python) | [Ruby](ruby) | [Swift](swift) ## Copyright and license @@ -92,6 +93,7 @@ Ice is a single-copyright project: all the source code in this [ice repository][ Copyright © ZeroC, Inc., with very few exceptions. As copyright owner, ZeroC can license Ice under different license terms, and offers the following licenses for Ice: + - [GPLv2], a popular open-source license with strong [copyleft][copyleft] conditions (the default license) - Commercial or closed-source licenses diff --git a/java-compat/BUILDING.md b/java-compat/BUILDING.md new file mode 100644 index 00000000000..5fc017ce1dc --- /dev/null +++ b/java-compat/BUILDING.md @@ -0,0 +1,249 @@ +# Ice for Java Compat Build Instructions + +This page describes how to build and install Ice for Java Compat from source. If you +prefer, you can also download a [binary distribution]. + +* [Build Requirements](#build-requirements) + * [Operating Systems](#operating-systems) + * [Slice to Java Compiler](#slice-to-java-compiler) + * [Java Version](#java-version) + * [Gradle](#gradle) + * [Bzip2 Compression](#bzip2-compression) +* [Building Ice for Java Compat](#building-ice-for-java-compat) +* [Installing Ice for Java Compat](#installing-ice-for-java-compat) +* [Running the Java Compat Tests](#running-the-java-compat-tests) +* [Building the Ice for Android Tests](#building-the-ice-for-android-tests) + +## Build Requirements + +### Operating Systems + +Ice for Java Compat builds and runs properly on Windows, macOS, and any recent +Linux distributions. It is fully supported on the platforms listed on the +[supported platforms] page. + +### Slice to Java Compiler + +You need the Slice to Java compiler to build Ice for Java Compat and also to use +Ice for Java Compat. The Slice to Java compiler (`slice2java`) is a command-line tool +written in C++. You can build the Slice to Java compiler from source, or alternatively +you can install an Ice [binary distribution] that includes this compiler. + +### Java Version + +Ice for Java Compat requires Java 7 or later. + +Make sure that the `javac` and `java` commands are present in your PATH. + +### Gradle + +Ice for Java Compat uses the [Gradle] build system, and includes the Gradle wrapper +in the distribution. You cannot build the Ice for Java Compat source distribution +without an Internet connection. Gradle will download all required packages +automatically from the Maven Central repository located at +https://repo1.maven.org/maven2/ + +### Bzip2 Compression + +Ice for Java Compat supports protocol compression using the bzip2 classes included +with [Apache Commons Compress]. + +The Maven package ID for the commons-compress JAR file is as follows: + +```gradle +groupId=org.apache.commons, version=1.20, artifactId=commons-compress +``` + +The demos and tests are automatically setup to enable protocol compression by +adding the commons-compress JAR to the manifest class path. For your own +applications you must add the commons-compress JAR to the application `CLASSPATH` +to enable protocol compression. + +## Building Ice for Java Compat + +The build system requires the Slice to Java compiler from Ice for C++. If you +have not built Ice for C++ in this source distribution, you must set the +`ICE_HOME` environment variable with the path name of your Ice installation. For +example, on Linux: + +```shell +export ICE_HOME=/opt/Ice-3.7.10 (For local build) +export ICE_HOME=/usr (For RPM installation) +``` + +On Windows: + +```shell +set ICE_HOME=C:\Program Files\ZeroC\Ice-3.7.10 (MSI installation) +``` + +On Windows if you are using Ice for C++ from a source distribution, you must set +the `CPP_PLATFORM` and `CPP_CONFIGURATION` environment variables to match the +platform and configuration used in your C++ build: + +```shell +set CPP_PLATFORM=x64 +set CPP_CONFIGURATION=Debug +``` + +The supported values for `CPP_PLATFORM` are `Win32` and `x64` and the supported +values for `CPP_CONFIGURATION` are `Debug` and `Release`. + +Before building Ice for Java Compat, review the settings in the file `gradle.properties` +and edit as necessary. + +To build Ice, all services, and tests, run + +```shell +gradlew build +``` + +Upon completion, the Ice JAR and POM files are placed in the `lib` subdirectory. + +If at any time you wish to discard the current build and start a new one, use +these commands: + +```shell +gradlew clean +gradlew build +``` + +## Installing Ice for Java Compat + +To install Ice for Java Compat in the directory specified by the `prefix` variable in +`gradle.properties` run the following command: + +```shell +gradlew install +``` + +The installation installs the following JAR files to `/lib`. + +* glacier2-compat-3.7.10.jar +* ice-compat-3.7.10.jar +* icebox-compat-3.7.10.jar +* icebt-compat-3.7.10.jar +* icediscovery-compat-3.7.10.jar +* icegrid-compat-3.7.10.jar +* icelocatordiscovery-compat-3.7.10.jar +* icepatch2-compat-3.7.10.jar +* icestorm-compat-3.7.10.jar + +POM files are also installed for ease of deployment to a Maven-based +distribution system. + +## Running the Java Compat Tests + +Some of the Ice for Java Compat tests employ applications that are part of the Ice for +C++ distribution. If you have not built Ice for C++ in this source distribution +then you must set the `ICE_HOME` environment variable with the path name of your +Ice installation. On Linux or macOS: + +```shell +export ICE_HOME=/opt/Ice-3.7.10 (For local build) +export ICE_HOME=/usr (For RPM installation) +``` + +On Windows: + +```shell +set ICE_HOME=C:\Program Files\ZeroC\Ice-3.7.10 +``` + +Python is required to run the test suite. To run the tests, open a command +window and change to the top-level directory. At the command prompt, execute: + +```shell +python allTests.py +``` + +If everything worked out, you should see lots of `ok` messages. In case of a +failure, the tests abort with `failed`. + +## Building the Ice for Android Tests + +The `test/android/controller` directory contains an Android Studio project +for the Ice test suite controller. + +### Android Build Requirements + +Building any Ice application for Android requires Android Studio and the Android +SDK build tools. We tested with the following components: + +* Android Studio Giraffe +* Android SDK 33 + +Ice requires at minimum API level 21: + +* Android 5 (API21) + +### Building the Android Test Controller + +You must first build Ice for Java Compat refer to [Building Ice for Java Compat](#building-ice-for-java-compat) +for instructions, then follow these steps: + +1. Start Android Studio +2. Select "Open an existing Android Studio project" +3. Navigate to and select the "android" subdirectory +4. Click OK and wait for the project to open and build + +To build the tests against the Ice binary distribution you must set `ICE_BIN_DIST` environment +variable to `all` before starting Android Studio. + +## Running the Android Tests + +The Android Studio project contains a `controller` app for the Ice test +suite. Prior to running the app, you must disable Android Studio's Instant Run +feature, located in File / Settings / Build, Execution, Deployment / +Instant Run. + +Tests are started from the dev machine using the `allTests.py` script, similar +to the other language mappings. The script uses Ice for Python to communicate +with the Android app, therefore you must build the [Python mapping](../../python) +before continuing. + +You also need to add the `tools\bin`, `platform-tools` and `emulator` +directories from the Android SDK to your PATH. On macOS, you can use the +following commands: + +```shell +export PATH=~/Library/Android/sdk/cmdline-tools/latest/bin:$PATH +export PATH=~/Library/Android/sdk/platform-tools:$PATH +export PATH=~/Library/Android/sdk/emulator:$PATH +``` + +On Windows, you can use the following commands: + +```shell +set PATH=%LOCALAPPDATA%\Android\sdk\cmdline-tools\latest\bin;%PATH% +set PATH=%LOCALAPPDATA%\Android\sdk\platform-tools;%PATH% +set PATH=%LOCALAPPDATA%\Android\sdk\emulator;%PATH% +``` + +Run the tests with the Android emulator by running the following command: + +```shell +python allTests.py --android --controller-app +``` + +To run the tests on a Android device connected through USB, you can use +the `--device=usb` option as shown below: + +```shell +python allTests.py --android --device=usb --controller-app +``` + +To connect to an Android device that is running adb you can use the +`--device=` + +```shell +python allTests.py --android --device= --controller-app +``` + +To run the tests against a `controller` application started from Android +Studio you should omit the `--controller-app` option from the commands above. + +[binary distribution]: https://zeroc.com/downloads/ice +[supported platforms]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-10 +[Gradle]: https://gradle.org +[Apache Commons Compress]: https://commons.apache.org/proper/commons-compress/ diff --git a/java-compat/README.md b/java-compat/README.md index 32ef6fc3ce1..4f809112249 100644 --- a/java-compat/README.md +++ b/java-compat/README.md @@ -1,252 +1,109 @@ -# Building Ice for Java Compat - -This page describes how to build and install Ice for Java from source. If -you prefer, you can also download a [binary distribution][1]. - -* [Build Requirements](#build-requirements) - * [Operating Systems](#operating-systems) - * [Slice to Java Compiler](#slice-to-java-compiler) - * [Java Version](#java-version) - * [Gradle](#gradle) - * [Bzip2 Compression](#bzip2-compression) -* [Building Ice for Java Compat](#building-ice-for-java-compat-1) -* [Installing Ice for Java Compat](#installing-ice-for-java-compat) -* [Running the Java Compat Tests](#running-the-java-compat-tests) -* [Building the Ice for Android Tests](#building-the-ice-for-android-tests) - -## Build Requirements - -### Operating Systems - -Ice for Java builds and runs properly on Windows, macOS, and any recent -Linux distribution, and is fully supported on the platforms listed on the -[supported platforms][2] page. - -### Slice to Java Compiler - -You need the Slice to Java compiler to build Ice for Java and also to use -Ice for Java. The Slice to Java compiler (`slice2java`) is a command-line tool -written in C++. You can build the Slice to Java compiler from source, or -alternatively you can install an Ice [binary distribution][1] that includes -this compiler. - -### Java Version - -Ice for Java requires J2SE 1.7.0 or later. - -Make sure that the `javac` and `java` commands are present in your PATH. - -### Gradle - -Ice for Java uses the [Gradle][3] build system, and includes the Gradle wrapper -in the distribution. You cannot build the Ice for Java source distribution -without an Internet connection. Gradle will download all required packages -automatically from Maven Central repository located at -http://central.maven.org/maven2/ - -### Bzip2 Compression - -Ice for Java supports protocol compression using the bzip2 classes included -with [Apache Commons Compress][4]. - -The Maven package id for the commons-compress JAR file is as follows: - -``` -groupId=org.apache.commons, version=1.20, artifactId=commons-compress -``` - -The demos and tests are automatically setup to enable protocol compression by -adding the commons-compress JAR to the manifest class path. For your own -applications you must add the commons-compress JAR to the application CLASSPATH -to enable protocol compression. - -## Building Ice for Java - -The build system requires the Slice to Java compiler from Ice for C++. If you -have not built Ice for C++ in this source distribution, you must set the -`ICE_HOME` environment variable with the path name of your Ice installation. For -example, on Linux: - -``` -export ICE_HOME=/opt/Ice-3.7.10 (For local build) -export ICE_HOME=/usr (For RPM installation) -``` - -On Windows: - -``` -set ICE_HOME=C:\Program Files\ZeroC\Ice-3.7.10 (MSI installation) -``` - -On Windows if you are using Ice for C++ from a source distribution, you must set -the `CPP_PLATFORM` and `CPP_CONFIGURATION` environment variables to match the -platform and configuration used in your C++ build: - -``` -set CPP_PLATFORM=x64 -set CPP_CONFIGURATION=Debug -``` - -The supported values for `CPP_PLATFORM` are `Win32` and `x64` and the supported -values for `CPP_CONFIGURATION` are `Debug` and `Release`. - -Before building Ice for Java, review the settings in the file -`gradle.properties` and edit as necessary. - -To build Ice, all services, and tests, run - -``` -gradlew build -``` - -Upon completion, the Ice JAR and POM files are placed in the `lib` subdirectory. - -If at any time you wish to discard the current build and start a new one, use -these commands: - -``` -gradlew clean -gradlew build -``` - -## Installing Ice for Java - -To install Ice for Java in the directory specified by the `prefix` variable in -`gradle.properties` run the following command: - -``` -gradlew install -``` - -The installation installs the following JAR files to `/lib`. - -``` -glacier2-compat-3.7.10.jar -ice-compat-3.7.10.jar -icebox-compat-3.7.10.jar -icebt-compat-3.7.10.jar -icediscovery-compat-3.7.10.jar -icegrid-compat-3.7.10.jar -icelocatordiscovery-compat-3.7.10.jar -icepatch2-compat-3.7.10.jar -icestorm-compat-3.7.10.jar -``` - -POM files are also installed for ease of deployment to a Maven-based -distribution system. - -## Running the Java Tests - -Some of the Ice for Java tests employ applications that are part of the Ice for -C++ distribution. If you have not built Ice for C++ in this source distribution -then you must set the `ICE_HOME` environment variable with the path name of your -Ice installation. On Linux or macOS: - -``` -export ICE_HOME=/opt/Ice-3.7.10 (For local build) -export ICE_HOME=/usr (For RPM installation) -``` - -On Windows: - -``` -set ICE_HOME=C:\Program Files\ZeroC\Ice-3.7.10 -``` - -Python is required to run the test suite. To run the tests, open a command -window and change to the top-level directory. At the command prompt, execute: - -``` -python allTests.py -``` - -If everything worked out, you should see lots of `ok` messages. In case of a -failure, the tests abort with `failed`. - -## Building the Ice for Android Tests - -The `test/android/controller` directory contains an Android Studio project -for the Ice test suite controller. - -### Build Requirements - -Building any Ice application for Android requires Android Studio and the Android -SDK build tools. We tested with the following components: - -- Android Studio Electric Eel -- Android SDK 33 - -Ice requires at minimum API level 21: - -- Android 5 (API21) - -### Building the Android Test Controller - -You must first build Ice for Java refer to [Building Ice for Java](#building-ice-for-java-1) -for instructions, then follow these steps: - -1. Start Android Studio -2. Select "Open an existing Android Studio project" -3. Navigate to and select the "android" subdirectory -4. Click OK and wait for the project to open and build - -To build the tests against the Ice binary distribution you must set `ICE_BIN_DIST` environment -variable to `all` before starting Android Studio. - -## Running the Android Tests - -The Android Studio project contains a `controller` app for the Ice test -suite. Prior to running the app, you must disable Android Studio's Instant Run -feature, located in File / Settings / Build, Execution, Deployment / -Instant Run. - -Tests are started from the dev machine using the `allTests.py` script, similar -to the other language mappings. The script uses Ice for Python to communicate -with the Android app, therefore you must build the [Python mapping] -(../../python) before continuing. - -You also need to add the `tools\bin`, `platform-tools` and `emulator` -directories from the Android SDK to your PATH. On macOS, you can use the -following commands: - -``` -export PATH=~/Library/Android/sdk/cmdline-tools/latest/bin:$PATH -export PATH=~/Library/Android/sdk/platform-tools:$PATH -export PATH=~/Library/Android/sdk/emulator:$PATH -``` - -On Windows, you can use the following commands: - -``` -set PATH=%LOCALAPPDATA%\Android\sdk\cmdline-tools\latest\bin;%PATH% -set PATH=%LOCALAPPDATA%\Android\sdk\platform-tools;%PATH% -set PATH=%LOCALAPPDATA%\Android\sdk\emulator;%PATH% -``` - -Run the tests with the Android emulator by running the following command: - -``` -python allTests.py --android --controller-app -``` - -To run the tests on a Android device connected through USB, you can use -the `--device=usb` option as shown below: - -``` -python allTests.py --android --device=usb --controller-app -``` - -To connect to an Android device that is running adb you can use the -`--device=` - -``` -python allTests.py --android --device= --controller-app -``` - -To run the tests against a `controller` application started from Android -Studio you should omit the `--controller-app` option from the commands above. - -[1]: https://zeroc.com/downloads/ice -[2]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-10 -[3]: https://gradle.org -[4]: https://commons.apache.org/proper/commons-compress/ +# Ice for Java Compat + +[Getting started] | [Examples] | [Maven packages] | [Documentation] | [Building from source] + +The [Ice framework] provides everything you need to build networked applications, +including RPC, pub/sub, server deployment, and more. + +Ice for Java Compat is a Java implementation of the Ice framework that is largely source +compatible with Ice for Java 3.6 and prior releases. + +## Sample Code + +```slice +// Slice definitions (Hello.ice) + +#pragma once + +module Demo +{ + interface Hello + { + void sayHello(); + } +} +``` + +```java +// Client implementation (Client.java) + +import Demo.*; +import Ice.*; + +public class Client +{ + public static void main(String[] args) + { + try(Communicator com = Util.initialize(args)) + { + HelloPrx hello = HelloPrxHelper.checkedCast( + com.stringToProxy("hello:default -h localhost -p 10000")); + hello.sayHello(); + } + } +} +``` + +```java +// Server implementation (Server.java) + +import Ice.*; + +public class Server +{ + public static void main(String[] args) + { + try(Communicator communicator = Util.initialize(args)) + { + // Install a shutdown hook to ensure the communicator gets shut down when + // the user interrupts the application with Ctrl-C. + Runtime.getRuntime().addShutdownHook(new ShutdownHook(communicator)); + + ObjectAdapter adapter = communicator.createObjectAdapterWithEndpoints( + "Hello", + "default -h localhost -p 10000"); + adapter.add(new Printer(), Util.stringToIdentity("hello")); + adapter.activate(); + communicator.waitForShutdown(); + } + } + + static class ShutdownHook extends Thread + { + @Override + public void run() + { + _communicator.shutdown(); + } + + ShutdownHook(Communicator communicator) + { + _communicator = communicator; + } + + private final Communicator _communicator; + } +} +``` + +```java +// Printer implementation (Printer.java) + +import Demo.*; + +public class Printer extends _HelloDisp +{ + @Override + public void sayHello(Ice.Current current) + { + System.out.println("Hello World!"); + } +} +``` + +[Getting started]: https://doc.zeroc.com/ice/3.7/hello-world-application/writing-an-ice-application-with-java-compat +[Examples]: https://github.com/zeroc-ice/ice-demos/tree/3.7/java-compat +[Maven packages]: https://central.sonatype.com/namespace/com.zeroc +[Documentation]: https://doc.zeroc.com/ice/3.7 +[Building from source]: https://github.com/zeroc-ice/ice/blob/3.7/java-compat/BUILDING.md +[Ice framework]: https://github.com/zeroc-ice/ice diff --git a/java/BUILDING.md b/java/BUILDING.md new file mode 100644 index 00000000000..c65ad8acc7a --- /dev/null +++ b/java/BUILDING.md @@ -0,0 +1,317 @@ +# Ice for Java build instructions + +This page describes how to build and install Ice for Java from source. If +you prefer, you can also download a [binary distribution]. + +* [Build Requirements](#build-requirements) + * [Operating Systems](#operating-systems) + * [Slice to Java Compiler](#slice-to-java-compiler) + * [Java Version](#java-version) + * [Gradle](#gradle) + * [Bzip2 Compression](#bzip2-compression) + * [JGoodies](#jgoodies) + * [ProGuard](#proguard) + * [Java Application Bundler](#java-application-bundler) +* [Building Ice for Java](#building-ice-for-java) +* [Installing Ice for Java](#installing-ice-for-java) +* [Running the Java Tests](#running-the-java-tests) +* [Building the Ice for Android Tests](#building-the-ice-for-android-tests) +* [IceGrid GUI Tool](#icegrid-gui-tool) + +## Build Requirements + +### Operating Systems + +Ice for Java builds and runs properly on Windows, macOS, and any recent Linux +distribution. It is fully supported on the platforms listed on the [supported platforms] +page. + +### Slice to Java Compiler + +You need the Slice to Java compiler to build Ice for Java and also to use +Ice for Java. The Slice to Java compiler (`slice2java`) is a command-line tool +written in C++. You can build the Slice to Java compiler from source, or +alternatively you can install an Ice [binary distribution] that includes +this compiler. + +### Java Version + +Ice for Java requires Java 8 or later. + +Make sure that the `javac` and `java` commands are present in your PATH. + +The IceGrid GUI tool's Metrics Graph feature requires JavaFX support. If you +build the source with a JVM that lacks JavaFX support, this feature will be +unavailable. Alternatively, building the source in an environment with +JavaFX produces an IceGrid GUI JAR file that can be used in JVMs with or without +JavaFX support, as the Metrics Graph feature is enabled dynamically. + +### Gradle + +Ice for Java uses the [Gradle] build system, and includes the Gradle wrapper +in the distribution. You cannot build the Ice for Java source distribution without +an Internet connection. Gradle will download all required packages automatically +from the Maven Central repository located at https://repo1.maven.org/maven2/ + +### Bzip2 Compression + +Ice for Java supports protocol compression using the bzip2 classes included +with [Apache Commons Compress]. + +The Maven package ID for the commons-compress JAR file is as follows: + +```gradle +groupId=org.apache.commons, version=1.20, artifactId=commons-compress +``` + +The demos and tests are automatically setup to enable protocol compression by +adding the commons-compress JAR to the manifest class path. For your own +applications you must add the commons-compress JAR to the application `CLASSPATH` +to enable protocol compression. + +### JGoodies + +The IceGrid GUI tool uses the JGoodies libraries Forms and Looks. The following +versions were tested: + +* JGoodies Forms 1.9.0 +* JGoodies Looks 2.7.0 + +The Maven package ids for the JGoodies packages are as follows: + +```gradle +groupId=com.jgoodies, version=1.9.0, artifactId=jgoodies-forms +groupId=com.jgoodies, version=2.7.0, artifactId=jgoodies-looks +``` + +### ProGuard + +Gradle uses [ProGuard] to create the standalone JAR file for the IceGrid +GUI tool. + +The Maven package id for the ProGuard gradle plugin is as follows: + +```gradle +groupId=com.guardsquare, version=7.3.1, artifactId=proguard-gradle +``` + +### Java Application Bundler + +Under macOS Gradle uses the Java Application Bundler to create an application +bundle for the IceGrid GUI tool. + +The Maven package id for the application bundler package is as follows: + +```gradle +groupId=com.panayotis, version=1.1.0, artifactId=appbundler +``` + +## Building Ice for Java + +The build system requires the Slice to Java compiler from Ice for C++. If you +have not built Ice for C++ in this source distribution, you must set the +`ICE_BIN_DIST` environment variable to `cpp` and the `ICE_HOME` environment +variable with the path name of your Ice installation. For example, on Linux with +an RPM installation: + +```shell +export ICE_BIN_DIST=cpp +export ICE_HOME=/usr +``` + +On Windows with an MSI installation: + +```shell +set ICE_BIN_DIST=cpp +set ICE_HOME=C:\Program Files\ZeroC\Ice-3.7.10 +``` + +If you are using Ice for C++ from a source build on Windows, you must set +the `CPP_PLATFORM` and `CPP_CONFIGURATION` environment variables to match the +platform and configuration used in your C++ build: + +```shell +set CPP_PLATFORM=x64 +set CPP_CONFIGURATION=Debug +``` + +The supported values for `CPP_PLATFORM` are `Win32` and `x64` and the supported +values for `CPP_CONFIGURATION` are `Debug` and `Release`. + +Before building Ice for Java, review the settings in the file +`gradle.properties` and edit as necessary. + +To build Ice, all services, and tests, run + +```shell +gradlew build +``` + +Upon completion, the Ice JAR and POM files are placed in the `lib` subdirectory. + +If at any time you wish to discard the current build and start a new one, use +these commands: + +```shell +gradlew clean +gradlew build +``` + +## Installing Ice for Java + +To install Ice for Java in the directory specified by the `prefix` variable in +`gradle.properties` run the following command: + +```shell +gradlew install +``` + +The following JAR files will be installed to `/lib`. + +* glacier2-3.7.10.jar +* ice-3.7.10.jar +* icebox-3.7.10.jar +* icebt-3.7.10.jar +* icediscovery-3.7.10.jar +* icegrid-3.7.10.jar +* icegridgui.jar +* icelocatordiscovery-3.7.10.jar +* icepatch2-3.7.10.jar +* icessl-3.7.10.jar +* icestorm-3.7.10.jar + +POM files are also installed for ease of deployment to a Maven-based +distribution system. + +## Running the Java Tests + +Some of the Ice for Java tests employ applications that are part of the Ice for +C++ distribution. If you have not built Ice for C++ in this source distribution +then you must set the `ICE_HOME` environment variable with the path name of your +Ice installation. On Unix: + +```shell +export ICE_HOME=/opt/Ice-3.7.10 (For local build) +export ICE_HOME=/usr (For RPM installation) +``` + +On Windows: + +```shell +set ICE_HOME=C:\Program Files\ZeroC\Ice-3.7.10 +``` + +Python is required to run the test suite. To run the tests, open a command +window and change to the top-level directory. At the command prompt, execute: + +```shell +python allTests.py +``` + +If everything worked out, you should see lots of `ok` messages. In case of a +failure, the tests abort with `failed`. + +## Building the Ice for Android Tests + +The `test/android/controller` directory contains an Android Studio project for +the Ice test suite controller. + +### Android Build Requirements + +To build an Ice application for Android, you need Android Studio and the Android SDK +build tools. We tested the following components: + +* Android Studio Giraffe +* Android SDK 33 + +To use Ice's Java mapping with Java 8, you need at least API level 24: + +* Android 7 (API24) + +### Building the Android Test Controller + +You must first build Ice for Java refer to [Building Ice for Java](#building-ice-for-java) +for instructions, then follow these steps: + +1. Start Android Studio +2. Select "Open an existing Android Studio project" +3. Navigate to and select the "java/test/android/controller" subdirectory +4. Click OK and wait for the project to open and build + +To build the tests against the Ice binary distribution you must set `ICE_BIN_DIST` environment +variable to `all` before starting Android Studio. + +### Running the Android Test Suite + +The Android Studio project contains a `controller` app for the Ice test +suite. Prior to running the app, you must disable Android Studio's Instant Run +feature, located in File / Settings / Build, Execution, Deployment / +Instant Run. + +Tests are started from the dev machine using the `allTests.py` script, similar +to the other language mappings. The script uses Ice for Python to communicate +with the Android app, therefore you must build the [Python mapping] before continuing. + +You also need to add the `tools\bin`, `platform-tools` and `emulator` +directories from the Android SDK to your PATH. On macOS, you can use the +following commands: + +```shell +export PATH=~/Library/Android/sdk/cmdline-tools/latest/bin:$PATH +export PATH=~/Library/Android/sdk/platform-tools:$PATH +export PATH=~/Library/Android/sdk/emulator:$PATH +``` + +On Windows, you can use the following commands: + +```shell +set PATH=%LOCALAPPDATA%\Android\sdk\cmdline-tools\latest\bin;%PATH% +set PATH=%LOCALAPPDATA%\Android\sdk\platform-tools;%PATH% +set PATH=%LOCALAPPDATA%\Android\sdk\emulator;%PATH% +``` + +Run the tests with the Android emulator by running the following command: + +```shell +python allTests.py --android --controller-app +``` + +To run the tests on a Android device connected through USB, you can use +the `--device=usb` option as shown below: + +```shell +python allTests.py --android --device=usb --controller-app +``` + +To connect to an Android device that is running adb you can use the +`--device=` + +```shell +python allTests.py --android --device= --controller-app +``` + +To run the tests against a `controller` application started from Android +Studio you should omit the `--controller-app` option from the commands above. + +## IceGrid GUI Tool + +Ice for Java includes the IceGrid GUI tool. It can be found in the file +`lib/icegridgui.jar`. + +This JAR file is completely self-contained and has no external dependencies. +You can start the tool with the following command: + +```shell +java -jar icegridgui.jar +``` + +On macOS, the build also creates an application bundle named IceGrid GUI. You +can start the IceGrid GUI tool by double-clicking the IceGrid GUI icon in +Finder. + +[binary distribution]: https://zeroc.com/downloads/ice +[supported platforms]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-10 +[Gradle]: https://gradle.org +[ProGuard]: http://proguard.sourceforge.net +[Apache Commons Compress]: https://commons.apache.org/proper/commons-compress/ +[Python Mapping]: ../python diff --git a/java/README.md b/java/README.md index 4c96c5967a7..34f19ea8a73 100644 --- a/java/README.md +++ b/java/README.md @@ -1,311 +1,92 @@ -# Building Ice for Java - -This page describes how to build and install Ice for Java from source. If -you prefer, you can also download a [binary distribution][1]. - -* [Build Requirements](#build-requirements) - * [Operating Systems](#operating-systems) - * [Slice to Java Compiler](#slice-to-java-compiler) - * [Java Version](#java-version) - * [Gradle](#gradle) - * [Bzip2 Compression](#bzip2-compression) - * [JGoodies](#jgoodies) - * [ProGuard](#proguard) - * [Java Application Bundler](#java-application-bundler) -* [Building Ice for Java](#building-ice-for-java-1) -* [Installing Ice for Java](#installing-ice-for-java) -* [Running the Java Tests](#running-the-java-tests) -* [Building the Ice for Android Tests](#building-the-ice-for-android-tests) -* [IceGrid GUI Tool](#icegrid-gui-tool) - -## Build Requirements - -### Operating Systems - -Ice for Java builds and runs properly on Windows, macOS, and any recent Linux -distribution, and is fully supported on the platforms listed on the -[supported platforms][2] page. - -### Slice to Java Compiler - -You need the Slice to Java compiler to build Ice for Java and also to use -Ice for Java. The Slice to Java compiler (`slice2java`) is a command-line tool -written in C++. You can build the Slice to Java compiler from source, or -alternatively you can install an Ice [binary distribution][1] that includes -this compiler. - -### Java Version - -Ice for Java requires J2SE 1.8 or later. - -Make sure that the `javac` and `java` commands are present in your PATH. - -The Metrics Graph feature of the IceGrid GUI tool requires JavaFX support. This -feature will not be available if you build the source with a JVM that lacks -support for JavaFX. Alternatively, building the source in an environment with -JavaFX produces an IceGrid GUI JAR file that can be used in JVMs with or without -JavaFX support, as the Metrics Graph feature is enabled dynamically. - -### Gradle - -Ice for Java uses the [Gradle][3] build system, and includes the Gradle wrapper -in the distribution. You cannot build the Ice for Java source distribution without -an Internet connection. Gradle will download all required packages automatically -from Maven Central repository located at http://central.maven.org/maven2/ - -### Bzip2 Compression - -Ice for Java supports protocol compression using the bzip2 classes included -with [Apache Commons Compress][5]. - -The Maven package id for the commons-compress JAR file is as follows: - -``` -groupId=org.apache.commons, version=1.20, artifactId=commons-compress -``` - -The demos and tests are automatically setup to enable protocol compression by -adding the commons-compress JAR to the manifest class path. For your own -applications you must add the commons-compress JAR to the application CLASSPATH -to enable protocol compression. - -### JGoodies - -The IceGrid GUI tool uses the JGoodies libraries Forms and Looks. The following -versions were tested: - -``` -JGoodies Forms 1.9.0 -JGoodies Looks 2.7.0 -``` - -The Maven package ids for the JGoodies packages are as follows: - -``` -groupId=com.jgoodies, version=1.9.0, artifactId=jgoodies-forms -groupId=com.jgoodies, version=2.7.0, artifactId=jgoodies-looks -``` - -### ProGuard - -Gradle uses [ProGuard][4] to create the standalone JAR file for the IceGrid -GUI tool. - -The Maven package id for the ProGuard gradle plugin is as follows: - -``` -groupId=com.guardsquare, version=7.3.1, artifactId=proguard-gradle -``` - -### Java Application Bundler - -Under macOS Gradle uses the Java Application Bundler to create an application -bundle for the IceGrid GUI tool. - -The Maven package id for the application bundler package is as follows: - -``` -groupId=com.panayotis, version=1.1.0, artifactId=appbundler -``` - -## Building Ice for Java - -The build system requires the Slice to Java compiler from Ice for C++. If you -have not built Ice for C++ in this source distribution, you must set the -`ICE_BIN_DIST` environment variable to `cpp` and the `ICE_HOME` environment -variable with the path name of your Ice installation. For example, on Linux with -an RPM installation: -``` -export ICE_BIN_DIST=cpp -export ICE_HOME=/usr -``` - -On Windows with an MSI installation: -``` -set ICE_BIN_DIST=cpp -set ICE_HOME=C:\Program Files\ZeroC\Ice-3.7.10 -``` - -If you are using Ice for C++ from a source build on Windows, you must set -the `CPP_PLATFORM` and `CPP_CONFIGURATION` environment variables to match the -platform and configuration used in your C++ build: -``` -set CPP_PLATFORM=x64 -set CPP_CONFIGURATION=Debug -``` - -The supported values for `CPP_PLATFORM` are `Win32` and `x64` and the supported -values for `CPP_CONFIGURATION` are `Debug` and `Release`. - -Before building Ice for Java, review the settings in the file -`gradle.properties` and edit as necessary. - -To build Ice, all services, and tests, run -``` -gradlew build -``` - -Upon completion, the Ice JAR and POM files are placed in the `lib` subdirectory. - -If at any time you wish to discard the current build and start a new one, use -these commands: -``` -gradlew clean -gradlew build -``` - -## Installing Ice for Java - -To install Ice for Java in the directory specified by the `prefix` variable in -`gradle.properties` run the following command: -``` -gradlew install -``` - -The following JAR files will be installed to `/lib`. - -``` -glacier2-3.7.10.jar -ice-3.7.10.jar -icebox-3.7.10.jar -icebt-3.7.10.jar -icediscovery-3.7.10.jar -icegrid-3.7.10.jar -icegridgui.jar -icelocatordiscovery-3.7.10.jar -icepatch2-3.7.10.jar -icessl-3.7.10.jar -icestorm-3.7.10.jar -``` - -POM files are also installed for ease of deployment to a Maven-based -distribution system. - -## Running the Java Tests - -Some of the Ice for Java tests employ applications that are part of the Ice for -C++ distribution. If you have not built Ice for C++ in this source distribution -then you must set the `ICE_HOME` environment variable with the path name of your -Ice installation. On Unix: -``` -export ICE_HOME=/opt/Ice-3.7.10 (For local build) -export ICE_HOME=/usr (For RPM installation) -``` - -On Windows: -``` -set ICE_HOME=C:\Program Files\ZeroC\Ice-3.7.10 -``` - -Python is required to run the test suite. To run the tests, open a command -window and change to the top-level directory. At the command prompt, execute: -``` -python allTests.py -``` - -If everything worked out, you should see lots of `ok` messages. In case of a -failure, the tests abort with `failed`. - -## Building the Ice for Android Tests - -The `test/android/controller` directory contains an Android Studio project for -the Ice test suite controller. - -### Android Build Requirements - -Building any Ice application for Android requires Android Studio and the Android -SDK build tools. We tested with the following components: - -- Android Studio Electric Eel -- Android SDK 33 - -Using Ice's Java mapping with Java 8 requires at minimum API level 24: - -- Android 7 (API24) - -### Building the Android Test Controller - -You must first build Ice for Java refer to [Building Ice for Java](#building-ice-for-java-1) -for instructions, then follow these steps: - -1. Start Android Studio -2. Select "Open an existing Android Studio project" -3. Navigate to and select the "java/test/android/controller" subdirectory -4. Click OK and wait for the project to open and build - -To build the tests against the Ice binary distribution you must set `ICE_BIN_DIST` environment -variable to `all` before starting Android Studio. - -### Running the Android Test Suite - -The Android Studio project contains a `controller` app for the Ice test -suite. Prior to running the app, you must disable Android Studio's Instant Run -feature, located in File / Settings / Build, Execution, Deployment / -Instant Run. - -Tests are started from the dev machine using the `allTests.py` script, similar -to the other language mappings. The script uses Ice for Python to communicate -with the Android app, therefore you must build the [Python mapping] -(../python) before continuing. - -You also need to add the `tools\bin`, `platform-tools` and `emulator` -directories from the Android SDK to your PATH. On macOS, you can use the -following commands: - -``` -export PATH=~/Library/Android/sdk/cmdline-tools/latest/bin:$PATH -export PATH=~/Library/Android/sdk/platform-tools:$PATH -export PATH=~/Library/Android/sdk/emulator:$PATH -``` - -On Windows, you can use the following commands: - -``` -set PATH=%LOCALAPPDATA%\Android\sdk\cmdline-tools\latest\bin;%PATH% -set PATH=%LOCALAPPDATA%\Android\sdk\platform-tools;%PATH% -set PATH=%LOCALAPPDATA%\Android\sdk\emulator;%PATH% -``` - -Run the tests with the Android emulator by running the following command: - -``` -python allTests.py --android --controller-app -``` - -To run the tests on a Android device connected through USB, you can use -the `--device=usb` option as shown below: - -``` -python allTests.py --android --device=usb --controller-app -``` - -To connect to an Android device that is running adb you can use the -`--device=` - -``` -python allTests.py --android --device= --controller-app -``` - -To run the tests against a `controller` application started from Android -Studio you should omit the `--controller-app` option from the commands above. - -## IceGrid GUI Tool - -Ice for Java includes the IceGrid GUI tool. It can be found in the file -`lib/icegridgui.jar`. - -This JAR file is completely self-contained and has no external dependencies. -You can start the tool with the following command: -``` -java -jar icegridgui.jar -``` - -On macOS, the build also creates an application bundle named IceGrid GUI. You -can start the IceGrid GUI tool by double-clicking the IceGrid GUI icon in -Finder. - -[1]: https://zeroc.com/downloads/ice -[2]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-100 -[3]: https://gradle.org -[4]: http://proguard.sourceforge.net -[5]: https://commons.apache.org/proper/commons-compress/ +# Ice for Java + +[Getting started] | [Examples] | [Maven packages] | [Documentation] | [Building from source] + +The [Ice framework] provides everything you need to build networked applications, +including RPC, pub/sub, server deployment, and more. + +Ice for Java is the Java implementation of the Ice framework. It includes the latest +Slice-to-Java mapping introduced in Ice 3.7. + +## Sample Code + +```slice +// Slice definitions (Hello.ice) + +#pragma once + +module Demo +{ + interface Hello + { + void sayHello(); + } +} +``` + +```java +// Client implementation (Client.java) + +import com.zeroc.Ice.*; +import Demo.*; + +public class Client +{ + public static void main(String[] args) + { + try(Communicator communicator = Util.initialize(args)) + { + HelloPrx hello = HelloPrx.checkedCast( + communicator.stringToProxy("hello:default -h localhost -p 10000")); + hello.sayHello(); + } + } +} +``` + +```java +// Server implementation (Server.java) + +import com.zeroc.Ice.*; + +public class Server +{ + public static void main(String[] args) + { + try(Communicator communicator = Util.initialize(args)) + { + // Install a shutdown hook to ensure the communicator gets shut down when + // the user interrupts the application with Ctrl-C. + Runtime.getRuntime().addShutdownHook(new Thread(() -> communicator.shutdown())); + ObjectAdapter adapter = communicator.createObjectAdapterWithEndpoints( + "Hello", + "default -h localhost -p 10000"); + adapter.add(new Printer(), Util.stringToIdentity("hello")); + adapter.activate(); + communicator.waitForShutdown(); + } + } +} +``` + +```java +// Printer implementation (Printer.java) + +import Demo.*; + +public class Printer implements Hello +{ + @Override + public void sayHello(com.zeroc.Ice.Current current) + { + System.out.println("Hello World!"); + } +} +``` + +[Getting started]: https://doc.zeroc.com/ice/3.7/hello-world-application/writing-an-ice-application-with-java +[Examples]: https://github.com/zeroc-ice/ice-demos/tree/3.7/java +[Maven packages]: https://central.sonatype.com/namespace/com.zeroc +[Documentation]: https://doc.zeroc.com/ice/3.7 +[Building from source]: https://github.com/zeroc-ice/ice/blob/3.7/java/BUILDING.md +[Ice framework]: https://github.com/zeroc-ice/ice