pushregistry.java

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

 *                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 > 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 > 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>
 * @since MIDP 2.0
 */

public class PushRegistry {

    /** Prevent instantiation of the push registry. */
    private PushRegistry() { };

    /**
     * Register a dynamic connection with the
     * application management software. Once registered,
     * the dynamic connection acts just like a
     * connection preallocated from the descriptor file.
     *
     * <P> The arguments for the dynamic connection registration are the 
     * same as the <A HREF="#PushAttr">Push Registration Attribute</A>
     * used for static registrations. 
     * </P>
     * <P> If the <code>connection</code> or <code>filter</code>
     * arguments are <code>null</code>,
     * then an <code>IllegalArgumentException</code> will be thrown.
     * If the <code>midlet</code> argument is <code>null</code> a 
     * <code>ClassNotFoundException</code> will be thrown. </P>
     *
     * @param connection generic connection <em>protocol</em>, <em>host</em>
     *              and <em>port number</em>
     *              (optional parameters may be included
     *              separated with semi-colons (;))
     * @param midlet  class name of the <code>MIDlet</code> to be launched,
     *              when new external data is available.
     * The named <code>MIDlet</code> MUST be registered in the
     * descriptor file or the jar file manifest with a
     * MIDlet-&lt;n&gt; record. This parameter has the same semantics
     * as the MIDletClassName in the Push registration attribute
     * defined above in the class description.
     * @param filter a connection URL string indicating which senders
     *              are allowed to cause the <code>MIDlet</code> to be launched
     * @exception  IllegalArgumentException if the connection string is not
     *              valid, or if the filter string is not valid
     * @exception ConnectionNotFoundException if the runtime system does not
     *              support push delivery for the requested
     *              connection protocol
     * @exception IOException if the connection is already
     *              registered or if there are insufficient resources
     *              to handle the registration request
     * @exception ClassNotFoundException if the <code>MIDlet</code>
     * class name can not be found in the current <code>MIDlet</code>
     * suite or if this class is not included in any of the
     * MIDlet-&lt;n&gt; records in the descriptor file or the jar file
     * manifest 
     * @exception SecurityException if the <code>MIDlet</code> does not
     *              have permission to register a connection
     * @see #unregisterConnection
     */
    public static void  registerConnection(String connection, String midlet,
					   String filter)
	throws ClassNotFoundException,
	        IOException {

	PushRegistryImpl
	    .registerConnection(connection, midlet, filter);
    }

    /**
     * Remove a dynamic connection registration.
     *
     * @param connection generic connection <em>protocol</em>,
     *            <em>host</em> and <em>port number</em>
     * @exception SecurityException if the connection was
     *            registered by another <code>MIDlet</code>
     *            suite
     * @return <code>true</code> if the unregistration was successful,
     *         <code>false</code> if the connection was not registered
     *         or if the connection argument was <code>null</code>
     * @see #registerConnection
     */
    public static boolean unregisterConnection(String connection) {

	return PushRegistryImpl.unregisterConnection(connection);
    }

    /**
     * Return a list of registered connections for the current
     * <code>MIDlet</code> suite.
     *
     * @param available if <code>true</code>, only return the list of
     *     connections with input available, otherwise return the 
     *     complete list of registered connections for the current 
     *     <code>MIDlet</code> suite
     * @return array of registered connection strings, where each connection 
     *      is represented by the generic connection <em>protocol</em>, 
     *       <em>host</em> and <em>port number</em> identification
     */
    public static String[] listConnections(boolean available) {
        String connections = PushRegistryImpl.listConnections(available);

        if (connections == null) {
            return new String[0];
        }

        /* Count the commas in the returned string */
        int count = 0;
        int offset = 0;
		
        do {
            offset = connections.indexOf(',', offset + 1);
            count ++;
        } while (offset > 0); 
		
        /* Now parse out the connections for easier access by caller. */
        String[] ret = new String[count];
        int start = 0;
        for (int i = 0; i < count; i++) {
            offset = connections.indexOf(',', start);
            if (offset > 0) {
                /* Up to the next comma */
                ret[i] = connections.substring(start, offset);
            } else {
                /* From the last comma to the end of the string. */
                ret[i] = connections.substring(start);
            }		
            start = offset + 1;
        }

        return ret;
    }

    /**
     * Retrieve the registered <code>MIDlet</code> for a requested connection.
     *
     * @param connection generic connection <em>protocol</em>, <em>host</em>
     *              and <em>port number</em>
     *              (optional parameters may be included
     *              separated with semi-colons (;))
     * @return  class name of the <code>MIDlet</code> to be launched,
     *              when new external data is available, or
     *              <code>null</code> if the connection was not
     *              registered by the current <code>MIDlet</code> suite
     *              or if the connection argument was <code>null</code>
     * @see #registerConnection
     */
    public static String getMIDlet(String connection) {
	// Delegate to implementation class for native lookup
	return 	PushRegistryImpl.getMIDlet(connection);
    }

    /**
     * Retrieve the registered filter for a requested connection.
     *
     * @param connection generic connection <em>protocol</em>, <em>host</em>
     *              and <em>port number</em>
     *              (optional parameters may be included
     *              separated with semi-colons (;))
     * @return a filter string indicating which senders
     *              are allowed to cause the <code>MIDlet</code> to be 
     *              launched or <code>null</code>, if the connection was not
     *              registered by the current <code>MIDlet</code> suite
     *              or if the connection argument was <code>null</code>
     * @see #registerConnection
     */
    public static String getFilter(String connection) {
	// Delegate to implementation class for native lookup
	return 	PushRegistryImpl.getFilter(connection);
    }

    /**
     * Register a time to launch the specified application. The
     * <code>PushRegistry</code> supports one outstanding wake up
     * time per <code>MIDlet</code> in the current suite. An application
     * is expected to use a <code>TimerTask</code> for notification
     * of time based events while the application is running.
     * <P>If a wakeup time is already registered, the previous value will
     * be returned, otherwise a zero is returned the first time the
     * alarm is registered. </P>
     *
     * @param midlet  class name of the <code>MIDlet</code> within the
     *                current running <code>MIDlet</code> suite
     *                to be launched,
     *                when the alarm time has been reached.
     * The named <code>MIDlet</code> MUST be registered in the
     * descriptor file or the jar file manifest with a
     * MIDlet-&lt;n&gt; record. This parameter has the same semantics
     * as the MIDletClassName in the Push registration attribute
     * defined above in the class description.
     * @param time time at which the <code>MIDlet</code> is to be executed
     *        in the format returned by <code>Date.getTime()</code>
     * @return the time at which the most recent execution of this
     *        <code>MIDlet</code> was scheduled to occur,
     *        in the format returned by <code>Date.getTime()</code>
     * @exception ConnectionNotFoundException if the runtime system does not
     *              support alarm based application launch
     * @exception ClassNotFoundException if the <code>MIDlet</code>
     * class name can not be found in the current <code>MIDlet</code>
     * suite or if this class is not included in any of the
     * MIDlet-&lt;n&gt; records in the descriptor file or the jar file
     * manifest or if the <code>midlet</code> argument is
     * <code>null</code>
     * @exception SecurityException if the <code>MIDlet</code> does not
     *              have permission to register an alarm
     * @see Date#getTime()
     * @see Timer
     * @see TimerTask
     */
    public static long registerAlarm(String midlet, long time)
	 throws ClassNotFoundException, ConnectionNotFoundException {
	// Delegate to implementation class for native registration
	return 	PushRegistryImpl.registerAlarm(midlet, time);
    }
 
}