/*
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.aries.subsystem;

import java.io.InputStream;
import java.util.Collection;
import java.util.Map;

import org.osgi.framework.Version;

/**
 * Subsystems administration interface.
 *
 * A service implementing this interface will be registered in the OSGi registry.
 *
 * Install / update / uninstall operations will be performed sequentially, i.e.
 * they will be synchronized so that no two operations will be performed at the
 * same time.
 *
 * This service will also be made available from managed subsystems, so that only subsystems
 * from the current framework will be available, not nested frameworks.
 *
 */
public interface SubsystemAdmin {

    /**
     * Retrieve all subsystems managed by this service.
     * This includes all the top-level subsystems installed in the composite
     * which this service has been retrieved from.
     *
     * @return
     */
    Collection<Subsystem> getSubsystems();

    /**
     * Retrieve a subsystem given its id.
     *
     * @param id
     * @return
     */
    Subsystem getSubsystem(long id);

    /**
     * Retrieve a subsystem given its symbolic name and id
     *
     * @param symbolicName
     * @param version
     * @return
     */
    Subsystem getSubsystem(String symbolicName, Version version);

    /**
     * Install a new subsystem from the specified location identifier.
     * 
     * This method performs the same function as calling <code>install(String, InputStream)</code> with the specified 
     * location identifier and a null InputStream.
     *
     * @param location
     * @return
     */
    Subsystem install(String location) throws SubsystemException;

    /**
     * Install a new subsystem from the specified InputStream object.  If the specified InputStream is null,
     * the InputStream must be created from the specified location.
     * 
     * The specified location identifier will be used as the identity of the subsystem. 
     * Every installed subsystem is uniquely identified by its location identifier which is typically in the form of a URL.
     * 
     * If a subsystem containing the same location identifier is already installed, the Subsystem object for that subsystem is returned.
     * 
     * @param location
     * @param content
     * @return
     */
    Subsystem install(String location, InputStream content) throws SubsystemException;

    /**
     * Update the given subsystem.
     *
     * The updated subsystem metadata will be loaded from
     * the subsystem location, or from the subsystem update location
     * if specified.
     *
     * @param subsystem
     */
    void update(Subsystem subsystem) throws SubsystemException;

    /**
     * Update the given subsystem
     *
     * @param subsystem
     * @param content
     */
    void update(Subsystem subsystem, InputStream content) throws SubsystemException;

    /**
     * Uninstall the given subsystem.
     *
     * @param subsystem
     */
    void uninstall(Subsystem subsystem) throws SubsystemException;

    /**
     * Abort the current operation.
     * The installing thread must throw a SubsystemException if the operation
     * has actually been canceled and rolled back before terminating.
     *
     * @return <code>true</code> if an operation was ongoing and requested to be
     *    cancelled, <code>false</code> if there was no ongoing operation
     */
    boolean cancel();

}
@@ -1983,22 +1983,24 @@
 calling 
-%3Ccode%3E
+%7B@link #
 install(
@@ -2019,23 +2019,17 @@
 tStream)
-%3C/code%3E
+%7D
  with th
@@ -2262,32 +2262,38 @@
 m the specified 
+%3Ccode%3E
 InputStream obje
@@ -2287,16 +2287,23 @@
 utStream
+%3C/code%3E
  object.
@@ -2304,16 +2304,32 @@
 bject.  
+%0A     * %0A     * 
 If the s
@@ -2337,16 +2337,22 @@
 ecified 
+%3Ccode%3E
 InputStr
@@ -2358,16 +2358,36 @@
 ream
- is null
+%3C/code%3E is %3Ccode%3Enull%3C/code%3E
 ,%0A  
@@ -2395,16 +2395,22 @@
   * the 
+%3Ccode%3E
 InputStr
@@ -2412,16 +2412,23 @@
 utStream
+%3C/code%3E
  must be
@@ -2696,24 +2696,99 @@
    * %0A     *
+ The following steps are required to install a subsystem:%0A     * %0A     * 1.
  If a subsys
@@ -2857,16 +2857,22 @@
 ed, the 
+%3Ccode%3E
 Subsyste
@@ -2872,16 +2872,23 @@
 ubsystem
+%3C/code%3E
  object 
@@ -2915,24 +2915,396 @@
 s returned.%0A
+     * 2. The subsystem's content is read from the input stream.  If this fails, a SubsystemException is thrown.%0A     * 3. The subsystem's associated resources are located%0A     * 4. The subsystem's state is set to %3Ccode%3EINSTALLED%3C/code%3E%0A     * 5. The subsystem event of type INSTALLED is fired.%0A     * 6. The subsystem object for the newly installed subsystem is returned%0A
      * %0A    
@@ -3518,153 +3518,176 @@
 * Th
-e updated subsystem metadata will be loaded from%0A     * the subsystem location, or from the subsystem update location%0A     * if specified
+is method performs the same function as calling %7B@link #update(Subsystem, InputStream)%7D %0A     * with the specified subsystem and a %3Ccode%3Enull%3C/code%3E InputStream
 .%0A     *
 %0A   
@@ -3674,32 +3674,33 @@
 utStream.%0A     *
+ 
 %0A     * @param s
@@ -3818,24 +3818,351 @@
 en subsystem
+ from an %3Ccode%3EInputStream%3C/code%3E.  %0A     * %0A     * If the specified %3Ccode%3EInputStream%3C/code%3E is %3Ccode%3Enull%3C/code%3E, the InputStream must be created from%0A     * the subsystem's %7B@link SubsystemConstants#SUBSYSTEM_UPDATELOCATION Subsystem-UpdateLocation%7D Manifest header %0A     * if present, or this subsystem's original location.
 %0A     *%0A    

clarify javadoc for install/update a bit