pushregistry.html

是MIDP 的API 查詢文件, 大家可以看一下裡面的index.html, 再用Package 或 Class 名字來查.

 data has been processed. (While it is possible to write
 applications that do not use any user visible interfaces,
 this could lead to a confused end user experience to
 launch an application that only performs a background
 function.)
 </P>
 <H3>Dynamic Connections Registered from a Running MIDlet</H3>

 <P>
 There are cases when defining a well known port registered
 with IANA is not necessary.
 Simple applications may just wish to exchange data using a private
 protocol between a <code>MIDlet</code> and server application.
 </P>

 <P>
 To accomodate this type of application, a mechanism is provided
 to dynamically allocate a connection and to register
 that information, as if it was known, when the application was
 installed. This information can then be sent to an agent on the network to
 use as the mechanism to communicate with the registered
 <code>MIDlet</code>.
 </P>
 <P>
 For instance, if a <a href="UDPDatagramConnection.html">
 <code>UDPDatagramConnection</code></a>
 is opened and a port number,
 was not specified, then the application is
 requesting a dynamic port
 to be allocated from the ports that are currently available. By
 calling <code>PushRegistry.registerConnection()</code> the
 <code>MIDlet</code> informs the AMS that it is the target for
 inbound communication, even
 after the <code>MIDlet</code> has been destroyed (See
 <code>MIDlet</code> life cycle for
 definition of "destroyed" state). If the application is deleted from the
 phone, then its dynamic communication connections are unregistered
 automatically.
 </P>
 <H3>AMS Runtime Handling - Implementation Notes</H3>

 <P>
 During installation each <code>MIDlet</code> that is expecting
 inbound communication
 on a well known address has the information recorded with the
 AMS from the push registration attribute in the manifest or
 application descriptor file. Once the installation has been
 successfully completed,
 (e.g. For the OTA recommended practices - when the <em>Installation
 notification message</em> has been successfully transmitted, the
 application is officially installed.)
 the <code>MIDlet</code> MAY then receive inbound communication.
 e.g. the push notification event.
 </P>

 <P>
 When the AMS is started, it checks the list of registered
 connections  and  begins listening for inbound communication.
 When a notification arrives the AMS starts the registered
 <code>MIDlet</code>.
 The <code>MIDlet</code> then opens
 the connection with <code>Connector.open()</code> method to
 perform whatever I/O operations are needed for the particular
 connection type. e.g. for a server socket the application
 uses <code>acceptAndOpen()</code> to get the socket connected
 and for a datagram connection the application uses
 <code>receive()</code> to read the delivered message.
 </P>
 <P>
 For message oriented transports the inbound message MAY be
 read by the AMS and saved for delivery to the <code>MIDlet</code>
 when it requests to read the data. For stream oriented transports
 the connection MAY be lost if the connection is not
 accepted before the server end of the connection request
 timeouts.
 </P>
 <P>
 When a <code>MIDlet</code> is started in response to a registered
 push connection notification, it is platform dependent what
 happens to the current running application. The <code>MIDlet</code>
 life cycle defines the expected behaviors that an interrupted
 <code>MIDlet</code> could see from a call to <code>pauseApp()</code>
 or from <code>destroyApp()</code>.
 </P>
 <H2>Sample Usage Scenarios</H2>
 <P>
 <strong>Usage scenario 1:</strong>
 The suite includes a <code>MIDlet</code> with a well
 known port for communication.
 During the <code>startApp</code> processing
 a thread is launched to handle the incoming data.
 Using a separate thread is the recommended practice
 for avoiding conflicts between blocking I/O operations
 and the normal user interaction events. The
 thread continues to receive messages until the
 <code>MIDlet</code> is destroyed.
 </P>

 <H4>Sample Chat Descriptor File -</H4>
 <P> In this sample, the descriptor file includes
 a static push
 connection registration. It also includes
 an indication that this <code>MIDlet</code>
 requires permission to use a datagram connection
 for inbound push messages.
 (See <A HREF="package-summary.html#push">
 Security of Push Functions</A> in the package
 overview for details about <code>MIDlet</code> permissions.)
 <strong>Note:</strong> this sample is appropriate for bursts of
 datagrams.
 It is written to loop on the connection, processing
 received messages.
 </P>
 <CODE>
 <PRE>
  MIDlet-Name: SunNetwork - Chat Demo
  MIDlet-Version: 1.0
  MIDlet-Vendor: Sun Microsystems, Inc.
  MIDlet-Description: Network demonstration programs for MIDP
  MicroEdition-Profile: MIDP-2.0
  MicroEdition-Configuration: CLDC-1.0
  MIDlet-1: InstantMessage, /icons/Chat.png, example.chat.SampleChat, *
  MIDlet-Push-1: datagram://:79,  example.chat.SampleChat, *
  MIDlet-Permissions: javax.microedition.io.PushRegistry, \\
                      javax.microedition.io.Connector.datagramreceiver
 </PRE>
 </CODE>

 <H4>Sample Chat MIDlet Processing -</H4>
 <CODE>
 <PRE>
 public class SampleChat extends MIDlet {
     // Current inbound message connection.
     DatagramConnection conn;
     // Flag to terminate the message reading thread.
     boolean done_reading;

     public void startApp() {
         // List of active connections.
         String connections[];

         // Check to see if this session was started due to
         // inbound connection notification.
         connections = PushRegistry.listConnections(true);

         // Start an inbound message thread for available
         // inbound messages for the statically configured
         // connection in the descriptor file.
         for (int i=0; i &lt; connections.length; i++) {
           Thread t = new Thread (new MessageHandler(
                            connections[i]));
           t.start();
         }

         ...
        }
     }

     // Stop reading inbound messages and release the push
     // connection to the AMS listener.
     public void destroyApp(boolean conditional) {
        done_reading = true;
        if (conn != null)
            conn.close();
        // Optionally, notify network service that we're
        // done with the current session.
        ...
     }

     // Optionally, notify network service.
     public void pauseApp() {
         ...
     }

  // Inner class to handle inbound messages on a separate thread.
  class MessageHandler implements Runnable {
      String connUrl ;
      MessageHandler(String url) {
           connUrl = url ;
      }
      // Fetch messages in a blocking receive loop.
      public void run() {
        try {
          // Get a connection handle for inbound messages
          // and a buffer to hold the inbound message.
          DatagramConnection conn = (DatagramConnection)
               Connector.open(connUrl);
          Datagram data = conn.newDatagram(conn.getMaximumLength());

          // Read the inbound messages
          while (!done_reading) {
             conn.receive(data);
            ...
          }
         } catch (IOException ioe) {
         ...
      }
      ...
 </PRE>
 </CODE>
 <P>
  <strong>Usage scenario 2:</strong>
  The suite includes a <code>MIDlet</code>
  that dynamically allocates port the first time
  it is started.
 </P>


 <H4>Sample Ping Descriptor File -</H4>
 <P> In this sample, the descriptor file includes an
 entry indicating that
 the application will need permission to use the datagram
 connection for inbound push messages. The dynamic connection
 is allocated in the constructor the first time it is run.
 The open connection is used during this session and
 can be reopened in a subsequent session in response to
 a inbound connection notification.
 </P>
 <CODE>
 <PRE>
  MIDlet-Name: SunNetwork - Demos
  MIDlet-Version: 1.0
  MIDlet-Vendor: Sun Microsystems, Inc.
  MIDlet-Description: Network demonstration programs for MIDP
  MicroEdition-Profile: MIDP-2.0
  MicroEdition-Configuration: CLDC-1.0
  MIDlet-1: JustCallMe, /icons/Ping.png, example.ping.SamplePingMe, *
  MIDlet-Permissions: javax.microedition.io.PushRegistry, \\
                      javax.microedition.io.Connector.datagramreceiver
 </PRE>
 </CODE>

 <H4>Sample Ping MIDlet Processing -</H4>
 <CODE>
 <PRE>
 public class SamplePingMe extends MIDlet {
    // Name of the current application for push registration.
    String myName = "example.chat.SamplePingMe";
    // List of registered push connections.
    String connections[];
    // Inbound datagram connection
    UDPDatagramConnection dconn;

    public SamplePingMe() {

        // Check to see if the ping connection has been registered.
        // This is a dynamic connection allocated on first
        // time execution of this MIDlet.
        connections = PushRegistry.listConnections(false);

        if (connections.length == 0) {
            // Request a dynamic port for out-of-band notices.
            // (Omitting the port number let's the system allocate
            //  an available port number.)
            try {
                dconn = (UDPDatagramConnection)
                        Connector.open("datagram://");
                String dport = "datagram://:"  + dconn.getLocalPort();

                // Register the port so the MIDlet will wake up, if messages
                // are posted after the MIDlet exits.
                PushRegistry.registerConnection(dport, myName, "*");

                // Post my datagram address to the network
                  ...
            } catch (IOException ioe) {
                ...
            } catch (ClassNotFoundException cnfe) {
                ...
            }
    }

    public void startApp() {
       // Open the connection if it's not already open.
       if (dconn == null) {
           // This is not the first time this is run, because the
           // dconn hasn't been opened by the constructor.

          // Check if the startup has been due to an incoming
          // datagram.
          connections = PushRegistry.listConnections(true);

          if (connections.length &gt; 0) {
             // There is a pending datagram that can be received.
             dconn = (UDPDatagramConnection)
                 Connector.open(connections[0]);

             // Read the datagram
             Datagram d = dconn.newDatagram(dconn.getMaximumLength());
             dconn.receive(d);
          } else {
             // There are not any pending datagrams, but open
             // the connection for later use.
             connections = PushRegistry.listConnections(false);
             if (connections.length &gt; 0) {
                     dconn = (UDPDatagramConnection)
                         Connector.open(connections[0]);
             }
         }
      }

    public void destroyApp(boolean unconditional) {
        // Close the connection before exiting
        if(dconn != null){
           dconn.close()
           dconn = null
        }
    }
    ...
 </PRE>
 </CODE>
<P>