Source Code Cross Referenced for PushRegistry.java in  » 6.0-JDK-Modules » j2me » javax » microedition » io » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Java Source Code / Java Documentation
1. 6.0 JDK Core
2. 6.0 JDK Modules
3. 6.0 JDK Modules com.sun
4. 6.0 JDK Modules com.sun.java
5. 6.0 JDK Modules sun
6. 6.0 JDK Platform
7. Ajax
8. Apache Harmony Java SE
9. Aspect oriented
10. Authentication Authorization
11. Blogger System
12. Build
13. Byte Code
14. Cache
15. Chart
16. Chat
17. Code Analyzer
18. Collaboration
19. Content Management System
20. Database Client
21. Database DBMS
22. Database JDBC Connection Pool
23. Database ORM
24. Development
25. EJB Server geronimo
26. EJB Server GlassFish
27. EJB Server JBoss 4.2.1
28. EJB Server resin 3.1.5
29. ERP CRM Financial
30. ESB
31. Forum
32. GIS
33. Graphic Library
34. Groupware
35. HTML Parser
36. IDE
37. IDE Eclipse
38. IDE Netbeans
39. Installer
40. Internationalization Localization
41. Inversion of Control
42. Issue Tracking
43. J2EE
44. JBoss
45. JMS
46. JMX
47. Library
48. Mail Clients
49. Net
50. Parser
51. PDF
52. Portal
53. Profiler
54. Project Management
55. Report
56. RSS RDF
57. Rule Engine
58. Science
59. Scripting
60. Search Engine
61. Security
62. Sevlet Container
63. Source Control
64. Swing Library
65. Template Engine
66. Test Coverage
67. Testing
68. UML
69. Web Crawler
70. Web Framework
71. Web Mail
72. Web Server
73. Web Services
74. Web Services apache cxf 2.0.1
75. Web Services AXIS2
76. Wiki Engine
77. Workflow Engines
78. XML
79. XML UI
Java
Java Tutorial
Java Open Source
Jar File Download
Java Articles
Java Products
Java by API
Photoshop Tutorials
Maya Tutorials
Flash Tutorials
3ds-Max Tutorials
Illustrator Tutorials
GIMP Tutorials
C# / C Sharp
C# / CSharp Tutorial
C# / CSharp Open Source
ASP.Net
ASP.NET Tutorial
JavaScript DHTML
JavaScript Tutorial
JavaScript Reference
HTML / CSS
HTML CSS Reference
C / ANSI-C
C Tutorial
C++
C++ Tutorial
Ruby
PHP
Python
Python Tutorial
Python Open Source
SQL Server / T-SQL
SQL Server / T-SQL Tutorial
Oracle PL / SQL
Oracle PL/SQL Tutorial
PostgreSQL
SQL / MySQL
MySQL Tutorial
VB.Net
VB.Net Tutorial
Flash / Flex / ActionScript
VBA / Excel / Access / Word
XML
XML Tutorial
Microsoft Office PowerPoint 2007 Tutorial
Microsoft Office Excel 2007 Tutorial
Microsoft Office Word 2007 Tutorial
Java Source Code / Java Documentation » 6.0 JDK Modules » j2me » javax.microedition.io 
Source Cross Referenced  Class Diagram Java Document (Java Doc) 


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-&lt;n&gt;</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>&lt;n&gt;: &lt;ConnectionURL&gt;,
096:         *      &lt;MIDletClassName&gt;, &lt;AllowedSender&gt;
097:         * </BLOCKQUOTE>
098:         * </CODE>  where :
099:         * <UL>
100:         * <LI> <code>MIDlet-Push-&lt;n&gt;</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 &lt;n&gt; 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-&lt;n&gt;</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 &lt; 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 &gt; 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 &gt; 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-&lt;n&gt; 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-&lt;n&gt; 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-&lt;n&gt; 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-&lt;n&gt; 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:        }
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.