org.osgi.framework.hooks.weaving.WovenClass Maven / Gradle / Ivy
Show all versions of payment-retries-plugin Show documentation
/*
* Copyright (c) OSGi Alliance (2010, 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;
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.
*
*
* After weaving is {@link #isWeavingComplete() complete}, this object becomes
* effectively immutable.
*
* @NotThreadSafe
* @noimplement
* @version $Id: 549caef41027c8f0d0fdb4deae756eae6b69d1ee $
*/
public interface WovenClass {
/**
* Returns the class file bytes to be used to define the
* {@link WovenClass#getClassName() named} class.
*
*
* 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.
* @throws SecurityException If the caller does not have
* {@code AdminPermission[bundle,WEAVE]} and the Java runtime
* environment supports permissions.
*/
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.
*
*
* 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}.
* @throws SecurityException If the caller does not have
* {@code AdminPermission[bundle,WEAVE]} and the Java runtime
* environment supports permissions.
*/
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.
*
*
* After weaving is {@link #isWeavingComplete() complete}, this object
* becomes effectively immutable and the returned list will be unmodifiable.
*
*
* If the Java runtime environment supports permissions, the caller must
* have {@code AdminPermission[bundle,WEAVE]} to modify the returned list.
*
* @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 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.
*
*
* 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 defined by this woven class. During weaving, this
* method will return {@code null}. Once weaving is
* {@link #isWeavingComplete() complete}, this method will return the class
* object if this woven class was used to define the class.
*
* @return The class associated with this woven class, or {@code null} if
* weaving is not complete, the class definition failed or this
* woven class was not used to define the class.
*/
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();
}