001: /*
002: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
004: *
005: * This program is free software; you can redistribute it and/or
006: * modify it under the terms of the GNU General Public License version
007: * 2 only, as published by the Free Software Foundation.
008: *
009: * This program is distributed in the hope that it will be useful, but
010: * WITHOUT ANY WARRANTY; without even the implied warranty of
011: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012: * General Public License version 2 for more details (a copy is
013: * included at /legal/license.txt).
014: *
015: * You should have received a copy of the GNU General Public License
016: * version 2 along with this work; if not, write to the Free Software
017: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
018: * 02110-1301 USA
019: *
020: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
021: * Clara, CA 95054 or visit www.sun.com if you need additional
022: * information or have any questions.
023: */
024:
025: package javax.microedition.io;
026:
027: import java.io.IOException;
028:
029: /**
030: * The <code>PushRegistry</code> maintains a list of inbound
031: * connections. An application can register the inbound
032: * connections with an entry in the application descriptor file
033: * or dynamically by calling the
034: * <code>registerConnection</code> method.
035: * <P> While an application is running, it is responsible for
036: * all I/O operations associated with the inbound connection.
037: * When the application is not running, the application
038: * management software(AMS) listens for inbound notification
039: * requests. When a notification arrives for a registered
040: * <code>MIDlet</code>, the AMS will start the <code>MIDlet</code>
041: * via the normal invocation of <code>MIDlet.startApp</code>
042: * method.</P>
043: *
044: * <H3> Installation Handling of Declared Connections </H3>
045: *
046: * <P>
047: * To avoid collisions on inbound generic connections, the application
048: * descriptor file MUST include information about static connections
049: * that are needed by the <code>MIDlet</code> suite.
050: *
051: * If all the static Push declarations in the application descriptor
052: * can not be fulfilled during the installation, the user MUST be
053: * notified that there are conflicts and the MIDlet suite MUST NOT be
054: * installed. (See <em>Over The Air User Initiated Provisioning
055: * Specification</em> section for errors reported in the event
056: * of conflicts.)
057: *
058: * Conditions
059: * when the declarations can not be fulfilled include: syntax errors in
060: * the Push attributes, declaration for a connection end point (e.g. port
061: * number) that is already reserved in the device, declaration for a
062: * protocol that is not supported for Push in the device, and declaration
063: * referencing a <code>MIDlet</code> class that is not listed in
064: * the <code>MIDlet-<n></code> attributes of the same
065: * application descriptor.
066: *
067: * If the <code>MIDlet</code> suite
068: * can function meaningfully even if a Push registration can't be
069: * fulfilled, it MUST register the Push connections using the dynamic
070: * registration methods in the <code>PushRegistry</code>.
071: * </P>
072: * <P>
073: * A conflict-free installation reserves each requested connection for
074: * the exclusive use of the
075: * <code>MIDlets</code> in the suite. While the suite is
076: * installed, any attempt by other applications to open one of the
077: * reserved connections will fail with an
078: * <code>IOException</code>. A call from a
079: * <code>MIDlet</code> to
080: * <code>Connector.open()</code>
081: * on a connection reserved for its suite will always
082: * succeed, assuming the suite does not already have the connection open.
083: * </P>
084: *
085: * <P>
086: * If two <code>MIDlet</code> suites have a static push connection in
087: * common, they cannot be installed together and both function
088: * correctly. The end user would typically have to uninstall one before
089: * being able to successfully install the other.
090: * </P>
091: * <H3> <A NAME="PushAttr"></A>Push Registration Attribute </H3>
092: * <P>
093: * Each push registration entry contains the following information :
094: * <CODE><BLOCKQUOTE>
095: * <strong>MIDlet-Push-</strong><n>: <ConnectionURL>,
096: * <MIDletClassName>, <AllowedSender>
097: * </BLOCKQUOTE>
098: * </CODE> where :
099: * <UL>
100: * <LI> <code>MIDlet-Push-<n></code> =
101: * the Push registration attribute name. Multiple push
102: * registrations can be provided in a <code>MIDlet</code>
103: * suite. The numeric value for <n> starts from 1 and
104: * MUST use consecutive ordinal numbers for additional entries.
105: * The first missing entry terminates the list. Any
106: * additional entries are ignored.
107: * </LI>
108: * <LI><code>ConnectionURL</code> =
109: * the connection string used in <code>Connector.open()</code></LI>
110: * <LI><code>MIDletClassName</code> =
111: * the <code>MIDlet</code> that is responsible for the connection.
112: * The named <code>MIDlet</code> MUST be registered in the
113: * descriptor file or the jar file manifest with a
114: * <code>MIDlet-<n></code> record.
115: * (This information is needed when displaying messages to
116: * the user about the application when push connections are detected,
117: * or when the user grants/revokes privileges for the application.)
118: * If the named <code>MIDlet</code> appears more than once in the
119: * suite, the first matching entry is used. </LI>
120: * <LI>
121: * <code>AllowedSender</code> = a designated filter that restricts which
122: * senders are valid for launching the requested <code>MIDlet</code>.
123: *
124: * The syntax and semantics of the <code>AllowedSender</code> field
125: * depend on the addressing format used for the protocol.
126: *
127: * However, every syntax for this field MUST support using the wildcard
128: * characters "*" and "?". The semantics of those wildcard are:
129: * <UL>
130: * <LI> "*" matches any string, including an empty string </LI>
131: * <LI> "?" matches any single character </LI>
132: * </UL>
133: * When the value of this field is just the wildcard character "*",
134: * connections will be accepted from any originating source.
135: *
136: * For Push attributes using the <CODE>datagram</CODE> and
137: * <CODE>socket</CODE> URLs (if supported by the platform), this field
138: * contains a numeric IP address in the same format for IPv4 and IPv6 as
139: * used in the respective URLs (IPv6 address including the square
140: * brackets as in the URL).
141: *
142: * It is possible to use the wildcards also in these IP addresses,
143: * e.g. "129.70.40.*" would allow subnet resolution. Note that the port
144: * number is not part of the filter for <CODE>datagram</CODE> and
145: * <CODE>socket</CODE> connections.
146: * </LI>
147: * </UL>
148: * <P>
149: * The MIDP specification defines the syntax for
150: * <code>datagram</code> and <code>socket</code> inbound
151: * connections. When other specifications
152: * define push semantics for additional connection types, they
153: * must define the expected syntax for the filter field, as well as
154: * the expected format for the connection URL string.
155: * </P>
156: * <H4> Example Descriptor File Declarative Notation </H4>
157: *
158: * <P>
159: * The following is a sample descriptor file entry that would reserve
160: * a stream socket at port 79 and a datagram connection at
161: * port 50000. (Port numbers are maintained by IANA
162: * and cover well-known, user-registered and dynamic port numbers)
163: * [See <a href="http://www.iana.org/numbers.html#P">
164: * IANA Port Number Registry</a>]
165: * </P>
166: *
167: * <CODE>
168: * <PRE>
169: * MIDlet-Push-1: socket://:79, com.sun.example.SampleChat, *
170: * MIDlet-Push-2: datagram://:50000, com.sun.example.SampleChat, *
171: * </PRE>
172: * </CODE>
173: * <H3> Buffered Messages </H3>
174: * <P>
175: * The requirements for buffering of messages are specific
176: * to each protocol used for Push and are defined separately
177: * for each protocol. There is no general requirement related
178: * to buffering that would apply to all protocols. If the
179: * implementation buffers messages, these messages MUST
180: * be provided to the <code>MIDlet</code> when the
181: * <code>MIDlet</code> is started and it opens the related
182: * <code>Connection</code> that it has registered for Push.
183: * </P>
184: * <P>
185: * When datagram connections are supported with Push, the
186: * implementation MUST guarantee that when a <code>MIDlet</code>
187: * registered for datagram Push is started in response to an incoming
188: * datagram, at least the datagram that caused the startup of the
189: * <code>MIDlet</code> is buffered by the implementation and will be
190: * available to the <code>MIDlet</code> when the <code>MIDlet</code>
191: * opens the <code>UDPDatagramConnection</code> after startup.
192: * </P>
193: * <P>
194: * When socket connections are supported with Push, the
195: * implementation MUST guarantee that when a <code>MIDlet</code>
196: * registered for socket Push is started in response to
197: * an incoming socket connection, this connection can
198: * be accepted by the <code>MIDlet</code> by opening the
199: * <code>ServerSocketConnection</code> after startup, provided
200: * that the connection hasn't timed out meanwhile.
201: * </P>
202: *
203: * <H3> Connection vs Push Registration Support </H3>
204: * <P>
205: * Not all generic connections will be appropriate for use
206: * as push application transport. Even if a protocol is supported
207: * on the device as an inbound connection type, it is not required
208: * to be enabled as a valid push mechanism. e.g. a platform might
209: * support server socket connections in a <code>MIDlet</code>,
210: * but might not support inbound socket connections for push
211: * launch capability.
212: * A <code>ConnectionNotFoundException</code> is thrown from
213: * the <code>registerConnection</code> and from the
214: * <code>registerAlarm</code> methods, when the platform
215: * does not support that optional capability.
216: * </P>
217: *
218: * <H3> AMS Connection Handoff </H3>
219: * <P>
220: * Responsibility for registered push connections is shared between
221: * the AMS and the <code>MIDlet</code> that handles the I/O
222: * operations on the inbound connection. To prevent any data
223: * from being lost, an application is responsible for
224: * all I/O operations on the connection from the time it calls
225: * <code>Connector.open()</code>
226: * until it calls <code>Connection.close()</code>.
227: * </P>
228: * <P>
229: * The AMS listens for inbound connection notifications. This
230: * MAY be handled via a native callback or polling mechanism
231: * looking for new inbound data. The AMS is
232: * responsible for enforcing the
233: * <A HREF="package-summary.html#push">Security of PushRegistry</A>
234: * and presenting notifications (if any) to the user before invoking
235: * the MIDlet suite.
236: *</P>
237: * <P>
238: * The AMS is responsible for the shutdown of any running
239: * applications (if necessary) prior to the invocation of
240: * the push <code>MIDlet</code> method.
241: * </P>
242: * <P>
243: * After the AMS has started the push application, the
244: * <code>MIDlet</code> is responsible for opening the
245: * connections and for all subsequent I/O operations.
246: * An application that needs to perform blocking I/O
247: * operations SHOULD use a separate thread to allow
248: * for interactive user operations.
249: * Once the application has been started and the connection
250: * has been opened, the AMS is no longer responsible for
251: * listening for push notifications for that connection.
252: * The application is
253: * responsible for reading all inbound data.
254: * </P>
255: * <P>
256: * If an application has finished with all inbound data
257: * it MAY <code>close()</code> the connection.
258: * If the connection is closed,
259: * then neither the AMS nor the application
260: * will be listening for push notifications. Inbound data
261: * could be lost, if the application closes the connection
262: * before all data has been received.
263: * </P>
264: * <P>
265: * When the application is destroyed, the AMS resumes its
266: * responsibility to watch for inbound connections.
267: * </P>
268: * <P>
269: * A push application SHOULD behave in a predictable manner
270: * when handling asynchronous data via the push mechanism.
271: * A well behaved application SHOULD inform the user that
272: * data has been processed. (While it is possible to write
273: * applications that do not use any user visible interfaces,
274: * this could lead to a confused end user experience to
275: * launch an application that only performs a background
276: * function.)
277: * </P>
278: * <H3>Dynamic Connections Registered from a Running MIDlet</H3>
279: *
280: * <P>
281: * There are cases when defining a well known port registered
282: * with IANA is not necessary.
283: * Simple applications may just wish to exchange data using a private
284: * protocol between a <code>MIDlet</code> and server application.
285: * </P>
286: *
287: * <P>
288: * To accommodate this type of application, a mechanism is provided
289: * to dynamically allocate a connection and to register
290: * that information, as if it was known, when the application was
291: * installed. This information can then be sent to an agent on the network to
292: * use as the mechanism to communicate with the registered
293: * <code>MIDlet</code>.
294: * </P>
295: * <P>
296: * For instance, if a <a href="UDPDatagramConnection.html">
297: * <code>UDPDatagramConnection</code></a>
298: * is opened and a port number,
299: * was not specified, then the application is
300: * requesting a dynamic port
301: * to be allocated from the ports that are currently available. By
302: * calling <code>PushRegistry.registerConnection()</code> the
303: * <code>MIDlet</code> informs the AMS that it is the target for
304: * inbound communication, even
305: * after the <code>MIDlet</code> has been destroyed (See
306: * <code>MIDlet</code> life cycle for
307: * definition of "destroyed" state). If the application is deleted from the
308: * phone, then its dynamic communication connections are unregistered
309: * automatically.
310: * </P>
311: * <H3>AMS Runtime Handling - Implementation Notes</H3>
312: *
313: * <P>
314: * During installation each <code>MIDlet</code> that is expecting
315: * inbound communication
316: * on a well known address has the information recorded with the
317: * AMS from the push registration attribute in the manifest or
318: * application descriptor file. Once the installation has been
319: * successfully completed,
320: * (e.g. For the OTA recommended practices - when the <em>Installation
321: * notification message</em> has been successfully transmitted, the
322: * application is officially installed.)
323: * the <code>MIDlet</code> MAY then receive inbound communication.
324: * e.g. the push notification event.
325: * </P>
326: *
327: * <P>
328: * When the AMS is started, it checks the list of registered
329: * connections and begins listening for inbound communication.
330: * When a notification arrives the AMS starts the registered
331: * <code>MIDlet</code>.
332: * The <code>MIDlet</code> then opens
333: * the connection with <code>Connector.open()</code> method to
334: * perform whatever I/O operations are needed for the particular
335: * connection type. e.g. for a server socket the application
336: * uses <code>acceptAndOpen()</code> to get the socket connected
337: * and for a datagram connection the application uses
338: * <code>receive()</code> to read the delivered message.
339: * </P>
340: * <P>
341: * For message oriented transports the inbound message MAY be
342: * read by the AMS and saved for delivery to the <code>MIDlet</code>
343: * when it requests to read the data. For stream oriented transports
344: * the connection MAY be lost if the connection is not
345: * accepted before the server end of the connection request
346: * timeouts.
347: * </P>
348: * <P>
349: * When a <code>MIDlet</code> is started in response to a registered
350: * push connection notification, it is platform dependent what
351: * happens to the current running application. The <code>MIDlet</code>
352: * life cycle defines the expected behaviors that an interrupted
353: * <code>MIDlet</code> could see from a call to <code>pauseApp()</code>
354: * or from <code>destroyApp()</code>.
355: * </P>
356: * <H2>Sample Usage Scenarios</H2>
357: * <P>
358: * <strong>Usage scenario 1:</strong>
359: * The suite includes a <code>MIDlet</code> with a well
360: * known port for communication.
361: * During the <code>startApp</code> processing
362: * a thread is launched to handle the incoming data.
363: * Using a separate thread is the recommended practice
364: * for avoiding conflicts between blocking I/O operations
365: * and the normal user interaction events. The
366: * thread continues to receive messages until the
367: * <code>MIDlet</code> is destroyed.
368: * </P>
369: *
370: * <H4>Sample Chat Descriptor File -</H4>
371: * <P> In this sample, the descriptor file includes
372: * a static push
373: * connection registration. It also includes
374: * an indication that this <code>MIDlet</code>
375: * requires permission to use a datagram connection
376: * for inbound push messages.
377: * (See <A HREF="package-summary.html#push">
378: * Security of Push Functions</A> in the package
379: * overview for details about <code>MIDlet</code> permissions.)
380: * <strong>Note:</strong> this sample is appropriate for bursts of
381: * datagrams.
382: * It is written to loop on the connection, processing
383: * received messages.
384: * </P>
385: * <CODE>
386: * <PRE>
387: * MIDlet-Name: SunNetwork - Chat Demo
388: * MIDlet-Version: 1.0
389: * MIDlet-Vendor: Sun Microsystems, Inc.
390: * MIDlet-Description: Network demonstration programs for MIDP
391: * MicroEdition-Profile: MIDP-2.0
392: * MicroEdition-Configuration: CLDC-1.0
393: * MIDlet-1: InstantMessage, /icons/Chat.png, example.chat.SampleChat, *
394: * MIDlet-Push-1: datagram://:79, example.chat.SampleChat, *
395: * MIDlet-Permissions: javax.microedition.io.PushRegistry, \\
396: * javax.microedition.io.Connector.datagramreceiver
397: * </PRE>
398: * </CODE>
399: *
400: * <H4>Sample Chat MIDlet Processing -</H4>
401: * <CODE>
402: * <PRE>
403: * public class SampleChat extends MIDlet {
404: * // Current inbound message connection.
405: * DatagramConnection conn;
406: * // Flag to terminate the message reading thread.
407: * boolean done_reading;
408: *
409: * public void startApp() {
410: * // List of active connections.
411: * String connections[];
412: *
413: * // Check to see if this session was started due to
414: * // inbound connection notification.
415: * connections = PushRegistry.listConnections(true);
416: *
417: * // Start an inbound message thread for available
418: * // inbound messages for the statically configured
419: * // connection in the descriptor file.
420: * for (int i=0; i < connections.length; i++) {
421: * Thread t = new Thread (new MessageHandler(
422: * connections[i]));
423: * t.start();
424: * }
425: *
426: * ...
427: * }
428: * }
429: *
430: * // Stop reading inbound messages and release the push
431: * // connection to the AMS listener.
432: * public void destroyApp(boolean conditional) {
433: * done_reading = true;
434: * if (conn != null)
435: * conn.close();
436: * // Optionally, notify network service that we're
437: * // done with the current session.
438: * ...
439: * }
440: *
441: * // Optionally, notify network service.
442: * public void pauseApp() {
443: * ...
444: * }
445: *
446: * // Inner class to handle inbound messages on a separate thread.
447: * class MessageHandler implements Runnable {
448: * String connUrl ;
449: * MessageHandler(String url) {
450: * connUrl = url ;
451: * }
452: * // Fetch messages in a blocking receive loop.
453: * public void run() {
454: * try {
455: * // Get a connection handle for inbound messages
456: * // and a buffer to hold the inbound message.
457: * DatagramConnection conn = (DatagramConnection)
458: * Connector.open(connUrl);
459: * Datagram data = conn.newDatagram(conn.getMaximumLength());
460: *
461: * // Read the inbound messages
462: * while (!done_reading) {
463: * conn.receive(data);
464: * ...
465: * }
466: * } catch (IOException ioe) {
467: * ...
468: * }
469: * ...
470: * </PRE>
471: * </CODE>
472: * <P>
473: * <strong>Usage scenario 2:</strong>
474: * The suite includes a <code>MIDlet</code>
475: * that dynamically allocates port the first time
476: * it is started.
477: * </P>
478: *
479: *
480: * <H4>Sample Ping Descriptor File -</H4>
481: * <P> In this sample, the descriptor file includes an
482: * entry indicating that
483: * the application will need permission to use the datagram
484: * connection for inbound push messages. The dynamic connection
485: * is allocated in the constructor the first time it is run.
486: * The open connection is used during this session and
487: * can be reopened in a subsequent session in response to
488: * a inbound connection notification.
489: * </P>
490: * <CODE>
491: * <PRE>
492: * MIDlet-Name: SunNetwork - Demos
493: * MIDlet-Version: 1.0
494: * MIDlet-Vendor: Sun Microsystems, Inc.
495: * MIDlet-Description: Network demonstration programs for MIDP
496: * MicroEdition-Profile: MIDP-2.0
497: * MicroEdition-Configuration: CLDC-1.0
498: * MIDlet-1: JustCallMe, /icons/Ping.png, example.ping.SamplePingMe, *
499: * MIDlet-Permissions: javax.microedition.io.PushRegistry, \\
500: * javax.microedition.io.Connector.datagramreceiver
501: * </PRE>
502: * </CODE>
503: *
504: * <H4>Sample Ping MIDlet Processing -</H4>
505: * <CODE>
506: * <PRE>
507: * public class SamplePingMe extends MIDlet {
508: * // Name of the current application for push registration.
509: * String myName = "example.chat.SamplePingMe";
510: * // List of registered push connections.
511: * String connections[];
512: * // Inbound datagram connection
513: * UDPDatagramConnection dconn;
514: *
515: * public SamplePingMe() {
516: *
517: * // Check to see if the ping connection has been registered.
518: * // This is a dynamic connection allocated on first
519: * // time execution of this MIDlet.
520: * connections = PushRegistry.listConnections(false);
521: *
522: * if (connections.length == 0) {
523: * // Request a dynamic port for out-of-band notices.
524: * // (Omitting the port number let's the system allocate
525: * // an available port number.)
526: * try {
527: * dconn = (UDPDatagramConnection)
528: * Connector.open("datagram://");
529: * String dport = "datagram://:" + dconn.getLocalPort();
530: *
531: * // Register the port so the MIDlet will wake up, if messages
532: * // are posted after the MIDlet exits.
533: * PushRegistry.registerConnection(dport, myName, "*");
534: *
535: * // Post my datagram address to the network
536: * ...
537: * } catch (IOException ioe) {
538: * ...
539: * } catch (ClassNotFoundException cnfe) {
540: * ...
541: * }
542: * }
543: *
544: * public void startApp() {
545: * // Open the connection if it's not already open.
546: * if (dconn == null) {
547: * // This is not the first time this is run, because the
548: * // dconn hasn't been opened by the constructor.
549: *
550: * // Check if the startup has been due to an incoming
551: * // datagram.
552: * connections = PushRegistry.listConnections(true);
553: *
554: * if (connections.length > 0) {
555: * // There is a pending datagram that can be received.
556: * dconn = (UDPDatagramConnection)
557: * Connector.open(connections[0]);
558: *
559: * // Read the datagram
560: * Datagram d = dconn.newDatagram(dconn.getMaximumLength());
561: * dconn.receive(d);
562: * } else {
563: * // There are not any pending datagrams, but open
564: * // the connection for later use.
565: * connections = PushRegistry.listConnections(false);
566: * if (connections.length > 0) {
567: * dconn = (UDPDatagramConnection)
568: * Connector.open(connections[0]);
569: * }
570: * }
571: * }
572: *
573: * public void destroyApp(boolean unconditional) {
574: * // Close the connection before exiting
575: * if(dconn != null){
576: * dconn.close()
577: * dconn = null
578: * }
579: * }
580: * ...
581: * </PRE>
582: * </CODE>
583: */
584:
585: public class PushRegistry {
586: /*
587: * Currently stubbed just to make TCK signature test
588: * pass and NAMS build configuration fine
589: */
590:
591: /** Prevent instantiation of the push registry. */
592: private PushRegistry() {
593: };
594:
595: /**
596: * Register a dynamic connection with the
597: * application management software. Once registered,
598: * the dynamic connection acts just like a
599: * connection preallocated from the descriptor file.
600: *
601: * <P> The arguments for the dynamic connection registration are the
602: * same as the <A HREF="#PushAttr">Push Registration Attribute</A>
603: * used for static registrations.
604: * </P>
605: * <P> If the <code>connection</code> or <code>filter</code>
606: * arguments are <code>null</code>,
607: * then an <code>IllegalArgumentException</code> will be thrown.
608: * If the <code>midlet</code> argument is <code>null</code> a
609: * <code>ClassNotFoundException</code> will be thrown. </P>
610: *
611: * @param connection generic connection <em>protocol</em>, <em>host</em>
612: * and <em>port number</em>
613: * (optional parameters may be included
614: * separated with semi-colons (;))
615: * @param midlet class name of the <code>MIDlet</code> to be launched,
616: * when new external data is available.
617: * The named <code>MIDlet</code> MUST be registered in the
618: * descriptor file or the jar file manifest with a
619: * MIDlet-<n> record. This parameter has the same semantics
620: * as the MIDletClassName in the Push registration attribute
621: * defined above in the class description.
622: * @param filter a connection URL string indicating which senders
623: * are allowed to cause the <code>MIDlet</code> to be launched
624: * @exception IllegalArgumentException if the connection string is not
625: * valid, or if the filter string is not valid
626: * @exception ConnectionNotFoundException if the runtime system does not
627: * support push delivery for the requested
628: * connection protocol
629: * @exception IOException if the connection is already
630: * registered or if there are insufficient resources
631: * to handle the registration request
632: * @exception ClassNotFoundException if the <code>MIDlet</code>
633: * class name can not be found in the current <code>MIDlet</code>
634: * suite or if this class is not included in any of the
635: * MIDlet-<n> records in the descriptor file or the jar file
636: * manifest
637: * @exception SecurityException if the <code>MIDlet</code> does not
638: * have permission to register a connection
639: * @see #unregisterConnection
640: */
641: public static void registerConnection(String connection,
642: String midlet, String filter)
643: throws ClassNotFoundException, IOException {
644: throw new ConnectionNotFoundException("not supported");
645: }
646:
647: /**
648: * Remove a dynamic connection registration.
649: *
650: * @param connection generic connection <em>protocol</em>,
651: * <em>host</em> and <em>port number</em>
652: * @exception SecurityException if the connection was
653: * registered by another <code>MIDlet</code>
654: * suite
655: * @return <code>true</code> if the unregistration was successful,
656: * <code>false</code> if the connection was not registered
657: * or if the connection argument was <code>null</code>
658: * @see #registerConnection
659: */
660: public static boolean unregisterConnection(String connection) {
661: return false;
662: }
663:
664: /**
665: * Return a list of registered connections for the current
666: * <code>MIDlet</code> suite.
667: *
668: * @param available if <code>true</code>, only return the list of
669: * connections with input available, otherwise return the
670: * complete list of registered connections for the current
671: * <code>MIDlet</code> suite
672: * @return array of registered connection strings, where each connection
673: * is represented by the generic connection <em>protocol</em>,
674: * <em>host</em> and <em>port number</em> identification
675: */
676: public static String[] listConnections(boolean available) {
677: return new String[0];
678: }
679:
680: /**
681: * Retrieve the registered <code>MIDlet</code> for a requested connection.
682: *
683: * @param connection generic connection <em>protocol</em>, <em>host</em>
684: * and <em>port number</em>
685: * (optional parameters may be included
686: * separated with semi-colons (;))
687: * @return class name of the <code>MIDlet</code> to be launched,
688: * when new external data is available, or
689: * <code>null</code> if the connection was not
690: * registered by the current <code>MIDlet</code> suite
691: * or if the connection argument was <code>null</code>
692: * @see #registerConnection
693: */
694: public static String getMIDlet(String connection) {
695: return null;
696: }
697:
698: /**
699: * Retrieve the registered filter for a requested connection.
700: *
701: * @param connection generic connection <em>protocol</em>, <em>host</em>
702: * and <em>port number</em>
703: * (optional parameters may be included
704: * separated with semi-colons (;))
705: * @return a filter string indicating which senders
706: * are allowed to cause the <code>MIDlet</code> to be
707: * launched or <code>null</code>, if the connection was not
708: * registered by the current <code>MIDlet</code> suite
709: * or if the connection argument was <code>null</code>
710: * @see #registerConnection
711: */
712: public static String getFilter(String connection) {
713: return null;
714: }
715:
716: /**
717: * Register a time to launch the specified application. The
718: * <code>PushRegistry</code> supports one outstanding wake up
719: * time per <code>MIDlet</code> in the current suite. An application
720: * is expected to use a <code>TimerTask</code> for notification
721: * of time based events while the application is running.
722: * <P>If a wakeup time is already registered, the previous value will
723: * be returned, otherwise a zero is returned the first time the
724: * alarm is registered. </P>
725: *
726: * @param midlet class name of the <code>MIDlet</code> within the
727: * current running <code>MIDlet</code> suite
728: * to be launched,
729: * when the alarm time has been reached.
730: * The named <code>MIDlet</code> MUST be registered in the
731: * descriptor file or the jar file manifest with a
732: * MIDlet-<n> record. This parameter has the same semantics
733: * as the MIDletClassName in the Push registration attribute
734: * defined above in the class description.
735: * @param time time at which the <code>MIDlet</code> is to be executed
736: * in the format returned by <code>Date.getTime()</code>
737: * @return the time at which the most recent execution of this
738: * <code>MIDlet</code> was scheduled to occur,
739: * in the format returned by <code>Date.getTime()</code>
740: * @exception ConnectionNotFoundException if the runtime system does not
741: * support alarm based application launch
742: * @exception ClassNotFoundException if the <code>MIDlet</code>
743: * class name can not be found in the current <code>MIDlet</code>
744: * suite or if this class is not included in any of the
745: * MIDlet-<n> records in the descriptor file or the jar file
746: * manifest or if the <code>midlet</code> argument is
747: * <code>null</code>
748: * @exception SecurityException if the <code>MIDlet</code> does not
749: * have permission to register an alarm
750: * @see Date#getTime()
751: * @see Timer
752: * @see TimerTask
753: */
754: public static long registerAlarm(String midlet, long time)
755: throws ClassNotFoundException, ConnectionNotFoundException {
756: throw new ConnectionNotFoundException("not supported");
757: }
758: }
|