/*
 * Copyright (c) OSGi Alliance (2010, 2013). 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.annotation.versioning.ProviderType;
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>
 * Upon entering one of the terminal states, this object becomes effectively
 * immutable.
 * 
 * @NotThreadSafe
 * @author $Id: b86db7713c738ae7147fe86f754302e2e324676b $
 */
@ProviderType
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 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.
	 * @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.
	 * 
	 * <p>
	 * 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
	 *        {@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 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.
	 */
	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 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, any modification to
	 * the returned list requires {@code AdminPermission[bundle,WEAVE]}.
	 * Additionally, any add or set modification requires
	 * {@code PackagePermission[package,IMPORT]}.
	 * 
	 * @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 class is defined.
	 * 
	 * @return {@code true} if {@link #getState() state} is {@link #DEFINED},
	 *         {@link #TRANSFORMING_FAILED} or {@link #DEFINE_FAILED};
	 *         {@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();

	/**
	 * 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();
}