<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--NewPage-->
<HTML>
<HEAD>
<!-- Generated by javadoc (build 1.4.2_03) on Mon Oct 10 16:31:47 CEST 2005 -->
<TITLE>
PushRegistry (IM Profile)
</TITLE>

<META NAME="keywords" CONTENT="javax.microedition.io.PushRegistry class">

<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../stylesheet.css" TITLE="Style">

<SCRIPT type="text/javascript">
function windowTitle()
{
    parent.document.title="PushRegistry (IM Profile)";
}
</SCRIPT>

</HEAD>

<BODY BGCOLOR="white" onload="windowTitle();">


<!-- ========= START OF TOP NAVBAR ======= -->
<A NAME="navbar_top"><!-- --></A>
<A HREF="#skip-navbar_top" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_top_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
  <TR ALIGN="center" VALIGN="top">
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="class-use/PushRegistry.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
  </TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
<strong>IM Profile</strong></EM>
</TD>
</TR>

<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../../javax/microedition/io/Connector.html" title="class in javax.microedition.io"><B>PREV CLASS</B></A>&nbsp;
&nbsp;NEXT CLASS</FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
  <A HREF="../../../index.html" target="_top"><B>FRAMES</B></A>  &nbsp;
&nbsp;<A HREF="PushRegistry.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
&nbsp;<SCRIPT type="text/javascript">
  <!--
  if(window==top) {
    document.writeln('<A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A>');
  }
  //-->
</SCRIPT>
<NOSCRIPT>
  <A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>

</FONT></TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
  SUMMARY:&nbsp;NESTED&nbsp;|&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;<A HREF="#method_summary">METHOD</A></FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL:&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;<A HREF="#method_detail">METHOD</A></FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_top"></A>
<!-- ========= END OF TOP NAVBAR ========= -->

<HR>
<!-- ======== START OF CLASS DATA ======== -->
<H2>
<FONT SIZE="-1">
javax.microedition.io</FONT>
<BR>
Class PushRegistry</H2>
<PRE>
<A HREF="../../../java/lang/Object.html" title="class in java.lang">java.lang.Object</A>
  <IMG SRC="../../../resources/inherit.gif" ALT="extended by"><B>javax.microedition.io.PushRegistry</B>
</PRE>
<HR>
<DL>
<DT>public class <B>PushRegistry</B><DT>extends <A HREF="../../../java/lang/Object.html" title="class in java.lang">Object</A></DL>

<P>
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
 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.
                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>

<P>
<DL>
<DT><B>Since:</B></DT>
  <DD>MIDP 2.0</DD>
</DL>
<HR>

<P>
<!-- ======== NESTED CLASS SUMMARY ======== -->


<!-- =========== FIELD SUMMARY =========== -->


<!-- ======== CONSTRUCTOR SUMMARY ======== -->


<!-- ========== METHOD SUMMARY =========== -->

<A NAME="method_summary"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=2><FONT SIZE="+2">
<B>Method Summary</B></FONT></TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;<A HREF="../../../java/lang/String.html" title="class in java.lang">String</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/io/PushRegistry.html#getFilter(java.lang.String)">getFilter</A></B>(<A HREF="../../../java/lang/String.html" title="class in java.lang">String</A>&nbsp;connection)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Retrieve the registered filter for a requested connection.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;<A HREF="../../../java/lang/String.html" title="class in java.lang">String</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/io/PushRegistry.html#getMIDlet(java.lang.String)">getMIDlet</A></B>(<A HREF="../../../java/lang/String.html" title="class in java.lang">String</A>&nbsp;connection)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Retrieve the registered <code>MIDlet</code> for a requested connection.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;<A HREF="../../../java/lang/String.html" title="class in java.lang">String</A>[]</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/io/PushRegistry.html#listConnections(boolean)">listConnections</A></B>(boolean&nbsp;available)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Return a list of registered connections for the current
 <code>MIDlet</code> suite.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;long</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/io/PushRegistry.html#registerAlarm(java.lang.String, long)">registerAlarm</A></B>(<A HREF="../../../java/lang/String.html" title="class in java.lang">String</A>&nbsp;midlet,
              long&nbsp;time)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Register a time to launch the specified application. </TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/io/PushRegistry.html#registerConnection(java.lang.String, java.lang.String, java.lang.String)">registerConnection</A></B>(<A HREF="../../../java/lang/String.html" title="class in java.lang">String</A>&nbsp;connection,
                   <A HREF="../../../java/lang/String.html" title="class in java.lang">String</A>&nbsp;midlet,
                   <A HREF="../../../java/lang/String.html" title="class in java.lang">String</A>&nbsp;filter)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Register a dynamic connection with the
 application management software. </TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;boolean</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/io/PushRegistry.html#unregisterConnection(java.lang.String)">unregisterConnection</A></B>(<A HREF="../../../java/lang/String.html" title="class in java.lang">String</A>&nbsp;connection)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Remove a dynamic connection registration.</TD>
</TR>
</TABLE>
&nbsp;<A NAME="methods_inherited_from_class_java.lang.Object"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#EEEEFF" CLASS="TableSubHeadingColor">
<TD><B>Methods inherited from class java.lang.<A HREF="../../../java/lang/Object.html" title="class in java.lang">Object</A></B></TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD><CODE><A HREF="../../../java/lang/Object.html#equals(java.lang.Object)">equals</A>, <A HREF="../../../java/lang/Object.html#getClass()">getClass</A>, <A HREF="../../../java/lang/Object.html#hashCode()">hashCode</A>, <A HREF="../../../java/lang/Object.html#notify()">notify</A>, <A HREF="../../../java/lang/Object.html#notifyAll()">notifyAll</A>, <A HREF="../../../java/lang/Object.html#toString()">toString</A>, <A HREF="../../../java/lang/Object.html#wait()">wait</A>, <A HREF="../../../java/lang/Object.html#wait(long)">wait</A>, <A HREF="../../../java/lang/Object.html#wait(long, int)">wait</A></CODE></TD>
</TR>
</TABLE>
&nbsp;
<P>

<!-- ============ FIELD DETAIL =========== -->


<!-- ========= CONSTRUCTOR DETAIL ======== -->


<!-- ============ METHOD DETAIL ========== -->

<A NAME="method_detail"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=1><FONT SIZE="+2">
<B>Method Detail</B></FONT></TD>
</TR>
</TABLE>

<A NAME="registerConnection(java.lang.String, java.lang.String, java.lang.String)"><!-- --></A><H3>
registerConnection</H3>
<PRE>
public static void <B>registerConnection</B>(<A HREF="../../../java/lang/String.html" title="class in java.lang">String</A>&nbsp;connection,
                                      <A HREF="../../../java/lang/String.html" title="class in java.lang">String</A>&nbsp;midlet,
                                      <A HREF="../../../java/lang/String.html" title="class in java.lang">String</A>&nbsp;filter)
                               throws <A HREF="../../../java/lang/ClassNotFoundException.html" title="class in java.lang">ClassNotFoundException</A>,
                                      <A HREF="../../../java/io/IOException.html" title="class in java.io">IOException</A></PRE>
<DL>
<DD>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>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>connection</CODE> - generic connection <em>protocol</em>, <em>host</em>
              and <em>port number</em>
              (optional parameters may be included
              separated with semi-colons (;))<DD><CODE>midlet</CODE> - 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.<DD><CODE>filter</CODE> - a connection URL string indicating which senders
              are allowed to cause the <code>MIDlet</code> to be launched
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../java/lang/IllegalArgumentException.html" title="class in java.lang">IllegalArgumentException</A></CODE> - if the connection string is not
              valid, or if the filter string is not valid
<DD><CODE><A HREF="../../../javax/microedition/io/ConnectionNotFoundException.html" title="class in javax.microedition.io">ConnectionNotFoundException</A></CODE> - if the runtime system does not
              support push delivery for the requested
              connection protocol
<DD><CODE><A HREF="../../../java/io/IOException.html" title="class in java.io">IOException</A></CODE> - if the connection is already
              registered or if there are insufficient resources
              to handle the registration request
<DD><CODE><A HREF="../../../java/lang/ClassNotFoundException.html" title="class in java.lang">ClassNotFoundException</A></CODE> - 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
<DD><CODE><A HREF="../../../java/lang/SecurityException.html" title="class in java.lang">SecurityException</A></CODE> - if the <code>MIDlet</code> does not
              have permission to register a connection<DT><B>See Also:</B><DD><A HREF="../../../javax/microedition/io/PushRegistry.html#unregisterConnection(java.lang.String)"><CODE>unregisterConnection(java.lang.String)</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="unregisterConnection(java.lang.String)"><!-- --></A><H3>
unregisterConnection</H3>
<PRE>
public static boolean <B>unregisterConnection</B>(<A HREF="../../../java/lang/String.html" title="class in java.lang">String</A>&nbsp;connection)</PRE>
<DL>
<DD>Remove a dynamic connection registration.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>connection</CODE> - generic connection <em>protocol</em>,
            <em>host</em> and <em>port number</em>
<DT><B>Returns:</B><DD><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>
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../java/lang/SecurityException.html" title="class in java.lang">SecurityException</A></CODE> - if the connection was
            registered by another <code>MIDlet</code>
            suite<DT><B>See Also:</B><DD><A HREF="../../../javax/microedition/io/PushRegistry.html#registerConnection(java.lang.String, java.lang.String, java.lang.String)"><CODE>registerConnection(java.lang.String, java.lang.String, java.lang.String)</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="listConnections(boolean)"><!-- --></A><H3>
listConnections</H3>
<PRE>
public static <A HREF="../../../java/lang/String.html" title="class in java.lang">String</A>[] <B>listConnections</B>(boolean&nbsp;available)</PRE>
<DL>
<DD>Return a list of registered connections for the current
 <code>MIDlet</code> suite.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>available</CODE> - 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
<DT><B>Returns:</B><DD>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</DL>
</DD>
</DL>
<HR>

<A NAME="getMIDlet(java.lang.String)"><!-- --></A><H3>
getMIDlet</H3>
<PRE>
public static <A HREF="../../../java/lang/String.html" title="class in java.lang">String</A> <B>getMIDlet</B>(<A HREF="../../../java/lang/String.html" title="class in java.lang">String</A>&nbsp;connection)</PRE>
<DL>
<DD>Retrieve the registered <code>MIDlet</code> for a requested connection.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>connection</CODE> - generic connection <em>protocol</em>, <em>host</em>
              and <em>port number</em>
              (optional parameters may be included
              separated with semi-colons (;))
<DT><B>Returns:</B><DD>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><DT><B>See Also:</B><DD><A HREF="../../../javax/microedition/io/PushRegistry.html#registerConnection(java.lang.String, java.lang.String, java.lang.String)"><CODE>registerConnection(java.lang.String, java.lang.String, java.lang.String)</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="getFilter(java.lang.String)"><!-- --></A><H3>
getFilter</H3>
<PRE>
public static <A HREF="../../../java/lang/String.html" title="class in java.lang">String</A> <B>getFilter</B>(<A HREF="../../../java/lang/String.html" title="class in java.lang">String</A>&nbsp;connection)</PRE>
<DL>
<DD>Retrieve the registered filter for a requested connection.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>connection</CODE> - generic connection <em>protocol</em>, <em>host</em>
              and <em>port number</em>
              (optional parameters may be included
              separated with semi-colons (;))
<DT><B>Returns:</B><DD>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><DT><B>See Also:</B><DD><A HREF="../../../javax/microedition/io/PushRegistry.html#registerConnection(java.lang.String, java.lang.String, java.lang.String)"><CODE>registerConnection(java.lang.String, java.lang.String, java.lang.String)</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="registerAlarm(java.lang.String, long)"><!-- --></A><H3>
registerAlarm</H3>
<PRE>
public static long <B>registerAlarm</B>(<A HREF="../../../java/lang/String.html" title="class in java.lang">String</A>&nbsp;midlet,
                                 long&nbsp;time)
                          throws <A HREF="../../../java/lang/ClassNotFoundException.html" title="class in java.lang">ClassNotFoundException</A>,
                                 <A HREF="../../../javax/microedition/io/ConnectionNotFoundException.html" title="class in javax.microedition.io">ConnectionNotFoundException</A></PRE>
<DL>
<DD>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>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>midlet</CODE> - 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.<DD><CODE>time</CODE> - time at which the <code>MIDlet</code> is to be executed
        in the format returned by <code>Date.getTime()</code>
<DT><B>Returns:</B><DD>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>
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../javax/microedition/io/ConnectionNotFoundException.html" title="class in javax.microedition.io">ConnectionNotFoundException</A></CODE> - if the runtime system does not
              support alarm based application launch
<DD><CODE><A HREF="../../../java/lang/ClassNotFoundException.html" title="class in java.lang">ClassNotFoundException</A></CODE> - 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>
<DD><CODE><A HREF="../../../java/lang/SecurityException.html" title="class in java.lang">SecurityException</A></CODE> - if the <code>MIDlet</code> does not
              have permission to register an alarm<DT><B>See Also:</B><DD><A HREF="../../../java/util/Date.html#getTime()"><CODE>Date.getTime()</CODE></A>, 
<A HREF="../../../java/util/Timer.html" title="class in java.util"><CODE>Timer</CODE></A>, 
<A HREF="../../../java/util/TimerTask.html" title="class in java.util"><CODE>TimerTask</CODE></A></DL>
</DD>
</DL>
<!-- ========= END OF CLASS DATA ========= -->
<HR>


<!-- ======= START OF BOTTOM NAVBAR ====== -->
<A NAME="navbar_bottom"><!-- --></A>
<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
  <TR ALIGN="center" VALIGN="top">
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="class-use/PushRegistry.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
  </TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
<strong>IM Profile</strong></EM>
</TD>
</TR>

<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../../javax/microedition/io/Connector.html" title="class in javax.microedition.io"><B>PREV CLASS</B></A>&nbsp;
&nbsp;NEXT CLASS</FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
  <A HREF="../../../index.html" target="_top"><B>FRAMES</B></A>  &nbsp;
&nbsp;<A HREF="PushRegistry.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
&nbsp;<SCRIPT type="text/javascript">
  <!--
  if(window==top) {
    document.writeln('<A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A>');
  }
  //-->
</SCRIPT>
<NOSCRIPT>
  <A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>

</FONT></TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
  SUMMARY:&nbsp;NESTED&nbsp;|&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;<A HREF="#method_summary">METHOD</A></FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL:&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;<A HREF="#method_detail">METHOD</A></FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_bottom"></A>
<!-- ======== END OF BOTTOM NAVBAR ======= -->

<HR>
<font size=\-1\><a href=\mailto:midp-feedback@risc.sps.mot.com\>Submit a comment or suggestion</a> Version 2.0 of IM Profile Specification<br>Java is a trademark or registered trademark of Sun Microsystems,  Inc. in the US and other countries. Copyright (c) 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A.  All Rights Reserved.</font>
</BODY>
</HTML>
