/* * Copyright (c) OSGi Alliance (2008, 2012). All Rights Reserved. * * 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.osgi.framework.launch; import java.io.InputStream; import java.net.URL; import java.util.Enumeration; import org.osgi.framework.Bundle; import org.osgi.framework.BundleException; import org.osgi.framework.Constants; import org.osgi.framework.FrameworkEvent; /** * A Framework instance. A Framework is also known as a System Bundle. * *

* Framework instances are created using a {@link FrameworkFactory}. The methods * of this interface can be used to manage and control the created framework * instance. * * @ThreadSafe * @noimplement * @version $Id: e76240d5de584d1666880d9bc358571a76cbd8fb $ */ public interface Framework extends Bundle { /** * Initialize this Framework. After calling this method, this Framework * must: *

* *

* This Framework will not actually be started until {@link #start() start} * is called. * *

* This method does nothing if called when this Framework is in the * {@link #STARTING}, {@link #ACTIVE} or {@link #STOPPING} states. * * @throws BundleException If this Framework could not be initialized. * @throws SecurityException If the Java Runtime Environment supports * permissions and the caller does not have the appropriate * {@code AdminPermission[this,EXECUTE]} or if there is a security * manager already installed and the * {@link Constants#FRAMEWORK_SECURITY} configuration property is * set. * */ void init() throws BundleException; /** * Wait until this Framework has completely stopped. The {@code stop} and * {@code update} methods on a Framework performs an asynchronous stop of * the Framework. This method can be used to wait until the asynchronous * stop of this Framework has completed. This method will only wait if * called when this Framework is in the {@link #STARTING}, {@link #ACTIVE}, * or {@link #STOPPING} states. Otherwise it will return immediately. *

* A Framework Event is returned to indicate why this Framework has stopped. * * @param timeout Maximum number of milliseconds to wait until this * Framework has completely stopped. A value of zero will wait * indefinitely. * @return A Framework Event indicating the reason this method returned. The * following {@code FrameworkEvent} types may be returned by this * method. *

* @throws InterruptedException If another thread interrupted the current * thread before or while the current thread was waiting for this * Framework to completely stop. The interrupted status of * the current thread is cleared when this exception is thrown. * @throws IllegalArgumentException If the value of timeout is negative. */ FrameworkEvent waitForStop(long timeout) throws InterruptedException; /** * Start this Framework. * *

* The following steps are taken to start this Framework: *

    *
  1. If this Framework is not in the {@link #STARTING} state, * {@link #init() initialize} this Framework.
    2. *
  2. All installed bundles must be started in accordance with each * bundle's persistent autostart setting. This means some bundles * will not be started, some will be started with eager activation * and some will be started with their declared activation policy. * The start level of this Framework is moved to the start level specified * by the {@link Constants#FRAMEWORK_BEGINNING_STARTLEVEL beginning start * level} framework property, as described in the Start Level * Specification. If this framework property is not specified, then the * start level of this Framework is moved to start level one (1). Any * exceptions that occur during bundle starting must be wrapped in a * {@link BundleException} and then published as a framework event of type * {@link FrameworkEvent#ERROR}
    3. *
  3. This Framework's state is set to {@link #ACTIVE}.
    4. *
  4. A framework event of type {@link FrameworkEvent#STARTED} is fired
    5. *
* * @throws BundleException If this Framework could not be started. * @throws SecurityException If the caller does not have the appropriate * {@code AdminPermission[this,EXECUTE]}, and the Java Runtime * Environment supports permissions. * @see "Start Level Specification" */ void start() throws BundleException; /** * Start this Framework. * *

* Calling this method is the same as calling {@link #start()}. There are no * start options for the Framework. * * @param options Ignored. There are no start options for the Framework. * @throws BundleException If this Framework could not be started. * @throws SecurityException If the caller does not have the appropriate * {@code AdminPermission[this,EXECUTE]}, and the Java Runtime * Environment supports permissions. * @see #start() */ void start(int options) throws BundleException; /** * Stop this Framework. * *

* The method returns immediately to the caller after initiating the * following steps to be taken on another thread. *

    *
  1. This Framework's state is set to {@link #STOPPING}.
    2. *
  2. All installed bundles must be stopped without changing each bundle's * persistent autostart setting. The start level of this Framework is * moved to start level zero (0), as described in the Start Level * Specification. Any exceptions that occur during bundle stopping must * be wrapped in a {@link BundleException} and then published as a framework * event of type {@link FrameworkEvent#ERROR}
    3. *
  3. Unregister all services registered by this Framework.
    4. *
  4. Event handling is disabled.
    5. *
  5. This Framework's state is set to {@link #RESOLVED}.
    6. *
  6. All resources held by this Framework are released. This includes * threads, bundle class loaders, open files, etc.
    7. *
  7. Notify all threads that are waiting at {@link #waitForStop(long) * waitForStop} that the stop operation has completed.
    8. *
*

* After being stopped, this Framework may be discarded, initialized or * started. * * @throws BundleException If stopping this Framework could not be * initiated. * @throws SecurityException If the caller does not have the appropriate * {@code AdminPermission[this,EXECUTE]}, and the Java Runtime * Environment supports permissions. * @see "Start Level Specification" */ void stop() throws BundleException; /** * Stop this Framework. * *

* Calling this method is the same as calling {@link #stop()}. There are no * stop options for the Framework. * * @param options Ignored. There are no stop options for the Framework. * @throws BundleException If stopping this Framework could not be * initiated. * @throws SecurityException If the caller does not have the appropriate * {@code AdminPermission[this,EXECUTE]}, and the Java Runtime * Environment supports permissions. * @see #stop() */ void stop(int options) throws BundleException; /** * The Framework cannot be uninstalled. * *

* This method always throws a BundleException. * * @throws BundleException This Framework cannot be uninstalled. * @throws SecurityException If the caller does not have the appropriate * {@code AdminPermission[this,LIFECYCLE]}, and the Java Runtime * Environment supports permissions. */ void uninstall() throws BundleException; /** * Stop and restart this Framework. * *

* The method returns immediately to the caller after initiating the * following steps to be taken on another thread. *

    *
  1. Perform the steps in the {@link #stop()} method to stop this * Framework.
    2. *
  2. Perform the steps in the {@link #start()} method to start this * Framework.
    3. *
* * @throws BundleException If stopping and restarting this Framework could * not be initiated. * @throws SecurityException If the caller does not have the appropriate * {@code AdminPermission[this,LIFECYCLE]}, and the Java Runtime * Environment supports permissions. */ void update() throws BundleException; /** * Stop and restart this Framework. * *

* Calling this method is the same as calling {@link #update()} except that * any provided InputStream is immediately closed. * * @param in Any provided InputStream is immediately closed before returning * from this method and otherwise ignored. * @throws BundleException If stopping and restarting this Framework could * not be initiated. * @throws SecurityException If the caller does not have the appropriate * {@code AdminPermission[this,LIFECYCLE]}, and the Java Runtime * Environment supports permissions. */ void update(InputStream in) throws BundleException; /** * Returns the Framework unique identifier. This Framework is assigned the * unique identifier zero (0) since this Framework is also a System Bundle. * * @return 0. * @see Bundle#getBundleId() */ long getBundleId(); /** * Returns the Framework location identifier. This Framework is assigned the * unique location "{@code System Bundle}" since this Framework is * also a System Bundle. * * @return The string "{@code System Bundle}". * @throws SecurityException If the caller does not have the appropriate * {@code AdminPermission[this,METADATA]}, and the Java Runtime * Environment supports permissions. * @see Bundle#getLocation() * @see Constants#SYSTEM_BUNDLE_LOCATION */ String getLocation(); /** * Returns the symbolic name of this Framework. The symbolic name is unique * for the implementation of the framework. However, the symbolic name * "{@code system.bundle}" must be recognized as an alias to the * implementation-defined symbolic name since this Framework is also a * System Bundle. * * @return The symbolic name of this Framework. * @see Bundle#getSymbolicName() * @see Constants#SYSTEM_BUNDLE_SYMBOLICNAME */ String getSymbolicName(); /** * Returns {@code null} as a framework implementation does not have a proper * bundle from which to return entry paths. * * @param path Ignored. * @return {@code null} as a framework implementation does not have a proper * bundle from which to return entry paths. */ Enumeration getEntryPaths(String path); /** * Returns {@code null} as a framework implementation does not have a proper * bundle from which to return an entry. * * @param path Ignored. * @return {@code null} as a framework implementation does not have a proper * bundle from which to return an entry. */ URL getEntry(String path); /** * Returns {@code null} as a framework implementation does not have a proper * bundle from which to return entries. * * @param path Ignored. * @param filePattern Ignored. * @param recurse Ignored. * @return {@code null} as a framework implementation does not have a proper * bundle from which to return entries. */ Enumeration findEntries(String path, String filePattern, boolean recurse); /** * Adapt this Framework to the specified type. * *

* Adapting this Framework to the specified type may require certain checks, * including security checks, to succeed. If a check does not succeed, then * this Framework cannot be adapted and {@code null} is returned. If this * Framework is not {@link #init() initialized}, then {@code null} is * returned if the specified type is one of the OSGi defined types to which * a system bundle can be adapted. * * @param The type to which this Framework is to be adapted. * @param type Class object for the type to which this Framework is to be * adapted. * @return The object, of the specified type, to which this Framework has * been adapted or {@code null} if this Framework cannot be adapted */ A adapt(Class type); }