pushregistry.java

来自「This is a resource based on j2me embedde」· Java 代码 · 共 758 行 · 第 1/3 页

 * 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 > 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>
 */

public class PushRegistry {
    /*
     * Currently stubbed just to make TCK signature test
     * pass and NAMS build configuration fine
     */

    /** 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 {
        throw new ConnectionNotFoundException("not supported");
    }

    /**
     * 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 false;
    }

    /**
     * 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) {
        return new String [0];
    }

    /**
     * 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) {
        return null;
    }

    /**
     * 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) {
        return null;
    }

    /**
     * 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 {
        throw new ConnectionNotFoundException("not supported");
    }
}