001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package javax.jbi.management;
018    
019    import javax.management.ObjectName;
020    
021    /**
022     * The installation service MBean allows administrative tools to manage
023     * component and shared library installations.  The tasks supported are:
024     * <ul>
025     *   <li>Installing (and uninstalling) a shared library</li>
026     *   <li>Creating (loading) and destroying (unloading) a component installer
027     *       MBean.</li>
028     *   <li>Finding an existing component installer MBean.
029     * </ul>
030     *
031     * Installing and uninstalling components is accomplished using
032     * {@link InstallerMBean}s, loaded by this MBean.  An individual installer MBean
033     * is needed for each component installation / uninstallation.  This is to support
034     * the more complex installation process that some components require.
035     *
036     * @author JSR208 Expert Group
037     */
038    public interface InstallationServiceMBean {
039    
040        /**
041         * Load the installer for a new component for the given component
042         * installation package.
043         *
044         * @param installZipURL URL locating a ZIP file containing the
045         *        JBI Installation package to be installed; must be non-null,
046         *        non-empty, and a legal URL
047         * @return the JMX ObjectName of the InstallerMBean loaded from
048         *         installZipURL; must be non-null
049         */
050        ObjectName loadNewInstaller(String installZipURL);
051    
052        /**
053         * Load the InstallerMBean for a previously installed component.
054         * <p>
055         * The "component name" refers to the
056         * <code>&lt;identification>&lt;name></code> element value from the
057         * component's installation package (see {@link #loadNewInstaller(String)}).
058         *
059         * @param aComponentName the component name identifying the installer to 
060         *        load; must be non-null and non-empty
061         * @return the JMX ObjectName of the InstallerMBean loaded from an existing
062         *         installation context; <code>null</code> if the installer MBean
063         *         doesn't exist
064         */
065        ObjectName loadInstaller(String aComponentName);
066    
067        /**
068         * Unload an InstallerMBean previously loaded for a component.
069         *
070         * @param aComponentName the component name identifying the installer to 
071         *        unload; must be non-null and non-empty
072         * @param isToBeDeleted <code>true</code> if the component is to be deleted
073         *        as well
074         * @return true if the operation was successful, otherwise false
075         */
076        boolean unloadInstaller(String aComponentName, boolean isToBeDeleted);
077    
078        /**
079         * Install a shared library installation package.
080         * <p>
081         * The return value is the unique name for the shared-library, as found
082         * in the the value of the installation descriptor's
083         * <code>&lt;identification>&lt;name></code> element.
084         *
085         * @param aSharedLibURI URL locating a zip file containing a shared library
086         *        installation package; must be non-null, non-empty, and a legal
087         *        URL
088         * @return the unique name of the shared library loaded from slZipURL; must
089         *         be non-null and non-empty
090         */
091        String installSharedLibrary(String aSharedLibURI);
092    
093        /**
094         * Uninstall a previously installed shared library.
095         *
096         * @param aSharedLibName the name of the shared name space to uninstall; must be
097         *        non-null and non-empty
098         * @return true if the uninstall was successful
099         */
100        boolean uninstallSharedLibrary(String aSharedLibName);
101    }