CHAMELEON Project. Developer Guide. - Mobile Client - Server - UDDIe Registry. CHAMELEON Client and Server side

Transcription

1 CHAMELEON Project Developer Guide - Mobile Client - Server - UDDIe Registry i

2 Version Changes Author(s) V2.0 The Mobile Client, the Server, the Resource Model, the Analyzer, and the Registry have been completely revised and extended according to the novel approach that support the Hybrid (static and dynamic) Analysis. The hybrid approach is based on a new Resource Model that characterizes the notion of resources. It uses an Abstract Resource Analyzer (ARA) that statically scans the bytecode abstract syntax tree of Java applications and refines the associated resource sets using a transition system. The latter models the semantics of the bytecode in terms of resource consumption. ARA is parametric with respect to a Resource Consumption Profile that, dynamically sent by the CHAMELEON-enabled devices requesting an application, associates resource consumption to particular patterns of Java bytecode instructions. The profile permits to define the resource consumption associated to both basic instructions (e.g., ipush, iload) and to complex ones such as method calls. In particular, the dynamic phase of the analysis avoids to statically performs the expensive inter-procedural call-closure for library methods. The preprocessor derives the Application Descriptor that, among other information, also lists the calls to external library methods for each alternative. Specifically, for each external method call in the list, the programmer (supported by the CHAMELEON IDE see the user guide of the CHAMELEON IDE) specifies the worst-case callcontext on the base of the application logic that has been coded. When a device requests an application, during the dynamic phase of the analysis, each library method is then executed by the CHAMELEON Client in the target execution environment, and its actual resource consumption is computed. This consumption is used to specify into the profile the resources consumed by each library method. The advantage of combining the static and the dynamic phase is to avoid to statically perform the expensive inter-procedural call-closure for library methods. In fact, the static inter-procedural call-closure in Java is extremely expensive for even a simple Hello World program due to the use of standard libraries. - Marco Autili, - Paolo Di Benedetto - Paola Inverardi ii

3 Table of Contents 1. ECLIPSE Project basic configuration Chameleon Mobile Client Chameleon Server CHAMELEON Server structure UDDIe - Eclipse Project configuration Creating the Database Creation and configuration of the UDDIe Eclipse project Appendix A - Advanced - Adding JAR Files to a MIDlet Suite Types of JAR Files Adding Hardware JAR files Using Device Definitions to Add Hardware JAR files Adding Directly To A Project Which Approach Is Better? Adding Application JAR files Emulator Caveats iii

4 1. ECLIPSE Project basic configuration The following guidelines work for the Eclipse Platform we used when writing this document. However, it should be easy to accommodate differences for later versions. In any case you need to: 1. install (if not already installed in your ECLIPSE version) the plugin EclipseME ( 2. install some Wireless Toolkit emulator. We used the Sun Java Wireless Toolkit for CLDC version on Windows (the site should work). 3. install tomcat. We used tomcat 6.0 ( Make sure to use JRE version 1.5 or later to make tomcat 6.0 run properly. Make also sure to set the Compiler compliance level to 1.5 or higher to avoid statically highlighted error. (right click on project root and choose Properties -> Java Compiler). Before reading the following guidelines, you should download the archive containing the Mobile Client, the Server, and the UDDIe Registry from the CHAMELEON web site import the Eclipse projects inside the archive, and adjust the Build Path to properly refer libraries, etc,. As first steps: o (Client) associate an emulator to the project; o (Server) associate a Tomcat server to the project; o (Server) set the paths into the files: o (i) web.xml (into the server-side folder WebContent/WEB-INF/) o (ii) chameleon.init.xml (into the server-side project root folder) see end of Section

5 2. Chameleon Mobile Client Choose File, New, Project, J2ME, J2ME Midlet Suite and call it (for instance) Chameleon Mobile Client (see Fig.1 and Fig.2) Fig. 1 2

6 Fig. 2 Choose Next and then Manage Device (Fig.3), Import (Fig.4) and Specify in Item Search Directory (Fig.5); select the destination path of the WTK to use (e.g., C:\WTK2.5.2), then click Refresh and, once completed, the checkbox lists of the various device types to be used will be shown (Fig.6). Choose Finish and the list of devices will appear: choose one of them. Once selected the type of device, press Apply, OK, Next and Finish. The project is created. 3

7 Fig. 3 4

8 Fig. 4 Fig. 5 5

9 Fig. 6 Load the src folder and the lib folder. The latter contains the kxml.jar library that must be included in the build path of the project. Thus, select Project, Properties, Java Build Path, Libraries, Add JARs and choose the two libraries (Fig. 7.1, Fig. 7.1, Fig. 7.3). In particular, the Order and Export tab specifies that the library kxml.jar will be included into the deployable MIDlet.jar file produced when packaging the Chameleon Client MIDlet. The files will be stored into the deployed folder. 6

10 Fig. 7.1 Fig

11 Fig. 7.3 When creating the.jad and the.jar files (directly from the Overview tab of the Application Descriptor, or by right click on the project root -> Mobile Tools for Java ->, or J2ME -> Create Package - See Figure Fig. 7.4), you may have the error: Could not find jar tool executable. 8

12 Fig. 7.4 This error occurs since the process of (obfuscated) packaging requires that the jar file created by the obfuscation tool must be preverified again. The preverifier tool needs to be able to invoke the jar executable tool while preverifying the jar file from the PATH environment. EclipseME searches for the jar executable within the Installed Java Runtime Environments in your Eclipse installation. EclipseME must find at least one full Java Development Kit within the Installed JRE's (a subcategory of the Java category). By default, Eclipse will recognize a JRE rather than a full JDK on Windows. To solve this problem, make sure to point the location of the installed JRE instance to the root directory of the JDK directory. For instance on Windows, that might be something like c:\j2sdk1.4.2 or C:\Program Files\Java\jdk1.6.0_24 (see Add in the following figure). 9

13 Fig. 7.5 MORE DETAILS on packaging can be found in APPENDIX A You may also need to edit the file Chameleon_Mobile_Client.jad (created by default) in order to have: MIDlet-Version: MIDlet-Vendor: Midlet Suite Vendor MIDlet-Jar-URL: Chameleon_Mobile_Client.jar MicroEdition-Configuration: CLDC-1.1 MIDlet-1: Chameleon Mobile Client,,it.univaq.di.chameleonclient.midlet.ChameleonMIDlet MicroEdition-Profile: MIDP-2.0 MIDlet-Name: Chameleon Mobile Client Midlet Suite The Midlet-1 attribute can be added directly from the tab MIDlets of the Application Descriptor window as shown below: 10

14 Fig. 8 If you want to create the file build.xml (so that the project can be properly exported) select Project, Export, General, Ant Buildfile, Next and then the project to build and press Finish (Fig.9 and Fig. 10). 11

15 Fig. 8 12

16 Fig. 9 Before running the midlet you need to configure the Chameleon server see Sections 1.2, 1.3 and the uddie server- see Section 2. Moreover, in order to avoid many (security related) warning messages (automatically produced by the emulator), you may want to set to maximum the Security Domain. In order to set the domain, right click on it.univaq.di.chameleonclient.midlet.chameleonmidlet.java and choose Run As -> Open Run Dialog (or Run As -> Run Configuration) and. (see Figure below). 13

17 14

18 3. Chameleon Server Choose File, New, Project, Web, Dynamic Web Project, and call it (for instance) Chameleon Server (Fig.11). Fig. 10 As Target Runtime choose Apache Tomcat v6.0, thus select New, Apache, Apache Tomcat v6.0 (Fig.12) and set the Tomcat installation directory (e.g., C:\Program Files\Tomcat \Tomcat 6.0). 15

19 Fig

20 Fig. 12 Press Installed JREs to select the JRE (Fig.13). 17

21 Fig. 13 If the jre1.6.x_x is not installed, select Add (Fig.14), indicate the JRE home directory (e.g., C:\Program Files\Java\jre1.6.x_x) and click OK. Within the Configurations panel (Fig.15), 18

22 Fig. 14 Select Default Configuration for Apache Tomcat v6.0 and press Next. At this point, heading Dynamic Web Module select the version 2.4 (Fig.16) and click Next and Finish. 19

23 Fig. 15 The project s configuration is complete and the CHAMELEON Server src folder can be loaded. 20

24 Fig Choosing Dynamic Web Module 2.4 should add into the Project Explorer tab (usually on the left hand side see Fig. 16.1) also the Deployment Descriptor node for easily editing /WEBINF/web.xml file. This will be useful for deploying the two CHAMELEON servlets (i.e., ListApplication.java and SendRequest.java ). If the two servlets does not appear as children of the Deployment Descriptor: Chameleon Server, Servlet Mapping (see Fig. 16.1), select Deployment Descriptor: Chameleon Server, Servlet Mapping, New, Other, Web, Servlet, Next; at the next stage, Use existing Servlet class must be selected (Fig.16.2) and then application servlet must be indicated using Browse button (Fig.16.3). This operation must be accomplished for both the ListApplication.java and SendRequest.java servlets. 21

25 Fig Fig

26 3.1. CHAMELEON Server structure Initially, the CHAMELEON Server must be structured as in Fig It basically contains the WebContent folder, the chameleon.init.xml and user.xml files. You can directly cut&paste the folder and the files from the downloaded.zip file. Fig o chameleon.init.xml initializes the server. You need to edit the initialization file to specify: the WorkingDir directory path (no tailing \ or / ) the Applications directory path (no tailing \ or / ) the Services directory path (no tailing \ or / ) o users.xml contains information about users and devices enabled to use the chameleon server: <?xml version="1.0" encoding="utf-8"?> <users> <user username="a" password="a" device="1"></user> <user username="b" password="b" device="2"></user> <user username="c" password="c" device="3"></user> <user username="d" password="d" device="4"></user> </users> 23

27 The paths of the chameleon.init.xml and user.xml files must be set into /WEBINF/web.xml. For instance: <context-param> <param-name>initpath</param-name> <param-value> C:\wspace\Chameleon Server\chameleon.init.xml </param-value> </context-param> <context-param> <param-name>userfilepath</param-name> <param-value> C:\wspace\Chameleon Server\user.xml </param-value> </context-param> where the values of <param-value> are the absolute paths of the initialization file, i.e., chameleon.init.xml, and the users file, i.e., user.xml. 24

28 Fig

29 o The Applications folder must be created into the WebContent folder. It will contain: applications.xml, the file specifies the list of the available applications; one folder for each adaptable application with the same name of the application(s) name (e.g., Navigator in Fig. 17.2) containing: a folder for each adaptation alternative (e.g., BT, IMG and SMS) containing the files.jar,.jad and.html. For example, for the SMS adaptation alternative of the Navigator adaptable application, these files must be called: NavigatorSMS.jar, NavigatorSMS.jad and SMS.html. a chameleon folder which, in turn, contains: a folder for each adaptation alternative (e.g., BT, IMG and SMS), each one having a classes folder that contains the.class files of the alternative; AdaptableApplicationDescriptor.xml, the file which specifies the various adaptation alternatives for the adaptable application (i.e., the Navigator); ResourcesDefinition.xml, the file contains the definition of the resources specific to the adaptable application (i.e., the Navigator); SLSDefinition.xml,, the file contains the definition of the SLSs specific to the adaptable application (i.e., the Navigator); a lib folder with the midpapi21.jar and cldcapi11.jar libraries and Annotation.class file (see the ARA documentation for further details CombinedSLS.xml, the file contains the specification of all the possible SLSs (Service Level Specifications) that represent the QoSs that can be offered by a provider alternative when accessed by a particular consumer alternative. In particular it specifies all the possible combinations of the code-embedded SLSs associated to the provider side adaptation alternatives with the code-embedded SLSs associated to all the consumer adaptation alternatives. o A Services folder structured like Applications folder 26

30 In addition, the WebContent folder must contain: o the Resources Definition folder with the AllResourcesDefinition.xml file that contains all resources managed in the Chameleon Project; o the index.jsp file, the welcome-file; o WEB-INF/lib, that must include all the libraries used by the CHAMELEON Server; o a XsdSchema folder that contains all the.xsd schemes used to validate all the.xml files; WEB-INF must have a classes folder with log4j.properties file. At the same level of WebContent a WorkingDir will be automatically created by the CHAMELEON Server upon the first request (Fig.18). This folder will contain the three files (listed below) automatically created by the server considering the information sent by the device after an application has been chosen: Fig ResourceProfile.xml, it is sent by the device and specifies the resource consumption linked to the execution of specific bytecode instructions represented through regular expressions. It s based on the scheme ResourceConsumptionProfile.xsd. Regular expressions must respect the syntax accepted by both dk.brics.automaton.regexp and java.util.regex classes. The character * indicates an indefinite number of characters. \ is the escape character, so for example \[ indicates [. 27

31 2. ResourceSupply.xml, specifies the amount of resources required by an application alternative (i.e., resource demand) or provided by a device (i.e., resource supply). It s based on the schemeresourceset.xsd. The type of resource set (i.e., Resource demand / supply) is defined from the "type" attribute of the root. 3. ResourcePriority.xml, specifies the priority assigned to each resource and it is used to calculate the Goodness. It s based on the scheme ResourcePriority.xsd. The declaration attribute of ResourcePriority specifies the file (full-path name) that contains the resources declaration. For each resource the priority is specified. It will be a: negative integer: the less the resource is waste, the best will be (e.g., CPU, ); zero: the resource in useless. It does not effect the Goodness; positive integer: the more the resource is used, the best will be (e.g., thread, screen resolution, ) Run As -> Run on server and the server will be listening for Chameleon Mobile Client requests. 28

32 4. UDDIe - Eclipse Project configuration You need: 1. A web server support for Java servlets (we used Tomcat) 2. A Relational Database Management System (we used MySQL) The project has been tested on Tomcat v5.5 and v6.0, MySQL Community Server a (5.1.53) and JDK 6.0. Before reading the following configuration guidelines note that you can download the UDDIEe archive from the CHAMELEON Web pages containing: Source files and libraries Uddie_mysql_chameleon_schema.sql Be sure that all the Libraries have been linked: 29

33 Be also sure that the proper target runtime is selected: 4.1. Creating the Database From the MySQL official website, download the required version. If you download the installer the Typical installation is enough, unless you know what you want. Once installation is completed, mysql will be, for instance, at the following path: C:\MySQL or C:\Program Files\MySQL or After installation, you will be ready for testing mysql capabilities. To start MySQL server from the DOS console, for instance: C:\> C:\mysql\bin\mysqld.exe or C:\Program Files\MySQL\MySQL Server 5.1\bin>\mysqld.exe 30

34 To access the server as a root user the first time: mysql -u root p The system will ask you to insert a password to start the server administrator interface. This is an example of what you see on the screen: window users can also run - MySql Server Instance Configuration Wizard from the Start menu (type MySql into the search box) or - MySQLInstanceConfig.exe directly from the bin directory into the installation directory of MySql 31

35 Follow the instructions: (More information are reported by the file my.ini into the installation directory) To create a new database CREATE DATABASE database name ; CHAMELEON requires you to create a database called uddie After creating our database, we ll be ready for working on it. But at first we need to select it using the script: USE uddie; 32

36 Once selected, the database is ready to be used. Thus, SOURCE c:/ file.sql file.sql is the path to the file Uddie_mysql_chameleon_schema.sql downloaded within the uddie project folder; Then press quit; your DB should be created. To manage the uddi registry, a GUI tool can be of help. We used MySQL Workbench. 33

37 4.2. Creation and configuration of the UDDIe Eclipse project Choose File, Import (Fig.19). Fig

38 Chose Existing Project into Workspace and, in the dialogue box, select the uddie project directory. Press Finish.(see Fig.20 and Fig.21) Fig

39 Fig

40 Now the project should be configured and visible into the workspace at the left side of the screen. Double-clicking on Deployment Descriptor: <web app> you will open the web.xml already configured. If web.xml is properly configured you should see: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" " <web-app> <servlet> <servlet-name>rpcrouter</servlet-name> <servlet-class>uk.ac.cf.cs.uddie.server.soap.rpcrouter</servlet-class> </servlet> <servlet-mapping> <servlet-name>rpcrouter</servlet-name> <url-pattern>/inquiry</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>rpcrouter</servlet-name> <url-pattern>/publish</url-pattern> </servlet-mapping> </web-app> Once created the project, select and set as follows the file soapuddi.config inside the package conf (see Fig.22). Fig

41 Configure UDDIE for the database by configuring the soapuddi.config Delete the # symbol in front of the URL and Class name for the database you are using. Type the URL address of the database Type the JDBC driver class name Type the username and password for accessing the database if required. Leave the rest of the configuration parameters at the time being. If you are using MySQL, soapuddie should look like this (we recall that the DB name is uddie): #The Global properties of the registry site. operator=chameleon authorisedname=chameleon #For MySQL server URL=jdbc:mysql://localhost:3306/<YOUR DB NAME> Class=com.mysql.jdbc.Driver #For MS SQL server #URL=jdbc:JSQLConnect://yourservername/database=yourdbname/user=yourusername #Class=com.jnetdirect.jsql.JSQLDriver #For Sybase #URL=jdbc:sybase:Tds:yourservername:yourserverport/yourdbname #Class=com.sybase.jdbc2.jdbc.SybDriver #For Oracle9 #URL=jdbc:oracle:thin:@yourOracleAddress #Class=oracle.jdbc.OracleDriver #Add user name and passwd if required user=<your DB username> passwd=<your DB password> lease_duration = # Allowed renewal time allowedrenwaltime = 10 # Maximum allowed infinit lease MaxInfinitLease = 10 38

42 Right click on the project already created, select Run as Run on server and then select the wished server. Check Always use this server when running this project and press Finish (see Fig.23) Fig

43 Open the following address: (generally You should get the following message: <html> <head> <title>soapuddi RPC Router</title> </head> <body> <h1>soapuddi RPC Router</h1> <p>sorry, I don't speak via HTTP GET- you have to use HTTP POST to talk to me.</p> </body> </html> Congratulation, the installation is successful! 40

44 5. Appendix A - Advanced - Adding JAR Files to a MIDlet Suite This appendix provides guidance on how to add external JAR files to a MIDlet Suite project Types of JAR Files From the point of view of a J2ME project, there are two general categories of JAR files that might be added to a MIDlet Suite project. It is very important that you understand the distinction between the two, since they have to be added differently to get the result you want. The two categories are: Hardware JAR Files. This category of JAR files contain functionality that allows a MIDlet to interact with hardware that is part of the phone or other mobile device onto which your MIDlet will be installed. A JAR file that contains Bluetooth interface classes is one example of this category. JAR files of this type are obtained from the device manufacturer, usually as part of a Wireless Toolkit (WTK), or else as an add-on to one. The JAR files exist solely to allow you, the J2ME developer, to compile your MIDlet properly against them so that it has all the correct references when your MIDlet is deployed. You will not be installing the classes in a Hardware JAR file onto the mobile device - they will already be there waiting for you. Application JAR Files. This category of JAR files contains classes that you, the J2ME developer may or may not have written, but which will end up as part of the MIDlet that you will deploy to the mobile device. An example of a JAR file in this category might be one that contains an XML parsing library that you will use to handle data that your MIDlet will send to, or receive from, a server. JAR files of this type are typically obtained from sources other than the device manufacturer. Certainly, if you wrote the code in the JAR file, it's in this category. The reason for the distinction has to do with what EclipseME needs to do with the classes in the JAR file. For Hardware JAR files, EclipseME needs ensure that the classes in the file are part of your classpath during the build process so that your MIDlet will compile properly, however these classes must not be packaged up as part of your deployed MIDlet. To do so would be to attempt to override classes that are already implemented in the mobile device. This would probably not work, in the first place, since many of these classes have native code hooks which cannot be used from inside the "sandbox" in which a MIDlet runs. In the second place, a MIDlet that contains native hooks should fail the mandatory preverification step that is part of the deployment process. Finally, even if that didn't happen, no selfrespecting MIDlet container should allow a MIDlet to override system classes - it should reject the MIDlet as being invalid. For Application JAR files, on the other hand, EclipseME needs to extract all the classes, resources, etc., combine them together with the corresponding items in the MIDlet suite project, and put them all into the resulting deployable JAR file. J2ME devices do not have the concept of a classpath the way that J2SE and J2EE systems do. A J2ME suite consists of only two files - a JAR file and a JAD file. Every class or resource that your MIDlet will access must therefore be bundled together into the single JAR file. 41

45 EclipseME distinguishes between the two categories of JAR files based on the way that you add the file to the system and, potentially, the "export" setting associated with the jar file. It is therefore important that you: a. determine the correct category for the JAR file and then b. add it to the system in the correct manner Adding Hardware JAR files There are two different ways that hardware JAR files can be added to the system. They can either be added via the Device Management preference page, or they can be added directly to the project, but not exported Using Device Definitions to Add Hardware JAR files Hardware JAR files may be added as a new library from the Device Management preferences page. In many cases, EclipseME is able to extract all the relevant information from your Wireless Toolkit to create the appropriate library definitions. If it does not, you first need to add a new library to a device definition (see here for how to do this). Finally, modify your MIDlet Suite Project's project properties to use the new or updated device definition. (see here) Once this is done, the JAR file will be included in your project's build path, so that the compiler will find the relevant class definitions, however EclipseME will not attempt to include these classes in your deployed JAR file - as far as EclipseME is concerned, this JAR file is now part of the Wireless Toolkit, and is there for reference purposes only. If, when you try to run your MIDlet in the emulator, particularly in OTA mode, you get complaints about illegal classes, this may be a sign that you have incorrectly added a Hardware JAR to the system as if it were an Application JAR Adding Directly To A Project Prior to release 0.9.4, the method described above was the only method of adding a hardware JAR to EclipseME. Beginning in release of EclipseME, hardware JAR files may also be added to a project by simply adding them to the "Libraries" tab in the "Java Build Path" portion of the project properties. For example, in the project shown below, the file mmapi.jar has been added to the project. 42

46 If you add a JAR file this way, however, it is vitally important that you not have the checkbox next to this item checked on the "Order and Export" page, as shown below: 43

47 If this box is checked, EclipseME will attempt to preverify and included the contents of mmapi.jar in the deployed JAR file, which would obviously be wrong Which Approach Is Better? Before release of EclipseME, you had only one way of adding Hardware JAR files, so things were pretty simple. Starting with release 0.9.4, you have two choices. Which way is better? The developers of EclipseME feel that, in the vast majority of cases, it is better to use the first approach - using device definitions to add the Hardware JAR files. This approach allows the changes to be reused across projects, and more properly associate the Hardware JAR files with the devices which, after all, describe the hardware to your project. If, for some reason, you cannot follow that approach however, the second course of action - adding the JAR file to the project but not exporting it - is now available to you Adding Application JAR files Application JAR files must be added to your project's build path just the way you would with JAR files in any non-j2me project. Select Properties from the Project menu, click on the Java Build Path item in the left-hand pane, and then add the JAR files (or class directories) to the list in the right-hand portion of the dialog box. 44

48 Thus, in the example above, we are adding the Application JAR file extensions.jar to the project in addition to the Hardware JAR file mmapi.jar. Beginning in release of EclipseME, it is essential that you put a check in the check box next to Applications JAR files in the "Order and Export" tab of the Java Build Path, as shown below: 45

49 Once you have done this, the classes in the JAR file or class directory will both be part of your project's build path, as well as deployed in your project's JAR file. Thus, in the example shown, the case above, EclipseME will collect the classes and other resources in extensions.jar, preverify them, and include them as part of your deployed MIDlet. EclipseME will not, however, do this with mmapi.jar, since the checkbox is empty. The resources in mmapi.jar will be available at compile time, but will not be deployed. If, when you try to run your MIDlet in the emulator, particularly in OTA mode, you get a ClassNotFoundException, this is a signal that the relevant classes did not get bundled into your deployed JAR file. This is usually a sign that you have not added the Application JAR file to your project's Java Build Path properly, or have forgotten to check the "export" box Emulator Caveats If you are using a special feature, such as Bluetooth, video, etc., you may run into a situation in which you correctly add the hardware JAR as specified above, your application compiles perfectly, but then when you run it in the emulator, the hardware device does not seem to function. In all likelihood, this is not an EclipseME issue - it is most likely an issue with the J2ME emulator. In many circumstances the emulator in a Wireless Toolkit has just enough support for a hardware feature to allow your MIDlet to load, but doesn't contain truly functional emulation for all the hardware features of the physical device itself. Unfortunately, there is nothing we can do to help you with this. 46