org.osgi.framework.launch.Framework Maven / Gradle / Ivy
Show all versions of aspectjtools Show documentation
/*
* Copyright (c) OSGi Alliance (2008, 2020). 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.annotation.versioning.ProviderType;
import org.osgi.framework.Bundle;
import org.osgi.framework.BundleException;
import org.osgi.framework.Constants;
import org.osgi.framework.FrameworkEvent;
import org.osgi.framework.FrameworkListener;
/**
* 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
* @author $Id: bf960bdc39d19a780694a8cab5a555b3e0dc0fde $
*/
@ProviderType
public interface Framework extends Bundle {
/**
* Initialize this Framework.
*
* This method performs the same function as calling
* {@link #init(FrameworkListener...)} with no framework listeners.
*
* @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.
* @see #init(FrameworkListener...)
*/
void init() throws BundleException;
/**
* Initialize this Framework. After calling this method, this Framework
* must:
*
* - Have generated a new {@link Constants#FRAMEWORK_UUID framework UUID}.
*
* - Be in the {@link #STARTING} state.
* - Have a valid Bundle Context.
* - Be at start level 0.
* - Have event handling enabled.
* - Have reified Bundle objects for all installed bundles.
* - Have registered any framework services. For example,
* {@code ConditionalPermissionAdmin}.
* - Be {@link #adapt(Class) adaptable} to the OSGi defined types to which
* a system bundle can be adapted.
* - Have called the {@code start} method of the extension bundle
* activator for all resolved extension bundles.
*
*
*
* 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.
*
*
* All framework events fired by this method are also delivered to the
* specified FrameworkListeners in the order they are specified before
* returning from this method. After returning from this method the
* specified listeners are no longer notified of framework events.
*
* @param listeners Zero or more listeners to be notified when framework
* events occur while initializing the framework. The specified
* listeners do not need to be otherwise registered with the
* framework. If a specified listener is registered with the
* framework, it will be notified twice for each framework event.
* @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.
* @since 1.2
*/
void init(FrameworkListener... listeners) 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.
*
* - {@link FrameworkEvent#STOPPED STOPPED} - This Framework has
* been stopped.
* - {@link FrameworkEvent#STOPPED_UPDATE STOPPED_UPDATE} - This
* Framework has been updated which has shutdown and will now
* restart.
* - {@link FrameworkEvent#STOPPED_SYSTEM_REFRESHED
* STOPPED_SYSTEM_REFRESHED} - The Framework has been stopped
* because of a refresh operation on the system bundle. A new class
* loader must be used to restart the Framework.
* - {@link FrameworkEvent#ERROR ERROR} - The Framework
* encountered an error while shutting down or an error has occurred
* which forced the framework to shutdown.
* - {@link FrameworkEvent#WAIT_TIMEDOUT WAIT_TIMEDOUT} - This
* method has timed out and returned before this Framework has
* stopped.
*
* @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:
*
* - If this Framework is not in the {@link #STARTING} state,
* {@link #init() initialize} this Framework.
* - 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}
* - This Framework's state is set to {@link #ACTIVE}.
* - A framework event of type {@link FrameworkEvent#STARTED} is fired
*
*
* @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"
*/
@Override
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()
*/
@Override
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.
*
* - This Framework's state is set to {@link #STOPPING}.
* - 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}
* - Unregister all services registered by this Framework.
* - Event handling is disabled.
* - This Framework's state is set to {@link #RESOLVED}.
* - All resources held by this Framework are released. This includes
* threads, bundle class loaders, open files, etc.
* - Notify all threads that are waiting at {@link #waitForStop(long)
* waitForStop} that the stop operation has completed.
*
*
* 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"
*/
@Override
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()
*/
@Override
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.
*/
@Override
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.
*
* - Perform the steps in the {@link #stop()} method to stop this
* Framework.
* - Perform the steps in the {@link #start()} method to start this
* Framework.
*
*
* @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.
*/
@Override
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.
*/
@Override
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()
*/
@Override
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
*/
@Override
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
*/
@Override
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.
*/
@Override
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.
*/
@Override
URL getEntry(String path);
/**
* Returns the time when the set of bundles in this framework was last
* modified. The set of bundles is considered to be modified when a bundle
* is installed, updated or uninstalled.
*
*
* The time value is the number of milliseconds since January 1, 1970,
* 00:00:00 UTC.
*
* @return The time when the set of bundles in this framework was last
* modified.
*/
@Override
long getLastModified();
/**
* 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.
*/
@Override
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
*/
@Override
A adapt(Class type);
}