/*
 * Copyright (c) OSGi Alliance (2016, 2017). 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.annotation.bundle;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Repeatable;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Define a requirement for a bundle.
 * <p>
 * For example:
 * 
 * <pre>
 * &#64;Requirement(namespace=ExtenderNamespace.EXTENDER_NAMESPACE,
 *              name="osgi.component", version="1.3.0")
 * </pre>
 * <p>
 * This annotation is not retained at runtime. It is for use by tools to
 * generate bundle manifests or otherwise process the a package.
 * 
 * @author $Id$
 */
@Documented
@Retention(RetentionPolicy.CLASS)
@Target({
		ElementType.TYPE, ElementType.PACKAGE
})
@Repeatable(Requirements.class)
public @interface Requirement {

	/**
	 * The namespace of this requirement.
	 */
	String namespace();

	/**
	 * The name of this requirement within the namespace.
	 * <p>
	 * If specified, adds an expression, using the {@code &} operator with any
	 * specified {@link #filter()}, to the requirement's filter directive to
	 * test that an attribute with the name of the namespace is equal to the
	 * value of the specified name.
	 */
	String name() default "";

	/**
	 * The floor version of the version range for this requirement.
	 * <p>
	 * If specified, adds a version range expression, using the {@code &}
	 * operator with any specified {@link #filter()}, to the requirement's
	 * filter directive. The ceiling version of the version range is the next
	 * major version from the floor version. For example, if the specified
	 * version is {@code 1.3}, then the version range expression is
	 * {@code (&(version>=1.3)(!(version>=2.0)))}.
	 * <p>
	 * The specified version must be a valid OSGi version string.
	 */
	String version() default "";

	/**
	 * The filter expression of this requirement, if any.
	 */
	String filter() default "";

	/**
	 * The effective time of this requirement.
	 * <p>
	 * Specifies the time the requirement is available. The OSGi framework
	 * resolver only considers requirement without an effective directive or
	 * effective:=resolve. Requirements with other values for the effective
	 * directive can be considered by an external agent.
	 * <p>
	 * If not specified, the {@code effective} directive is omitted from the
	 * requirement clause.
	 */
	String effective() default "resolve"; // Namespace.EFFECTIVE_RESOLVE

	/**
	 * A list of attribute or directive names and values.
	 * <p>
	 * Each string should be specified in the form:
	 * <ul>
	 * <li>{@code "name=value"} for attributes.</li>
	 * <li>{@code "name:type=value"} for typed attributes.</li>
	 * <li>{@code "name:=value"} for directives.</li>
	 * </ul>
	 * These are added, separated by semicolons, to the export package clause.
	 */
	String[] attribute() default {};

	/**
	 * The cardinality of this requirement.
	 * <p>
	 * Indicates if this requirement can be wired a single time or multiple
	 * times.
	 * <p>
	 * If not specified, the {@code cardinality} directive is omitted from the
	 * requirement clause.
	 */
	Cardinality cardinality() default Cardinality.SINGLE;

	/**
	 * Cardinality for this requirement.
	 */
	public enum Cardinality {
		/**
		 * Indicates if the requirement can only be wired a single time.
		 */
		SINGLE,

		/**
		 * Indicates if the requirement can be wired multiple times.
		 */
		MULTIPLE
	}

	/**
	 * The resolution policy of this requirement.
	 * <p>
	 * A mandatory requirement forbids the bundle to resolve when this
	 * requirement is not satisfied; an optional requirement allows a bundle to
	 * resolve even if this requirement is not satisfied.
	 * <p>
	 * If not specified, the {@code resolution} directive is omitted from the
	 * requirement clause.
	 */
	Resolution resolution() default Resolution.MANDATORY;

	/**
	 * Resolution for this requirement.
	 */
	public enum Resolution {
		/**
		 * A mandatory requirement forbids the bundle to resolve when the
		 * requirement is not satisfied.
		 */
		MANDATORY,

		/**
		 * An optional requirement allows a bundle to resolve even if the
		 * requirement is not satisfied.
		 */
		OPTIONAL
	}
}

@@ -41,9 +41,9 @@
  201
-7
+8
 ). A
@@ -3958,17 +3958,59 @@
 %09%09SINGLE
-,
+(%22single%22), // Namespace.CARDINALITY_SINGLE
 %0A%0A%09%09/**%0A
@@ -4088,16 +4088,215 @@
 MULTIPLE
+(%22multiple%22); // Namespace.CARDINALITY_MULTIPLE%0A%0A%09%09private final String value;%0A%0A%09%09Cardinality(String value) %7B%0A%09%09%09this.value = value;%0A%09%09%7D%0A%0A%09%09@Override%0A%09%09public String toString() %7B%0A%09%09%09return value;%0A%09%09%7D
 %0A%09%7D%0A%0A%09/*
@@ -4919,17 +4919,64 @@
 ANDATORY
-,
+(%22mandatory%22), // Namespace.RESOLUTION_MANDATORY
 %0A%0A%09%09/**%0A
@@ -5084,16 +5084,16 @@
 .%0A%09%09 */%0A
-
 %09%09OPTION
@@ -5094,14 +5094,211 @@
 OPTIONAL
+(%22optional%22); // Namespace.RESOLUTION_OPTIONAL%0A%0A%09%09private final String value;%0A%0A%09%09Resolution(String value) %7B%0A%09%09%09this.value = value;%0A%09%09%7D%0A%0A%09%09@Override%0A%09%09public String toString() %7B%0A%09%09%09return value;%0A%09%09%7D
 %0A%09%7D%0A%7D%0A

Add toString implementation for Requirement enums