====================================================================== Contents ====================================================================== Table of Contents ----------------- 1. Introduction 2. Requirements 3. Installation 4. Eclipse Development 5. Sample Projects 6. Application Notes ====================================================================== 1. Introduction ====================================================================== This Ice for Android distribution contains the following components: * Ice for Android run time (java/lib/IceAndroid.jar) * Ice for Android tests (java/lib/IceTest.jar) * Eclipse projects for three sample clients and a test suite * Source code for the Ice for Android run time, demos, and tests We encourage you to review the RELEASE_NOTES file for important information about this release. If you are interested in building Ice for Android from source, please consult the INSTALL file. ====================================================================== 2. Requirements ====================================================================== You must install Ice 3.3 to use Ice for Android. Binary and source distributions of Ice can be downloaded at the link below: http://www.zeroc.com/download.html Ice for Android also requires the Android 1.1r1 SDK, which is available at the following link: http://developer.android.com ====================================================================== 3. Installation ====================================================================== You can extract this distribution in the location of your choice. The only file in this distribution that is necessary for developing your own Android applications is the Ice for Android run time JAR file (java/lib/IceAndroid.jar), which you may prefer to copy to another directory. ====================================================================== 4. Eclipse Development ====================================================================== This section discusses Ice for Android development using Eclipse. If you are not using Eclipse to develop your Android application, you may find the information in the INSTALL file useful. Slice2Java Plugin ----------------- ZeroC has created a Slice2Java plugin for Eclipse that automates the translation of your Slice files. We strongly recommend using this plugin for your own development, and the plugin is required if you intend to build any of the Eclipse projects included in this distribution. For more information on installing and using the plugin, please refer to the link below: http://www.zeroc.com/eclipse.html The instructions in this file assume that you have already installed and configured the Slice2Java plugin. Configuring your Project ------------------------ After installing and configuring the Slice2Java plugin, you will need to add the Ice for Android run time JAR file to your project: 1. Select Java Build Path in the project's properties 2. Click on the Libraries tab 3. Click Add External JARs... and choose IceAndroid.jar from the directory in which you installed it 4. Click OK to save your changes ====================================================================== 5. Sample Projects ====================================================================== The following prerequisites are necessary for using the sample projects in this distribution: 1. Eclipse is installed See http://www.eclipse.org 2. Android ADT is installed and configured See http://code.google.com/android/intro/installing.html#installingplugin 3. Ice 3.3 is installed See http://www.zeroc.com/download.html 4. Slice2Java plugin is installed and configured See the section "Eclipse Development" above. 5. Your workspace is configured with a linked resource that allows the sample projects to locate the Ice for Android run time JAR file. Perform the following steps to add the resource: 1. In Eclipse, choose Window->Preferences 2. Open the General->Workspace folder 3. Select the Linked Resources entry 4. Click New... to add a new path variable 5. Enter ICE_JAR_HOME in the Name field 6. Enter the path name /java/lib in the Location field, such as C:\IceAndroid-0.1.1\java\lib on Windows or /opt/IceAndroid-0.1.1/java/lib on Linux. 7. Click OK to save the path variable It is not necessary to define this resource in your own projects, and you can remove it as soon as you are finished using the sample projects. In Eclipse, you can open a sample project by choosing File->Import... and selecting one of the subdirectories of /android/demo To open the testsuite project, select the following subdirectory: /android/testsuite The projects are described below. Hello ----- The hello client is the Android equivalent of our command-line demo of the same name. In order to use this client, you must run a hello server and enter the server's address in the client's "Hostname" field. This distribution includes the Java version of the command- line demo in java/demo/Ice/hello (see the README file in that directory for usage information), or you can use a server from your Ice installation. Note that in order to use the server in java/demo/Ice/hello you must build the demo. As discussed in the INSTALL file, you must have Ant and Ice installed on your system, and the ICE_HOME environment variable must be set to the location of your Ice installation. To build the demo, open a command window, change to the demo directory, and run 'ant'. You will need to add IceAndroid.jar to your CLASSPATH when executing the server. Chat ---- The chat client provides Android devices with native access to our sample chat system. This client demonstrates several useful techniques that are instructive for Android developers: * Issuing asynchronous Ice invocations to maintain a responsive user interface * Using Glacier2 and bidirectional connections to receive "push notifications" from a remote server * Proper separation of UI and application logic By default the client uses "demo.zeroc.com" as its server, which refers to the public chat server hosted by ZeroC. For more information about the chat system, or to download the source code for the chat system so that you can run your own server, please refer to the link below: http://www.zeroc.com/chat/index.html Library ------- The library client is an example of an Android front-end for an enterprise-style application. It allows you to query and manipulate a library of books by issuing Ice invocations to a remote server implemented using JDBC and MySQL. Like the chat client, this program defaults to a ZeroC-hosted server on "demo2.zeroc.com". If you prefer, you can download the source code for the library server at the link below: http://www.zeroc.com/labs/icetouch/download.html Test Suite ---------- The Ice for Android test suite project is an Android front end for the tests encapsulated in the JAR file named /java/lib/IceTest.jar. In order to build this project, it may be necessary for you to increase Eclipse's maximum memory limit. Locate the eclipse.ini file in your Eclipse installation and change it to contain the following line: -Xmx512m The test suite is entirely self-contained in that the client-server communication all occurs locally between sockets in the same Android process. When you start the test suite program, you are presented with a list of all possible tests along with a checkbox that, when enabled, forces all communication to use SSL instead of the default TCP. Each test must be run individually; after starting a test, its progress is displayed with "ok" messages indicating success. Upon the test's completion, you can press the Next button to start the next test in the sequence or press the Back button if you want to start a different test. ====================================================================== 6. Application Notes ====================================================================== Protocol Compression -------------------- Ice for Android supports protocol compression using the bzip2 classes included with Apache Ant. To enable this feature, the classes must be present in the application's CLASSPATH or Android package (.apk) file. The bzip2 classes can be found in ant.jar, or you can download only the bzip2 classes from http://www.kohsuke.org/bzip2/ Note that these classes are a pure Java implementation of the bzip2 algorithm and therefore add significant latency to Ice requests. Also be aware that the Ice run time loads these classes dynamically; if you use a packaging tool such as ProGuard, you may need to explicitly include the bzip2 classes to ensure that they are included with the application. For more information on protocol compression, see this issue of the newsletter: http://www.zeroc.com/newsletter/issue7.pdf