pushregistry.java

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

/*
 * @(#)PushRegistry.java	1.35 02/09/06 @(#)
 *
 * Copyright (c) 2001-2002 Sun Microsystems, Inc.  All rights reserved.
 * PROPRIETARY/CONFIDENTIAL
 * Use is subject to license terms.
 */

package javax.microedition.io;

import java.lang.ClassNotFoundException;
import java.lang.IllegalStateException;
import java.lang.IllegalArgumentException;
import java.lang.String;
import java.io.IOException;
import java.util.Date;
import java.util.Timer;
import java.util.TimerTask;

import com.sun.midp.io.Util;
import com.sun.midp.io.j2me.push.PushRegistryImpl;

/**
 * The <code>PushRegistry</code> maintains a list of inbound
 * connections. An application can register the inbound
 * connections with an entry in the application descriptor file
 * or dynamically by calling the
 * <code>registerConnection</code> method.
 * <P> While an application is running, it is responsible for
 * all I/O operations associated with the inbound connection.
 * When the application is not running, the application
 * management software(AMS) listens for inbound notification
 * requests. When a notification arrives for a registered
 * <code>MIDlet</code>, the AMS will start the <code>MIDlet</code>
 * via the normal invocation of <code>MIDlet.startApp</code>
 * method.</P>
 *
 * <H3> Installation Handling of Declared Connections </H3>
 *
 * <P>
 * To avoid collisions on inbound generic connections, the application
 * descriptor file MUST include information about static connections
 * that are needed by the <code>MIDlet</code> suite.
 *
 * If all the static Push declarations in the application descriptor
 * can not be fulfilled during the installation, the user MUST be
 * notified that there are conflicts and the MIDlet suite MUST NOT be
 * installed. (See <em>Over The Air User Initiated Provisioning
 * Specification</em> section for errors reported in the event
 * of conflicts.)
 *
 * Conditions
 * when the declarations can not be fulfilled include: syntax errors in
 * the Push attributes, declaration for a connection end point (e.g. port
 * number) that is already reserved in the device, declaration for a
 * protocol that is not supported for Push in the device, and declaration
 * referencing a <code>MIDlet</code> class that is not listed in
 * the <code>MIDlet-&lt;n&gt;</code> attributes of the same
 * application descriptor.
 *
 * If the <code>MIDlet</code> suite
 * can function meaningfully even if a Push registration can't be
 * fulfilled, it MUST register the Push connections using the dynamic
 * registration methods in the <code>PushRegistry</code>.
 * </P>
 * <P>
 * A conflict-free installation reserves each requested connection for
 * the exclusive use of the
 * <code>MIDlets</code> in the suite. While the suite is
 * installed, any attempt by other applications to open one of the
 * reserved connections will fail with an
 * <code>IOException</code>. A call from a
 * <code>MIDlet</code> to
 * <code>Connector.open()</code>
 * on a connection reserved for its suite will always
 * succeed, assuming the suite does not already have the connection open.
 * </P>
 *
 * <P>
 * If two <code>MIDlet</code> suites have a static push connection in
 * common, they cannot be installed together and both function
 * correctly. The end user would typically have to uninstall one before
 * being able to successfully install the other.
 * </P>
 * <H3> <A NAME="PushAttr"></A>Push Registration Attribute </H3>
 * <P>
 * Each push registration entry contains the following information :
 * <CODE><BLOCKQUOTE>
 * <strong>MIDlet-Push-</strong>&lt;n&gt;: &lt;ConnectionURL&gt;,
 *      &lt;MIDletClassName&gt;, &lt;AllowedSender&gt;
 * </BLOCKQUOTE>
 * </CODE>  where :
 * <UL>
 * <LI> <code>MIDlet-Push-&lt;n&gt;</code> =
 *    the Push registration attribute name. Multiple push
 *    registrations can be provided in a <code>MIDlet</code>
 *    suite. The numeric value for &lt;n&gt; starts from 1 and
 *    MUST use consecutive ordinal numbers for additional entries.
 *    The first missing entry terminates the list. Any
 *    additional entries are ignored.
 * </LI>
 * <LI><code>ConnectionURL</code> =
 *    the connection string used in <code>Connector.open()</code></LI>
 * <LI><code>MIDletClassName</code> =
 *   the <code>MIDlet</code> that is responsible for the connection.
 *   The named <code>MIDlet</code> MUST be registered in the
 *   descriptor file or the jar file manifest with a
 *   <code>MIDlet-&lt;n&gt;</code> record.
 *   (This information is needed when displaying messages to
 *   the user about the application when push connections are detected,
 *   or when the user grants/revokes priveleges for the application.)
 *   If the named <code>MIDlet</code> appears more than once in the
 *   suite, the first matching entry is used.  </LI>
 * <LI>
 * <code>AllowedSender</code> = a designated filter that restricts which
 * senders are valid for launching the requested <code>MIDlet</code>.
 *
 * The syntax and semantics of the <code>AllowedSender</code> field
 * depend on the addressing format used for the protocol.
 *
 * However, every syntax for this field MUST support using the wildcard
 * characters "*" and "?". The semantics of those wildcard are:
 * <UL>
 *   <LI> "*" matches any string, including an empty string </LI>
 *   <LI> "?" matches any single character </LI>
 * </UL>
 * When the value of this field is just the wildcard character "*",
 * connections will be accepted from any originating source.
 *
 * For Push attributes using the <CODE>datagram</CODE> and
 * <CODE>socket</CODE> URLs (if supported by the platform), this field
 * contains a numeric IP address in the same format for IPv4 and IPv6 as
 * used in the respective URLs (IPv6 address including the square
 * brackets as in the URL).
 *
 * It is possible to use the wildcards also in these IP addresses,
 * e.g. "129.70.40.*" would allow subnet resolution.  Note that the port
 * number is not part of the filter for <CODE>datagram</CODE> and
 * <CODE>socket</CODE> connections.
 * </LI>
 * </UL>
 * <P>
 * The MIDP 2.0 specification defines the syntax for
 * <code>datagram</code> and <code>socket</code> inbound
 * connections. When other specifications
 * define push semantics for additional connection types, they
 * must define the expected syntax for the filter field, as well as
 * the expected format for the connection URL string.
 * </P>
 * <H4> Example Descriptor File Declarative Notation </H4>
 *
 * <P>
 * The following is a sample descriptor file entry that would reserve
 * a stream socket at port 79 and a datagram connection at
 * port 50000. (Port numbers are maintained by IANA
 * and cover well-known, user-registered and dynamic port numbers)
 * [See <a href="http://www.iana.org/numbers.html#P">
 * IANA Port Number Registry</a>]
 * </P>
 *
 * <CODE>
 * <PRE>
 *  MIDlet-Push-1: socket://:79, com.sun.example.SampleChat, *
 *  MIDlet-Push-2: datagram://:50000, com.sun.example.SampleChat, *
 * </PRE>
 * </CODE>
 * <H3> Buffered Messages </H3>
 * <P>
 * The requirements for buffering of messages are specific
 * to each protocol used for Push and are defined separately
 * for each protocol. There is no general requirement related
 * to buffering that would apply to all protocols. If the
 * implementation buffers messages, these messages MUST
 * be provided to the <code>MIDlet</code> when the
 * <code>MIDlet</code> is started and it opens the related
 * <code>Connection</code> that it has registered for Push.
 * </P>
 * <P>
 * When datagram connections are supported with Push, the
 * implementation MUST guarantee that when a <code>MIDlet</code>
 * registered for datagram Push is started in response to an incoming
 * datagram, at least the datagram that caused the startup of the
 * <code>MIDlet</code> is buffered by the implementation and will be
 * available to the <code>MIDlet</code> when the <code>MIDlet</code>
 * opens the <code>UDPDatagramConnection</code> after startup.
 * </P>
 * <P>
 * When socket connections are supported with Push, the
 * implementation MUST guarantee that when a <code>MIDlet</code>
 * registered for socket Push is started in response to
 * an incoming socket connection, this connection can
 * be accepted by the <code>MIDlet</code> by opening the
 * <code>ServerSocketConnection</code> after startup, provided
 * that the connection hasn't timed out meanwhile.
 * </P>
 *
 * <H3> Connection vs Push Registration Support </H3>
 * <P>
 * Not all generic connections will be appropriate for use
 * as push application transport. Even if a protocol is supported
 * on the device as an inbound connection type, it is not required
 * to be enabled as a valid push mechanism. e.g. a platform might
 * support server socket connections in a <code>MIDlet</code>,
 * but might not support inbound socket connections for push
 * launch capability.
 * A <code>ConnectionNotFoundException</code> is thrown from
 * the <code>registerConnection</code> and from the
 * <code>registerAlarm</code> methods, when the platform
 * does not support that optional capability.
 * </P>
 *
 * <H3> AMS Connection Handoff </H3>
 * <P>
 * Responsibility for registered push connections is shared between
 * the AMS and the <code>MIDlet</code> that handles the I/O
 * operations on the inbound connection. To prevent any data
 * from being lost, an application is responsible for
 * all I/O operations on the connection from the time it calls
 * <code>Connector.open()</code>
 * until it calls <code>Connection.close()</code>.
 * </P>
 * <P>
 * The AMS listens for inbound connection notifications. This
 * MAY be handled via a native callback or polling mechanism
 * looking for new inbound data. The AMS is
 * responsible for enforcing the
 * <A HREF="package-summary.html#push">Security of PushRegistry</A>
 * and presenting notifications (if any) to the user before invoking
 * the MIDlet suite.
 *</P>
 * <P>
 * The AMS is responsible for the shutdown of any running
 * applications (if necessary) prior to the invocation of
 * the push <code>MIDlet</code> method.
 * </P>
 * <P>
 * After the AMS has started the push application, the
 * <code>MIDlet</code> is responsible for opening the
 * connections and for all subsequent I/O operations.
 * An application that needs to perform blocking I/O
 * operations SHOULD use a separate thread to allow
 * for interactive user operations.
 * Once the application has been started and the connection
 * has been opened, the AMS is no longer responsible for
 * listening for push notifications for that connection.
 * The application is
 * responsible for reading all inbound data.
 * </P>
 * <P>
 * If an application has finished with all inbound data
 * it MAY <code>close()</code> the connection.
 * If the connection is closed,
 * then neither the AMS nor the application
 * will be listening for push notifications. Inbound data
 * could be lost, if the application closes the connection
 * before all data has been received.
 * </P>
 * <P>
 * When the application is destroyed, the AMS resumes its
 * responsiblity to watch for inbound connections.
 * </P>
 * <P>
 * A push application SHOULD behave in a predictable manner