Please note that this documentation is not final and is subject to change.

javax.management.namespace
Class JMXNamespacePermission

java.lang.Object
  java.security.Permission
      javax.management.namespace.JMXNamespacePermission

All Implemented Interfaces:

Serializable, Guard

public class JMXNamespacePermission
extends Permission

A permission controlling access to MBeans located in namespaces. If a security manager has been set using System.setSecurityManager(java.lang.SecurityManager), 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 JMXNamespace class.

As with other Permission objects, a JMXNamespacePermission can represent either a permission that you have or a permission that you need. 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 imply the permission you need.

A JMXNamespacePermission contains four items of information:

• The action.

  For a permission you need, this is one of the actions in the list below. For a permission you have, this is a comma-separated list of those actions, or *, representing all actions.

  The action is returned by getActions().

• The MBean Server name.

  For a permission you need, this is the name of the MBeanServer from which the MBean is accessed.

  For a permission you have, this is either the name of the MBeanServer from which the MBean for which you have this permission is accessed, or a pattern against which that MBean Server name will be matched.
  An mbeanServername pattern can also be empty, or the single character "*", both of which match any MBeanServer name. The string "-" doesn't match any MBeanServer name.

  Example:

     // 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";
   

• The member.

  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.

  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 "*", both of which grant access to any member.

  There is a special case for actions registerMBean and instantiate, where for a permission you need, 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.

• The object name.

  For a permission you need, this is the ObjectName of the MBean you are accessing. It is of the form <namespace>//<mbean name> where <namespace> is the name of the name space for which the permission is checked, and <mbean name> is the name of the MBean within that namespace.
  For operations that do not reference a single MBean, the object name is null. It is never an object name pattern.

  For a permission you have, this is the ObjectName of the MBean or MBeans you can access. It is of the form <namespace>//<mbean name> where <namespace> is the name of the name space for which the permission is checked, and <mbean name> is the name of the MBean within that namespace. Both <namespace> and <mbean name> can be patterns. The object name 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 ** matches any number of sub namespaces recursively, but only if used as a complete namespace path element, as in **//b//c//D:k=v or a//**//c//D:k=v - see ObjectName documentation for more details.

If you have a JMXNamespacePermission, it allows operations only if all four of the items match.

The MBeanServer name, member, and object name can be written together as a single string, which is the name of this permission. The name of the permission is the string returned by getName(). The format of the string is:

<mbean server name>::<member>[<namespace>//<mbean name>]

The <mbean server name> is optional. If omitted, "*" is assumed, and these three permission names are thus equivalent:

*::<member>[<namespace>//<mbean name>]
::<member>[<namespace>//<mbean name>]
<member>[<namespace>//<mbean name>]

The <namespace>//<mbean name> string can be in the form of a traditional ObjectName pattern - meaning that ? will match any single character, and * will match any sequence of characters, except "//" In addition, when included in a namespace path the special path element ** matches any number of sub namespaces recursively. A <namespace>//<mbean name> string of the form **//*:* thus means that the permission is granted for all MBeans in all namespaces, recursively (see below for more details.

Namespace permission checking may be tricky to configure, depending on whether the namespaces crossed to reach the MBean are local or remote.
For instance, let a//b//D:k=v be an MBean exposing an attribute Foo. If namespace a is a plain JMXNamespace pointing to a local MBeanServer in the same JVM, then the permissions you need to get the attribute Foo will be:

    // 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]
 

On the other hand, if namespace a is a JMXRemoteNamespace pointing to an MBeanServer in a remote JVM, then the only permission you need to get the attribute Foo will be:

    // granting permission to access attribute 'Foo' of MBean a//b//D:k=v
    // from 'srv1'
    srv1::Foo[a//b//D:k=v]
 

The namespace b 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.

The <mbean name> is written using the usual syntax for ObjectName. It may contain any legal characters, including ]. It is terminated by a ] character that is the last character in the string.

Below are some examples of permission names:

    // 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[*//*:*]
 

For instance, the first two permissions listed above will let through getAttribute("a//b//D:k=v","Foo"); in all MBeanServers, but will block access to getAttribute("a//b//c//D:k=v","Foo"); in MBeanServers whose name do not start with "myapp.".

Depending on how your namespace hierarchy is defined some of these wildcard permission names can be useful:

    // 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[*//*:*]

 

Note on wildcards: In an object name pattern, a path element of exactly ** corresponds to a meta wildcard that will match any number of sub namespaces. See ObjectName documentation for more details.

If <mbean server name>:: is omitted, then one of member or object name may be omitted. If the object name is omitted, the [] may be too (but does not have to be). It is not legal to omit all items, that is to have a name which is the empty string.

If <mbean server name> is present, it must be followed by the "::" separator - otherwise it will be interpreted as a member name.

One or more of the MBean Server name, member or object name may be the character "-", 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.

The possible actions are these:

• addNotificationListener
• getAttribute
• getClassLoader
• getClassLoaderFor
• getClassLoaderRepository
• getMBeanInfo
• getObjectInstance
• instantiate
• invoke
• isInstanceOf
• queryMBeans
• queryNames
• registerMBean
• removeNotificationListener
• setAttribute
• unregisterMBean

In a comma-separated list of actions, spaces are allowed before and after each action.

Since:

1.7

See Also:

Serialized Form

Constructor and Description

JMXNamespacePermission(String name, String actions)
Create a new JMXNamespacePermission object with the specified target name and actions.

JMXNamespacePermission(String mbeanServerName, String member, ObjectName objectName, String actions)
Create a new JMXNamespacePermission object with the specified target name (namespace name, member, object name) and actions.

JMXNamespacePermission(String mbeanServerName, String member, String actions)
Create a new JMXNamespacePermission object with the specified MBean Server name, member, and actions.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object obj) Checks two JMXNamespacePermission objects for equality.
String	getActions() Returns the "canonical string representation" of the actions.
int	hashCode() Returns the hash code value for this Permission object.
boolean	implies(Permission p) Checks if this JMXNamespacePermission object "implies" the specified permission.

Methods inherited from class java.security.Permission

checkGuard, getName, newPermissionCollection, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JMXNamespacePermission

public JMXNamespacePermission(String name,
                              String actions)

Create a new JMXNamespacePermission object with the specified target name and actions.

The target name is of the form "mbeanServerName::member[objectName]" where each part is optional. This target name must not be empty or null. If objectName is present, it is of the form namespace//MBeanName.

For a permission you need, mbeanServerName is the name of the MBeanServer from which objectName is being accessed.

For a permission you have, mbeanServerName is the name of the MBeanServer from which access to objectName is granted. It can also be a pattern, and if omitted, "*" is assumed, meaning that access to objectName is granted in all MBean servers in the JVM.

The actions parameter contains a comma-separated list of the desired actions granted on the target name. It must not be empty or null.

Parameters:

name - the triplet "mbeanServerName::member[objectName]". If objectName is present, it is of the form namespace//MBeanName.

actions - the action string.

Throws:

IllegalArgumentException - if the name or actions is invalid.

JMXNamespacePermission

public JMXNamespacePermission(String mbeanServerName,
                              String member,
                              ObjectName objectName,
                              String actions)

Create a new JMXNamespacePermission object with the specified target name (namespace name, member, object name) and actions.

The MBeanServer name, member and object name parameters define a target name of the form "mbeanServerName::member[objectName]" where each part is optional. This will be the result of Permission.getName() on the resultant JMXNamespacePermission. If the mbeanServerName is empty or exactly "*", then "mbeanServerName::" is omitted in that result.

The actions parameter contains a comma-separated list of the desired actions granted on the target name. It must not be empty or null.

Parameters:

mbeanServerName - the name of the MBeanServer to which this permission applies. May be null or "-", which represents an MBeanServer name that is implied by any MBeanServer name but does not imply any other MBeanServer name.

member - the member to which this permission applies. May be null or "-", which represents a member that is implied by any member but does not imply any other member.

objectName - the object name to which this permission applies. May be null, which represents an object name that is implied by any object name but does not imply any other object name. If not null, the objectName must be of the form <namespace>//<mbean name> - where <namespace> can be a domain pattern, and <mbean name> can be an ObjectName pattern. For a permission you need, <namespace> is the name of the name space for which the permission is checked, and <mbean name> is the name of the MBean in that namespace. The composed name <namespace>//<mbean name> thus represents the name of the MBean as seen by the mbeanServerName containing <namespace>.

actions - the action string.

JMXNamespacePermission

public JMXNamespacePermission(String mbeanServerName,
                              String member,
                              String actions)

Create a new JMXNamespacePermission object with the specified MBean Server name, member, and actions.

The MBeanServer name and member parameters define a target name of the form "mbeanServerName::member[]" where each part is optional. This will be the result of Permission.getName() on the resultant JMXNamespacePermission. If the mbeanServerName is empty or exactly "*", then "mbeanServerName::" is omitted in that result.

The actions parameter contains a comma-separated list of the desired actions granted on the target name. It must not be empty or null.

Parameters:

mbeanServerName - the name of the MBeanServer to which this permission applies. May be null or "-", which represents an MBeanServer name that is implied by any MBeanServer name but does not imply any other MBeanServer name.

member - the member to which this permission applies. May be null or "-", which represents a member that is implied by any member but does not imply any other member.

actions - the action string.

Method Detail

getActions

public String getActions()

Returns the "canonical string representation" of the actions. That is, this method always returns actions in alphabetical order.

Specified by:

getActions in class Permission

Returns:

the canonical string representation of the actions.

hashCode

public int hashCode()

Description copied from class: Permission

Returns the hash code value for this Permission object.

The required hashCode behavior for Permission Objects is the following:

• Whenever it is invoked on the same Permission object more than once during an execution of a Java application, the hashCode method must consistently return the same integer. This integer need not remain consistent from one execution of an application to another execution of the same application.

• If two Permission objects are equal according to the equals method, then calling the hashCode method on each of the two Permission objects must produce the same integer result.

Specified by:

hashCode in class Permission

Returns:

a hash code value for this object.

See Also:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

implies

public boolean implies(Permission p)

Checks if this JMXNamespacePermission object "implies" the specified permission.

More specifically, this method returns true if:

• p is an instance of JMXNamespacePermission; and
• p has a null mbeanServerName or p's mbeanServerName matches this object's mbeanServerName; and
• p has a null member or p's member matches this object's member; and
• p has a null object name or p's object name matches this object's object name; and
• p's actions are a subset of this object's actions

If this object's mbeanServerName is a pattern, then p's mbeanServerName is matched against that pattern. An empty mbeanServerName is equivalent to "*". A null mbeanServerName is equivalent to "-".

If this object's mbeanServerName is "*" or is empty, p's mbeanServerName always matches it.

If this object's member is "*", p's member always matches it.

If this object's objectName n1 is an object name pattern, p's objectName n2 matches it if n1.equals(n2) or if n1.apply(n2).

A permission that includes the queryMBeans action is considered to include queryNames as well.

Specified by:

implies in class Permission

Parameters:

p - the permission to check against.

Returns:

true if the specified permission is implied by this object, false if not.

equals

public boolean equals(Object obj)

Checks two JMXNamespacePermission objects for equality. Checks that obj is an JMXNamespacePermission, and has the same name and actions as this object.

Specified by:

equals in class Permission

Parameters:

obj - the object we are testing for equality with this object.

Returns:

true if obj is an JMXNamespacePermission, and has the same name and actions as this JMXNamespacePermission object.

See Also:

Object.hashCode(), HashMap