1 /*

     2  * Copyright 2008 Sun Microsystems, Inc.  All Rights Reserved.

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

     4  *

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

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

     7  * published by the Free Software Foundation.  Sun designates this

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

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

    10  *

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

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

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

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

    15  * accompanied this code).

    16  *

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

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

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

    20  *

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

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

    23  * have any questions.

    24  */

    25 

    26 import java.io.IOException;

    27 import java.util.Map;

    28 

    29 import javax.management.ObjectName;

    30 import javax.management.remote.JMXServiceURL;

    31 

    32 /**

    33  * The {@link NamespaceController} MBean makes it possible to easily

    34  * create mount points ({@link JMXNamespace JMXNamespaces}) in an

    35  * {@code MBeanServer}.

    36  */

    37 // This API was originally in the draft of javax/management/namespaces

    38 // but we decided to retire it. Rather than removing all the associated

    39 // tests I have moved the API to the test hierarchy - so it is now used as

    40 // an additional (though somewhat complex) test case...

    41 //

    42 public interface NamespaceControllerMBean {

    43     /**

    44      * Mount MBeans from the source path of the source URL into the specified

    45      * target path of the target.

    46      * @param url URL of the mounted source.

    47      * @param targetPath Target path in which MBeans will be mounted.

    48      * @param optionsMap connection map and options. See {@link

    49      *      javax.management.namespace.JMXRemoteNamespace.Options

    50      *      JMXRemoteNamespace.Options}

    51      * @throws IOException Connection with the source failed

    52      * @throws IllegalArgumentException Supplied parameters are

    53      *         illegal, or combination of supplied parameters is illegal.

    54      * @return A mount point id.

    55      */

    56     public String mount(JMXServiceURL url,

    57             String targetPath,

    58             Map<String,Object> optionsMap)

    59             throws IOException, IllegalArgumentException;

    60 

    61     /**

    62      * Mount MBeans from the source path of the source URL into the specified

    63      * target path of the target.

    64      * @param url URL of the mounted source.

    65      * @param targetPath Target path in which MBeans will be mounted.

    66      * @param sourcePath source namespace path.

    67      * @param optionsMap connection map and options. See {@link

    68      *      javax.management.namespace.JMXRemoteNamespace.Options

    69      *      JMXRemoteNamespace.Options}

    70      * @throws IOException Connection with the source failed

    71      * @throws IllegalArgumentException Supplied parameters are

    72      *         illegal, or combination of supplied parameters is illegal.

    73      * @return A mount point id.

    74      */

    75     public String mount(JMXServiceURL url,

    76             String targetPath,

    77             String sourcePath,

    78             Map<String,Object> optionsMap)

    79             throws IOException, IllegalArgumentException;

    80 

    81     /**

    82      * Unmount a previously mounted mount point.

    83      * @param mountPointId A mount point id, as previously returned

    84      *        by mount.

    85      * @throws IllegalArgumentException Supplied parameters are

    86      *         illegal, or combination of supplied parameters is illegal.

    87      * @throws IOException thrown if the mount point {@link JMXNamespace}

    88      *         couldn't be unregistered.

    89      */

    90     public boolean unmount(String mountPointId)

    91         throws IOException, IllegalArgumentException;

    92 

    93     /**

    94      * Tells whether there already exists a {@link JMXNamespace} for

    95      * the given <var>targetPath</var>.

    96      * @param targetPath a target name space path.

    97      * @return true if a {@link JMXNamespace} is registered for that

    98      *         name space path.

    99      **/

   100     public boolean ismounted(String targetPath);

   101 

   102     /**

   103      * Returns the handler name for the provided target name space

   104      * path. Can throw IllegalArgumentException if the provided

   105      * targetPath contains invalid characters (like e.g. ':').

   106      * @param targetPath A target name space path.

   107      * @return the handler name for the provided target name space

   108      * path.

   109      **/

   110     public ObjectName getHandlerNameFor(String targetPath);

   111 

   112     /**

   113      * Return a sorted array of locally mounted name spaces.

   114      * This is equivalent to calling {@link

   115      * #findNamespaces(java.lang.String,java.lang.String,int)

   116      *  findNamespaces(null,null,0)};

   117      * @return a sorted array of locally mounted name spaces.

   118      **/

   119     public String[] findNamespaces();

   120 

   121     /**

   122      * Return a sorted array of mounted name spaces, starting at

   123      * <var>from</var> (if non null), and recursively searching up to

   124      * provided <var>depth</var>.

   125      * @param from A name spaces from which to start the search. If null,

   126      *        will start searching from the MBeanServer root.

   127      *        If not null, all returned names will start with <var>from//</var>.

   128      * @param regex A regular expression that the returned names must match.

   129      *        If null - no matching is performed and all found names are

   130      *        returned. If not null, then all returned names satisfy

   131      *        {@link String#matches name.matches(regex)};

   132      * @param depth the maximum number of levels that the search algorithm

   133      *        will cross. 0 includes only top level name spaces, 1 top level

   134      *        and first level children etc... <var>depth</var> is evaluated

   135      *        with regard to where the search starts - if a non null

   136      *        <var>from</var> parameter is provided - then {@code depth=0}

   137      *        corresponds to all name spaces found right below

   138      *        <var>from//</var>.

   139      * @return A sorted array of name spaces matching the provided criteria.

   140      *         All returned names end with "//".

   141      **/

   142     public String[] findNamespaces(String from, String regex, int depth);

   143 }