Description
Introduction
In this assignment, you will write a simple messenger app for Android. The purpose of this assignmentistohelpyoudeterminewhetheryouhavetherightbackgroundforthiscourse. If you can finish this assignment allbyyourself, withouthelpfromothers, then it is probably the casethatyouarepreparedforthiscourse. TheapplicationyoudevelopinthisassignmentwillsimplyallowtwoAndroiddevicesto send messages to each other. This will help you understand the basics of the Android environment, refresh your memory on network programming, help ease you into the Android development tools, and introduce you to our testing environment. There are four high-level challenges in this assignment:
• Reading and understanding background material: You will need to read API documentation, tutorials, and articles online in becoming familiar with Android development.
• Infrastructure setup: You will have to install a number of software packages, configure them, and become familiar with their usage. You will also need to get plumbed into GitHub Classroom and UB Autograder.
• Becoming comfortable with Android development: You will encounter roadblocks in developingforAndroid,particularlyifthisisyourfirsttime. Thisistrueforanyplatform or operating environment. Fortunately there is excellent documentation available for Android Studio and the Android APIs.
• WorkingaroundAndroidvirtualdevicerestrictions: The AVD emulator has, in particular, restrictions on network communication for virtual devices. You will need to get used to this for this assignment and for this course.
1 GettingStarted
Unless you are already familiar with Android development, I suggest that you start with some Android tutorials. In addition, you should consult the Android programming assignmentwebpageforthiscourseandensurethatyouhaveinstalledacompatibledevelopment environment (e.g., Android Studio 3.0.1, Android SDK 19). Pleasenote that there are some knownproblemsrunningAndroidStudioinsomeenvironments,andthereareworkarounds on that page!
1Thisassignmentisbased,withpermission,onanassignmentdevelopedandusedbySteveKoinhisversion of CSE 486/586. Large portions of text are used verbatim from that assignment.
1
TheinstructionsforcreatingAVDimagesandconfiguringtheemulatorinvarioustutorials will vary. Note that recent versions of Android Studio require a 64-bit processor with Intel VT-x or AMD-V virtualization extensions, OpenGL graphics support, and x86 emulator images. This greatly speeds up emulation and debugging, but makes running Android Studio in a hypervisor or on older hardware difficult. The first tutorials to look at are:
• The Building Your First App tutorial is advisable for all students, even those with previous Android experience, as a help in validating your Android development environment. Thistutorialwillguideyouthroughinstallingthenecessarysoftwareandbuilding a simple application. Note that we are using Android API version 19, and you should configureyourbuildappropriately!
• Next, look at Managing the Activity Lifecycle, which will help you understand some basicAndroidconceptsthatareusedintheprovidedcodeandthatwillberequiredto successfully complete this assignment.
You will probably want to review some important Android documentation, as well, such
as:
• Application Fundamentals
• Activities
• Processes and Threads
To be successful in this and all future programming assignments, it is critical that you understand the Android virtual device (AVD) emulator both for executing and debugging your application. YouwillbeusingtheemulatorthroughAndroidStudio,standalone,andviathe grading scripts for this course. Please take the time to become familiar with it now! You should review:
• Run Apps on the Android Emulator
• Debug Your App
• Logcat Command-line Tool
2 SettingupaTestingEnvironment
You will need to run two AVDs in order to test your app. Unfortunately, Android does not provideaflexiblenetworkingenvironmentforAVDs,sotherearesomehurdlestojumpover in order to set up the right environment. The following are the instructions. These instructions will assume that your Android SDK directory (configured when you setupAndroidStudio)islocatedin$ANDROID_SDK_ROOT,andthatthisvariableissetappropriately in your environment. This is required for things to work properly!
2
• You need to have the Android SDK and Python 2.x (not 3.x; Python 3.x versions are not compatible with the scripts provided.) installed on your machine. If you have not installed these, please do it first and proceed to the next step. • SetANDROID_HOMEto$ANDROID_SDK_ROOTin your environment. • Add the following directories to your path: – $ANDROID_SDK_ROOT/tools/bin – $ANDROID_SDK_ROOT/platform-tools – $ANDROID_SDK_ROOT/emulator A good reference on how to change$PATHis here. • Download and save these files somewhere convenient: – create_avd.py – run_avd.py – set_redir.py • At this point, makesurethatyourenvironmentandpatharesetupcorrectly! • Create five AVDs by runningpython create_avd.py 5 $ANDROID_HOME. – Youshouldrunthiscommandonlyonce,anditmaytakequitesometimetocomplete. – Youmaybeaskedtoagreetoalicenseagreement[y/N];youwillhavetoagreeto continue. – YouwillbeaskedDo you wish to create a custom hardware profile [no]multiple times. Donotenteranythingwhenasked, the script will handle this automatically. • At this point you should have five AVDs, named avd0 through avd4. You can view and manipulate them in Android Studio, but please do not change or delete them as they are necessary for our scripts to work. • Start a single emulator with the commandemulator @avd0. Wait for it to boot entirely, thenclickandholdthepowerbutton()untilthepoweroffmenuappearsontheemulated device. Click power off, then confirm, and wait for the device to shut down entirely (the emulator command will exit).
• For all of the programming assignments except this one, you will need to run all five AVDs at the same time. You will need to find a machine that can comfortably run five emulators simultaneously. • In order to test this, runpython run_avd.py 5. The first time you do this, it may take a verylongtimeandsomeemulatorsmayfailtostart. Ifso,waituntiltheyhaveallmade asmuchprogressaspossible(eitherbootedorvisiblyfrozen,typically),shutdownthe emulators, and try again.
3
• For this assignment, you will use only two AVDs, so you will start them with python run_avd.py 2. • After you successfully launch all five AVDs, run the commandpython set_redir 10000 to create an emulated network connecting the five AVDs. There are some restrictions to how this works, discussed later in this document.
• After verifying your development environment, you can shut down the emulators.
3 TheSimpleMessengerApp
The graded portion of this project is writing the simple messenger app. You will need to downloadtheprojectfromGitHubClassroom(youshouldhavereceivedaninvitationtoour classroom; if you have not, please contact me ASAP!) and open it in Android Studio.
1. Accept the invitation to GitHub Classroom to create your project repository.
2. Clone the GitHub your repository for SimpleMessenger. The repository URL will be git@github.com/ub-cse586-s18/SimpleMessenger-$githubid,where$githubidisyourGitHub username. You can do this on the command line or in Android Studio.
3. Open the cloned project in Android Studio.
4. Take some time to understand the template code. • The main Activity is inSimpleMessengerActivity.java. • Please read both the code and the comments carefully!
5. Add your code to the cloned project, committing to GitHub as you make progress. There are places in the template marked “TODO”; these are the places where you will need to add your code.
3.1 Requirements These are the project requirements. You must follow these instructions exactly. If you do not, you will receive nocredit for this assignment. Whenwesaynocredit,wemeanit. It is critical that you follow directions precisely and accurately in this course.
1. There should be only one app that you develop and need to install for grading, and it shouldusethemanifestprovidedinthetemplatecode. Ifyouusetheprojecttemplate code, you should satisfy this requirement.
2. There should be only one text box on-screen where the user of the device can enter a text message to be sent to the other device. If you use the project template code, you should satisfy this requirement.
4
3. Each device should display on-screen what it has received. The project template contains basic code for displaying messages on the screen.
4. You need to use the Java Socket API.
5. All communication should be over TCP.
6. You may assume that the size of a message will never exceed 128 bytes (ASCII characters).
3.2 Communication As mentioned above, the Android emulator is not very flexible in the networking facilities thatitprovidesforcommunicationbetweenAVDs. Althoughset_redir.pyenablesnetworking among multiple AVDs, it is very different from a typical networking setup. When you write your socket code, you will have the following restrictions: • In your app, you can open only one server socket, which must listen on port 10000 regardless of which AVD your app is running on. • The app onavd0can connect to the listening server socket of the app onavd1by connecting to 10.0.2.2:11112 (that is, IP address 10.0.2.2, port number 11112). • The app onavd1can connect to the listening server socket of the app onavd0by connecting to 10.0.2.2:11108. • Your app knows which AVD it is running on via the following code snippet. IfportStr is5554, then it isavd0. IfportStris5556, then it isavd1: TelephonyManager tel = (TelephonyManager)this.getSystemService(Context.TELEPHONY_SERVICE); String portStr = tel.getLine1Number().substring(tel.getLine1Number().length() – 4); Theprojecttemplatealreadyimplementstheabovecode,butyouareexpectedtounderstand thecodeasthisiscriticalfortherestoftheprogrammingassignments. • In general, set_redir.py creates an emulated, port-redirected network like this (VR stands for “virtual router”):
5
3.3 Testing We have testing programs to help you see how your code does with our grading criteria. If youfindroughedgesinthetestingprograms,pleasereportitsotheteachingstaffcanfixit. The instructions for using the testing programs are the following:
1. Downloadatestingprogramforyourplatform. Ifyourplatformdoesnotrunit,please report it.
(a) Windows: Tested on 64-bit Windows 8. (b) Linux: Testedon64-bitDebian9and64-bitUbuntu17.10(seebelowforimportant information about 64-bit systems). (c) Mac OS: Tested on 64-bit Mac OS 10.9 Mavericks. 2. Before you run the program, please make sure that you are running two AVDs (avd0 andavd1). You can usepython run_avd.py 2to start them. 3. Make sure that you have installed your SimpleMessenger application on both AVDs!
4. Run the testing program from the command line.
5. It may issue some warnings or errors during execution. Some of them are normal, some may indicate errors in your program. Examine them to find out!
6. At completion, it will give you one of three outputs:
• No communication verified: The SimpleMessenger instances cannot communicate with each other. This would be worth 0 points. • One-waycommunicationverified: TheSimpleMessengeronavd0cansendamessage to the SimpleMessenger onavd1. This is worth 2 points. • Two-waycommunicationverified: BothAVDscancommunicatewitheachother. This is worth an additional 3 points, for a total of 5.
Remember that this is only a simple test against the grading criteria. It is not a test for development progress! You will want to create your own tests as you go along.
Notesfor64-bitLinux: Thetestingprogramiscompiled32-bit. Ifyougetanerrorlikethe following, install the 32-bitlibzfor your system: ./simplemessenger-grading.linux: error while loading shared libraries: libz.so.1: cannot open shared object file: No such file or directory OnDebian-baseddistributions,youcanaccomplishthiswiththecommandapt-get install libz1g:i386 as root (you may need to use sudo or su). If apt-get reports an error about the architectureorsaysthepackageisnotfound,youmayneedtoenablemultiarch. Todothis, rundpkg –add-architecture i386as root, then update your APT repositories withapt-get updateas root. Once this is done, you should be able to install the 32-bitlibz. For other distributions you will need to consult your distribution documentation.
6
3.4 Submission We use UB CSE autograder for submission. You can find autograder athttps://autograder. cse.buffalo.edu/, and log in with your UBITName and password. Once again, it is critical that you follow everything below exactly. Failure to do so willlead tonocreditforthisassignment. ZipupyourentireAndroidStudioprojectsourcetreeinasinglezipfilenamedSimpleMessenger. zip. Ensure that all of the following are true: 1. You didnot create your zip file from inside theSimpleMessengerdirectory. 2. Thetop-leveldirectoryinyourzipfileisSimpleMessenger,anditcontainsbuild.gradle and all of your sources.
3. Youusedaziputilityandnotanyothercompressionorarchivetool: thismeansno7-Zip, no RAR, no tar, etc.
3.5 Deadline This project is due 2018-02-05 11:59:00 AM. This is one hour before our class. This is a firm deadline. If the timestamp on your submission is 11:59:01, it is a late submission. You are expected to attend class on this day!
3.6 Grading This assignment is 5% of your final grade. Credit for this assignment will be apportioned as follows: • 2%: Your messenger app can send one-way messages fromavd0toavd1. • 3%: Your messenger app can send two-way messages betweenavd0andavd1.
Thus, an application that can send two-way messages will receive a total of 5%: 2% for sending fromavd0toavd1, and 3% for also being able to send messages back.
4 OtherResources
In addition to Android Developers and the course Android documentation (which will be updatedwithFAQsandfixes,sokeepaneyeonit!),Ihavepreparedafewvideostohelpwith gettingthedevelopmentenvironmentsetupandpreparingthehandoutcodeusingGitHub Classroom. You can find them on YouTube.