Bug 439445 - Equinox console bundle has hard dependency to Equinox framework and not to supplement bundle

5 files changed, 434 insertions, 0 deletions

diff --git a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/console/CommandInterpreter.java b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/console/CommandInterpreter.java
new file mode 100644
index 000000000..220e0b1f9
--- /dev/null
+++ b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/console/CommandInterpreter.java
@@ -0,0 +1,91 @@
+/*******************************************************************************
+ * Copyright (c) 2003, 2012 IBM Corporation and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ *     IBM Corporation - initial API and implementation
+ *******************************************************************************/
+
+package org.eclipse.osgi.framework.console;
+
+import java.util.Dictionary;
+import org.osgi.framework.Bundle;
+
+/**	
+ * A command interpreter is a shell that can interpret command
+ * lines. This object is passed as parameter when a CommandProvider
+ * is invoked.
+ * <p>
+ * This interface is not intended to be implemented by clients.
+ * </p>
+ * @since 3.1
+ * @noimplement This interface is not intended to be implemented by clients.
+ */
+public interface CommandInterpreter {
+	/**
+	 * Get the next argument in the input.  If no arguments are left then null is returned.
+	 *
+	 * E.g. if the commandline is hello world, the _hello method
+	 * will get "world" as the first argument.
+	 * @return the next argument or null if no arguments are left.
+	 */
+	public String nextArgument();
+
+	/**
+	 * Execute a command line as if it came from the end user
+	 * and return the result.
+	 * @param cmd The command line to execute.
+	 * @return the result of the command.
+	 */
+	public Object execute(String cmd);
+
+	/**
+	 * Prints an object to the outputstream
+	 *
+	 * @param o	the object to be printed
+	 */
+	public void print(Object o);
+
+	/**
+	 * Prints an empty line to the outputstream
+	 */
+	public void println();
+
+	/**
+	 * Prints an object to the output medium (appended with newline character).
+	 * <p>
+	 * If running on the target environment the user is prompted with '--more'
+	 * if more than the configured number of lines have been printed without user prompt.
+	 * That way the user of the program has control over the scrolling.
+	 * <p>
+	 * For this to work properly you should not embedded "\n" etc. into the string.
+	 *
+	 * @param	o	the object to be printed
+	 */
+	public void println(Object o);
+
+	/**
+	 * Print a stack trace including nested exceptions.
+	 * @param t The offending exception
+	 */
+	public void printStackTrace(Throwable t);
+
+	/**
+	 * Prints the given dictionary sorted by keys.
+	 *
+	 * @param dic	the dictionary to print
+	 * @param title	the header to print above the key/value pairs
+	 */
+	public void printDictionary(Dictionary<?, ?> dic, String title);
+
+	/**
+	 * Prints the given bundle resource if it exists
+	 *
+	 * @param bundle	the bundle containing the resource
+	 * @param resource	the resource to print
+	 */
+	public void printBundleResource(Bundle bundle, String resource);
+}
diff --git a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/console/CommandProvider.java b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/console/CommandProvider.java
new file mode 100644
index 000000000..afbee8461
--- /dev/null
+++ b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/console/CommandProvider.java
@@ -0,0 +1,46 @@
+/*******************************************************************************
+ * Copyright (c) 2003, 2012 IBM Corporation and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ *     IBM Corporation - initial API and implementation
+ *******************************************************************************/
+
+package org.eclipse.osgi.framework.console;
+
+/**
+ When an object wants to provide a number of commands
+ to the console, it should register an object with this
+ interface. Some console can then pick this up and execute
+ command lines.
+ The SERVICE_RANKING registration property can be used to influence the
+ order that a CommandProvider gets called.  Specify a value less than
+ Integer.MAXVALUE, where higher is more significant.  The default value
+ if SERVICE_RANKING is not set is 0.
+ <p>
+ The interface contains only methods for the help.
+ The console should use inspection
+ to find the commands. All public commands, starting with
+ a '_' and taking a CommandInterpreter as parameter
+ will be found. E.g.
+ <pre>
+ public Object _hello( CommandInterpreter intp ) {
+ return "hello " + intp.nextArgument();
+ }
+ </pre>
+ * <p>
+ * Clients may implement this interface.
+ * </p>
+ * @since 3.1
+ */
+public interface CommandProvider {
+	/**
+	 Answer a string (may be as many lines as you like) with help
+	 texts that explain the command.
+	 */
+	public String getHelp();
+
+}
diff --git a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/console/ConsoleSession.java b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/console/ConsoleSession.java
new file mode 100644
index 000000000..97cd3aae2
--- /dev/null
+++ b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/console/ConsoleSession.java
@@ -0,0 +1,95 @@
+/*******************************************************************************
+ * Copyright (c) 2009, 2012 IBM Corporation and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ *     IBM Corporation - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.osgi.framework.console;
+
+import java.io.InputStream;
+import java.io.OutputStream;
+import org.osgi.framework.*;
+
+/**
+ * A console session service provides the input and output to a single console session.
+ * The input will be used by the console to read in console commands.  The output will
+ * be used to print the results of console commands. 
+ * <p>
+ * The console session must be registered as an OSGi service in order to be associated 
+ * with a console instance. The console implementation will discover any console session 
+ * services and will create a new console instance using the console session for input and 
+ * output.  When a session is closed then the console session service will be unregistered 
+ * and the console instance will terminate and be disposed of.  The console instance will 
+ * also terminate if the console session service is unregistered for any reason.
+ * </p>
+ * @since 3.6
+ */
+public abstract class ConsoleSession implements ServiceFactory<Object> {
+	private volatile ServiceRegistration<Object> sessionRegistration;
+
+	/**
+	 * Called by the console implementation to free resources associated
+	 * with this console session.  This method will result in the console
+	 * session service being unregistered from the service registry.
+	 * @noreference This method is not intended to be referenced by clients.
+	 */
+	public final void close() {
+		doClose();
+		ServiceRegistration<Object> current = sessionRegistration;
+		if (current != null) {
+			sessionRegistration = null;
+			try {
+				current.unregister();
+			} catch (IllegalStateException e) {
+				// This can happen if the service is in the process of being 
+				// unregistered or if another thread unregistered the service.
+				// Ignoring the exception.
+			}
+		}
+	}
+
+	/**
+	 * Called by the {@link #close()} method to free resources associated 
+	 * with this console session.  For example, closing the streams 
+	 * associated with the input and output for this session.
+	 * @noreference This method is not intended to be referenced by clients.
+	 */
+	protected abstract void doClose();
+
+	/**
+	 * Returns the input for this console session.  This input will be used
+	 * to read console commands from the user of the session.
+	 * @return the input for this console session
+	 * @noreference This method is not intended to be referenced by clients.
+	 */
+	public abstract InputStream getInput();
+
+	/**
+	 * Returns the output for this console session.  This output will be 
+	 * used to write the results of console commands.
+	 * @return the output for this console session.
+	 * @noreference This method is not intended to be referenced by clients.
+	 */
+	public abstract OutputStream getOutput();
+
+	/**
+	 * @noreference This method is not intended to be referenced by clients.
+	 */
+	public final Object getService(Bundle bundle, ServiceRegistration<Object> registration) {
+		if (sessionRegistration == null)
+			sessionRegistration = registration;
+		return this;
+	}
+
+	/**
+	 * @noreference This method is not intended to be referenced by clients.
+	 */
+	public final void ungetService(Bundle bundle, ServiceRegistration<Object> registration, Object service) {
+		// do nothing
+	}
+
+}
diff --git a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/console/package.html b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/console/package.html
new file mode 100644
index 000000000..d140bf5b7
--- /dev/null
+++ b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/console/package.html
@@ -0,0 +1,17 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+   <title>Package-level Javadoc</title>
+</head>
+<body>
+Provides services related to the Equinox console.
+<h2>
+Package Specification</h2>
+This package specifies the API for services related to the Equinox console.
+<p>
+Clients which provide commands or provide sessions to the Equinox console 
+will likely be interested in the types provided by this package.
+</p>
+</body>
+</html>
diff --git a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/report/resolution/ResolutionReport.java b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/report/resolution/ResolutionReport.java
new file mode 100644
index 000000000..04768c84b
--- /dev/null
+++ b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/report/resolution/ResolutionReport.java
@@ -0,0 +1,185 @@
+/*******************************************************************************
+ * Copyright (c) 2012, 2013 IBM Corporation and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ * 
+ * Contributors:
+ *     IBM Corporation - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.osgi.report.resolution;
+
+import java.util.List;
+import java.util.Map;
+import org.osgi.framework.hooks.resolver.ResolverHook;
+import org.osgi.resource.Resource;
+import org.osgi.service.resolver.ResolutionException;
+
+/**
+ * A resolution report is associated with a single resolve process.  Entries
+ * contained in a resolution report will contain entries for all resources
+ * that were attempted to be resolved in a single resolve process.
+ * Resolution reports are gathered by a special type of {@link ResolverHook}
+ * which implements the report {@link Listener} interface.  The following
+ * example demonstrates how to gather a resolution report for a list of bundles
+ * <pre>
+
+	public static ResolutionReport getResolutionReport(Bundle[] bundles, BundleContext context) {
+		DiagReportListener reportListener = new DiagReportListener(bundles);
+		ServiceRegistration<ResolverHookFactory> hookReg = context.registerService(ResolverHookFactory.class, reportListener, null);
+		try {
+			Bundle systemBundle = context.getBundle(Constants.SYSTEM_BUNDLE_LOCATION);
+			FrameworkWiring frameworkWiring = systemBundle.adapt(FrameworkWiring.class);
+			frameworkWiring.resolveBundles(Arrays.asList(bundles));
+			return reportListener.getReport();
+		} finally {
+			hookReg.unregister();
+		}
+	}
+
+	private static class DiagReportListener implements ResolverHookFactory {
+		private final Collection<BundleRevision> targetTriggers = new ArrayList<BundleRevision>();
+		volatile ResolutionReport report = null;
+
+		public DiagReportListener(Bundle[] bundles) {
+			for (Bundle bundle : bundles) {
+				BundleRevision revision = bundle.adapt(BundleRevision.class);
+				if (revision != null && revision.getWiring() == null) {
+					targetTriggers.add(revision);
+				}
+			}
+			
+		}
+
+		class DiagResolverHook implements ResolverHook, ResolutionReport.Listener {
+
+			public void handleResolutionReport(ResolutionReport report) {
+				DiagReportListener.this.report = report;
+			}
+
+			public void filterResolvable(Collection<BundleRevision> candidates) { }
+
+			public void filterSingletonCollisions(BundleCapability singleton,
+					Collection<BundleCapability> collisionCandidates) { }
+
+			public void filterMatches(BundleRequirement requirement,
+					Collection<BundleCapability> candidates) { }
+
+			public void end() { }
+			
+		}
+		public ResolverHook begin(Collection<BundleRevision> triggers) {
+			if (triggers.containsAll(targetTriggers)) {
+				// this is the triggers we are looking for
+				return new DiagResolverHook();
+			}
+			// did not find the expected triggers do not participate
+			// in the resolve process to gather the report
+			return null;
+		}
+		ResolutionReport getReport() {
+			return report;
+		}
+	}
+ * </pre> 
+ * @since 3.10
+ */
+public interface ResolutionReport {
+	public interface Entry {
+		enum Type {
+			/**
+			 * Indicates a resource failed to resolve because a resolver hook
+			 * filtered it out. The structure of the data is <code>null</code>.
+			 */
+			// TODO This could possibly be improved by adding a reference to the
+			// hook that filtered it out.
+			FILTERED_BY_RESOLVER_HOOK,
+			/**
+			 * Indicates a resource failed to resolve because no capabilities
+			 * matching one of the resource's requirements could not be found.
+			 * The structure of the data is <code>Requirement</code>, which
+			 * represents the missing requirement.
+			 */
+			MISSING_CAPABILITY,
+			/**
+			 * Indicates a resource failed to resolve because (1) it's a
+			 * singleton, (2) there was at least one collision, and (3) it was
+			 * not the selected singleton. The structure of the data is <code>
+			 * Resource</code>, which represents the singleton with which the
+			 * resource collided.
+			 */
+			SINGLETON_SELECTION,
+			/**
+			 * Indicates a resource failed to resolve because one or more
+			 * providers of capabilities matching the resource's requirements
+			 * were not resolved. The structure of the data is <code>
+			 * Map&lt;Requirement, Set&lt;Capability&gt;&gt;</code>.
+			 */
+			UNRESOLVED_PROVIDER,
+			/**
+			 * Indicates a resource failed to resolve because of a uses
+			 * constraint violation.  The structure of the data is
+			 * <code>ResolutionException</code>.
+			 */
+			USES_CONSTRAINT_VIOLATION
+		}
+
+		// TODO Can this make use of generics? Or should this be Map<String, Object>
+		// and each enum would define the key constants?
+		/**
+		 * Returns the data associated with this resolution report entry.  The 
+		 * structure of the data is determined by the <code>Type</code>
+		 * of the entry and may by <code>null</code>.
+		 * 
+		 * @return the data associated with this resolution report entry.
+		 * @see Type
+		 */
+		Object getData();
+
+		/**
+		 * Returns the type for this resolution report entry.
+		 * @return the type for this resolution report entry.
+		 */
+		Type getType();
+	}
+
+	/**
+	 * A resolution report listener gets called an the end of resolve process
+	 * in order to receive a resolution report.  All {@link ResolverHook resolver hooks}
+	 * that also implement the {@link Listener listener} interface will be called
+	 * to receive the resolution report associated with the resolve process.
+	 */
+	public interface Listener {
+		void handleResolutionReport(ResolutionReport report);
+	}
+
+	/**
+	 * Returns all resolution report entries associated with this report.
+	 * The key is the unresolved resource and the value is a list of 
+	 * report entries that caused the associated resource  to not be able to resolve.
+	 * @return all resolution report entries associated with this report.
+	 */
+	Map<Resource, List<Entry>> getEntries();
+
+	/**
+	 * Returns the resolution exception associated with the resolve process
+	 * or {@code null} if there is no resolution exception.  For some resolve
+	 * operations a resolution exception may not be thrown even if the 
+	 * resolve process could not resolve some resources.  For example, if
+	 * the resources are optional resources to resolve.
+	 * @return the resolution exception or {@code null} if there is 
+	 * no resolution exception.
+	 */
+	ResolutionException getResolutionException();
+
+	/**
+	 * Returns a resolution report message for the given resource.
+	 * The resource must be included as an {@link #getEntries entry} for this resolution report.
+	 * This is a convenience method intended to help display messaged for resolution
+	 * errors.
+	 * @param resource the resource to get the resolution report message for.
+	 * @return a resolution report message.
+	 */
+	String getResolutionReportMessage(Resource resource);
+}