pushregistry.java

用于移动设备上的java虚拟机源代码

 * when handling asynchronous data via the push mechanism.
 * A well behaved application SHOULD inform the user that
 * 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.