/*

* Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:

*

*/

package javax.microedition.io;

import java.security.Permission;

import java.security.PermissionCollection;

/**

 * This class represents access rights to connections via the "comm" protocol.

 * A CommProtocolPermission consists of a URI string but no actions list.

 * <p>

 * The URI string specifies a logical serial port connection and optional

 * parameters. It takes the following general form:

 * <p>

 * <code>comm:{port identifier}[{optional parameters}]</code>

 * <p>

 * The detailed syntax for the <code>CommProtocolPermission</code> URI is

 * provided by this BNF. In addition, an asterisk may terminate the URI

 * string within the <code>{port identifier}</code> field to indicate a

 * wildcard * match of 0 or more characters. Valid examples include

 * "comm:*" and "comm:port*".

 *

 * @see Connector.open(java.lang.String)

 * @see "javax.microedition.io.CommConnection" in MIDP 3.0 Specification

 *

 * @author Nokia Corporation

 * @version 1.0

 */

public final class CommProtocolPermission

        extends GCFPermission

{

    /**

     * Creates a new <code>CommProtocolPermission</code> with the specified URI

     * as its name. The URI string must conform to the specification given above,

     * and is normalized to facilitate subsequent comparisons.

     *

     * @param uri the URI string

     * @throws IllegalArgumentException - if uri is malformed.

     * @throws NullPointerException - if uri is null.

     */

    public CommProtocolPermission(String uri)

    {

        super(uri);

    }

    /**

     * Checks if this CommProtocolPermission object "implies" the specified

     * permission.

     * <p>

     * More specifically, this method returns true if:

     * <ul>

     * <li>p is an instanceof CommProtocolPermission</li>

     * <li>p's {port identifier} string equals or is implied by this object's

     * {port identifier} string. For example:<li>"comm:port*" implies

     * "comm:port1"</li>

     * <li>"comm:port1" implies "comm:port2" if both port identifiers are

     * mapped to the same logical port.</li></li>

     * <li>for each of the parameters permitted in the {optional parameters}

     * string, either:<li>the parameter value for this object and for p are

     * identical, or</li><li>this object does not define a value for the

     * parameter.</li><p>For example:<li>"comm:port1;baudrate=300;autorts=on"

     * implies "comm:port1;autorts=on;baudrate=300"</li><li>"comm:port*"

     * implies "comm:port1;baudrate=300"</li></li>

     * </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)

    {

        if (p instanceof CommProtocolPermission)

        {

            return true;

        }

        return false;

    }

    /**

     * Checks two CommProtocolPermission objects for equality. Checks that

     * obj is a PropertyPermission, and has the same name and actions as

     * this object.

     *

     * @param obj the object we are testing for equality with this object.

     * @return true if obj is a CommProtocolPermission and has the same URI

     *         string as this CommProtocolPermission object.

     */

    public boolean equals(Object obj)

    {

        return true;

    }

    /**

     * Returns the hash code value for this object

     *

     * @return a hash code 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

     * CommProtocolPermission.

     *

     * @return the empty string "".

     */

    public String getActions()

    {

        return "";

    }

    /**

     * Returns a new PermissionCollection for storing CommProtocolPermission

     * objects.

     * <p>

     * CommProtocolPermission objects must be stored in a manner that allows

     * them to be inserted into the collection in any order, but that also

     * enables the PermissionCollection implies method to be implemented in

     * an efficient (and consistent) manner.

     *

     * @return a new PermissionCollection suitable for storing

     *         CommProtocolPermission objects.

     */

    public PermissionCollection newPermissionCollection()

    {

        return null;

    }

}