/*

 * Copyright 2002-2008 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package javax.management.namespace;

import javax.management.*;

import com.sun.jmx.mbeanserver.Util;

import java.io.IOException;

import java.io.ObjectInputStream;

import java.security.Permission;

/**

 * <p>A permission controlling access to MBeans located in namespaces.

 * If a security manager has been set using {@link

 * System#setSecurityManager}, most operations on an MBean mounted in a

 * namespace require that the caller's permissions imply a

 * JMXNamespacePermission appropriate for the operation.

 * This is described in detail in the

 * documentation for the

 * <a href="JMXNamespace.html#PermissionChecks">JMXNamespace</a>

 * class.</p>

 *

 * <p>As with other {@link Permission} objects,

 * a JMXNamespacePermission can represent either a permission that

 * you <em>have</em> or a permission that you <em>need</em>.

 * When a sensitive operation is being checked for permission,

 * a JMXNamespacePermission is constructed

 * representing the permission you need.  The operation is only

 * allowed if the permissions you have {@linkplain #implies imply} the

 * permission you need.</p>

 *

 * <p>A JMXNamespacePermission contains four items of information:</p>

 *

 * <ul>

 *

 * <li id="Action"><p>The <em>action</em>.</p>

 * <p>For a permission you need,

 * this is one of the actions in the list <a

 * href="#action-list">below</a>.  For a permission you have, this is

 * a comma-separated list of those actions, or <code>*</code>,

 * representing all actions.</p>

 *

 * <p>The action is returned by {@link #getActions()}.</p>

 *

 * <li id="MBeanServerName"><p>The <em>MBean Server name</em>.</p>

 *

 * <p>For a permission you need, this is the {@linkplain

 * javax.management.MBeanServerFactory#getMBeanServerName

 * name of the MBeanServer}

 * from which the <a href="#MBeanName">MBean</a> is accessed.</p>

 *

 * <p>For a permission you have, this is either the  {@linkplain

 * javax.management.MBeanServerFactory#getMBeanServerName

 * name of the MBeanServer} from which the <a href="#MBeanName">MBean</a>

 * for which you have this permission is accessed,

 * or a pattern against which that MBean Server name will be matched.<br>

 * An {@code mbeanServername} pattern can also be empty, or the single

 * character {@code "*"}, both of which match any {@code MBeanServer} name.

 * The string {@code "-"} doesn't match any MBeanServer name.

 * </p>

 *

 * <p>Example:</p>

 * <pre>

 *   // grant permission to invoke the operation "stop" on any MBean

 *   // whose name matches "a//**//*:type=JMXConnectorServer" when

 *   // accessed from any MBeanServer whose name matches myapp.*"

 *   permission javax.management.namespace.JMXNamespacePermission "myapp.*::stop[a//**//*:type=JMXConnectorServer]", "invoke";

 * </pre>

 *

 * <li id="Member"><p>The <em>member</em>.</p>

 *

 * <p>For a permission you need, this is the name of the attribute or

 * operation you are accessing.  For operations that do not reference

 * an attribute or operation, the member is null.</p>

 *

 * <p>For a permission you have, this is either the name of an attribute

 * or operation you can access, or it is empty or the single character

 * "<code>*</code>", both of which grant access to any member.</p>

 *

 * <p>There is a special case for actions {@code registerMBean} and

 *    {@code instantiate}, where for a permission you need, {@code member}

 *    indicates the name of the class for which you are trying

 *    to create, instantiate, or register an MBean instance. For a

 *    permission you have, it is a pattern that will be matched against

 *    the full class name of the MBean being created, instantiated, or

 *    registered.

 * </p>

 *

 *

 * <li id="MBeanName"><p>The <em>object name</em>.</p>

 *

 * <p>For a permission you need, this is the {@link ObjectName} of the

 * MBean you are accessing. It is of the form {@code <namespace>//<mbean name>}

 * where {@code <namespace>} is the name of the name space for which the

 * permission is checked, and {@code <mbean name>} is the name of the MBean

 * within that namespace.

 * <br>

 * For operations that do not reference a

 * single MBean, the <em>object name</em> is null.  It is never an object

 * name pattern.

 * </p>

 *

 * <p>For a permission you have, this is the {@link ObjectName} of the

 * MBean or MBeans you can access. It is of the form

 * {@code <namespace>//<mbean name>}

 * where {@code <namespace>} is the name of the name space for which the

 * permission is checked, and

 * {@code <mbean name>} is the name of the MBean

 * within that namespace. Both {@code <namespace>} and {@code <mbean name>}

 * can be patterns. The <em>object name</em>

 * may also be empty, which grants access to all MBeans whatever their

 * name and namespace.

 * When included in a namespace path the special path element

 * <code>**</code> matches any number of sub namespaces

 * recursively, but only if used as a complete namespace path element,

 * as in <code>*&#42;//b//c//D:k=v</code> or <code>a//*&#42;//c//D:k=v</code>

 * - see <a href="#metawildcard">below</a>.

 * </p>

 *

 *

 * </ul>

 *

 * <p>If you have a JMXNamespacePermission, it allows operations only

 * if all four of the items match.</p>

 *

 * <p>The <a href="#MBeanServerName">MBeanServer name</a>,

 * <a href="#Member">member</a>, and <a href="#MBeanName">object name</a>

 * can be written together

 * as a single string, which is the <em>name</em> of this permission.

 * The name of the permission is the string returned by {@link

 * java.security.Permission#getName() getName()}.

 * The format of the string is:</p>

 *

 * <blockquote>

 * {@code <mbean server name>::<member>[<namespace>//<mbean name>]}

 * </blockquote>

 *

 * <p>

 * The {@code <mbean server name>} is optional. If omitted, {@code "*"} is

 * assumed, and these three permission names

 * are thus equivalent:

 * </p>

 * <blockquote>

 * {@code *::<member>[<namespace>//<mbean name>]}<br>

 * {@code ::<member>[<namespace>//<mbean name>]}<br>

 * {@code <member>[<namespace>//<mbean name>]}<br>

 * </blockquote>

 * <p>

 *    The {@code <namespace>//<mbean name>} string can be in the form

 *    of a traditional ObjectName

 *    pattern - meaning that <code>?</code> will match any single

 *    character, and <code>*</code> will match any sequence of characters,

 *    except {@value

 *    javax.management.namespace.JMXNamespaces#NAMESPACE_SEPARATOR}

 *    In addition, when included in a namespace path the special

 *    path element <code>**</code> matches any number of sub namespaces

 *    recursively.

 *    A {@code <namespace>//<mbean name>} string of the form

 *    <code>*&#42;//*:*</code> thus means that the permission is

 *    granted for all MBeans in all namespaces, recursively (see

 *    <a href="#metawildcard">below</a> for more details.

 * </p>

 * <p>Namespace permission checking may be tricky to configure, depending

 *    on whether the namespaces crossed to reach the MBean are local or

 *    remote.<br>

 *    For instance, let <code>a//b//D:k=v</code> be an MBean exposing an

 *    attribute <code>Foo</code>.

 *    If namespace <code>a</code> is a plain JMXNamespace pointing to

 *    a local MBeanServer in the same JVM, then the permissions you need

 *    to get the attribute <code>Foo</code> will be:

 * </p>

 * <pre>

 *    // granting permission to access attribute 'Foo' of MBean a//b//D:k=v

 *    // from MBeanServer named 'srv1'

 *    // This permission will be checked by the MBeanServer that contains 'a'.

 *    srv1::Foo[a//b//D:k=v]

 *

 *    // Since a is local, you also need the following additional permission,

 *    // which will be checked by the MBeanServer 'srv2' that contains 'b':

 *    //

 *    // granting permission to access attribute 'Foo' of MBean b//D:k=v from

 *    // 'srv2'

 *    srv2::Foo[b//D:k=v]

 * </pre>

 * <p>On the other hand, if namespace <code>a</code> is a JMXRemoteNamespace

 *    pointing to an MBeanServer in a remote JVM, then the only permission you

 *    need to get the attribute <code>Foo</code> will be:

 * </p>

 * <pre>

 *    // granting permission to access attribute 'Foo' of MBean a//b//D:k=v

 *    // from 'srv1'

 *    srv1::Foo[a//b//D:k=v]

 * </pre>

 * <p>The namespace <code>b</code> resides in the remote JVM, and

 *    therefore the permissions concerning access to MBeans from

 *    namespace 'b' will only be checked in the remote JVM, if that JVM is

 *    configured to do so.

 * </p>

 *

 * <p>The {@code <mbean name>} is written using the usual syntax for {@link

 * ObjectName}.  It may contain any legal characters, including

 * <code>]</code>.  It is terminated by a <code>]</code> character

 * that is the last character in the string.

 * </p>

 * <p>Below are some examples of permission names:</p>

 * <pre>

 *    // allows access to Foo in 'a//b//*:*' from any MBeanServer in the JVM.

 *    Foo[a//b//*:*]

 *

 *    // allows access to Foo in all subnamespaces of 'a//b', but only for

 *    // MBeanServers whose name matches 'myapp.*'

 *    myapp.*::Foo[a//b//**//*:*]

 *

 *    // allows access to Foo from all namespaces in the MBeanServer named

 *    // 'myapp.srv1' - but not recursively.

 *    myapp.srv1::Foo[*//*:*]

 * </pre>

 * <p>For instance, the first two permissions listed above

 *    will let through {@code getAttribute("a//b//D:k=v","Foo");} in

 *    all MBeanServers, but will block access to

 *    {@code getAttribute("a//b//c//D:k=v","Foo");} in MBeanServers whose

 *    name do not start with {@code "myapp."}.

 * </p>

 * <p><a name="metawildcard">Depending on how your namespace hierarchy

 *    is defined some of these wildcard permission names can be useful</a>:</p>

 * <pre>

 *    // allows access to Foo in all namespaces, recursively.

 *    //

 *    *::Foo[**//*:*]

 *

 *    // This permission name is the equivalent to the permission names above:

 *    // Foo[**//*:*] and Foo[] are equivalent.

 *    //

 *    Foo[]

 *

 *    // This permission name is the equivalent to the two permission names

 *    // above:

 *    // Foo[**//*:*], Foo[], Foo are equivalent.

 *    //

 *    Foo

 *

 *    // allows access to Foo from all namespaces - but not recursively.

 *    // This wildcard permission complements the previous one: it allows

 *    // access to 'Foo' from an MBean directly registered in any local namespace.

 *    //

 *    Foo[*//*:*]

 *

 * </pre>

 * <p><b>Note on wildcards:</b> In an object name pattern, a path element

 *    of exactly <code>**</code> corresponds to a meta

 *    wildcard that will match any number of sub namespaces. Hence:</p>

 * <ul>

 * <table border="1">

 * <thead><th>pattern</th><th>matches</th><th>doesn't match</th></thead>

 * <tbody>

 * <tr><td><code>*&#42;//D:k=v</code></td>

 *     <td><code>a//D:k=v</code><br>

 *         <code>a//b//D:k=v</code><br>

 *         <code>a//b//c//D:k=v</code></td>

 *     <td><code>D:k=v</code></td></tr>

 * <tr><td><code>a//*&#42;//D:k=v</code></td>

 *     <td><code>a//b//D:k=v</code><br>

 *         <code>a//b//c//D:k=v</code></td>

 *     <td><code>b//b//c//D:k=v</code><br>

 *         <code>a//D:k=v</code><br>

 *         <code>D:k=v</code></td></tr>

 * <tr><td><code>a//*&#42;//e//D:k=v</code></td>

 *     <td><code>a//b//e//D:k=v</code><br>

 *         <code>a//b//c//e//D:k=v</code></td>

 *     <td><code>a//b//c//c//D:k=v</code><br>

 *         <code>b//b//c//e//D:k=v</code><br>

 *         <code>a//e//D:k=v</code><br>

 *         <code>e//D:k=v</code></td></tr>

 * <tr><td><code>a//b*&#42;//e//D:k=v</code></td>

 *      <td><code>a//b//e//D:k=v</code></td>

 *      <td><code>a//b//c//e//D:k=v</code><br>

 *          because in that case <code>b*&#42;</code><br>

 *         is not a meta-wildcard - and <code>b**</code><br>

 *         is thus equivalent to <code>b*</code>.</td></tr>

 * </tbody>

 * </table>

 *</ul>

 *

 * <p>If {@code <mbean server name>::} is omitted, then one of

 * <code>member</code> or <code>object name</code> may be omitted.

 * If the <code>object name</code> is omitted,

 * the <code>[]</code> may be too (but does not have to be).  It is

 * not legal to omit all items, that is to have a <em>name</em>

 * which is the empty string.</p>

 * <p>If {@code <mbean server name>} is present, it <b>must be followed</b> by

 *    the {@code "::"} separator - otherwise it will be interpreted as

 *    a {@code member name}.

 * </p>

 *

 * <p>

 * One or more of the <a href="#MBeanServerName">MBean Server name</a>,

 * <a href="#Member">member</a>

 * or <a href="#MBeanName">object name</a> may be the character "<code>-</code>",

 * which is equivalent to a null value.  A null value is implied by

 * any value (including another null value) but does not imply any

 * other value.

 * </p>

 *

 * <p><a name="action-list">The possible actions are these:</a></p>

 *

 * <ul>

 * <li>addNotificationListener</li>

 * <li>getAttribute</li>

 * <li>getClassLoader</li>

 * <li>getClassLoaderFor</li>

 * <li>getClassLoaderRepository</li>

 * <li>getMBeanInfo</li>

 * <li>getObjectInstance</li>

 * <li>instantiate</li>

 * <li>invoke</li>

 * <li>isInstanceOf</li>

 * <li>queryMBeans</li>

 * <li>queryNames</li>

 * <li>registerMBean</li>

 * <li>removeNotificationListener</li>

 * <li>setAttribute</li>

 * <li>unregisterMBean</li>

 * </ul>

 *

 * <p>In a comma-separated list of actions, spaces are allowed before

 * and after each action.</p>

 *

 * @since 1.7

 */

public class JMXNamespacePermission extends Permission {

    private static final long serialVersionUID = -2416928705275160661L;

    private static final String WILDPATH = "**" +

                JMXNamespaces.NAMESPACE_SEPARATOR + "*";

    /**

     * Actions list.

     */

    private static final int AddNotificationListener    = 0x00001;

    private static final int GetAttribute               = 0x00002;

    private static final int GetClassLoader             = 0x00004;

    private static final int GetClassLoaderFor          = 0x00008;

    private static final int GetClassLoaderRepository   = 0x00010;

    // No GetDomains because it is not possible to route a call to

    // getDomains() on a NamespaceInterceptor - getDomains() doesn't

    // have any ObjectName.

    // private static final int GetDomains                 = 0x00020;

    private static final int GetMBeanInfo               = 0x00040;

    private static final int GetObjectInstance          = 0x00080;

    private static final int Instantiate                = 0x00100;

    private static final int Invoke                     = 0x00200;

    private static final int IsInstanceOf               = 0x00400;

    private static final int QueryMBeans                = 0x00800;

    private static final int QueryNames                 = 0x01000;

    private static final int RegisterMBean              = 0x02000;

    private static final int RemoveNotificationListener = 0x04000;

    private static final int SetAttribute               = 0x08000;

    private static final int UnregisterMBean            = 0x10000;

    /**

     * No actions.

     */

    private static final int NONE = 0x00000;

    /**

     * All actions.

     */

    // No GetDomains because it is not possible to route a call to

    // getDomains() on a NamespaceInterceptor - getDomains() doesn't

    // have any ObjectName.

    //

    private static final int ALL =

        AddNotificationListener    |

        GetAttribute               |

        GetClassLoader             |

        GetClassLoaderFor          |

        GetClassLoaderRepository   |

        GetMBeanInfo               |

        GetObjectInstance          |

        Instantiate                |

        Invoke                     |

        IsInstanceOf               |

        QueryMBeans                |

        QueryNames                 |

        RegisterMBean              |

        RemoveNotificationListener |

        SetAttribute               |

        UnregisterMBean;

    /**

     * The actions string.

     */

    private String actions;

    /**

     * The actions mask.

     */

    private transient int mask;

    /**

     * The name of the MBeanServer in which this permission is checked, or

     * granted.  If null, is implied by any MBean server name

     * but does not imply any non-null MBean server name.

     */

    private transient String mbeanServerName;

    /**

     * The member that must match.  If null, is implied by any member

     * but does not imply any non-null member.

     */

    private transient String member;

    /**

     * The objectName that must match.  If null, is implied by any

     * objectName but does not imply any non-null objectName.

     */

    private transient ObjectName objectName;

    /**

     * If objectName is missing from name, then allnames will be

     * set to true.

     */

    private transient boolean  allnames = false;

    /**

     * Parse <code>actions</code> parameter.

     */

    private void parseActions() {

        int amask;

        if (actions == null)

            throw new IllegalArgumentException("JMXNamespaceAccessPermission: " +

                                               "actions can't be null");

        if (actions.equals(""))

            throw new IllegalArgumentException("JMXNamespaceAccessPermission: " +

                                               "actions can't be empty");

        amask = getMask(actions);

        if ((amask & ALL) != amask)

            throw new IllegalArgumentException("Invalid actions mask");

        if (amask == NONE)

            throw new IllegalArgumentException("Invalid actions mask");

        this.mask = amask;

    }

    /**

     * Parse <code>name</code> parameter.

     */

    private void parseName() {

        String name = getName();

        if (name == null)

            throw new IllegalArgumentException("JMXNamespaceAccessPermission name " +

                                               "cannot be null");

        if (name.equals(""))

            throw new IllegalArgumentException("JMXNamespaceAccessPermission name " +

                                               "cannot be empty");

        final int sepIndex = name.indexOf("::");

        if (sepIndex < 0) {

            setMBeanServerName("*");

        } else {

            setMBeanServerName(name.substring(0,sepIndex));

        }

        /* The name looks like "mbeanServerName::member[objectname]".

           We subtract elements from the right as we parse, so after

           parsing the objectname we have "class#member" and after parsing the

           member we have "class".  Each element is optional.  */

        // Parse ObjectName

        final int start = (sepIndex<0)?0:sepIndex+2;

        int openingBracket = name.indexOf("[",start);

        if (openingBracket == -1) {

            // If "[on]" missing then ObjectName("*:*")

            //

            objectName = null;

            allnames = true;

            openingBracket=name.length();

        } else {

            if (!name.endsWith("]")) {

                throw new IllegalArgumentException("JMXNamespaceAccessPermission: " +

                                                   "The ObjectName in the " +

                                                   "target name must be " +

                                                   "included in square " +

                                                   "brackets");

            } else {

                // Create ObjectName

                //

                String on = name.substring(openingBracket + 1,

                                           name.length() - 1);

                try {

                    // If "[]" then allnames are implied

                    //

                    final ObjectName target;

                    final boolean    all;

                    if (on.equals("")) {

                        target = null;

                        all = true;

                    } else if (on.equals("-")) {

                        target = null;

                        all = false;

                    } else {