Bug 326707 - [RFC 159] Support in core for WeavingHook

3 files changed, 261 insertions, 0 deletions

diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/hooks/weaving/WeavingException.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/hooks/weaving/WeavingException.java
new file mode 100644
index 000000000..884279750
--- /dev/null
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/hooks/weaving/WeavingException.java
@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) OSGi Alliance (2010). 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.hooks.weaving;
+
+/**
+ * A weaving exception used to indicate that the class load should be failed but
+ * the weaving hook must not be blacklisted by the framework.
+ * 
+ * <p>
+ * This exception conforms to the general purpose exception chaining mechanism.
+ * 
+ * @version $Id: eb38b85f6ed66ec445fb2f0ee7143df021327a9a $
+ */
+
+public class WeavingException extends RuntimeException {
+	private static final long	serialVersionUID	= 1L;
+
+	/**
+	 * Creates a {@code WeavingException} with the specified message and
+	 * exception cause.
+	 * 
+	 * @param msg The associated message.
+	 * @param cause The cause of this exception.
+	 */
+	public WeavingException(String msg, Throwable cause) {
+		super(msg, cause);
+	}
+
+	/**
+	 * Creates a {@code WeavingException} with the specified message.
+	 * 
+	 * @param msg The message.
+	 */
+	public WeavingException(String msg) {
+		super(msg);
+	}
+}
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/hooks/weaving/WeavingHook.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/hooks/weaving/WeavingHook.java
new file mode 100644
index 000000000..be57658ed
--- /dev/null
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/hooks/weaving/WeavingHook.java
@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) OSGi Alliance (2010). 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.hooks.weaving;
+
+/**
+ * OSGi Framework Weaving Hook Service.
+ * 
+ * <p>
+ * Bundles registering this service will be called during framework class
+ * loading operations. Weaving hook services are called when a class is being
+ * loaded by the framework and have an opportunity to transform the class file
+ * bytes that represents the class being loaded. Weaving hooks may also ask the
+ * framework to wire in additional dynamic imports to the bundle.
+ * 
+ * <p>
+ * When a class is being loaded, the framework will create a {@link WovenClass}
+ * object for the class and pass it to each registered weaving hook service for
+ * possible modification. The first weaving hook called will see the original
+ * class file bytes. Subsequently called weaving hooks will see the class file
+ * bytes as modified by previously called weaving hooks.
+ * 
+ * @ThreadSafe
+ * @version $Id: d1985029024baba2db1c56aab1e06ee953fd6365 $
+ */
+
+public interface WeavingHook {
+	/**
+	 * Weaving hook method.
+	 * 
+	 * This method can modify the specified woven class object to weave the
+	 * class being defined.
+	 * 
+	 * <p>
+	 * If this method throws any exception, the framework must log the exception
+	 * and fail the class load in progress. This weaving hook service must be
+	 * blacklisted by the framework and must not be called again. The
+	 * blacklisting of this weaving hook service must expire when this weaving
+	 * hook service is unregistered. However, this method can throw a
+	 * {@link WeavingException} to deliberately fail the class load in progress
+	 * without being blacklisted by the framework.
+	 * 
+	 * @param wovenClass The {@link WovenClass} object that represents the data
+	 *        that will be used to define the class.
+	 * @throws WeavingException If this weaving hook wants to deliberately fail
+	 *         the class load in progress without being blacklisted by the
+	 *         framework
+	 */
+	public void weave(WovenClass wovenClass);
+}
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/hooks/weaving/WovenClass.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/hooks/weaving/WovenClass.java
new file mode 100644
index 000000000..58cf64f2e
--- /dev/null
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/hooks/weaving/WovenClass.java
@@ -0,0 +1,147 @@
+/*
+ * Copyright (c) OSGi Alliance (2010). 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.hooks.weaving;
+
+import java.security.ProtectionDomain;
+import java.util.List;
+
+import org.osgi.framework.wiring.BundleWiring;
+
+/**
+ * A class being woven.
+ * 
+ * This object represents a class being woven and is passed to each
+ * {@link WeavingHook} for possible modification. It allows access to the most
+ * recently transformed class file bytes and to any additional packages that
+ * should be added to the bundle as dynamic imports.
+ * 
+ * <p>
+ * After weaving is {@link #isWeavingComplete() complete}, this object becomes
+ * effectively immutable.
+ * 
+ * @NotThreadSafe
+ * @noimplement
+ * @version $Id: f54547066bd0632e85242cac434a6bb8a759dff6 $
+ */
+public interface WovenClass {
+
+	/**
+	 * Returns the class file bytes to be used to define the
+	 * {@link WovenClass#getClassName() named} class.
+	 * 
+	 * <p>
+	 * While weaving is not {@link #isWeavingComplete() complete}, this method
+	 * returns a reference to the class files byte array contained in this
+	 * object. After weaving is {@link #isWeavingComplete() complete}, this
+	 * object becomes effectively immutable and a copy of the class file byte
+	 * array is returned.
+	 * 
+	 * @return The bytes to be used to define the
+	 *         {@link WovenClass#getClassName() named} class.
+	 */
+	public byte[] getBytes();
+
+	/**
+	 * Set the class file bytes to be used to define the
+	 * {@link WovenClass#getClassName() named} class. This method must not be
+	 * called outside invocations of the {@link WeavingHook#weave(WovenClass)
+	 * weave} method by the framework.
+	 * 
+	 * <p>
+	 * While weaving is not {@link #isWeavingComplete() complete}, this method
+	 * replaces the reference to the array contained in this object with the
+	 * specified array. After weaving is {@link #isWeavingComplete() complete},
+	 * this object becomes effectively immutable and this method will throw an
+	 * {@link IllegalStateException}.
+	 * 
+	 * @param newBytes The new classfile that will be used to define the
+	 *        {@link WovenClass#getClassName() named} class. The specified array
+	 *        is retained by this object and the caller must not modify the
+	 *        specified array.
+	 * @throws NullPointerException If newBytes is {@code null}.
+	 * @throws IllegalStateException If weaving is {@link #isWeavingComplete()
+	 *         complete}.
+	 */
+	public void setBytes(byte[] newBytes);
+
+	/**
+	 * Returns the list of dynamic import package descriptions to add to the
+	 * {@link #getBundleWiring() bundle wiring} for this woven class. Changes
+	 * made to the returned list will be visible to later {@link WeavingHook
+	 * weaving hooks} called with this object. The returned list must not be
+	 * modified outside invocations of the {@link WeavingHook#weave(WovenClass)
+	 * weave} method by the framework.
+	 * 
+	 * <p>
+	 * After weaving is {@link #isWeavingComplete() complete}, this object
+	 * becomes effectively immutable and the returned list will be unmodifiable.
+	 * 
+	 * @return A list containing zero or more dynamic import package
+	 *         descriptions to add to the bundle wiring for this woven class.
+	 *         This list must throw {@code IllegalArgumentException} if a
+	 *         malformed dynamic import package description is added.
+	 * @see "Core Specification, Dynamic Import Package, for the syntax of a dynamic import package description."
+	 */
+	public List<String> getDynamicImports();
+
+	/**
+	 * Returns whether weaving is complete in this woven class. Weaving is
+	 * complete after the last {@link WeavingHook weaving hook} is called and
+	 * the class is defined.
+	 * 
+	 * <p>
+	 * After weaving is complete, this object becomes effectively immutable.
+	 * 
+	 * @return {@code true} weaving is complete, {@code false} otherwise.
+	 */
+	public boolean isWeavingComplete();
+
+	/**
+	 * Returns the fully qualified name of the class being woven.
+	 * 
+	 * @return The fully qualified name of the class being woven.
+	 */
+	public String getClassName();
+
+	/**
+	 * Returns the protection domain to which the woven class will be assigned
+	 * when it is defined.
+	 * 
+	 * @return The protection domain to which the woven class will be assigned
+	 *         when it is defined, or {@code null} if no protection domain will
+	 *         be assigned.
+	 */
+	public ProtectionDomain getProtectionDomain();
+
+	/**
+	 * Returns the class associated with this woven class. When loading a class
+	 * for the first time this method will return {@code null} until weaving is
+	 * {@link #isWeavingComplete() complete}. Once weaving is complete, this
+	 * method will return the class object.
+	 * 
+	 * @return The class associated with this woven class, or {@code null} if
+	 *         weaving is not complete or the class definition failed.
+	 */
+	public Class< ? > getDefinedClass();
+
+	/**
+	 * Returns the bundle wiring whose class loader will define the woven class.
+	 * 
+	 * @return The bundle wiring whose class loader will define the woven class.
+	 */
+	public BundleWiring getBundleWiring();
+}