Copyright (c) 2012, 2016 IBM Corporation and others.
This program and the accompanying materials
are made available under the terms of the Eclipse Public License 2.0
which accompanies this distribution, and is available at
https://www.eclipse.org/legal/epl-2.0/
SPDX-License-Identifier: EPL-2.0
Contributors:
    IBM Corporation - initial API and implementation
/*******************************************************************************
 * Copyright (c) 2012, 2016 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 * 
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.osgi.container;

import java.io.DataInputStream;
import java.util.EnumSet;
import java.util.concurrent.Executor;
import java.util.concurrent.ScheduledExecutorService;
import org.eclipse.osgi.container.Module.Settings;
import org.eclipse.osgi.service.debug.DebugOptions;
import org.osgi.framework.Constants;
import org.osgi.framework.FrameworkListener;
import org.osgi.framework.hooks.resolver.ResolverHookFactory;
import org.osgi.framework.startlevel.FrameworkStartLevel;

Adapts the behavior of a container.
Since:
3.10/**
 * Adapts the behavior of a container.
 * @since 3.10
 */
public abstract class ModuleContainerAdaptor {
	private static Executor defaultExecutor = new Executor() {
		@Override
		public void execute(Runnable command) {
			command.run();
		}
	};

	
Event types that may be published for a container. /**
	 * Event types that may be {@link #publishContainerEvent(ContainerEvent, Module, Throwable, FrameworkListener...) published}
	 * for a container.
	 *
	 */
	public enum ContainerEvent {
		
A container refresh operation has completed /**
		 * A container {@link ModuleContainer#refresh(java.util.Collection) refresh} operation has completed
		 */
		REFRESH,

		
A container start level change has completed. /**
		 * A container {@link ModuleContainer#getFrameworkStartLevel() start level} change has completed.
		 */
		START_LEVEL,

		
The container has been started.
/**
		 * The container has been started.
		 */
		STARTED,

		
This event is returned by SystemModule.waitForStop(long) to indicate that the container has stopped. /**
		 * This event is returned by {@link SystemModule#waitForStop(long)}
		 * to indicate that the container has stopped.
		 */
		STOPPED,

		
This event is returned by SystemModule.waitForStop(long) to indicate that the container has stopped because of an update operation. /**
		 * This event is returned by {@link SystemModule#waitForStop(long)}
		 * to indicate that the container has stopped because of an update
		 * operation.
		 */
		STOPPED_UPDATE,

		
This event is returned by SystemModule.waitForStop(long) to indicate that the container has stopped because of an refresh operation. /**
		 * This event is returned by {@link SystemModule#waitForStop(long)}
		 * to indicate that the container has stopped because of an refresh
		 * operation.
		 */
		STOPPED_REFRESH,

		
This event is returned by SystemModule.waitForStop(long) to indicate that the wait operation has timed out.. /**
		 * This event is returned by {@link SystemModule#waitForStop(long)}
		 * to indicate that the wait operation has timed out..
		 */
		STOPPED_TIMEOUT,

		
An event fired for an error condition.
/**
		 * An event fired for an error condition.
		 */
		ERROR,

		
An event fired for a warning condition.
/**
		 * An event fired for a warning condition.
		 */
		WARNING,

		
An event fired for informational purposes only.
/**
		 * An event fired for informational purposes only.
		 */
		INFO
	}

	
Event types that may be published for a module indicating a state change has occurred for a module. /**
	 * Event types that may be {@link #publishModuleEvent(ModuleEvent, Module, Module) published} for a module
	 * indicating a {@link Module#getState() state} change has occurred for a module.
	 */
	public static enum ModuleEvent {
		
The module has been installed
/**
		 * The module has been installed
		 */
		INSTALLED,
		
The module has been activated with the lazy activation policy and is waiting a trigger class load. /**
		 * The module has been activated with the lazy activation policy and
		 * is waiting a {@link Module.StartOptions#LAZY_TRIGGER trigger} class load.
		 */
		LAZY_ACTIVATION,
		
The module has been resolved.
/**
		 * The module has been resolved.
		 */
		RESOLVED,
		
The module has beens started.
/**
		 * The module has beens started.
		 */
		STARTED,
		
The module is about to be activated.
/**
		 * The module is about to be activated.
		 */
		STARTING,
		
The module has been stopped.
/**
		 * The module has been stopped.
		 */
		STOPPED,
		
The module is about to be deactivated.
/**
		 * The module is about to be deactivated.
		 */
		STOPPING,
		
The module has been uninstalled.
/**
		 * The module has been uninstalled.
		 */
		UNINSTALLED,
		
The module has been unresolved.
/**
		 * The module has been unresolved.
		 */
		UNRESOLVED,
		
The module has been updated.
/**
		 * The module has been updated.
		 */
		UPDATED
	}

	
Returns the collision hook the container will use.
Returns:
the collision hook the container will use./**
	 * Returns the collision hook the container will use.
	 * @return the collision hook the container will use.
	 */
	public abstract ModuleCollisionHook getModuleCollisionHook();

	
Returns the resolver hook factory the container will use.
Returns:
the resolver hook factory the container will use./**
	 * Returns the resolver hook factory the container will use.
	 * @return the resolver hook factory the container will use.
	 */
	public abstract ResolverHookFactory getResolverHookFactory();

	
Publishes the specified container event.
No locks are held by the container when this method is called
Params:
type – the type of event
module – the module associated with the event
error – the error associated with the event, may be null
listeners – additional listeners to publish the event to synchronously/**
	 * Publishes the specified container event.
	 * No locks are held by the container when this method is called
	 * @param type the type of event
	 * @param module the module associated with the event
	 * @param error the error associated with the event, may be {@code null}
	 * @param listeners additional listeners to publish the event to synchronously
	 */
	public abstract void publishContainerEvent(ContainerEvent type, Module module, Throwable error, FrameworkListener... listeners);

	
Publishes the specified module event type for the specified module.
No locks are held by the container when this method is called
Params:
type – the event type to publish
module – the module the event is associated with
origin – the module which is the origin of the event. For the event type ModuleEvent.INSTALLED, this is the module whose context was used to install the module. Otherwise it is the module itself. May be null only when the event is not of type ModuleEvent.INSTALLED./**
	 * Publishes the specified module event type for the specified module.
	 * No locks are held by the container when this method is called
	 * @param type the event type to publish
	 * @param module the module the event is associated with
	 * @param origin the module which is the origin of the event. For the event
	 *        type {@link ModuleEvent#INSTALLED}, this is the module whose context was used
	 *        to install the module. Otherwise it is the module itself. May be null only
	 *        when the event is not of type {@link ModuleEvent#INSTALLED}.
	 */
	public abstract void publishModuleEvent(ModuleEvent type, Module module, Module origin);

	
Returns the specified configuration property value
Params:
key – the key of the configuration property
Returns:
the configuration property value/**
	 * Returns the specified configuration property value
	 * @param key the key of the configuration property
	 * @return the configuration property value
	 */
	public String getProperty(String key) {
		return null;
	}

	
Creates a new ModuleLoader for the specified wiring. 
Params:
wiring – the module wiring to create a module loader for
Returns:
a new ModuleLoader for the specified wiring./**
	 * Creates a new {@link ModuleLoader} for the specified wiring.
	 * @param wiring the module wiring to create a module loader for
	 * @return a new {@link ModuleLoader} for the specified wiring.
	 */
	public ModuleLoader createModuleLoader(ModuleWiring wiring) {
		throw new UnsupportedOperationException("Container adaptor does not support module class loaders."); //$NON-NLS-1$
	}

	
Creates a new module. This gets called when a new module is installed or when loading persistent data into this database. 
Params:
location – the location for the module
id – the id for the module
settings – the settings for the module. May be null if there are no settings.
startlevel – the start level for the module
Returns:
the Module/**
	 * Creates a new module.  This gets called when a new module is installed
	 * or when {@link ModuleDatabase#load(DataInputStream) loading} persistent data into this
	 * database.
	 * @param location the location for the module
	 * @param id the id for the module
	 * @param settings the settings for the module.  May be {@code null} if there are no settings.
	 * @param startlevel the start level for the module
	 * @return the Module
	 */
	public abstract Module createModule(String location, long id, EnumSet<Settings> settings, int startlevel);

	
Creates the system module. This gets called when the system module is installed or when loading persistent data into this database. 
 The returned system module must have an id of zero and a location of System Bundle. 
Returns:
the system module/**
	 * Creates the system module.  This gets called when the system module is installed
	 * or when {@link ModuleDatabase#load(DataInputStream) loading} persistent data into this
	 * database.
	 * <p>
	 * The returned system module must have an {@link Module#getId() id} of zero and a location
	 * of {@link Constants#SYSTEM_BUNDLE_LOCATION System Bundle}.
	 * @return the system module
	 */
	public abstract SystemModule createSystemModule();

	
Returns the current revision info for a module with the specified location and id
Params:
location – the location of the module
id – the id of the module
Returns:
the revision info, may be null/**
	 * Returns the current revision info for a module with the specified location and id
	 * @param location the location of the module
	 * @param id the id of the module
	 * @return the revision info, may be {@code null}
	 */
	public Object getRevisionInfo(String location, long id) {
		return null;
	}

	
After a revision is created this method is called with the specified revision info.
Params:
revision – the newly created revision
revisionInfo – the revision info that got associated with the revision/**
	 * After a revision is created this method is called with the specified revision info.
	 * @param revision the newly created revision
	 * @param revisionInfo the revision info that got associated with the revision
	 */
	public void associateRevision(ModuleRevision revision, Object revisionInfo) {
		// do nothing by default
	}

	
This is called when a wiring is made invalid and allows the adaptor to react 
to this.  This method is called while holding state change lock for the
module as well as for the module database.  Care must be taken not to introduce
deadlock.
Params:
moduleWiring – the module wiring being invalidated
current – the current module loader associated with the wiring, may be null./**
	 * This is called when a wiring is made invalid and allows the adaptor to react 
	 * to this.  This method is called while holding state change lock for the
	 * module as well as for the module database.  Care must be taken not to introduce
	 * deadlock.
	 * @param moduleWiring the module wiring being invalidated
	 * @param current the current module loader associated with the wiring, may be <code>null</code>.
	 */
	public void invalidateWiring(ModuleWiring moduleWiring, ModuleLoader current) {
		// do nothing by default
	}

	
This is called if a request to refresh modules causes the system module
to be refreshed.  This causes the system module to be stopped in a back
ground thread.  This method is called before the background thread is 
started to stop the system module.
/**
	 * This is called if a request to refresh modules causes the system module
	 * to be refreshed.  This causes the system module to be stopped in a back
	 * ground thread.  This method is called before the background thread is 
	 * started to stop the system module.
	 */
	public void refreshedSystemModule() {
		// do nothing by default
	}

	
This is called whenever the module database has been updated.
/**
	 * This is called whenever the module database has been updated.
	 */
	public void updatedDatabase() {
		// do nothing by default
	}

	
This is called when the SystemModule.init() is running. /**
	 * This is called when the {@link SystemModule#init()} is running.
	 */
	public void initBegin() {
		// do nothing by default
	}

	
This is called just before the SystemModule.init() returns. /**
	 * This is called just before the {@link SystemModule#init()} returns.
	 */
	public void initEnd() {
		// do nothing by default
	}

	
Returns the debug options for the module container.
Returns:
the debug options for the module container, or null if there are no debug options./**
	 * Returns the debug options for the module container.
	 * @return the debug options for the module container, or null if there are no debug options.
	 */
	public DebugOptions getDebugOptions() {
		// be default there are no debug options
		return null;
	}

	
Returns the executor used to perform resolve operations
Returns:
the executor used to perform resolve operations
Since:
3.11/**
	 * Returns the executor used to perform resolve operations
	 * @return the executor used to perform resolve operations
	 * @since 3.11
	 */
	public Executor getResolverExecutor() {
		return defaultExecutor;
	}

	
Returns the executor used to by the FrameworkStartLevel implementation to start bundles that have the same start level. This allows bundles to be started in parallel. 
Returns:
the executor used by the FrameworkStartLevel implementation.
Since:
3.14/**
	 * Returns the executor used to by the 
	 * {@link ModuleContainer#getFrameworkStartLevel() FrameworkStartLevel} implementation to
	 * start bundles that have the same start level.  This allows bundles to be
	 * started in parallel.
	 * @return the executor used by the {@link FrameworkStartLevel} implementation.
	 * @since 3.14
	 */
	public Executor getStartLevelExecutor() {
		return defaultExecutor;
	}

	
Allows a builder to be modified before it is used by the container. This gets call when a new module is installed into the container or when an existing module is updated with a new revision. The container does not call any methods on the builder before calling this method. 
Params:
operation – The lifecycle operation event that is in progress using the supplied builder. This will be either installed or updated.
origin – The module which originated the lifecycle operation. The origin may be null for installed operations. This is the module passed to the install or update method.
builder – the builder that will be used to create a new ModuleRevision.
revisionInfo – the revision info that will be used for the new revision, may be null.
Returns:
The modified builder or a completely new builder to be used by the bundle. A null value indicates the original builder should be used, which may have been modified by adding requirements or capabilities.
Since:
3.12/**
	 * Allows a builder to be modified before it is used by the container. This gets
	 * call when a new module is {@link ModuleContainer#install(Module, String, ModuleRevisionBuilder, Object) installed}
	 * into the container or when an existing module is {@link ModuleContainer#update(Module, ModuleRevisionBuilder, Object) updated}
	 * with a new revision.  The container does not call any methods on the builder before calling this method.
	 * @param operation The lifecycle operation event that is in progress using the supplied builder. 
	 * This will be either {@link ModuleEvent#INSTALLED installed} or {@link ModuleEvent#UPDATED updated}.
	 * @param origin The module which originated the lifecycle operation. The origin may be {@code null} for
	 * {@link ModuleEvent#INSTALLED installed} operations.  This is the module
	 * passed to the {@link ModuleContainer#install(Module, String, ModuleRevisionBuilder, Object) install} or 
	 * {@link ModuleContainer#update(Module, ModuleRevisionBuilder, Object) update} method.
	 * @param builder the builder that will be used to create a new {@link ModuleRevision}.
	 * @param revisionInfo the revision info that will be used for the new revision, may be {@code null}.
	 * @return The modified builder or a completely new builder to be used by the bundle.  A {@code null} value
	 * indicates the original builder should be used, which may have been modified by adding requirements or
	 * capabilities.
	 * @since 3.12
	 */
	public ModuleRevisionBuilder adaptModuleRevisionBuilder(ModuleEvent operation, Module origin, ModuleRevisionBuilder builder, Object revisionInfo) {
		// do nothing by default
		return null;
	}

	
Returns the scheduled executor that may be used by the
container to schedule background tasks.
Returns:
the scheduled executor, or null if background tasks are not supported
Since:
3.13/**
	 * Returns the scheduled executor that may be used by the
	 * container to schedule background tasks.
	 * @return the scheduled executor, or null if background tasks are not supported
	 * @since 3.13
	 */
	public ScheduledExecutorService getScheduledExecutor() {
		return null;
	}
}