Bug 391275 - OSGi Core source updates for RFC 191: Weaving Hook Enhancements.

3 files changed, 171 insertions, 22 deletions

diff --git a/bundles/org.eclipse.osgi/META-INF/MANIFEST.MF b/bundles/org.eclipse.osgi/META-INF/MANIFEST.MF
index cd9e197..3f4eeb9 100644
--- a/bundles/org.eclipse.osgi/META-INF/MANIFEST.MF
+++ b/bundles/org.eclipse.osgi/META-INF/MANIFEST.MF
@@ -45,7 +45,7 @@ Export-Package: org.eclipse.core.runtime.adaptor;x-friends:="org.eclipse.core.ru
  org.osgi.framework.hooks.bundle;version="1.1",
  org.osgi.framework.hooks.resolver;version="1.0",
  org.osgi.framework.hooks.service;version="1.1",
- org.osgi.framework.hooks.weaving;version="1.0",
+ org.osgi.framework.hooks.weaving;version="1.1",
  org.osgi.framework.launch;version="1.1",
  org.osgi.framework.namespace;version="1.0",
  org.osgi.framework.startlevel;version="1.0",
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
index 549caef..db897c5 100644
--- 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
@@ -29,25 +29,92 @@ import org.osgi.framework.wiring.BundleWiring;
  * should be added to the bundle as dynamic imports.
  * 
  * <p>
- * After weaving is {@link #isWeavingComplete() complete}, this object becomes
- * effectively immutable.
+ * Upon entering one of the terminal states, this object becomes effectively
+ * immutable.
  * 
  * @NotThreadSafe
  * @noimplement
  * @version $Id$
  */
 public interface WovenClass {
+	/**
+	 * The woven class is being transformed.
+	 * 
+	 * <p>
+	 * The woven class is in this state while {@link WeavingHook weaving hooks}
+	 * are being called. The woven class is mutable so the {@link #getBytes()
+	 * class bytes} may be {@link #setBytes(byte[]) modified} and
+	 * {@link #getDynamicImports() dynamic imports} may be added. If a weaving
+	 * hook throws an exception the state transitions to
+	 * {@link #TRANSFORMING_FAILED}. Otherwise, after the last weaving hook has
+	 * been successfully called, the state transitions to {@link #TRANSFORMED}.
+	 * 
+	 * @since 1.1
+	 */
+	int	TRANSFORMING		= 0x00000001;
+
+	/**
+	 * The woven class has been transformed.
+	 * 
+	 * <p>
+	 * The woven class is in this state after {@link WeavingHook weaving hooks}
+	 * have been called and before the class is defined. The woven class cannot
+	 * be further transformed. The woven class is in this state while defining
+	 * the class. If a failure occurs while defining the class, the state
+	 * transitions to {@link #DEFINE_FAILED}. Otherwise, after the class has
+	 * been defined, the state transitions to {@link #DEFINED}.
+	 * 
+	 * @since 1.1
+	 */
+	int	TRANSFORMED			= 0x00000002;
+
+	/**
+	 * The woven class has been defined.
+	 * <p>
+	 * The woven class is in this state after the class is defined. The woven
+	 * class cannot be further transformed. This is a terminal state. Upon
+	 * entering this state, this object is effectively immutable, the
+	 * {@link #getBundleWiring() bundle wiring} has been updated with the
+	 * {@link #getDynamicImports() dynamic import requirements} and the class
+	 * has been {@link #getDefinedClass() defined}.
+	 * 
+	 * @since 1.1
+	 */
+	int	DEFINED				= 0x00000004;
+
+	/**
+	 * The woven class failed to transform.
+	 * <p>
+	 * The woven class is in this state if a {@link WeavingHook weaving hook}
+	 * threw an exception. The woven class cannot be further transformed or
+	 * defined. This is a terminal state. Upon entering this state, this object
+	 * is effectively immutable.
+	 * 
+	 * @since 1.1
+	 */
+	int	TRANSFORMING_FAILED	= 0x00000008;
+
+	/**
+	 * The woven class failed to define.
+	 * <p>
+	 * The woven class is in this state when a failure occurs while defining the
+	 * class. The woven class cannot be further transformed or defined. This is
+	 * a terminal state. Upon entering this state, this object is effectively
+	 * immutable.
+	 * 
+	 * @since 1.1
+	 */
+	int	DEFINE_FAILED		= 0x00000010;
 
 	/**
 	 * 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.
+	 * While in the {@link #TRANSFORMING} state, this method returns a reference
+	 * to the class files byte array contained in this object. After leaving the
+	 * {@link #TRANSFORMING} state, this woven class can no longer be
+	 * transformed 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.
@@ -64,10 +131,10 @@ public interface 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
+	 * While in the {@link #TRANSFORMING} state, this method replaces the
+	 * reference to the array contained in this object with the specified array.
+	 * After leaving the {@link #TRANSFORMING} state, this woven class can no
+	 * longer be transformed and this method will throw an
 	 * {@link IllegalStateException}.
 	 * 
 	 * @param newBytes The new classfile that will be used to define the
@@ -75,8 +142,9 @@ public interface WovenClass {
 	 *        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}.
+	 * @throws IllegalStateException If state is {@link #TRANSFORMED},
+	 *         {@link #DEFINED}, {@link #TRANSFORMING_FAILED} or
+	 *         {@link #DEFINE_FAILED}.
 	 * @throws SecurityException If the caller does not have
 	 *         {@code AdminPermission[bundle,WEAVE]} and the Java runtime
 	 *         environment supports permissions.
@@ -92,8 +160,8 @@ public interface 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.
+	 * After leaving the {@link #TRANSFORMING} state, this woven class can no
+	 * longer be transformed and the returned list will be unmodifiable.
 	 * 
 	 * <p>
 	 * If the Java runtime environment supports permissions, the caller must
@@ -109,13 +177,11 @@ public interface WovenClass {
 
 	/**
 	 * 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.
+	 * complete after the class is defined.
 	 * 
-	 * @return {@code true} weaving is complete, {@code false} otherwise.
+	 * @return {@code true} if {@link #getState() state} is {@link #DEFINED},
+	 *         {@link #TRANSFORMING_FAILED} or {@link #DEFINE_FAILED};
+	 *         {@code false} otherwise.
 	 */
 	public boolean isWeavingComplete();
 
@@ -154,4 +220,16 @@ public interface WovenClass {
 	 * @return The bundle wiring whose class loader will define the woven class.
 	 */
 	public BundleWiring getBundleWiring();
+
+	/**
+	 * Returns the current state of this woven class.
+	 * <p>
+	 * A woven class can be in only one state at any time.
+	 * 
+	 * @return Either {@link #TRANSFORMING}, {@link #TRANSFORMED},
+	 *         {@link #DEFINED}, {@link #TRANSFORMING_FAILED} or
+	 *         {@link #DEFINE_FAILED}.
+	 * @since 1.1
+	 */
+	public int getState();
 }
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/hooks/weaving/WovenClassListener.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/hooks/weaving/WovenClassListener.java
new file mode 100644
index 0000000..0405b08
--- a/dev/null
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/hooks/weaving/WovenClassListener.java
@@ -0,0 +1,71 @@
+/*
+ * Copyright (c) OSGi Alliance (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.hooks.weaving;
+
+
+
+/**
+ * OSGi Framework Woven Class Listener Service.
+ * 
+ * <p>
+ * Bundles registering this service will receive notifications whenever a
+ * {@link WovenClass woven class} completes a {@link WovenClass#getState()
+ * state} transition. Implementers will therefore be unable to modify the woven
+ * class in contrast with {@link WeavingHook weaving hooks}.
+ * 
+ * <p>
+ * Receiving a woven class in the {@link WovenClass#TRANSFORMED TRANSFORMED}
+ * state allows listeners to observe the modified {@link WovenClass#getBytes()
+ * byte codes} before the class has been {@link WovenClass#DEFINED DEFINED} as
+ * well as the additional {@link WovenClass#getDynamicImports() dynamic imports}
+ * before the {@link WovenClass#getBundleWiring() bundle wiring} has been
+ * updated.
+ * 
+ * <p>
+ * Woven class listeners are synchronously {@link #modified(WovenClass) called}
+ * when a woven class completes a state transition. The woven class processing
+ * will not proceed until all woven class listeners are done.
+ * 
+ * <p>
+ * If the Java runtime environment supports permissions, the caller must have
+ * {@code ServicePermission[WovenClassListener,REGISTER]} in order to register a
+ * listener.
+ * 
+ * @ThreadSafe
+ * @since 1.1
+ * @version $Id$
+ */
+
+public interface WovenClassListener {
+	/**
+	 * Receives notification that a {@link WovenClass woven class} has completed
+	 * a state transition.
+	 * 
+	 * <p>
+	 * The listener will be notified when a woven class has entered the
+	 * {@link WovenClass#TRANSFORMED TRANSFORMED}, {@link WovenClass#DEFINED
+	 * DEFINED}, {@link WovenClass#TRANSFORMING_FAILED TRANSFORMING_FAILED} and
+	 * {@link WovenClass#DEFINE_FAILED DEFINE_FAILED} states.
+	 * 
+	 * <p>
+	 * If this method throws any exception, the Framework must log the exception
+	 * but otherwise ignore it.
+	 * 
+	 * @param wovenClass The woven class that completed a state transition.
+	 */
+	public void modified(WovenClass wovenClass);
+}