summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJohn Ross2012-10-05 16:48:35 (EDT)
committer Thomas Watson2012-10-17 16:41:37 (EDT)
commit52dbb846c9aad917ea6ec65ca9ca8bedd74919c5 (patch)
treea0b56cc2170ac538c74b9d6f88caee1a774611dc
parent2bfd4c08f3fb44d9aa62f08200666621c75f7fe9 (diff)
downloadrt.equinox.framework-52dbb846c9aad917ea6ec65ca9ca8bedd74919c5.zip
rt.equinox.framework-52dbb846c9aad917ea6ec65ca9ca8bedd74919c5.tar.gz
rt.equinox.framework-52dbb846c9aad917ea6ec65ca9ca8bedd74919c5.tar.bz2
Bug 391275 - OSGi Core source updates for RFC 191: Weaving Hook Enhancements.
-rw-r--r--bundles/org.eclipse.osgi/META-INF/MANIFEST.MF2
-rw-r--r--bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/hooks/weaving/WovenClass.java120
-rw-r--r--bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/hooks/weaving/WovenClassListener.java71
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
--- /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);
+}