Design

MIDlet architecture

The following figure shows the basic architecture of the MIDlet:

Figure: CapitalMIDlet basic architecture

The client side of the application consists of the CapitalMIDlet class, a set of classes to create and control the user interface, the generated stub and service interface, and a Poster class that executes the remote procedure call in a separate thread. The CapitalMIDlet class controls the display and performs all screen transitions. Additionally, it creates the Poster class, requests the web service calls, and handles the answer from the web service.

The server side of the application is not covered in this example in detail. The main reason is that the web service architecture allows you to ignore the implementation details on the server side while developing the client. The server side WSDL definition is shown below:

<definitions name="capitals"
   targetNamespace="urn:nokia:example:capitals:2005-01">
  <types>
    <schema targetNamespace="urn:nokia:example:capitals:2005-01">
      <element name="request" type="string"/>
      <element name="response" type="string"/>
    </schema>
  </types>

  <message name="capitalRequest">
    <part name="nation" element="tns:request"/>
  </message>

  <message name="capitalResponse">
    <part name="capital" element="tns:response"/>
  </message>

  <portType name="capitalPortType">
    <operation name="getCapital">
      <input message="tns:capitalRequest"/>
      <output message="tns:capitalResponse"/>
    </operation>
  </portType>

  <binding name="capitalBinding" type="tns:capitalPortType">
    <operation name="getCapital">
      <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
        <soap:operation soapAction=""/>
    </operation>
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" 
      style="document"/>
  </binding>

  <service name="capitals">
    <documentation>Simple capital query service</documentation>
    <port name="capitalPort" binding="tns:capitalBinding">
      <soap:address
        location="http://194.137.80.38:80/CapitalService/Capitals"/>
    </port>
  </service>

</definitions>

MIDlet UI

The following figure shows the MIDlet UI:

Figure: CapitalMIDlet user interface

The UI is implemented with the following classes:

• Screen—Abstract class that encapsulates the basic functionality required to display something on the screen. Implementers use it, for example, to create forms so that the MIDlet can easily display them.

• WelcomeScreen—Implements the opening screen displayed by the MIDlet. It shows the name and version of the application, and moves to the main screen when the user clicks OK.

• MainScreen—Implements a very simple screen that contains a field where the user can enter the name of the country. The name is used to call the remote web service.

• WaitingScreen—Implements a screen that is displayed while the Poster class is contacting the remote service. Since the operation can take a while, the screen provides the user with feedback in the form of a gauge widget, whose value is increased continually until a response is received from the remote service.

• ResultsScreen—Implements the screen that shows the returned value after a successful remote procedure call. The screen is a simple form containing fields for the names of the country and its capital.

• ErrorScreen—Implements a screen that is displayed when the remote call fails. The failure can be caused by various reasons, such as problems in the remote end, communication issues caused by proxies and firewalls, or changes in the service definition. JAX-RPC uses RemoteException to encapsulate all the errors in a unique Java exception.

Implementation

For information about implementing the MIDlet, see section Implementation.