tutorial java p800

July 2002 Java support in Sony Ericsson mobile phones P800 and P802 2 Contents Preface……………………………………………………………………………….3 Java and its possibilities for Sony Ericsson………………………………… 4 PersonalJava applications and SymbianOS………………………………… 6 Java characteristics for P800/P802…………………………………………….8 P800/P802.…………………………………………………………………………14 Appendix………………………………………………………………………… 23 Index……………………………………………………………………………… 26 These Developers’ Guidelines are published by: Sony Ericsson Mobile Communications AB, SE-221 88 Lund, Sweden Phone:+46 46 19 40 00 Fax: +46 46 19 41 00 www.SonyEricssonMobile.com First edition (July 2002) Publication number: EN/LZT 108 5746 R1A This document is published b y Son y Ericsson Mobile Communications AB, without any warranty. Improvements and changes to this text necessitated by typographical errors, inaccuracies of current information or improvements to programs and/or equipment, may be made by Sony Ericsson Mobile Communications AB at any time and without notice. Such changes will, however, be incorporated into new editions of this document. Any hard copies of this document are to be 3 1. Preface This document describes how to implement Java based applications in the Sony Ericsson mobile phones P800/P802. Who should read this guide? This document is intended for developers of Java applications who want an insight into the Sony Ericsson P800/P802 mobile phones. It will also illustrate for network operators the advanced capabilities and revenue generating potential of Java applications within the P800/802. It is assumed that the reader is familiar with Java. 4 2. Java and its possibilities for Sony Ericsson mobile phones Sony Ericsson, with its strong commitment to bringing out the best in mobile communications, has developed a superbly designed, attractive phone that is crammed with useful and exciting functionality. One of the gems in this collection of functionality is Java. Java offers great possibilities for end-users, network operators and content providers. There is virtually no limit to the content that can be supplied and downloaded. Users can effortlessly add new information and entertainment-based applications to their phones, bringing personalization to new heights. Gaming is already a very popular feature in Sony Ericsson phones. With Java, users can add new games and skill levels to further enhance the entertainment value of Sony Ericsson phones. For network operators and content providers, the Java technology gives a secure platform from which to offer dynamic value-added services, with new opportunities to boost revenue and increase customer loyalty. Since Java is a flexible and open technology, developers can rapidly create new applications, and speed up the time to market. Operators and providers can quickly and easily adapt and take advantage of changes in market demands to differentiate their products and gain the competitive edge. Users will undoubtedly find the concept of enhanced personalization and greater diversity in application supply very tempting, leading to increased customer on-air time. Java — the key to personalization The number of mobile phone users in the world is increasing rapidly. An ever-increasing number of phones will be connected to the Internet. This opens new possibilities for users, operators and content providers. Users will have the option to personalize their mobile devices by downloading new applications such as games and utility software. This need for customized content makes greater demands on the application development platform than has traditionally been the case. Java, which is a widely used, extensible programming platform, makes the development of personalized applications and content much easier. Background Originally developed by Sun in 1991, Java is a programming language used to develop applications, - utility programs, games, plug-ins etc. for different hardware and software platforms. Users of Java- enabled devices can install new applications and games to make their devices more personal and adapt them to specific needs. Sun marketed Java as a “write once, run anywhere” concept, which at the time was a good description of Java's strength. Simply put, Sun based the Java concept on two parts, the Java application and the Java interpreter, called Java Virtual Machine (JVM). A Java application cannot run by itself - it needs an interpreter that translates the code and runs the program. This was the secret behind Java's ability to work on various platforms. A developer could write an application without having to think about different computers and operating systems as long as hardware and software manufacturers included Java Virtual Machines in their products. 5 Even if “write once, run anywhere” still applies to some degree, the evolution of handheld computers and telecommunications forced Sun to adapt Java to the requirements of mobile devices with small displays and slow connections. This led, among other things, to the development of PersonalJava, J2ME™ (Java 2 Platform, Micro Edition) and the K Virtual Machine (KVM). Two types of Java for mobile phones The types of applications that can be installed are dependent on the type of Java in the phone. There are two main versions of Java in Sony Ericsson mobile phones, J2ME CLDC/MIDP (often called kJava) and PersonalJava (pJava). PersonalJava PersonalJava, which is sometimes called pJava, was one of the first Java programming environments targeted at applications for resource-limited devices. These devices include PDAs (Personal Digital Assistants) and Communicators/Smart phones. PersonalJava introduced features that reduce memory usage and adapt applications to different screens and graphical interfaces. PersonalJava was transferred into the J2ME platform in 1999. The new version is called J2ME CDC/Personal Profile. However, CDC/Personal Profile has not really taken off yet and pending its breakthrough, PersonalJava will still be a powerful option for years to come. Sony Ericsson high-end phones based on the Symbian OS, like the P800/802, offer this advanced capability to develop feature-rich applications in Java. In addition to PersonalJava, it is possible for developers to access JavaPhone through the SymbianOS UIQ SDK. This will allow developers to develop and test applications on a Windows PC. Although JavaPhone will not be available in the first version of P800/P802 it will be included in the second release. CLDC/MIDP Historic overview In 1999, Sun regrouped its Java technologies into three platforms or editions. J2ME (Java 2 Platform, Micro Edition) became the platform targeting “micro” devices with small processors and memory capacities, such as mobile phones, communicators and PDAs (the other two Java platforms are Java 2 Platform, Standard Edition, J2SE™, and Java 2 Platform, Enterprise Edition, J2EE™). J2ME addresses a variety of devices. To handle the diversity, two concepts have been introduced — configurations and profiles. A configuration defines a minimum platform for a family of devices with similar processing and memory capacities. A profile targets a specific device category within that family, for instance mobile phones. Two J2ME configurations are available: CDC, Connected Device Configuration. This configuration is aimed at devices like PDAs. CLDC, Connected Limited Device Configuration. This configuration is aimed at devices like mobile phones and pagers. Current situation So far, two profiles have been established for J2ME - MIDP, Mobile Information Device Profile, and Personal Profile. MIDP is connected to the CLDC configuration and provides developers with essential information and guidance when writing programs for mobile phones and two-way pagers. Personal Profile is linked to CDC, Connected Device Configuration. Targeted at PDAs, this combination replaces PersonalJava in J2ME. 6 3. PersonalJava applications and SymbianOS This section offers advice about developing PersonalJava applications that require SymbianOS environment specific knowledge typically not needed for MIDP applications. A good starting point for development is getting access to the Symbian UIQ SDK that contains complete documentation on the PersonalJava environment and the tools needed for packaging applications into installable format. It is important for the PersonalJava developer to become familiar with the 'Aifbuilder' and 'makesis' tools for preparing applications to run on the P800. Aifbuilder is needed for generating three files with the suffixes .aif, .app and .txt, which are installed along with, jar files and/or class files of the application. The .aif and .app file are required in order for the application to appear in the Application Launcher list of applications. “makesis” is needed for generating SIS format installation files that make it possible to make a personalJava application available to end users for installation. This step is not needed during development where the developer can simply copy the application into the P800 file system over the Symbian Connect link and run it. 'sisar' is a GUI front end towards 'makesis' that can speed up the process of frequently generating new SIS file versions. All these are documented in the UIQ SDK. Aifbuilder and makesis are also used in preparing installable C++ applications. In earlier releases of Symbian SDKs there have been setup/environment variable problems with these tools but running these from the UIQ SDK work well. The problems that can occur are caused by keeping a mixed environment of different SDK versions on the same development host so that environment settings come into conflict. Installing the UIQ SDK on a 'clean' machine and not installing other Symbian SDK versions on the same host is the safest approach to ensuring the tools work. PersonalJava application considerations on P800 Apart from keeping in mind performance limitations, PersonalJava applications on P800 require little additional consideration compared to ordinary desktop Java development. Available screen size is 276x208 pixels and an application is usually based on the java.awt.Frame class. A good rule to minimize startup of applications that contain complex GUIs, is not to instantiate all GUI elements at startup but instead just before they are first needed. To give the user a perception of a quick starting application it may be a good idea to load and display a 'splash screen' as the first action while additional initialisation continues. This is something to consider for commercial grade applications where this additional development work is well worth the effort. PersonalJava performance The P800 java runtime is installed in a secondary 'pseudo ROM' file system where the virtual machine will not execute directly from ROM but instead the VM and all classes become loaded into RAM before execution. This adds an additional one-second-startup time compared to ROM execution but as a slight bonus, execution from RAM is somewhat faster than from ROM once the VM and classes have been loaded. Java was moved out of 'real ROM'due to project decisions to store other software there. Excellent opportunities for reusable code Java provides excellent support for reusing developed solutions due to the good modularity and limited runtime dependency on other code. Once a 'startup framework' for applications has been developed giving good end user perception, that solution can be quickly reused in many applications to give a uniform experience for the end user of applications from a specific vendor. 7 P800 folders When developing a PersonalJava application it is not necessary to package it in a SIS file for every new version to be tested. The developer may copy the files that make up the application to a folder in the User internal file system (C:) or to a folder on the Memory Stick (D:) using the Symbian Connect serial link. The application is copied to a folder /System/Apps/<name of application>/<application files> on the desired logical disk.(C: or D:) Typically an application consists of a number of mandatory files and a number of additional files specific to the actual application. Mandatory files in case of PersonalJava are .app .aif and.txt files that define the PersonalJava application so that it can appear in the Application Launcher. You use the Symbian 'aifbuilder' tool to generate these files. See the Symbian UIQ SDK for detailed documentation on this. In addition you need the actual class files that can either be stored as one or more jar files or as class files in any structure referred to by a class path. Again, see the Symbian documentation for details on this. Typically during development the developer need only update those files that are changing during development such as jar files and the test iteration cycle can be kept short. Optional download features supported The browser can download jar/jad or SIS files from WAP and HTML pages provided that the server supports the actual file types. P800 can also download JAR/JAD/SIS files from ordinary web servers provided that they support the mime type for each of the file types. Some servers need to be configured for this. 8 4. Java characteristics for P800/P802 The P800/802 is based on Symbian OS v7.0 and the established UIQ MMI. Sony Ericsson and Symbian have been actively working with software developers and a range of UIQ-based applications has been publicly demonstrated. Sony Ericsson is also an active participant in developer events such as the Symbian Developer Conference and Java One. Third party applications may make use of the communications, display and storage facilities of the P800/802. Such applications may therefore be much more powerful than browser-based applications, enabling games to be faster and more exciting. Applications from other PDA OSs and from the PC world may be expected to be ported across to the P800/802. Applications already available for Symbian OS (for example, on Psion products) may be ported by the supplier to run on the P800/802. The P800/802 supports both PersonalJava TM and J2ME CLDC/MIDP. It is ready to run many applications written for handheld computers and mobile phones. It has 12 Mbytes user data space in which settings, user data and third party applications are stored. (9 Mbytes on the P802). Applications are easily downloaded directly to the P800/802 using the browser, or may be installed from a connected PC. There is also a Memory Stick consisting of a flash memory and controller. The P800/802 uses the Memory Stick Duo, which is smaller than a regular Memory Stick. Width Height Depth Memory Stick 21.5mm 2.8mm 50.0mm Memory Stick Duo 20.0mm 1.6mm 31.0mm PIM data cannot use the MS, but multimedia content such as images, movie clips, sound clips etc. can be stored either in local memory or on a Memory Stick. Also general-purpose files such as Word documents can be stored there and then accessed using the viewers provided with the P800/802. Third party (Java and C++) applications can use the MS both for the application itself and for storing data. Applications may be written in both C++ and Java. Supported Java environments are PersonalJava TM and J2ME CLDC/MIDP, both of which are optimised for quick start-up time. C++ is the most comprehensive and flexible programming environment, which enables rich applications to be developed. C++ applications will run faster than those written in Java. The P800 supports this J2ME CLDC 1.0 / MIDP 1.0 environment. Applications may make use of Persistent storage - (RecordStore class only — no access to the rest of the filing system) and theTouch Screen - Virtual Keyboard and Jog Dial (up, down, select) input J2ME/CLDC uses a sandbox. The sandbox includes a number of system components working together to ensure that untrusted applications cannot gain access to system resource. MIDP Application running on MIDP/CLDC/KVM UIQ Virtual Keyboard + Jog Dial Internet Persistent Storage JAR file resource Services and pages with response in HTML format Other networked devices (datagram communication) J2ME CLDC Sandbox HTTP/ Datagram 9 MIDP applications can interact with arbitrary remote services that exist as a URL. Data may also be exchanged with remote devices that accept an HTTP or datagram connection. Applications are typically downloaded from the mobile operator’s portal or the Internet. Applications are used in FO mode. When the flip closes, the instance of the Virtual Machine is not visible, but the user may return to the application by selecting it from the Application Launcher. Sony Ericsson Advanced Developer Support The Advanced Developer Support equips professional developers with everything they need to successfully develop world-class applications for Sony Ericsson products. With this support contract, developers get access to a high-quality online support with fast response and resolution times and up to 50 technical support incidents. They also get access to early technical product information and development tools as well as the complete range of interactive and static online support resources. This service requires a paid subscription. Sony Ericsson Basic Developer Support The Basic Developer Support is an annual support service package that provides developers with all the basics to successfully develop world-class applications for Sony Ericsson products. With this support contract, developers get access to a high-quality online support with same-day response and resolution times, five technical support incidents as well as the ability to purchase more. They also get access to complete technical product information and development tools as well as the whole range of interactive and static online support resources. This service requires a paid subscription. Sony Ericsson Online Support Some online resources are available to all developers for free. All that is needed is to register as an Ericsson Mobility World Community member. After registration, access is granted to selected technical product information and development tools as well as limited access to interactive and static online support resources. Security Sony Ericsson will provide service through Ericsson Mobility World, which will enable application developers to obtain a certification of their applications from Sony Ericsson. Digital certificates are used to classify the status of applications and media that are to be loaded: Unsigned: No certification or testing: The provider of the application has not been assessed. There is no guarantee that the application is from the advertised source. The application may or may not have been tested to ensure that it works well on the P800, but any claims to that effect are not independently tested. Signed & Certified Both the software vendor and the application have been tested and certified. The application is certified as originating from the named vendor. The application has been tested to check compatibility with the P800 End users should select certified applications wherever possible, in order to avoid the risk of a badly written or malicious application creating problems such as deleting data, corrupting the configuration or preventing other applications from operating correctly. Mobile Operators may choose to factory-customise the P800 so that only certified applications can be loaded. 10 Screen sizes The image below shows the screen size when working with PersonalJava, 276 x 208 pixels. [...]... Environment J2EE Java 2 Platform, Enterprise Edition J2ME Java 2 Platform, Micro Edition A Java platform targeting “micro” devices with small processors and memory capacities, such as mobile phones, communicators and PDAs J2SE Java 2 Platform, Standard Edition JAD Java Application Descriptor (file) JAR Java Archive (file) JSR Java Specification Request JVM Java Virtual Machine 23 kJava An older term... embedded in the component forces a new line P800/ P802 PersonalJava font limitations (java. awt.Font) The fonts and font sizes available to PersonalJava applications on P800/ P802 are limited by the native fonts available in SymbianOS It is possible to get a list of fonts available using the java. awt.Toolkit class: First obtain the toolkit using: java. awt.Tookit tk =java. awt.Toolkit.getDefaultTookit(); You... Links Java technology J2ME White Paper: http:/ /java. sun.com/products/cldc/wp/KVMwp.pdf CLDC (JSR-30):\ http:\jcp.org\jsr\detail\30.jsp MIDP (JSR-37): http://jcp.org/jsr/detail/37.jsp OTA provisioning: http:/ /java. sun.com/products/midp/OTAProvisioning-1.0.pdf Helpful hints for developers: http:/ /java. sun.com/j2me/docs/pdf/midpwp.pdf PersonalJava: http:/ /java. sun.com/products/personaljava/ PersonalJava... x 208 pixels 11 Others 236 x 208 pixels 12 Additional characteristics P800/ P802 Pixel ratio (H : W) 1:1 Colors 4096 Memory storage P800 12 M Memory 9M storage P802 Memory, heap 8M CLDC version 1.0.2 MIDP version 1.0.3 Other API support PersonalJava supports JNI (Java Native Interface) PersonalJava version 1.1.1a Java IR APIs No Java Bluetooth APIs No Serial USB Debug interface JDWP OTA RP v 1.0 Yes... Supported tools The P800/ 802 supports the following tools: Sun Java One Studio 4 and Metrowerks Code Warrior Wireless Studio and Metrowerks Codewarrior Development Tools for SymbianOS for C++ development and PersonalJava These tools, as well as the Sony Ericsson device emulators (skins) can be found at: http://www.ericsson.com/mobilityworld/sub/open/technologies /java/ tools.html?PU =java& P Uname =Java& PUCat=technologies... http://www.ericsson.com/mobilityworld/sub/open/technologies /java/ tools.html?PU =java& P Uname =Java& PUCat=technologies Supported protocols The P800 supports MIDP 1.0 and PersonalJava 1.1.1 To access the latest information about supported protocols please go to the following address: http:/ /java. sun.com 13 5 P800/ P802 Key mapping The following key mapping is implemented in the P800/ P802 Java applications can only be navigated in the Flip Open mode The available character... screen 16 P800/ P802 Common characteristics MIDP/PersonalJava Display color support 4096 colors Each of the P800/ 802 display RGB channels are 4 bits, 0x0-0xF Decimal representation in Java: In Java a 24 bit value is used to hold a color The following will apply to a 24-bit binary value (0000 indicates fields which will have no display effect) : (msb)RRRR0000GGGG0000BBBB0000(lsb) RGB representation in Java: ... http:/ /java. sun.com/j2me/docs/pdf/midpwp.pdf PersonalJava: http:/ /java. sun.com/products/personaljava/ PersonalJava http://www.symbian.com/books/wjsd/wjsd-info.html JavaPhone: http:/ /java. sun.com/products/javaphone/ Java on Symbian OS http://www.symbian.com/technology/standard -java. html Sony Ericsson Java White Paper http://.ericsson.com/mobilityworld/ 25 7 Index A Abbreviations 23 Aifbuilder 6 Alert class 18 API support 22 Application... then becomes visible on screen again 17 P800/ P802 MIDP specific characteristics Touch screen support Your application can use the following MIDP methods of class javax.microedition.lcdui.Canvas to determine touch screen availability: public static boolean hasPointerEvents(); (Returns TRUE on P800/ 802) public static boolean hasPointerMotionEvents(); (Returns TRUE on P800/ P802) Alert class Alerts are always... Wireless Application Protocol Related information The Java Language Specification by James Gosling, Bill Joy, and Guy L Steele Addison-Wesley, 1996, ISBN 0-201-63451-1 24 The Java Virtual Machine Specification (Java Series), Second Edition by Tim Lindholm and Frank Yellin Addison-Wesley, 1999, ISBN 0-201-43294-3 Programming Wireless Devices with the Java2 Platform, Micro Edition by Roger Riggs, Antero . type of Java in the phone. There are two main versions of Java in Sony Ericsson mobile phones, J2ME CLDC/MIDP (often called kJava) and PersonalJava (pJava). PersonalJava PersonalJava, which. description of Java& apos;s strength. Simply put, Sun based the Java concept on two parts, the Java application and the Java interpreter, called Java Virtual Machine (JVM). A Java application. 17 P800/ P802 Common characteristics MIDP/PersonalJava Display color support 4096 colors. Each of the P800/ 802 display RGB channels are 4 bits, 0x0-0xF. Decimal representation in Java: In Java