001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package com.sun.midp.midlet;
028:
029: import javax.microedition.io.ConnectionNotFoundException;
030:
031: /**
032: * Abstracts the platform request functionality for each VM platform.
033: */
034: public interface PlatformRequest {
035: /**
036: * Requests that the device handle (e.g. display or install)
037: * the indicated URL.
038: *
039: * <p>If the platform has the appropriate capabilities and
040: * resources available, it SHOULD bring the appropriate
041: * application to the foreground and let the user interact with
042: * the content, while keeping the MIDlet suite running in the
043: * background. If the platform does not have appropriate
044: * capabilities or resources available, it MAY wait to handle the
045: * URL request until after the MIDlet suite exits. In this case,
046: * when the requesting MIDlet suite exits, the platform MUST then
047: * bring the appropriate application to the foreground to let the
048: * user interact with the content.</p>
049: *
050: * <p>This is a non-blocking method. In addition, this method does
051: * NOT queue multiple requests. On platforms where the MIDlet
052: * suite must exit before the request is handled, the platform
053: * MUST handle only the last request made. On platforms where the
054: * MIDlet suite and the request can be handled concurrently, each
055: * request that the MIDlet suite makes MUST be passed to the
056: * platform software for handling in a timely fashion.</p>
057: *
058: * <p>If the URL specified refers to a MIDlet suite (either an
059: * Application Descriptor or a JAR file), the request is
060: * interpreted as a request to install the named package. In this
061: * case, the platform's normal MIDlet suite installation process
062: * SHOULD be used, and the user MUST be allowed to control the
063: * process (including cancelling the download and/or
064: * installation). If the MIDlet suite being installed is an
065: * <em>update</em> of the currently running MIDlet suite, the
066: * platform MUST first stop the currently running MIDlet suite
067: * before performing the update. On some platforms, the currently
068: * running MIDlet suite MAY need to be stopped before any
069: * installations can occur.</p>
070: *
071: * <p>If the URL specified is of the form
072: * <code>tel:<number></code>, as specified in <a
073: * href="http://rfc.net/rfc2806.html">RFC2806</a>, then the
074: * platform MUST interpret this as a request to initiate a voice
075: * call. The request MUST be passed to the "phone"
076: * application to handle if one is present in the platform.</p>
077: *
078: * <p>Devices MAY choose to support additional URL schemes beyond
079: * the requirements listed above.</p>
080: *
081: * <p>Many of the ways this method will be used could have a
082: * financial impact to the user (e.g. transferring data through a
083: * wireless network, or initiating a voice call). Therefore the
084: * platform MUST ask the user to explicitly acknowledge each
085: * request before the action is taken. Implementation freedoms are
086: * possible so that a pleasant user experience is retained. For
087: * example, some platforms may put up a dialog for each request
088: * asking the user for permission, while other platforms may
089: * launch the appropriate application and populate the URL or
090: * phone number fields, but not take the action until the user
091: * explicitly clicks the load or dial buttons.</p>
092: *
093: * @return true if the MIDlet suite MUST first exit before the
094: * content can be fetched.
095: *
096: * @param URL The URL for the platform to load.
097: *
098: * @exception ConnectionNotFoundException if
099: * the platform cannot handle the URL requested.
100: *
101: */
102: boolean dispatch(String URL) throws ConnectionNotFoundException;
103: }
|