Sun Java System logo     
JavaTM Smart Ticket Sample Application



JavaTM Smart Ticket Sample Application


This document describes how to utilize the JavaTM Smart Ticket 1.1.1 sample application from Java BluePrints in conjunction with the Sun Java (tm) System Application Server 7.

This sample application document contains the following sections:



Overview

Today's businesses have the Java 2 Platform, Enterprise Edition (J2EE) as the established standard for developing enterprise applications.

The Java 2 Platform, Micro Edition (J2ME) provides businesses with the opportunity to accommodate the following new set of enterprise clients:

  • Cell phones

  • Two-way pagers

  • Palmtops

These devices can be programmed using the Mobile Information Device Profile (MIDP) and Connected Limited Device Configuration (CLDC) to provide a complete Java runtime environment.

The high level architecture of a Java wireless enterprise application is shown in Figure 1.

Figure 1    J2EE-J2ME Application Architecture

The client tier consists of an MIDP application, or MIDLet. The MIDLet provides the user interface on the mobile device and communicates with Java servlets in the Web tier to access the business logic of Enterprise JavaBeans components in the EJB tier. Both the servlets and enterprise beans are located on a J2EE application server. Finally, the Enterprise Information Systems (EIS) tier supports access to the application database through the JDBC API.

JavaTM Smart Ticket 1.1.1 is a wireless sample application that demonstrates how to build wireless services connecting J2ME mobile clients to J2EE application servers. In this sample application, customers go through a typical e-shopping scenario to buy movie tickets through a mobile device as shown in Figure 2.


Signing In

Customers can sign in to the application using an account that they create when they first install the application. The customers' application preferences are stored with their account information. Some of these preferences are stored on the server side in a database, while the rest are stored locally in the record store of the client device.


Browsing Movies

The application gives the customer a list of movies which is initially filtered by the customer's zip code. After selecting from this list, customers may choose the theater where they want to see the movie and the time they want to see it.


Reserving Seats

Once customers have chosen the show (movie, theater, time), they can view a seating plan for the theater and choose specific seats. The application then prompts them to confirm their purchase. While customers decide, the seats are reserved. If the customer confirms the purchase, it is recorded in the database. Otherwise, the reservations are cancelled.

Figure 2    An E-Shopping Scenario


Setting Up the Environment



This section describes the steps required to set up the environment in order to compile, deploy, or run the sample application.

  1. Install the J2ME Wireless Toolkit.



    Note This step is required to compile or run the sample application.



    The JavaTM Smart Ticket sample application is included in the Sun Java (tm) System application server.

    For example,

    <as_install_dir>/samples/smartticket1.1.1/

    For convenience, name it <st_dir>.

    For demonstration purposes, the sample requires the J2ME Wireless Toolkit (J2MEWTK). The Java 2 Platform, Micro Edition Wireless Toolkit (v1.0.4) can be downloaded from the following site:

    http://java.sun.com/products/j2mewtoolkit/download.html

    • Install J2MEWTK on the machine where the application server is installed and configure the sample to point to it.

    • Set j2mewtk.home=<wtk_install_dir> in the <st_dir>/smarticket.properties file.

      For example:

      • On Windows:

        j2mewtk.home=C:/wtk104

      • On Solaris:

        j2mewtk.home=/export/home/wtk104

  2. Set the Compiling and Deploying Environment.

    Ensure that the application server's bin directory <as_install_dir>/bin appears in the path.

  3. Start up the Database.

    The Application Server uses the PointBase database server. The database is populated with all of the demo data for the Smart Ticket sample application.

    • To start the PointBase database server, go to the directory <as_install_dir>/pointbase/server.

    • Run the script:

      • On Solaris:

        StartServer.sh

      • On Windows:

        StartServer.bat

  4. Register PointBase JDBC Resource in Application Server.

    Use the asant command to register a JDBC resource and define a JDBC connection pool for this sample in the application server.

    • Go to <st_dir>

    • Execute the command

      asant regdb

    After setting up the environment, you can go to the next section to compile sample application.

If you would like to run sample with using Oracle Database, please refer to the section of Configuring for Using Oracle Database.

Compiling and Deploying the Sample Application



This section contains instructions to compile, assemble, and deploy the Smart Ticket sample application.

  1. Go to the Sample Directory.

    <st_dir>

  2. Compile and Assemble the Sample.

    Execute the command.

    asant



    Note You may skip this step and go to Step 3 to use prebuilt files.



  3. Deploy the Sample.

    Execute the command.

    asant deploy

  4. Optionally, you may verify the registration.

    Go to http://server:port/SmarTicketApp/

    The document root of the application appears indicating that your application is deployed and the application context root is registered properly.

    After deploying the sample application, you may proceed to the next section to run the sample application.



Running the Sample Application

This section describes how to run the MIDP part of the sample application using the J2ME Wireless Toolkit in the default configuration.

  1. Go to the sample directory.

    <st_dir>

  2. Bring up a Phone emulator.

    Execute the command

    asant emulate

    to bring up a phone emulator.

  3. Launch the Demo.

    Press Launch to start the Java Smart Ticket demo.

  4. Set up Preferences.

    If you are running the application for the very first time, fill out the user preferences form to create a new user account.

    • Press Sign In.

      A dialog box appears prompting you to create an account.

    • Fill out the user preferences form completely.

    • Click Save.

  5. Use the Application.

    You can now use the application to sign in, browse movies, and reserve seats.



Configuring the Sample Application

This section describes the steps needed to set up features of the sample application which are not supported by the default configuration.


Connecting to a Remote Server

By default, the client is set to connect to a server running on localhost at port 1024.

This section describes the steps to connect a client to remote server.

  1. Create a Package for the Sample Application.

    • On the machine where the sample is deployed with the application server, go to the sample directory <st_dir>.

    • Execute the command,

      asant package

      This creates a package as <st_dir>/smarticket.zip.

  2. Install the Package on another machine.

    Transfer it to another machine and then unpack it in a directory (for example, <st_install_dir>).

  3. Configure the MIDP client.

    • On the second machine, configure the server to which the client connects.

    • In the file <st_install_dir>/smarticket/bin/smarticket.jad, look for the following lines:

      SMARTicket-Servlet-URL: http://localhost:1024/SmarTicketApp/servlet/

      SMARTicket-Poster-URL: http://localhost:1024/SmarTicketApp/

      SMARTicket-Splash-URL: http://localhost:1024/SmarTicketApp/

      Replace all occurrences of localhost and 1024 with the name of the host and the port on which the application server is running.

  4. Install the J2ME Wireless Toolkit.

    Install the J2ME Toolkit in a directory (for example, <wtk_install_dir>) on the machine where the Smart Ticket package is installed.

  5. Bring up the Emulator.

    • Go to the sample directory (for example, <st_install_dir>/smarticket/bin).

    • Execute the command,

      <wtk_install_dir>/bin/emulator   -Xdescriptor:smarticket.jad

      on Solaris, or click smarticket.jad on Windows to bring up the emulator.

  6. Run the Sample Application.

    Now you can run the sample from this client to a remote server.


Connecting Over HTTPS

The J2ME Wireless Toolkit supports HTTPS, although not all MIDP devices are required to support it. This section describes how to configure the Java Smart Ticket Demo to use HTTP over SSL (HTTPS).

  1. Enable SSL on Application Server

    Follow the instructions provided in Sun Java (tm) System Application Server Administrator's Guide to Security to enable SSL on Application Server. The outline is provided below:

    • Create a Trust Database.
    • Generate a Certificate Request.
    • Get Certificates.
      Save the certificates in files, which will be used in configuring J2ME Toolkits. For example, the SSL server certificate is in the file of server.cer, while the root certificate is in the file of root.cer.
    • Install Certificates.
    • Manage Certificates.
    • Add a HTTP listener on a separate port.
      In the listener, make sure you enable security and all the ciphers when enabling SSL2 and SSL3, but don't enable Client Authentication.
    • Test HTTPS
      Try to connect to the secure port through the browser, e.g.
      https://server:secure-port/SmarTicketApp/

     

  2. Import Server Certificates into J2ME Wireless Toolkit.

    Normally you would use the keytool's -certreq option, and ask some Certificate Authority (CA) to sign your server's public key certificate, while ensuring that the CA's root certificate was in the J2ME Wireless Toolkit's keystore. However, for testing purposes, you can put the server's public key and root certificates into the J2ME Wireless Toolkit's keystore.

    For example, you can use the certificate files saved in previous section.

    • Go to J2ME Wireless Toolkit directory, e.g.
      <wtk_install_dir>.
    • Create a keystore with server and root certificates.

      keytool -import -alias server -file server.cer -keystore keystore -storepass changeit

      keytool -import -alias root -file root.cer -keystore keystore -storepass changeit

      which puts the certificates in the file of keystore.

    • Import certificates to J2ME Toolkit database

      On Solaris:

      java -jar bin/MEKeyTool.jar -import -alias server -keystore keystore -storepass changeit

      java -jar bin/MEKeyTool.jar -import -alias root -keystore keystore -storepass changeit


      On Windows:

      java -jar bin\MEKeyTool.jar -import -alias server -keystore keystore -storepass changeit

      java -jar bin\MEKeyTool.jar -import -alias root -keystore keystore -storepass changeit

    • Verify the certificate installation.

      On Solaris:

      java -jar bin/MEKeyTool.jar -list

      On Windows:

      java -jar bin\MEKeyTool.jar -list

      You should see the certificates in the list.

  3. Edit the JAD File to Use Secure Port.

    In the file <st_install_dir>/smarticket/bin/smarticket.jad, look for the following lines:

    SMARTicket-Servlet-URL: http://localhost:1024/SmarTicketApp/servlet/

    SMARTicket-Poster-URL: http://localhost:1024/SmarTicketApp/

    SMARTicket-Splash-URL: http://localhost:1024/SmarTicketApp/

    Replace all occurrences of http, localhost and 1024 with https, server (the name of the host where the application server is running) and secure-port.

Using a Different Character Set

The Java Smart Ticket Demo is internationalized. It is also localized in US English, French, and Japanese. This section describes how to use a different character set.

With the default configuration, three sets of messages are stored in the client or server for demonstration purposes, as shown in Table 1. These three sets will be shown in the locale screen of emulator.


Table 1     Localized Messages in Default Configuration
Set Locale Messages Stored Message Source Files
0 en_US MIDP Client <st_dir>/messages/en_US.properties
1 en_GB J2EE Server <st_dir>/src/sql/smarticket.sql
2 fr_FR J2EE Server <st_dir>/src/sql/smarticket.sql

 

Using Sample in French

To use French, the locale can be simply selected from emulator with default configuration and environment as using Sample in English.

  1. Bring up the emulator, e.g.
    asant emulate

  2. Choose locale as fr_FR after launching sample.

  3. Exit emulator.

  4. Bring up emulator again to sign in.
The emulator should display French messages.

Using Sample in Japanese

The Japanese localization use different character set and encoding from the US English or French localization. In order to display Japanese messages properly on the J2ME WTK emulator, please follow these steps.

  1. Configure and Compile the Sample

    Change locale setting as
       midp.locale=ja_JP
    in build configuration file (<st_dir>/smarticket.properties).

    Clean the project area and then compile in sample directory (<st_dir>), e.g.
       asant clean
       asant

    After compiling, the message file (<st_dir>/messages/ja_JP.properties) is used as default properties in MIDP client. That is, the first set of locale is changed from en_US as shown in Table 1 to ja_JP. The locale options for sample become ja_JP, en_GB and fr_FR which will be shown in the locale screen of emulator.

  2. Clean Emulator DataBase

    If the previous setting of the emualtor is en_US, you need to clean its database since en_US is not an option in current configuration. To clean the emulator database, remove the files of <wtk_install_dir>/appdb/run_by*.

  3. Run Emulator in Japanese Environment

    The message file of ja_JP.properties is encoded in SJIS. The emulator needs to run in the Japanese environment which has default system encoding as SJIS.

    For example, on Solaris 8, choose Language as ja_JP.PCK and then login. You should be able to view the message file of ja_JP.properties correctly with Text Editor (dtpad). Bring up the emulator in this environment. Optionally, choose locale as ja_JP (default) after launching Smart Ticket demo.

The emulator should display Japanese messages. You can start demo to create an account, sign in, browse movies and reserve seats.


Further Studying the Sample

To better understand the sample, you may refer to the Overview of API document. Besides the basic options for the asant command described before, there are more options for further studying the sample as listed in Table 2.



Table 2    Arguments for the asant command

Argument

Purpose

core  

Builds the entire application. (This is the default target.)  

midp  

Builds the MIDP client part of the application.  

j2ee  

Builds the J2EE server part of the application.  

clean  

Cleans out the build output directories.  

emulate  

Runs the MIDP client part in the emulator.  

deploy  

Deploys the J2EE server part on the application server.  

undeploy  

Undeploys the J2EE server part from the application server.  

package  

Creates a package for entire application.  

regdb  

Registers JDBC Resource on the application Server.  

unregdb  

Unregisters JDBC Resource from the application Server.  

freshdb  

Repopulate demo data on PointBase database server.  



Configuring for Using Oracle Database


The section describes the setup for using Oracle database.

  1. Create an Oracle User

    A tablespace is recommended to be created once for all samples in Oracle database. Please refer to Working with Oracle Database for creating tablespace. After having a tablesapce (e.g. samples), you can create an Oracle user (e.g. smarticket) by executing the cr_ora_user.sql script as an Oracle system user (e.g. system/manager@sid) in the directory of <as_install_dir>/samples/docs, i.e.

      SQL> @cr_ora_user.sql smarticket smarticket samples

  2. Populate Demo Data

    The demo data needs to be populated for this sample. It can be done by executing the smarticket.sql script as the Oracle user created in the last step (e.g. smarticket/smarticket@sid) in the directory of <st_dir>/src/sql, i.e.

      SQL> @smarticket.sql

  3. Register Oracle JDBC Driver

    Oracle JDBC driver is recommended to register once in Application Server for all samples. Please refer to Working with Oracle Database for configuring Application Server with Oracle JDBC driver. Make sure the JVM Settings (Path Settings and JVM Options) are configured properly for Oracle JDBC driver as instructed.

  4. Register Oracle JDBC Resource in Application Server

    The Oracle JDBC resource needs to be registered once for this sample.

    If you have followed the instructions to run this sample with the PointBase database server, then

    (a) Go to the sample directory, <st_dir>.

    (b) Unregister JDBC resource for using PointBase, e.g. execute the command,

      asant unregdb

    (c) Register JDBC resource for using Oracle, e.g. execute the command,

      asant regdb_ora -Ddb.host=<host> -Ddb.port=<port> -Ddb.sid=<sid>

    (d) Restart the server instance.

    (e) Clean emulator database.

    To clean the emulator database, remove the files of <wtk_install_dir>/appdb/run_by*.

    After steps (a) - (e), you can run the sample with using Oracle database server.

    If you have not registered PointBase JDBC resource before, then do steps (a) and (c) only to register Oracle JDBC resource.

    If you have not compiled, deployed or run the sample before, please refer to the instructions in the previous sections to compile, deploy or run the sample.

The above steps provided a supplementary information for Setting Up the Environment in regarding to the use of Oracle database.

Troubleshooting and Notes



  • Monitor Log
    As you run the application, monitor the server log to learn what is going on.

  • Cannot Connect to Server
    If you see the message, "Cannot connect to server" in the screen of phone emulator, the server port in emulator configuration is probably wrong. The default port is 1024. If your server port is not 1024, please correct it in the following file:
      <st_dir>/bin/smarticket.jad

  • Repopulate Demo Data
    The PointBase database for Application Server is already populated with demo data for Smart Ticket sample. If you need to repopulate the demo data for it, execute asant freshdb in the sample directory, i.e. <st_dir>.

    If you used Oracle database, you need to execute smarticket.sql script with sqlplus to repopulate the demo data.

    If you need to clean the client (emulator) database, remove the files of <wtk_install_dir>/appdb/run_by*.



Copyright © 2002 Sun Microsystems, Inc. All rights reserved.