JSR 82 maintenance review 4

$Id: changes.html 407 2010-03-31 11:14:34Z tpr $

JSR 82: Java APIs for Bluetooth Wireless Technology

The maintenance lead is Tim Renouf of Aplix Corp, tpr@aplixcorp.com.

This maintenance review proposes changes to update JSR 82 1.1.1 to JSR 82 1.2.

Comments received by maintenance lead

comment disposition
artf3091 : Introduce class-based permissions for CLDC 1.1.1 & MIDP 3.0 integration included
artf2540 : A.10.1 JAM Operation for Blacklist devices needs updating. The current specification states that the JAM does not accept connections for Push requests for devices on the blacklist. This is not consistent with the MIDP specification. Instead, the specification needs to change to state that the JAM does not start the MIDlet if the device is on the blacklist. included

artf2665 : Section A.6.1 contains vague statements. This section contains the following statement: "Note that in case of dynamic registration the JAM MUST NOT start to listen to the registered connection immediately, but rather after MIDlet termination (see Section A.9, where exact rules for the JAM behavior are defined)."

It is unclear when the JAM should start listening for the MIDlet. Based on section A.9, it appears as though there is an assumption that the MIDlet that is registering the connection is the same as the push MIDlet. This may not be true. If these are not the same MIDlet, the JAM should start listening for the connection once it is registered.

included
artf2941 : Different Exceptions are specified for an "authorize=XXX" statement in a client string. The JSR-82 specification specifies two different exceptions (IllegalArgumentException and BluetoothConnectionException) if "authorize=XXX" is contained in a client connection string. This needs to be clarified in the specification. In particular, the IllegalArgumentException should be used since it has been tested for the last 2 years. included
artf2550 : L2CapConnection.send() incorrectly listed as non-blocking, artf2546 : Remove Appendix B. included
artf2940 : TransmitMTU needs to be clearly defined as positive. There exists tests to verify that the transmitMTU in an L2CAP connection string is positive, but the JSR-82 specification does not clearly state this. Add a statement to this effect to the specification. included
artf2909 : Typos in the Javadoc: There is a typo in the ClientSession.put() Javadoc. It currently reads: "If the headers argument may be null." This should read: "The headers argument may be null." A second typo needs to be fixed: SessionNotifier second acceptAndOpen "Note : once an application invokes close() on a any SessionNotifier, L2CAP" "a" is extra, should be: "on any" included
Make L2CAP SHOULD rather than MUST, to allow JSR 82 implementation on a platform does not expose L2CAP to applications. included
Remove reserved ranges from L2CAP PSM values, to allow a Java application to use a Bluetooth protocol that is built on top of L2CAP using a PSM value in the "reserved" range. included
Change restrictions on the incoming MTU: Allow the implementation to set the MTU to more than DEFAULT_MTU if the underlying stack allows it, to improve throughput. included
artf2614 : Update JSR-82 specification to address new security capabilities in BT v2.1 deferred: Not enough evidence that any changes are needed or what the changes would be.
artf2722 : Modify the Operation.getResponseCode() description to add the word final. In other words, change the first sentence to: "Returns the final response code received from the server." rejected: The current wording seems clear enough

Changelog for maintenance review 4

These are the proposed changes from JSR 82 Java APIs for Bluetooth Wireless Technology version 1.1.1 to version 1.2.

# change description reason spec version status
artf3091

Introduce classes javax.bluetooth.Btl2capProtocolPermission, javax.bluetooth.BtsppProtocolPermission, javax.obex.BtgoepProtocolPermission, javax.obex.IrdaobexProtocolPermission, javax.obex.TcpobexProtocolPermission, each extending GCFPermission, and each with a URI string but no actions list. The URI string has the same form as in the corresponding protocol, with wildcard matching specified in a way suggested by analogous permission classes in CLDC 1.1.1. In the table in 9.2, add a new middle column to the table "Permission class (CLDC 1.1.1)" so the table now specifies the correspondence between MIDP 2 permissions, CLDC 1.1.1 permission classes and permitted API calls. See below for full details.

Update 2010-03-31: Roger Riggs from Oracle pointed out that the new permission classes should be in packages defined in JSR 82, not in javax.microedition.io. The change described above and in more detail below now does this.

Update 2010-03-31: In the table in 9.2, the row for a tcpobex client connection permission gave a MIDP 3 permission of javax.obex.TcpobexProtocolPermission("tcpobex://*"). Andrey Nazarov from Oracle pointed out that this would default to port 650, and would not allow any other port. The entry has now been corrected to javax.obex.TcpobexProtocolPermission("tcpobex://*:*").

Introduce class-based permissions for CLDC 1.1.1 & MIDP 3.0 integration 1.2 proposed
artf2540 A.10.1 change from
If an initiator of a registered Bluetooth connection fails to pass the AllowedSender filter, the JAM MUST NOT accept the connection. A push MIDlet MUST NOT be launched.
to
If an initiator of a registered Bluetooth connection fails to pass the AllowedSender filter, a push MIDlet MUST NOT be launched.
The wording is inconsistent with the MIDP spec. 1.2 proposed
artf2665 A.6.1 first paragraph last sentence: add a clause, shown here emphasized:
Note that in case of dynamic registration where the registering MIDlet is the same as the newly registered push MIDlet, or part of the same MIDlet suite, the JAM MUST NOT start to listen to the registered connection immediately, but rather after MIDlet termination (see Section A.9, where exact rules for the JAM behavior are defined).
Section A.6.1 contains vague statements not consistent with A.9. 1.2 proposed
artf2941 8.2.5 Client Requests in the Connection String, paragraph after bullet list:
With this API, the only device that needs to grant permission to use a service is the device that offers that service. Consequently, the parameter authorize is not allowed in client connections. A BluetoothConnectionException is thrown if either authorize=true or authorize=false appears in a client connection string.
change BluetoothConnectionException to IllegalArgumentException.
Different Exceptions are specified for an "authorize=XXX" statement in a client string 1.2 proposed
artf2550, artf2546 Remove appendix B. Appendix B incorrectly lists L2CapConnection.send() as non-blocking, and otherwise only repeats information available elsewhere in the specification. 1.2 proposed
artf2940 11.3.1 L2CAP Server and Client Connection URLs: Just before the fourth para on p89 (starting "If a connection fails,"), insert a new para:
If the client or server application requests a TransmitMTU value of 0, the Connector.open MUST fail.
TransmitMTU needs to be clearly defined as positive 1.2 proposed
artf2909

Javadoc ClientSession.put(): Change

If the headers argument may be null.
to
The headers argument may be null.

Javadoc SessionNotifier.acceptAndOpen(ServerRequestHandler handler, Authenticator auth): remove the extra "a" from

Note : once an application invokes close() on a any SessionNotifier, L2CAP...

Remove Javadoc typos. 1.2 proposed

2.2.3 Bluetooth System Requirements, second bullet, third sub-bullet, add the condition in parentheses:

  • Logical Link Control and Adaptation Protocol (L2CAP) (if the JSR 82 implementation provides L2CAP)

2.3 Scope, first list, point 2: Append a sentence:

An implementation of this specification SHOULD provide L2CAP. However an implementation may be unable to provide L2CAP if the underlying operating system and drivers do not expose sufficient functionality.

2.3 Scope, third list, point 3, change from

Establish RFCOMM, L2CAP and OBEX connections
to
Establish RFCOMM, L2CAP (where provided)and OBEX connections

11.2 API Overview: Insert new second para:

An implementation of this specification SHOULD provide L2CAP. However an implementation may be unable to provide L2CAP if the underlying operating system and drivers do not expose sufficient functionality. Where L2CAP is not provided, any attempt to create an L2CAP connection using Connector.open MUST fail. The L2CAP-related interfaces specified in the Javadoc MUST be provided anyway.

Page 24, table 3-2, bluetooth.l2cap.receiveMTU.max: Append a sentence to the description:

This property is not present if L2CAP is not supported.
and add a new property bluetooth.l2cap.supported with the description
Is L2CAP supported? Valid values are either "true" or "false".

Javadoc for LocalDevice.getProperty, property bluetooth.l2cap.receiveMTU.max: Append the same sentence as above to the description.

Javadoc for LocalDevice.getProperty: Add a new property bluetooth.l2cap.supported with the same description as above.

Allow implementation of JSR 82 on platforms where the OS does not expose L2CAP to applications. 1.2 proposed

11.3.1 L2CAP Server and Client Connection URLs, in the BNF on page 87: Just above the “receiveMTU = ...” rule, add a new rule

psm = ";psm=" 1*(HEXDIG) ; see constraints below
Modify the “srvParams = ...” rule as follows by inserting extra text shown here emphasized:
srvParams = name / master / encrypt / authorize / authenticate / psm / receiveMTU / transmitMTU
In the paragraph at the top of p88, modify to the following, splitting the paragraph in two:

The psm in the preceding client connection string description represents the Protocol Service Multiplexor (PSM) value for the service. L2CAP server applications on a device can identify themselves with a PSM value, which is by default assigned by the implementation, but is overridden by the value specified as a hexadecimal integer in the psm parameter, if any, in the server connection string. If the implementation is unable to use the value given in the psm parameter, then Connector.open fails and throws an exception.

Legal PSM values are in the range (0x0005..0xFFFF), and the least significant byte must be odd and all other bytes must be even. When a server connection string does not have a psm parameter, the server PSM value assigned by the implementation must be no less than 0x1001.

11.3.2 L2CAP Service Record, table on page 90, in the “PSM value” row, change the contents of the last cell in the row:

Value assigned and inserted by the implementation; the value is obtained from the server connection string’s psm parameter if any, or, if none, assigned by the implementation. Used by btl2cap clients to identify the service to connect to.

9.2 Bluetooth Permissions: Add two new MIDP2 permissions javax.microedition.io.Connector.bluetooth.client.reserved and javax.microedition.io.Connector.bluetooth.server.reserved, as detailed below with the other changes to that table.

Allow Java application programmers to implement other protocols on top of L2CAP that use a PSM value in the "reserved" range. 1.2 proposed
11.2.1 Channel Configuration, "This API assumes that" list, second bullet: Change second sentence from:
The application can specify the incoming MTU that it would like to use for the connection. If an application does not specify this value, then the DEFAULT_MTU of 672 bytes or the Bluetooth stack max MTU is used, whichever is smaller.
to
The application can specify the incoming MTU that it would like to use for the connection. If an application does not specify this value, then the implementation chooses a value that is no less than the DEFAULT_MTU of 672 bytes and no greater than the Bluetooth stack max MTU; if the max MTU is less than 672 bytes, then the max MTU is used.
Allow the JSR 82 implementation to use the maximum throughput available with the Bluetooth stack. 1.2 proposed

Table 3-2, bluetooth.api.version and obex.api.version, change "1.1.1" to "1.2".

Javadoc for LocalDevice.getProperty, property bluetooth.api.version, change "1.1.1" to "1.2".

Allow applications to discover which version of JSR 82 is implemented. 1.2 proposed

Full list of changes for class-based permissions

9: Change title to "MIDP 2 and CLDC 1.1.1 Security"

9.1 Introduction: Add mention of CLDC 1.1.1 as follows (splitting the single paragraph, and adding the text that is here emphasized for clarity):

This chapter describes the Bluetooth Permissions that are an extension of the framework first defined in MIDP 2.0.1, and the class-based permissions that are an extension of the framework first defined in CLDC 1.1.1 and referenced by MIDP 3.0.

The MIDP 2.0.1 specification defines the framework for authenticating the source of a MIDlet suite and authorizing the MIDlet suite to perform protected functions by granting permissions that it may have requested based on the security policy on the device. It also identifies functions that are deemed security vulnerable and defines permissions for those protected functions. Additionally, MIDP 2.0.1 specifies the common rules for APIs that can be used together with the MIDP but are specified outside the MIDP. The MIDP 2.0.1 specification does not mandate a single trust model but rather allows the model to accord with the device trust policy. This chapter defines the recommended security policy for Bluetooth. The Function group definitions referred to below can be found in MIDP 2.0.1 or later.

The CLDC 1.1.1 specification (referenced by MIDP 3.0) similarly defines a framework, but with class-based permissions. The table below lists the classes defined for this purpose when JSR 82 is combined with CLDC 1.1.1. The classes are actually defined in this specification's accompanying Javadoc.

9.2 Bluetooth Permissions: Rename "Permission" column to "Permission Name (MIDP 2)", and insert a new column "Permission Class (CLDC 1.1.1)".

Also add new MIDP2 permissions javax.microedition.io.Connector.bluetooth.client.reserved and javax.microedition.io.Connector.bluetooth.server.reserved. This is for the “allow Java application programmers to implement other protocols on top of L2CAP that use a PSM value in the ‘reserved’ range” change.

Permission name (MIDP 2) Permission class (CLDC 1.1.1) Permitted API calls Function group
javax.microedition.io.Connector.bluetooth.client javax.bluetooth.BtsppProtocolPermission("btspp://*:*") Connector.open("btspp://<server BD_ADDR>...") Local Connectivity
javax.bluetooth.Btl2capProtocolPermission("btl2cap://*:1001-FFFF") Connector.open("btl2cap://<server BD_ADDR>...")
javax.microedition.io.Connector.bluetooth.client.reserved javax.bluetooth.Btl2capProtocolPermission("btl2cap://*:5-FFF")
javax.microedition.io.Connector.obex.client javax.obex.BtgoepProtocolPermission("btgoep://*:*") Connector.open("btgoep://<server BD_ADDR>...") Local Connectivity
javax.obex.IrdaobexProtocolPermission("irdaobex://*") Connector.open("irdaobex://discover...")
Connector.open("irdaobex://addr...")
Connector.open("irdaobex://conn...")
Connector.open("irdaobex://name...")
javax.microedition.io.Connector.obex.client.tcp javax.obex.TcpobexProtocolPermission("tcpobex://*:*") Connector.open("tcpobex://<server IP_ADDR>...") Net Access
javax.microedition.io.Connector.bluetooth.server javax.bluetooth.BtsppProtocolPermission("btspp://localhost:*") Connector.open("btspp://localhost:...") Local Connectivity
javax.bluetooth.Btl2capProtocolPermission("btl2cap://localhost:*") Connector.open("btl2cap://localhost:...")
javax.microedition.io.Connector.bluetooth.server.reserved javax.bluetooth.Btl2capProtocolPermission("btl2cap://localhost:*;psm=5-FFF")
javax.microedition.io.Connector.obex.server javax.obex.BtgoepProtocolPermission("btgoep://localhost:*") Connector.open("btgoep://localhost...") Local Connectivity
javax.obex.IrdaobexProtocolPermission("irdaobex://localhost") Connector.open("irdaobex://localhost...")
javax.microedition.io.Connector.obex.server.tcp javax.obex.TcpobexProtocolPermission("tcpobex://:*") Connector.open("tcpobex://:<PORT>")
Connector.open("tcpobex://")
Net Access

Add new classes to Javadoc as follows.

javax.obex.BtgoepProtocolPermission

package javax.obex;
import javax.microedition.io.GCFPermission;

/**
 * This class represents access
 * rights to connections via the "btgoep"
 * protocol. A <code>BtgoepProtocolPermission</code> consists of a URI string
 * but no actions list.
 * <p>
 * The class must be present if the platform has <code>GCFPermission</code>,
 * and must be not present otherwise.
 * <p>
 * The URI string specifies a Bluetooth Generic Object Exchange Protocol
 * connection, as described in JSR 82 1.2 section 12.4.1 <em>OBEX Over RFCOMM</em>, with
 * additional changes to allow wildcard matching: the part of the
 * <code>{target}</code>
 * before the ':' character, or the part of the <code>{target}</code> after the ':'
 * character, or both, may each be replaced by a '*' wildcard character. The
 * semantics of wildcard matching are specified below in the
 * <code>implies</code> method.
 * <p>
 * Examples:
 * </p>
 * <table>
 * <tr><td>
 * <code>btgoep://0050C000321B:12</code>
 * <td>matches a client URI with that Bluetooth
 * address and channel identifier, ignoring params
 * <tr><td>
 * <code>btgoep://0050C000321B:12;encrypt=true</code>
 * <td>matches a client URI with that
 * Bluetooth address and channel identifier, and with encrypt=true, ignoring
 * other params
 * <tr><td>
 * <code>btgoep://*:*</code>
 * <td>matches any client URI
 * <tr><td>
 * <code>btgoep://*:*;encrypt=true</code>
 * <td>matches any client URI with encrypt=true, ignoring
 * other params
 * <tr><td>
 * <code>btgoep://*:12</code>
 * <td>matches any client URI with a channel identifier of 12
 * <tr><td>
 * <code>btgoep://localhost:*</code>
 * <td>matches any server URI
 * </table>
 */
public final class BtgoepProtocolPermission extends GCFPermission {

    /**
     * Creates a new <code>BtgoepProtocolPermission</code> with the specified URI as
     * name. The URI string must conform to the specification given
     * above, and is normalized (per the rules of
     * <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>)
     * to facilitate subsequent comparisons.
     *
     * @param uri the URI string
     * @throws IllegalArgumentException if uri is malformed
     * @throws NullPointerException if uri is null.
     */
    public BtgoepProtocolPermission(String uri) { }

    /**
     * Checks if this <code>BtgoepProtocolPermission</code> object
     * "implies" the specified permission.
     * <p>
     * The method acts as if it follows these steps to determine whether
     * this object implies p:
     * </p>
     * <ul>
     * <li>
     * If p is not an instanceof BtgoepProtocolPermission, return false.
     * <li>
     * If this object has any <code>{params}</code>, and any one of
     * the params does not
     * match the setting in p (using the default value if the param is not
     * specified in p), then return false.
     * <li>
     * If this object's <code>{target}</code> matches p's <code>{target}</code>,
     * return true.
     * <li>
     * If this object's <code>{target}</code> is "*:*", and p is a client URI,
     * return true.
     * <li>
     * If this object's <code>{target}</code> consists of "*:" followed by
     * a channel identifier, and p is a client URI with a matching channel
     * identifier, return true.
     * <li>
     * If this object's <code>{target}</code> consists of "localhost:*",
     * and p is a server URI, return true.
     * <li>
     * Otherwise return false.
     * </ul>
     *
     * @param p the permission to check against.
     *
     * @return true if the specified permission is implied by this
     * object, false if not.
     */
    public boolean implies(Permission p) { return false; }

    /**
     * Checks two <code>BtgoepProtocolPermission</code> objects for equality.
     *
     * @param obj the object we are testing for equality with this object.
     *
     * @return true if obj is a <code>BtgoepProtocolPermission</code>
     * and has the same URI string as this object.
     */
    public boolean equals(Object obj) { return false; }

    /**
     * Returns the hash code value for this object.
     *
     * @return a hash value for this object.
     */
    public int hashCode() { return 0; }

    /**
     * Returns the canonical string representation of the actions, which
     * currently is the empty string "", since there are no actions defined for
     * <code>BtgoepProtocolPermission</code>.
     *
     * @return the empty string "".
     */
    public String getActions() { return null; }

    /**
     * Returns a new <code>PermissionCollection</code> for storing
     * <code>BtgoepProtocolPermission</code> objects.
     *
     * <code>BtgoepProtocolPermission</code> objects must be stored in a manner that allows
     * them to be inserted into the collection in any order, but that also
     * enables the <code>PermissionCollection</code> implies method to be implemented in an
     * efficient (and consistent) manner.
     *
     * @return a new <code>PermissionCollection</code> suitable for storing
     * <code>BtgoepProtocolPermission</code> objects.
     */
    public PermissionCollection newPermissionCollection() { return null; }
}

javax.bluetooth.Btl2capProtocolPermission

package javax.bluetooth;
import javax.microedition.io.GCFPermission;

/**
 * This class represents access rights to connections via the "btl2cap"
 * protocol. <code>A Btl2capProtocolPermission</code> consists of a URI string
 * but no actions list.
 * <p>
 * The class must be present if the platform has <code>GCFPermission</code>,
 * and must be not present otherwise.
 * <p>
 * The URI string specifies a Bluetooth L2CAP connection, as described in JSR
 * 82 1.2 section 11.3 <em>L2CAP Connection Interface</em>,
 * with additional changes to
 * allow wildcard matching: the part of the <code>{target}</code>
 * before the ':' character, or the part of the <code>{target}</code> after the ':'
 * character, or both, may each be replaced by a '*' wildcard character.
 * The part of the <code>{target}</code> after the ':' character in a client connection
 * string may be replaced by a range, consisting of two hexadecimal numbers
 * separated by a hyphen. If a <code>psm</code> parameter is included
 * in a server connection
 * string, its value may be replaced by a range, consisting of two hexadecimal
 * numbers separated by a hyphen.
 * The semantics of wildcard matching are specified below in the
 * <code>implies</code> method.
 * <p>
 * Examples:
 * </p><table>
 * <tr><td>
 * <code>btl2cap://0050C000321B:10B3</code>
 * <td>matches a client URI with that Bluetooth
 * address and PSM value, ignoring params
 *
 * <tr><td>
 * <code>btl2cap://0050C000321B:*</code>
 * <td>matches a client URI with that Bluetooth
 * address and any PSM value, ignoring params
 *
 * <tr><td>
 * <code>btl2cap://0050C000321B:1001-FFFF</code>
 * <td>matches a client URI with that Bluetooth
 * address and a PSM value in the range 1001-FFFF, ignoring params
 *
 * <tr><td>
 * <code>btl2cap://*:10B3</code>
 * <td>matches a client URI with any Bluetooth
 * address and a PSM value of 10B3, ignoring params
 *
 * <tr><td>
 * <code>btl2cap://0050C000321B:10B3;encrypt=true</code>
 * <td>matches a client URI with that
 * Bluetooth address and PSM value, and with encrypt=true, ignoring
 * other params
 *
 * <tr><td>
 * <code>btl2cap://*:*</code>
 * <td>matches any client URI
 *
 * <tr><td>
 * <code>btl2cap://*:*;encrypt=true</code>
 * <td>matches any client URI with encrypt=true,
 * ignoring other params
 *
 * <tr><td>
 * <code>btl2cap://*:1001-FFFF</code>
 * <td>matches any client URI with a PSM value in the range
 * 1001-FFFF
 *
 * <tr><td>
 * <code>btl2cap://localhost:3B9FA89520078C303355AAA694238F08</code>
 * <td>matches a server URI
 * with the stated UUID, ignoring params
 *
 * <tr><td>
 * <code>btl2cap://localhost:*</code>
 * <td>matches any server URI that does not have a psm
 * param, or has one that specifies a PSM value in the range 1001-FFFF
 * (so not including the reserved PSM range)
 *
 * <tr><td>
 * <code>btl2cap://localhost:*;name=L2CAPEx</code>
 * <td>matches a server URI with any UUID and
 * with the stated name value, ignoring other params, except that there must be
 * no psm param, or one that specifies a PSM value in the range 1001-FFFF
 * (so not including the reserved PSM range)
 *
 * <tr><td>
 * <code>btl2cap://localhost:*;psm=5-FFFF</code>
 * <td>matches any server URI that specifies a
 * PSM value, even in the PSM reserved range
 *
 * <tr><td>
 * <code>btl2cap://localhost:*;psm=1021-102F</code>
 * <td>matches any server URI with a
 * specified PSM value in the range 1021-102F
 * </table>
 */
public final class Btl2capProtocolPermission extends GCFPermission {

    /**
     * Creates a new <code>Btl2capProtocolPermission</code> with the specified URI as
     * name. The URI string must conform to the specification given
     * above, and is normalized (per the rules of
     * <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>)
     * to facilitate subsequent comparisons.
     *
     * @param uri the URI string
     * @throws IllegalArgumentException if uri is malformed
     * @throws NullPointerException if uri is null.
     */
    public Btl2capProtocolPermission(String uri) {}

    /**
     * Checks if this <code>Btl2capProtocolPermission</code> object "implies" the
     * specified permission.
     * <p>
     * The method acts as if it follows these steps to determine whether
     * this object implies p:
     * </p>
     * <ul>
     * <li>
     * If p is not an instanceof Btl2capProtocolPermission, return false.
     * <li>
     * If this object's <code>{target}</code> and p's <code>{target}</code> both start with
     * "localhost:" (they are both server URIs), and this object has a
     * 'psm' param that is a range (two hexadecimal numbers separated by
     * a hyphen), and either p does not have a "psm" param, or it does
     * but its value is not in the range, then return false.
     * <li>
     * If this object's <code>{target}</code> and p's <code>{target}</code> both start with
     * "localhost:" (they are both server URIs), and this object has a
     * 'psm' param that is not a range, and p does not have a matching
     * 'psm' param, then return false.
     * <li>
     * If this object's <code>{target}</code> and p's <code>{target}</code> both start with
     * "localhost:" (they are both server URIs), and this object has no
     * 'psm' param, and p does have a "psm" param whose value is not
     * in the range 1001-FFFF, then return false.
     * <li>
     * If this object has any <code>{params}</code>, and any one of the params other
     * than "psm" does not match the setting in p (using the default value
     * if the param is not specified in p), then return false.
     * <li>
     * If this object's <code>{target}</code> matches p's <code>{target}</code>, return true.
     * <li>
     * If this object's <code>{target}</code> is "*:*", and p is a client URI, return
     * true.
     * <li>
     * If this object's <code>{target}</code> consists of "*:" followed by a PSM
     * value, and p is a client URI with a matching PSM value, return true.
     * <li>
     * If this object's <code>{target}</code> consists of a Bluetooth address followed
     * by ":*", and p is a client URI with a matching Bluetooth address,
     * return true.
     * <li>
     * If this object's <code>{target}</code> consists of "*:" followed by a PSM
     * range (two PSM values separated by a hyphen), and p is a client
     * URI with a PSM value in that range, return true.
     * <li>
     * If this object's <code>{target}</code> consists of "localhost:*", and p is a
     * server URI, return true.
     * <li>
     * Otherwise return false.
     * </ul>
     *
     * @param p the permission to check against.
     *
     * @return true if the specified permission is implied by this
     * object, false if not.
     */
    public boolean implies(Permission p) { return false; }

    /**
     * Checks two <code>Btl2capProtocolPermission</code> objects for equality.
     *
     * @param obj the object we are testing for equality with this object.
     *
     * @returns true if obj is a <code>Btl2capProtocolPermission</code> and has the same
     * URI string as this object.
     */
    public boolean equals(Object obj) { return false; }

    /**
     * Returns the hash code value for this object.
     *
     * @return a hash value for this object.
     */
    public int hashCode() { return 0; }

    /**
     * Returns the canonical string representation of the actions, which
     * currently is the empty string "", since there are no actions defined for
     * <code>Btl2capProtocolPermission</code>.
     *
     * @return the empty string "".
     */
    public String getActions() { return null; }

    /**
     * Returns a new <code>PermissionCollection</code> for storing
     * <code>Btl2capProtocolPermission</code> objects.
     * <p>
     * <code>Btl2capProtocolPermission</code> objects must be stored in a
     * manner that allows them to be inserted into the collection in any order,
     * but that also enables the <code>PermissionCollection</code> implies
     * method to be implemented in an efficient (and consistent) manner.
     *
     * @return a new <code>PermissionCollection</code> suitable for storing
     * <code>Btl2capProtocolPermission</code> objects.
     */
    public PermissionCollection newPermissionCollection() { return null; }
}

javax.bluetooth.BtsppProtocolPermission

package javax.bluetooth;
import javax.microedition.io.GCFPermission;

/**
 * This class represents access rights to connections via the "btspp"
 * protocol. A <code>BtsppProtocolPermission</code> consists of a URI string
 * but no actions list.
 * <p>
 * The class must be present if the platform has <code>GCFPermission</code>,
 * and must be not present otherwise.
 * <p>
 * The URI string specifies a Bluetooth L2CAP connection, as described in JSR
 * 82 1.2 section 10.3 <em>L2CAP Connection Interface</em>, with additional changes to
 * allow wildcard matching: the part of the <code>{target}</code>
 * before the ':' character, or the part of the <code>{target}</code> after the ':'
 * character, or both, may each be replaced by a '*' wildcard character. The
 * semantics of wildcard matching are specified below in the implies method.
 * <p>
 * Examples:
 * </p>
 * <table>
 * <tr><td>
 * <code>btspp://0050C000321B:12</code>
 * <td>matches a client URI with that Bluetooth
 * address and channel identifier, ignoring params
 * 
 * <tr><td>
 * <code>btspp://0050C000321B:12;encrypt=true</code>
 * <td>matches a client URI with that
 * Bluetooth address and channel identifier, and with encrypt=true, ignoring
 * other params
 *
 * <tr><td>
 * <code>btspp://*:*</code>
 * <td>matches any client URI
 *
 * <tr><td>
 * <code>btspp://*:*;encrypt=true</code>
 * <td>matches any client URI with encrypt=true, ignoring
 * other params
 *
 * <tr><td>
 * <code>btspp://*:12</code>
 * <td>matches any client URI with a channel identifier of 12
 *
 * <tr><td>
 * <code>btspp://localhost:*</code>
 * <td>matches any server URI
 * </table>
 */
public final class BtsppProtocolPermission extends GCFPermission {

    /**
     * Creates a new <code>BtsppProtocolPermission</code> with the specified URI as
     * name. The URI string must conform to the specification given
     * above, and is normalized (per the rules of
     * <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>)
     * to facilitate subsequent comparisons.
     *
     * @param uri the URI string
     * @throws IllegalArgumentException if uri is malformed
     * @throws NullPointerException if uri is null.
     */
    public BtsppProtocolPermission(String uri) {}

    /**
     * Checks if this <code>BtsppProtocolPermission</code> object "implies" the
     * specified permission.
     * <p>
     * The method acts as if it follows these steps to determine whether
     * this object implies p:
     * <p>
     * <ul>
     * <li>If p is not an instanceof BtsppProtocolPermission, return false.
     *
     * <li>If this object has any <code>{params}</code>, and any one of the params does not
     * match the setting in p (using the default value if the param is not
     * specified in p), then return false.
     *
     * <li>If this object's <code>{target}</code> matches p's <code>{target}</code>, return true.
     *
     * <li>If this object's <code>{target}</code> is "*:*", and p is a client URI, return
     * true.
     *
     * <li>If this object's <code>{target}</code> consists of "*:" followed by a channel
     * identifier, and p is a client URI with a matching channel identifier,
     * return true.
     *
     * <li>If this object's <code>{target}</code> consists of "localhost:*", and p is a
     * server URI, return true.
     *
     * <li>Otherwise return false.
     * </ul>
     *
     * @param p the permission to check against.
     *
     * @return true if the specified permission is implied by this
     * object, false if not.
     */
    public boolean implies(Permission p) { return false; }

    /**
     * Checks two <code>BtsppProtocolPermission</code> objects for equality.
     *
     * @param obj the object we are testing for equality with this object.
     * @returns true if obj is a <code>BtsppProtocolPermission</code> and has the same
     * URI string as this object.
     */
    public boolean equals(Object obj) { return false; }

    /**
     * Returns the hash code value for this object.
     *
     * @return a hash value for this object.
     */
    public int hashCode() { return 0; }

    /**
     * Returns the canonical string representation of the actions, which
     * currently is the empty string "", since there are no actions defined for
     * <code>BtsppProtocolPermission</code>.
     *
     * @return the empty string "".
     */
    public String getActions() { return null; }

    /**
     * Returns a new <code>PermissionCollection</code> for storing
     * <code>BtsppProtocolPermission</code> objects.
     * <p>
     * <code>BtsppProtocolPermission</code> objects must be stored in a manner that allows
     * them to be inserted into the collection in any order, but that also
     * enables the <code>PermissionCollection</code> implies method to be implemented in an
     * efficient (and consistent) manner.
     *
     * @return a new PermissionCollection suitable for storing
     * <code>BtsppProtocolPermission</code> objects.
     */
    public PermissionCollection newPermissionCollection() { return null; }
}

javax.obex.IrdaobexProtocolPermission

package javax.obex;
import javax.microedition.io.GCFPermission;

/**
 * This class represents access rights to connections via the "irdaobex"
 * protocol. An <code>IrdaobexProtocolPermission</code> consists of a URI string
 * but no actions list.
 * <p>
 * The class must be present if the platform has <code>GCFPermission</code>,
 * and must be not present otherwise.
 * <p>
 * The URI string specifies an OBEX over IRDA connection, as described in JSR
 * 82 1.2 section 12.4.3 <em>OBEX Over IrDA</em>, with an additional change to allow wildcard matching:
 * the whole <code>{target}</code> may be replaced by a '*' wildcard character. The
 * semantics of wildcard matching are specified below in the implies method.
 * <p>
 * Examples:
 * </p><table>
 * <tr><td>
 * <code>irdaobex://discover</code>
 * <td>matches any client discover URI, ignoring params
 *
 * <tr><td>
 * <code>irdaobex://discover;ias=MyAppOBEX,OBEX,OBEX:IrXfer</code>
 * <td>matches any client
 * discover URI with that value of the <code>ias</code> param, ignoring other params
 *
 * <tr><td>
 * <code>irdaobex://*</code>
 * <td>matches any client URI, ignoring params
 * 
 * <tr><td>
 * <code>irdaobex://localhost</code>
 * <td>matches any server URI, ignoring params
 * </table>
 */
public final class IrdaobexProtocolPermission extends GCFPermission {

    /**
     * Creates a new <code>IrdaobexProtocolPermission</code> with the specified URI as
     * name. The URI string must conform to the specification given
     * above, and is normalized (per the rules of
     * <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>)
     * to facilitate subsequent comparisons.
     * <p>
     * @param uri the URI string
     * @throws IllegalArgumentException if uri is malformed
     * @throws NullPointerException if uri is null.
     */
    public IrdaobexProtocolPermission(String uri) {}

    /**
     * Checks if this <code>IrdaobexProtocolPermission</code> object "implies" the
     * specified permission.
     * <p>
     * The method acts as if it follows these steps to determine whether
     * this object implies p:
     * <ul>
     * <li>If p is not an instanceof IrdaobexProtocolPermission, return false.
     *
     * <li>If this object has any <code>{params}</code>, and any one of the params does not
     * match the setting in p (using the default value if the param is not
     * specified in p), then return false.
     *
     * <li>If this object's <code>{target}</code> matches p's <code>{target}</code>, ignoring hint bits in
     * either, then return true.
     *
     * <li>If this object's <code>{target}</code> is "*", and p is a client URI, return
     * true.
     *
     * <li>Otherwise return false.
     * </ul>
     *
     * @param p the permission to check against.
     *
     * @return true if the specified permission is implied by this
     * object, false if not.
     */
    public boolean implies(Permission p) { return false; }

    /**
     * Checks two <code>IrdaobexProtocolPermission</code> objects for equality.
     *
     * @param obj the object we are testing for equality with this object.
     * @return true if obj is a <code>IrdaobexProtocolPermission</code> and has the same
     * URI string as this object.
     */
    public boolean equals(Object obj) { return false; }

    /**
     * Returns the hash code value for this object.
     *
     * @returns a hash value for this object.
     */
    public int hashCode() { return 0; }

    /**
     * Returns the canonical string representation of the actions, which
     * currently is the empty string "", since there are no actions defined for
     * IrdaobexProtocolPermission.
     *
     * @return the empty string "".
     */
    public String getActions() { return null; }

    /**
     * Returns a new <code>PermissionCollection</code> for storing
     * <code>IrdaobexProtocolPermission</code> objects.
     * <p>
     * <code>IrdaobexProtocolPermission</code> objects must be stored in a manner that allows
     * them to be inserted into the collection in any order, but that also
     * enables the <code>PermissionCollection</code> implies method to be implemented in an
     * efficient (and consistent) manner.
     *
     * @returns a new <code>PermissionCollection</code> suitable for storing
     * <code>IrdaobexProtocolPermission</code> objects.
     */
    public PermissionCollection newPermissionCollection() { return null; }
}

javax.obex.TcpobexProtocolPermission

package javax.obex;
import javax.microedition.io.GCFPermission;

/**
 * This class represents access rights to connections via the "tcpobex"
 * protocol. A <code>TcpobexProtocolPermission</code> consists of a URI string
 * but no actions list.
 * <p>
 * The class must be present if the platform has <code>GCFPermission</code>,
 * and must be not present otherwise.
 * <p>
 * The URI string specifies an OBEX over TCP connection, as described in JSR 82
 * 1.2 section 12.4.2 <em>OBEX Over TCP/IP</em>, with additional changes to allow wildcard matching:
 * <ul>
 * <li>the IP address part of the {target} may be replaced by a '*' wildcard
 * character;
 *
 * <li>the port number part of the {target} may be specified as '*', or
 * have the form 'M-' or '-N' or 'M-N' (where M and N are port numbers).
 * </ul>
 * The semantics of wildcard matching are specified below in the implies
 * method.
 * <p>
 * Examples:
 * </p><table>
 * <tr><td>
 * <code>tcpobex://132.53.12.154:5005</code>
 * <td>matches that client URI, ignoring params
 *
 * <tr><td>
 * <code>tcpobex://132.53.12.154</code>
 * <td>matches that client URI, with implied or explicit port number 650,
 * ignoring params
 *
 * <tr><td>
 * <code>tcpobex://*</code>
 * <td>matches any client URI with implied or explicit port number 650,
 * ignoring params
 *
 * <tr><td>
 * <code>tcpobex://*:500-999</code>
 * <td>matches any client URI with a port number in the range
 * 500-999, including one with an implied port number of 650, ignoring params
 *
 * <tr><td>
 * <code>tcpobex://*:*</code>
 * <td>matches any client URI ignoring params
 *
 * <tr><td>
 * <code>tcpobex://:5005</code>
 * <td>matches that server URI, ignoring params
 *
 * <tr><td>
 * <code>tcpobex://:*</code>
 * <td>matches any server URI, ignoring params
 * </table>
 */
public final class TcpobexProtocolPermission extends GCFPermission {

    /**
     * Creates a new <code>TcpobexProtocolPermission</code> with the specified URI as
     * name. The URI string must conform to the specification given
     * above, and is normalized to facilitate subsequent comparisons in a way
     * that follows the rules of
     * <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>,
     * plus the additional procedures described in the JSR 139 (CLDC 1.1.1)
     * document <em>URI Normalization</em> (where the implied port number
     * is 650 if none is specified).
     *
     * @param uri the URI string
     * @throws IllegalArgumentException if uri is malformed
     * @throws NullPointerException if uri is null.
     */
    public TcpobexProtocolPermission(String uri) {}

    /**
     * Checks if this <code>TcpobexProtocolPermission</code> object "implies" the
     * specified permission.
     * <p>
     * The method acts as if it follows these steps to determine whether
     * this object implies p:
     * <ul>
     * <li>If p is not an instanceof <code>TcpobexProtocolPermission</code>, return false.
     *
     * <li>If this object has any <code>{params}</code>, and any one of the params does not
     * match the setting in p (using the default value if the param is not
     * specified in p), then return false.
     *
     * <li>If this object's <code>{target}</code> matches p's <code>{target}</code> return true.
     *
     * <li>If this object's port number is a range that does not include
     * p's port number, then return false.
     *
     * <li>If this object's port number is a single port number that does not
     * match p's port number, then return false.
     *
     * <li>If this
     * object's IP address is '*' and p is a client URI, then return true.
     *
     * <li>If this object's IP address matches p's IP address (including the case
     * of neither having an IP address due to being server URIs),
     * then return true.
     *
     * <li>Otherwise return false.
     * </ul>
     *
     * @param p the permission to check against.
     *
     * @return true if the specified permission is implied by this
     * object, false if not.
     */
    public boolean implies(Permission p) { return false; }

    /**
     * Checks two <code>TcpobexProtocolPermission</code> objects for equality.
     *
     * @param obj the object we are testing for equality with this object.
     * @return true if obj is a <code>TcpobexProtocolPermission</code> and has the same
     * URI string as this object.
     */
    public boolean equals(Object obj);

    /**
     * Returns the hash code value for this object.
     *
     * @return a hash value for this object.
     */
    public int hashCode() { return 0; }

    /**
     * Returns the canonical string representation of the actions, which
     * currently is the empty string "", since there are no actions defined for
     * <code>TcpobexProtocolPermission</code>.
     *
     * @return the empty string "".
     */
    public String getActions() { return null; }

    /**
     * Returns a new <code>PermissionCollection</code> for storing
     * <code>TcpobexProtocolPermission</code> objects.
     * <p>
     * <code>TcpobexProtocolPermission</code> objects must be stored in a manner that allows
     * them to be inserted into the collection in any order, but that also
     * enables the <code>PermissionCollection</code> implies method to be implemented in an
     * efficient (and consistent) manner.
     *
     * @return a new <code>PermissionCollection</code> suitable for storing
     * <code>TcpobexProtocolPermission</code> objects.
     */
    public PermissionCollection newPermissionCollection() { return null; }
}