[webbeans-commits] Webbeans SVN: r1246 - in ri/trunk: webbeans-api/src/main/java/javax/context and 6 other directories.

Author: pete.muir(a)jboss.org Date: 2009-01-27 10:25:32 -0500 (Tue, 27 Jan 2009) New Revision: 1246 Modified: ri/trunk/webbeans-api/src/main/java/javax/annotation/Named.java ri/trunk/webbeans-api/src/main/java/javax/annotation/Stereotype.java ri/trunk/webbeans-api/src/main/java/javax/context/ApplicationScoped.java ri/trunk/webbeans-api/src/main/java/javax/context/Context.java ri/trunk/webbeans-api/src/main/java/javax/context/ContextNotActiveException.java ri/trunk/webbeans-api/src/main/java/javax/context/Contextual.java ri/trunk/webbeans-api/src/main/java/javax/context/Conversation.java ri/trunk/webbeans-api/src/main/java/javax/context/ConversationScoped.java ri/trunk/webbeans-api/src/main/java/javax/context/Dependent.java ri/trunk/webbeans-api/src/main/java/javax/context/RequestScoped.java ri/trunk/webbeans-api/src/main/java/javax/context/ScopeType.java ri/trunk/webbeans-api/src/main/java/javax/context/SessionScoped.java ri/trunk/webbeans-api/src/main/java/javax/decorator/Decorates.java ri/trunk/webbeans-api/src/main/java/javax/decorator/Decorator.java ri/trunk/webbeans-api/src/main/java/javax/event/AfterTransactionCompletion.java ri/trunk/webbeans-api/src/main/java/javax/event/AfterTransactionFailure.java ri/trunk/webbeans-api/src/main/java/javax/event/AfterTransactionSuccess.java ri/trunk/webbeans-api/src/main/java/javax/event/BeforeTransactionCompletion.java ri/trunk/webbeans-api/src/main/java/javax/event/Event.java ri/trunk/webbeans-api/src/main/java/javax/event/IfExists.java ri/trunk/webbeans-api/src/main/java/javax/event/Observer.java ri/trunk/webbeans-api/src/main/java/javax/event/ObserverException.java ri/trunk/webbeans-api/src/main/java/javax/event/Observes.java ri/trunk/webbeans-api/src/main/java/javax/inject/AmbiguousDependencyException.java ri/trunk/webbeans-api/src/main/java/javax/inject/AnnotationLiteral.java ri/trunk/webbeans-api/src/main/java/javax/inject/BindingType.java ri/trunk/webbeans-api/src/main/java/javax/inject/CreationException.java ri/trunk/webbeans-api/src/main/java/javax/inject/DefinitionException.java ri/trunk/webbeans-api/src/main/java/javax/inject/DeploymentException.java ri/trunk/webbeans-api/src/main/java/javax/inject/DeploymentType.java ri/trunk/webbeans-api/src/main/java/javax/inject/Disposes.java ri/trunk/webbeans-api/src/main/java/javax/inject/ExecutionException.java ri/trunk/webbeans-api/src/main/java/javax/inject/IllegalProductException.java ri/trunk/webbeans-api/src/main/java/javax/inject/InconsistentSpecializationException.java ri/trunk/webbeans-api/src/main/java/javax/inject/Initializer.java ri/trunk/webbeans-api/src/main/java/javax/inject/Instance.java ri/trunk/webbeans-api/src/main/java/javax/inject/NullableDependencyException.java ri/trunk/webbeans-api/src/main/java/javax/inject/Produces.java ri/trunk/webbeans-api/src/main/java/javax/inject/Standard.java ri/trunk/webbeans-api/src/main/java/javax/inject/TypeLiteral.java ri/trunk/webbeans-api/src/main/java/javax/inject/UnproxyableDependencyException.java ri/trunk/webbeans-api/src/main/java/javax/inject/UnsatisfiedDependencyException.java ri/trunk/webbeans-api/src/main/java/javax/inject/UnserializableDependencyException.java ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Bean.java ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Decorator.java ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Deployed.java ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Initialized.java ri/trunk/webbeans-api/src/main/java/javax/inject/manager/InterceptionType.java ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Interceptor.java ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Manager.java ri/trunk/webbeans-api/src/main/java/javax/interceptor/Interceptor.java ri/trunk/webbeans-api/src/main/java/javax/interceptor/InterceptorBindingType.java ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/ManagerImpl.java Log: javadoc Modified: ri/trunk/webbeans-api/src/main/java/javax/annotation/Named.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/annotation/Named.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/annotation/Named.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -27,7 +27,7 @@ import java.lang.annotation.Target; /** - * Specifies the name of a Web Bean. + * Specifies the name of a bean. * * @author Gavin King * @author Pete Muir @@ -42,9 +42,16 @@ /** * If no name is explicitly specified, the default name is used. * - * @return the component name + * For simple beans and session beans the default name is the unqualified + * class name of the bean class, after converting the first character to + * lower case. + * + * For producer methods the default name is the method name, unless the + * method follows the JavaBeans property getter naming convention, in which + * case the default name is the JavaBeans property name. + * + * @return the bean name */ - public String value() default ""; } Modified: ri/trunk/webbeans-api/src/main/java/javax/annotation/Stereotype.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/annotation/Stereotype.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/annotation/Stereotype.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -26,7 +26,7 @@ import java.lang.annotation.Target; /** - * Specifies that an annotation type is a Web Beans stereotype. + * Specifies that an annotation type is a stereotype. * * @author Pete Muir * @author Gavin King @@ -38,8 +38,18 @@ public @interface Stereotype { + /** + * Restrict the scope of the stereotyped bean + * + * @return the allowed scopes + */ public Class<? extends Annotation>[] supportedScopes() default {}; + /** + * Require that stereotype beans have certain API types + * + * @return the required types + */ public Class<?>[] requiredTypes() default {}; } Modified: ri/trunk/webbeans-api/src/main/java/javax/context/ApplicationScoped.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/context/ApplicationScoped.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/context/ApplicationScoped.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -28,10 +28,9 @@ import java.lang.annotation.Target; /** - * Specifies that a Web Bean is application scoped. + * Specifies that a bean is application scoped. * * @author Gavin King - * * @author Pete Muir */ Modified: ri/trunk/webbeans-api/src/main/java/javax/context/Context.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/context/Context.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/context/Context.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -20,7 +20,7 @@ import java.lang.annotation.Annotation; /** - * The contract between the Web Bean manager and a Web Beans context object. + * The contract between the manager and a contextual object. * This interface should not be called directly by the application. * * @author Gavin King @@ -30,12 +30,44 @@ public interface Context { + /** + * The scope which this context implements + * + * @return the scope + */ public Class<? extends Annotation> getScopeType(); + /** + * Return an existing instance of a contextual type or create a new instance + * of a contextual type + * + * @param <T> the type of contextual type + * @param contextual the contextual type + * @param creationalContext the creational context in which incompletely + * initialized may be placed + * @return the contextual instance, or null if no creational context is given + * and an instance does not exist in the context + * @throws ContextNotActiveException if the context is not active + */ public <T> T get(Contextual<T> contextual, CreationalContext<T> creationalContext); + /** + * Return an existing instance of a contextual type or create a new instance + * of a contextual type + * + * @param <T> the type of the contextual type + * @param contextual the contextual type + * @return the contextual instance, or null if an instance does not exist in + * the context + * @throws ContextNotActiveException if the context is not active + */ public <T> T get(Contextual<T> contextual); + /** + * The context is only active at certain points in the application lifecycle + * + * @return true if the context is active + */ boolean isActive(); } Modified: ri/trunk/webbeans-api/src/main/java/javax/context/ContextNotActiveException.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/context/ContextNotActiveException.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/context/ContextNotActiveException.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -33,6 +33,8 @@ public class ContextNotActiveException extends ExecutionException { + private static final long serialVersionUID = -3599813072560026919L; + public ContextNotActiveException() { super(); Modified: ri/trunk/webbeans-api/src/main/java/javax/context/Contextual.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/context/Contextual.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/context/Contextual.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -17,15 +17,31 @@ package javax.context; +import javax.inject.CreationException; + /** - * The contract between a Context and an object that has its lifecycle managed - * by the context + * The contract between a context and a contextual type + * This interface should not be implemented directly by the application. * * @author Nicklas Karlsson + * @author Pete Muir */ public interface Contextual<T> { + /** + * Create a new instance of the contextual type + * + * @param creationalContext the creational context in which incompletely + * initialized contexts may be placed + * @return the contextual instance + * @throws CreationException if a checked exception occurs whilst creating + * the instance + */ public T create(CreationalContext<T> creationalContext); + /** + * Destroys an instance of the contexual type + * @param instance the insance to destroy + */ public void destroy(T instance); } Modified: ri/trunk/webbeans-api/src/main/java/javax/context/Conversation.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/context/Conversation.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/context/Conversation.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -1,11 +1,76 @@ +/* +* JBoss, Home of Professional Open Source +* Copyright 2008, Red Hat Middleware LLC, and individual contributors +* by the @authors tag. See the copyright.txt in the distribution for a +* full listing of individual contributors. +* +* 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 javax.context; -public interface Conversation { +/** + * Provides conversation management operations + * + * @author Pete Muir + * + */ +public interface Conversation +{ + + /** + * Mark a transient conversation long running. The container will generate an + * id + */ public void begin(); + + /** + * Mark a transient conversation long running. + * + * @param id the id of the conversation + */ public void begin(String id); + + /** + * Mark a long running conversation transient + */ public void end(); + + /** + * Determine if a conversation is long running or transient + * + * @return true if the conversation is long running + */ public boolean isLongRunning(); + + /** + * Get the id associated with the current long running conversation + * + * @return the id of the current long running conversation + */ public String getId(); + + /** + * Get the timeout for the current long running conversation. + * + * The conversation will destroy the conversation if it has not been accessed + * within this time period. + * + * @return the current timeout in milliseconds + */ public long getTimeout(); + + /** + * Set the timeout for the current long running conversation + * + * @param milliseconds the new timeout in milliseconds + */ public void setTimeout(long milliseconds); } \ No newline at end of file Modified: ri/trunk/webbeans-api/src/main/java/javax/context/ConversationScoped.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/context/ConversationScoped.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/context/ConversationScoped.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -27,7 +27,7 @@ import java.lang.annotation.Target; /** - * Specifies that a Web Bean is conversation scoped. + * Specifies that a bean is conversation scoped. * * @author Gavin King * @author Pete Muir Modified: ri/trunk/webbeans-api/src/main/java/javax/context/Dependent.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/context/Dependent.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/context/Dependent.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -28,7 +28,7 @@ import java.lang.annotation.Target; /** - * Specifies that a Web Bean is dependent scoped. + * Specifies that a bean is dependent scoped. * * @author Gavin King * @author Pete Muir Modified: ri/trunk/webbeans-api/src/main/java/javax/context/RequestScoped.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/context/RequestScoped.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/context/RequestScoped.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -28,7 +28,7 @@ import java.lang.annotation.Target; /** - * Specifies that a Web Bean is request scoped. + * Specifies that a bean is request scoped. * * @author Gavin King * @author Pete Muir Modified: ri/trunk/webbeans-api/src/main/java/javax/context/ScopeType.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/context/ScopeType.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/context/ScopeType.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -25,7 +25,7 @@ import java.lang.annotation.Target; /** - * Specifies that an annotation type is a Web Beans scope type. + * Specifies that an annotation type is a scope type. * * @author Gavin King * @author Pete Muir @@ -43,7 +43,7 @@ boolean normal() default true; /** - * @return true if this is a passivating scope (Web Beans with this scope + * @return true if this is a passivating scope (beans with this scope * type must be serializable) */ boolean passivating() default false; Modified: ri/trunk/webbeans-api/src/main/java/javax/context/SessionScoped.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/context/SessionScoped.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/context/SessionScoped.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -28,7 +28,7 @@ import java.lang.annotation.Target; /** - * Specifies that a Web Bean is session scoped. + * Specifies that a bean is session scoped. * * @author Gavin King * @author Pete Muir Modified: ri/trunk/webbeans-api/src/main/java/javax/decorator/Decorates.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/decorator/Decorates.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/decorator/Decorates.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -30,7 +30,6 @@ * @author Gavin King * @author Pete Muir */ - @Target(FIELD) @Retention(RUNTIME) @Documented Modified: ri/trunk/webbeans-api/src/main/java/javax/decorator/Decorator.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/decorator/Decorator.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/decorator/Decorator.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -27,12 +27,11 @@ import javax.annotation.Stereotype; /** - * Specifies that a class is a Web Beans decorator. + * Specifies that a class is a decorator. * * @author Gavin King * @author Pete Muir */ - @Target(TYPE) @Retention(RUNTIME) @Documented Modified: ri/trunk/webbeans-api/src/main/java/javax/event/AfterTransactionCompletion.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/event/AfterTransactionCompletion.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/event/AfterTransactionCompletion.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -24,7 +24,7 @@ import java.lang.annotation.Target; /** - * Specifies that an observer method is a transactional observer. + * Specifies that an observer method is an after transaction completion observer. * * @author Gavin King * Modified: ri/trunk/webbeans-api/src/main/java/javax/event/AfterTransactionFailure.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/event/AfterTransactionFailure.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/event/AfterTransactionFailure.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -24,7 +24,7 @@ import java.lang.annotation.Target; /** - * Specifies that an observer method is a transactional observer. + * Specifies that an observer method is an after transaction failure observer. * * @author Gavin King * Modified: ri/trunk/webbeans-api/src/main/java/javax/event/AfterTransactionSuccess.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/event/AfterTransactionSuccess.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/event/AfterTransactionSuccess.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -24,7 +24,7 @@ import java.lang.annotation.Target; /** - * Specifies that an observer method is a transactional observer. + * Specifies that an observer method is an transaction failure observer. * * @author Gavin King * Modified: ri/trunk/webbeans-api/src/main/java/javax/event/BeforeTransactionCompletion.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/event/BeforeTransactionCompletion.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/event/BeforeTransactionCompletion.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -24,7 +24,8 @@ import java.lang.annotation.Target; /** - * Specifies that an observer method is a transactional observer. + * Specifies that an observer method is an after transaction completion + * observer. * * @author Gavin King * Modified: ri/trunk/webbeans-api/src/main/java/javax/event/Event.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/event/Event.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/event/Event.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -27,14 +27,26 @@ * @author Pete Muir * * @param <T> -* the type of the event object + * the type of the event object */ public interface Event<T> { + /** + * Fire an event + * + * @param event the event type + * @param bindings the event bindings + */ public void fire(T event, Annotation... bindings); + /** + * Register an observer for a specific type + * + * @param observer the observer to register + * @param bindings the bindings to observe the event for + */ public void observe(Observer<T> observer, Annotation... bindings); } Modified: ri/trunk/webbeans-api/src/main/java/javax/event/IfExists.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/event/IfExists.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/event/IfExists.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -26,7 +26,7 @@ /** * Specifies that an observer method is only called if the current instance of - * the Web Bean declaring the observer method already exists. + * the bean declaring the observer method already exists. * * @author Gavin King * @author Pete Muir Modified: ri/trunk/webbeans-api/src/main/java/javax/event/Observer.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/event/Observer.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/event/Observer.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -1,7 +1,7 @@ package javax.event; /** - * The contract between the Web Bean manager and a Web Beans observer object. + * The contract between the manager and an observer object. * This interface should not be called directly by the application. * * @author Gavin King Modified: ri/trunk/webbeans-api/src/main/java/javax/event/ObserverException.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/event/ObserverException.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/event/ObserverException.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -20,6 +20,8 @@ import javax.inject.ExecutionException; /** + * Wraps any checked exceptions which occur during the notification of an + * observer * * @author Pete Muir */ @@ -27,6 +29,8 @@ public class ObserverException extends ExecutionException { + private static final long serialVersionUID = -801836224808304381L; + public ObserverException() { Modified: ri/trunk/webbeans-api/src/main/java/javax/event/Observes.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/event/Observes.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/event/Observes.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -25,7 +25,7 @@ import java.lang.annotation.Target; /** - * Specifies that a parameter of a method of a Web Bean + * Specifies that a parameter of a method of a bean * implementation class is the event parameter * of an observer method. * Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/AmbiguousDependencyException.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/AmbiguousDependencyException.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/AmbiguousDependencyException.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -18,16 +18,18 @@ package javax.inject; /** - * An AmbiguousDependencyException is thrown when within the set of enabled Web - * Beans with the API type and bind- ing types declared there exists no unique - * Web Bean with a higher precedence than all other Web Beans in the set. + * An AmbiguousDependencyException is thrown when within the set of enabled + * beans with the API type and bind- ing types declared there exists no unique + * Web Bean with a higher precedence than all other beans in the set. * * * @author Pete Muir */ public class AmbiguousDependencyException extends DeploymentException { - + + private static final long serialVersionUID = -2132733164534544788L; + public AmbiguousDependencyException() { } Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/AnnotationLiteral.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/AnnotationLiteral.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/AnnotationLiteral.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -17,8 +17,15 @@ package javax.inject; +import java.lang.annotation.Annotation; +import java.lang.reflect.InvocationTargetException; +import java.lang.reflect.Method; +import java.lang.reflect.ParameterizedType; +import java.lang.reflect.Type; + + /** - * Supports inline instantiation of annotation types. + * Supports inline instantiation of annotation type instances. * * @author Pete Muir * @author Gavin King @@ -26,13 +33,6 @@ * @param <T> * the annotation type */ -import java.lang.annotation.Annotation; -import java.lang.reflect.InvocationTargetException; -import java.lang.reflect.Method; -import java.lang.reflect.ParameterizedType; -import java.lang.reflect.Type; - - public abstract class AnnotationLiteral<T extends Annotation> implements Annotation { @@ -91,11 +91,21 @@ return null; } + /** + * {@inheritDoc} + * + * @return {@inheritDoc} + */ public Class<? extends Annotation> annotationType() { return annotationType; } + /** + * {@inheritDoc} + * + * @return {@inheritDoc} + */ @Override public String toString() { @@ -112,6 +122,12 @@ return string + ")"; } + /** + * {@inheritDoc} + * + * @param other {@inheritDoc} + * @return {@inheritDoc} + */ @Override public boolean equals(Object other) { @@ -136,10 +152,10 @@ } @Override - /* - * The hash code of a primitive value v is equal to WrapperType.valueOf(v).hashCode(), where WrapperType is the wrapper type corresponding to the primitive type of v (Byte, Character, Double, Float, Integer, Long, Short, or Boolean). - * The hash code of a string, enum, class, or annotation member-value I v is computed as by calling v.hashCode(). (In the case of annotation member values, this is a recursive definition.) - * The hash code of an array member-value is computed by calling the appropriate overloading of Arrays.hashCode on the value. (There is one overloading for each primitive type, and one for object reference types.) + /** + * {@inheritDoc} + * + * @return {@inheritDoc} */ public int hashCode() { Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/BindingType.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/BindingType.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/BindingType.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -26,7 +26,7 @@ /** * - * Specifies that an annotation type is a Web Beans binding type. + * Specifies that an annotation type is a binding type. * * @author Pete Muir * @author Gavin King Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/CreationException.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/CreationException.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/CreationException.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -18,13 +18,15 @@ package javax.inject; /** + * Wraps any checked exceptions which occur during creation of an bean * * @author Pete Muir */ - public class CreationException extends ExecutionException { + private static final long serialVersionUID = 1002854668862145298L; + public CreationException() { Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/DefinitionException.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/DefinitionException.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/DefinitionException.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -18,12 +18,15 @@ package javax.inject; /** + * Thrown if the definition of a bean is incorrect * * @author Pete Muir */ public class DefinitionException extends RuntimeException { + private static final long serialVersionUID = 8014646336322875707L; + public DefinitionException() { super(); Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/DeploymentException.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/DeploymentException.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/DeploymentException.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -18,12 +18,15 @@ package javax.inject; /** + * Thrown if an error occurs during bean deployment * * @author Pete Muir */ public class DeploymentException extends RuntimeException { + private static final long serialVersionUID = -332013557319725211L; + public DeploymentException() { super(); Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/DeploymentType.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/DeploymentType.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/DeploymentType.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -25,7 +25,7 @@ import java.lang.annotation.Target; /** - * Specifies that an annotation type is a Web Beans deployment type. + * Specifies that an annotation type is a deployment type. * * @author Gavin King * @author Pete Muir Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/Disposes.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/Disposes.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/Disposes.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -25,8 +25,8 @@ import java.lang.annotation.Target; /** - * Specifies that a parameter of a method of a Web Bean implementation class - * class is the disposed parameter of a disposal method. + * Specifies that a parameter of a method of bean is the disposed parameter + * of a disposal method. * * @author Gavin King * @author Pete Muir Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/ExecutionException.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/ExecutionException.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/ExecutionException.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -19,12 +19,15 @@ package javax.inject; /** + * Thrown if an exception occurs during execution * * @author Pete Muir */ public class ExecutionException extends RuntimeException { + private static final long serialVersionUID = -4418792077313780514L; + public ExecutionException() { super(); Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/IllegalProductException.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/IllegalProductException.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/IllegalProductException.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -17,10 +17,14 @@ package javax.inject; /** + * Thrown if a producer method returns a null value or a producer field contains + * a null value, and the scope of the method or field is not @Dependent */ public class IllegalProductException extends ExecutionException { + private static final long serialVersionUID = -6280627846071966243L; + public IllegalProductException() { super(); Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/InconsistentSpecializationException.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/InconsistentSpecializationException.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/InconsistentSpecializationException.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -25,6 +25,8 @@ public class InconsistentSpecializationException extends DeploymentException { + private static final long serialVersionUID = 4359656880524913555L; + public InconsistentSpecializationException() { super(); Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/Initializer.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/Initializer.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/Initializer.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -17,8 +17,8 @@ package javax.inject; +import static java.lang.annotation.ElementType.CONSTRUCTOR; import static java.lang.annotation.ElementType.METHOD; -import static java.lang.annotation.ElementType.CONSTRUCTOR; import static java.lang.annotation.RetentionPolicy.RUNTIME; import java.lang.annotation.Documented; @@ -26,8 +26,8 @@ import java.lang.annotation.Target; /** - * Specifies that a method of a Web Bean implementation class is a Web Beans - * initializer method, or that a constructor is the Web Bean constructor. + * Specifies that a method of a bean is a bean initializer method, or that a + * constructor is the bean constructor. * * @author Gavin King * @author Pete Muir Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/Instance.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/Instance.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/Instance.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -21,7 +21,7 @@ /** - * An interface for looking up web beans of a particular type. + * An interface for looking up beans of a particular type. * * @author Gavin King * @@ -32,13 +32,13 @@ public interface Instance<T> { /** - * Get an instance of a Web Bean of the specified type. + * Get an instance of a bean of the specified type. * * Additional binding annotations may be specified at the injection point. * * @param bindings * Additional binding types - * @return an instance of a Web Bean of the specified type + * @return an instance of a bean of the specified type * @throws DuplicateBindingTypeException * if two instances of the same binding type are passed * @throws IllegalArgumentException Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/NullableDependencyException.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/NullableDependencyException.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/NullableDependencyException.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -19,12 +19,16 @@ package javax.inject; /** + * Thrown if an injection point of primitive type resolves to a bean which may + * be null * * @author Pete Muir */ public class NullableDependencyException extends DeploymentException { + private static final long serialVersionUID = 6877485218767005761L; + public NullableDependencyException() { super(); Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/Produces.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/Produces.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/Produces.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -17,8 +17,8 @@ package javax.inject; -import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; import java.lang.annotation.Documented; @@ -27,8 +27,7 @@ /** * - * Specifies that a method of a Web Bean implementation class is a producer - * method. + * Specifies that a method of a bean is a producer method. * * @author Gavin King * @author Pete Muir Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/Standard.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/Standard.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/Standard.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -27,8 +27,7 @@ import java.lang.annotation.Target; /** - * Deployment type for standard components defined by the Web Beans - * specification. + * Deployment type for standard components defined by the JSR-299 specification. * * @author Gavin King * @author Pete Muir Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/TypeLiteral.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/TypeLiteral.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/TypeLiteral.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -50,11 +50,21 @@ } } + /** + * Get the actual type represented by type literal + * + * @return + */ public final Type getType() { return actualType; } + /** + * Get the raw type represented by the type literal + * + * @return + */ @SuppressWarnings("unchecked") public final Class<T> getRawType() { Type type = getType(); Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/UnproxyableDependencyException.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/UnproxyableDependencyException.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/UnproxyableDependencyException.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -19,12 +19,16 @@ package javax.inject; /** + * Thrown if a bean has normal scope and the type cannot be proxied by the + * container * * @author Pete Muir */ public class UnproxyableDependencyException extends DeploymentException { + private static final long serialVersionUID = 1667539354548135465L; + public UnproxyableDependencyException() { super(); Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/UnsatisfiedDependencyException.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/UnsatisfiedDependencyException.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/UnsatisfiedDependencyException.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -19,12 +19,15 @@ package javax.inject; /** + * Thrown if no beans can be resolved * * @author Pete Muir */ public class UnsatisfiedDependencyException extends DeploymentException { + private static final long serialVersionUID = 5350603312442756709L; + public UnsatisfiedDependencyException() { super(); Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/UnserializableDependencyException.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/UnserializableDependencyException.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/UnserializableDependencyException.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -19,12 +19,18 @@ package javax.inject; /** + * Thrown if a simple bean is dependent scoped and injected into a stateful + * session bean, into a non-transient field, bean constructor parameter or + * initializer method parameter of a bean which declares a passivating scope, or + * into a parameter of a producer method which declares a passivating scope * * @author Pete Muir */ public class UnserializableDependencyException extends DeploymentException { + private static final long serialVersionUID = -6287506607413810688L; + public UnserializableDependencyException() { super(); Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Bean.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Bean.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Bean.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -24,41 +24,91 @@ import javax.context.Contextual; /** - * The contract between the Web Bean manager and a Web Bean. This interface + * The contract between the manager and a bean. This interface * should not be called directly by the application. * * @author Gavin King * - * @param <T> an API type of the Web Bean + * @param <T> an API type of the bean */ public abstract class Bean<T> implements Contextual<T> { private final Manager manager; + /** + * Create an instance of a bean + * + * @param manager + */ protected Bean(Manager manager) { this.manager = manager; } + /** + * Get the manager used to create this bean + * + * @return an instance of the manager + */ protected Manager getManager() { return manager; } + /** + * The client-visible types of a bean + * + * @return the bean types + */ public abstract Set<Type> getTypes(); + /** + * The bindings of a bean + * + * @return the bindings + */ public abstract Set<Annotation> getBindings(); + /** + * The scope of a bean + * + * @return the scope + */ public abstract Class<? extends Annotation> getScopeType(); + /** + * The deployment type of a bean + * + * @return the deployment type + */ public abstract Class<? extends Annotation> getDeploymentType(); + /** + * The name of a bean + * + * @return the name + */ public abstract String getName(); + /** + * The serializability of a bean + * + * @return true if the bean is serializable + */ public abstract boolean isSerializable(); + /** + * The nullability of a bean + * + * @return true if the bean is nullable + */ public abstract boolean isNullable(); + /** + * The injection points of a bean + * + * @return the injection points of a bean + */ public abstract Set<? extends InjectionPoint> getInjectionPoints(); } Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Decorator.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Decorator.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Decorator.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -20,18 +20,48 @@ import java.lang.annotation.Annotation; import java.util.Set; +/** + * The Bean object for a a decorator + * + * This interface should not be called directly by the application. + * + * @author Pete Muir + * + */ public abstract class Decorator extends Bean<Object> { + /** + * Create an interceptor bean + * + * @param manager + * the manager to create the interceptor for + */ protected Decorator(Manager manager) { super(manager); } + /** + * Obtains the type of the decorated bean + * + * @return + */ public abstract Class<?> getDelegateType(); + /** + * Obtains the bindings of the decorated bean + * + * @return + */ public abstract Set<Annotation> getDelegateBindings(); + /** + * Injects the delegate + * + * @param instance the instance to inject the delegate into + * @param delegate the delegate to inject + */ public abstract void setDelegate(Object instance, Object delegate); } Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Deployed.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Deployed.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Deployed.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -27,8 +27,10 @@ import javax.inject.BindingType; /** - * Event binding type for the event that is raised by the Web Bean manager when + * Event binding type for the event that is raised by the manager when * it has completed resolving and validation + * + * @author Pete Muir */ @BindingType Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Initialized.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Initialized.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Initialized.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -27,8 +27,10 @@ import javax.inject.BindingType; /** - * Event binding type for the event that is raised by the Web Bean manager when + * Event binding type for the event that is raised by the manager when * it has completed discovery and bean creation + * + * @author Pete Muir */ @BindingType @Retention(RUNTIME) Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/manager/InterceptionType.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/manager/InterceptionType.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/manager/InterceptionType.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -17,7 +17,37 @@ package javax.inject.manager; +/** + * Identifies the kind of lifecycle callback or business method + * + * @author Pete Muir + * + */ public enum InterceptionType { - AROUND_INVOKE, POST_CONSTRUCT, PRE_DESTROY, PRE_PASSIVATE, POST_ACTIVATE + + /** + * Intercepts method invocation + */ + AROUND_INVOKE, + + /** + * Intercepts bean construction + */ + POST_CONSTRUCT, + + /** + * Intercepts bean destruction + */ + PRE_DESTROY, + + /** + * Intercepts bean passivation + */ + PRE_PASSIVATE, + + /** + * Intercepts bean activation + */ + POST_ACTIVATE } \ No newline at end of file Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Interceptor.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Interceptor.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Interceptor.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -21,16 +21,44 @@ import java.lang.reflect.Method; import java.util.Set; +/** + * The contract between the manager and a interceptor. + * + * This interface should not be called directly by the application. + * + * @author Pete Muir + * + */ public abstract class Interceptor extends Bean<Object> { - + + /** + * Create an interceptor bean + * + * @param manager + * the manager to create the interceptor for + */ protected Interceptor(Manager manager) { super(manager); } - + + /** + * The interceptor bindings used to bind an interceptor to a bean + * + * @return the interceptor bindings + */ public abstract Set<Annotation> getInterceptorBindingTypes(); - + + /** + * The interceptor method for the specified lifecycle callback or business + * method + * + * @param type + * the interception type + * @return the method, or null if the interceptor does not intercept + * lifecycle callbacks or business methods + */ public abstract Method getMethod(InterceptionType type); - + } Modified: ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Manager.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Manager.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/inject/manager/Manager.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -24,68 +24,448 @@ import java.util.Set; import javax.context.Context; +import javax.context.ContextNotActiveException; import javax.context.CreationalContext; import javax.event.Observer; +import javax.inject.AmbiguousDependencyException; +import javax.inject.DuplicateBindingTypeException; import javax.inject.TypeLiteral; +import javax.inject.UnsatisfiedDependencyException; /** - * The contract between the application and the Web Bean manager. Also the - * contract between the Web Bean manager and Bean, Context and Observer objects. + * The contract between the application and the manager. Also the contract + * between the manager and Bean, Context and Observer objects. * + * The application should not normally need to call this interface. + * * @author Gavin King + * @author Pete Muir * */ public interface Manager { - - public <T> Set<Bean<T>> resolveByType(Class<T> apiType, Annotation... bindings); - - public <T> Set<Bean<T>> resolveByType(TypeLiteral<T> apiType, Annotation... bindings); - + + /** + * Allows beans to be matched to injection point by considering bean type, + * bindings, and deployment precedence. + * + * Typesafe resolution usually occurs at container deployment time. + * + * @param <T> + * the type of the beans to be resolved + * @param type + * the type of the beans to be resolved + * @param bindings + * the bindings used to restrict the matched beans + * @return the matched beans + * @throws IllegalArgumentException + * if a parameterized type with a type parameter or a wildcard is + * passed + * @throws IllegalArgumentException + * if an annotation which is not a binding type is passed + * @throws DuplicateBindingTypeException + * if two instances of the same binding type are passed + */ + public <T> Set<Bean<T>> resolveByType(Class<T> type, Annotation... bindings); + + /** + * Allows beans to be matched to injection point by considering bean type, + * bindings, and deployment precedence. + * + * Typesafe resolution usually occurs at container deployment time. + * + * @param <T> + * the type of the beans to be resolved + * @param type + * the type of the beans to be resolved + * @param bindings + * the bindings used to restrict the matched beans + * @return the matched beans + * @throws IllegalArgumentException + * if a parameterized type with a type parameter or a wildcard is + * passed + * @throws IllegalArgumentException + * if an annotation which is not a binding type is passed + * @throws DuplicateBindingTypeException + * if two instances of the same binding type are passed + */ + public <T> Set<Bean<T>> resolveByType(TypeLiteral<T> type, Annotation... bindings); + + /** + * Obtains an instance of a bean by considering bean type, bindings, and + * deployment precedence. + * + * @param <T> + * the type of the bean to obtain + * @param type + * the type of the bean to obtain + * @param bindings + * the bindings used to restrict the matched beans + * @return an instance of the bean + * @throws IllegalArgumentException + * if a parameterized type with a type parameter or a wildcard is + * passed + * @throws IllegalArgumentException + * if an annotation which is not a binding type is passed + * @throws DuplicateBindingTypeException + * if two instances of the same binding type are passed + * @throws UnsatisfiedDependencyException + * if no bean can be resolved for the given type and bindings + * @throws AmbiguousDependencyException + * if more than one bean is resolved for the given type and + * bindings + */ public <T> T getInstanceByType(Class<T> type, Annotation... bindings); - + + /** + * Obtains an instance of a bean by considering bean type, bindings, and + * deployment precedence. + * + * @param <T> + * the type of the bean to obtain + * @param type + * the type of the bean to obtain + * @param bindings + * the bindings used to restrict the matched beans + * @return an instance of the bean + * @throws IllegalArgumentException + * if a parameterized type with a type parameter or a wildcard is + * passed + * @throws IllegalArgumentException + * if an annotation which is not a binding type is passed + * @throws DuplicateBindingTypeException + * if two instances of the same binding type are passed + * @throws UnsatisfiedDependencyException + * if no bean can be resolved for the given type and bindings + * @throws AmbiguousDependencyException + * if more than one bean is resolved for the given type and + * bindings + */ public <T> T getInstanceByType(TypeLiteral<T> type, Annotation... bindings); - + + /** + * Allows beans to be matched by considering the bean name and deployment + * precedence. + * + * Used in an environment that doesn't support typing such EL. + * + * @param name + * the name used to restrict the beans matched + * @return the matched beans + */ public Set<Bean<?>> resolveByName(String name); - + + /** + * Obtains an instance of a bean by considering the bean name and deployment + * precedence. + * + * Used in an environment that doesn't support typing such EL. + * + * @param name + * the name used to restrict the beans matched + * @return an instance of the bean or null if no beans matched + * @throws AmbiguousDependencyException + * if more than one bean matches + */ public Object getInstanceByName(String name); - + + /** + * Obtains an instance of a bean + * + * @param <T> + * the type of the bean + * @param bean + * the bean to obtain an instance of + * @return an instance of the bean + */ public <T> T getInstance(Bean<T> bean); + /** + * Obtains an instance of bean for a given injection point. + * + * This method should not be called by an application. + * + * @param <T> + * the type of the bean + * @param injectionPoint + * the injection point the instance is needed for + * @param creationalContext + * the context in which the injection is occurring + * @return an instance of the bean + * @throws UnsatisfiedDependencyException + * if no bean can be resolved for the given type and bindings + * @throws AmbiguousDependencyException + * if more than one bean is resolved for the given type and + * bindings + */ public <T> T getInstanceToInject(InjectionPoint injectionPoint, CreationalContext<?> creationalContext); + /** + * Obtains an instance of bean for a given injection point. + * + * This method should not be called by an application. + * + * @param <T> + * the type of the bean + * @param injectionPoint + * the injection point the instance is needed for + * @return an instance of the bean + * @throws UnsatisfiedDependencyException + * if no bean can be resolved for the given type and bindings + * @throws AmbiguousDependencyException + * if more than one bean is resolved for the given type and + * bindings + */ public <T> T getInstanceToInject(InjectionPoint injectionPoint); - + + /** + * Fire an event + * + * @param event + * the event object + * @param bindings + * the event bindings used to restrict the observers matched + * @throws IllegalArgumentException + * if a parameterized type with a type parameter or a wildcard is + * passed + */ public void fireEvent(Object event, Annotation... bindings); - + + /** + * Obtain an active context instance for the given scope type. + * + * @param scopeType + * the scope to get the context instance for + * @return the context instance + * @throws ContextNotActiveException + * if no active contexts exist for the given scope type + * @throws IllegalArgumentException + * if more than one active context exists for the given scope type + */ public Context getContext(Class<? extends Annotation> scopeType); - + + /** + * Associate a custom Context with a scope. + * + * This method may be called at any time in the applications lifecycle. + * + * @param context + * the context to register + * @return the manager the context was registered with + */ public Manager addContext(Context context); - + + /** + * Allows a new bean to be registered. + * + * This method may be called at any time in the applications lifecycle. + * + * @param bean + * the bean to register + * @return the manager the bean was registered with + */ public Manager addBean(Bean<?> bean); - + + /** + * Allows a new interceptor to be registered. + * + * This method may be called at any time in the applications lifecycle. + * + * @param interceptor + * the interceptor to register + * @return the manager the interceptor was registered with + */ public Manager addInterceptor(Interceptor interceptor); - + + /** + * Allows a new decorator to be registered. + * + * This method may be called at any time in the applications lifecycle. + * + * @param decorator + * the decorator to register + * @return the manager the decorator was registered with + */ public Manager addDecorator(Decorator decorator); + /** + * Allows additional XML based to be provided. + * + * This method may be called at any time in the applications lifecycle. + * + * @param xmlStream + * the XML metadata + * @return the manager the XML metadata was registered with + */ public Manager parse(InputStream xmlStream); - public Manager createChildManager(); - - public Manager setCurrent(); + /** + * Create a new child activity. A child activity inherits all beans, + * interceptors, decorators, observers, and contexts defined by its direct + * and indirect parent activities. + * + * This method should not be called by the application. + * + * @return the child activity + */ + public Manager createActivity(); + /** + * Associate an activity with the current context for a normal scope + * + * @param scopeType + * the scope to associate the activity with + * @return the activity + * @throws ContextNotActiveException + * if the given scope is inactive + * @throws IllegalArgumentException + * if the given scope is not a normal scope + */ + public Manager setCurrent(Class<? extends Annotation> scopeType); + + /** + * Register an observer with the container + * + * @param <T> + * the type of the observer + * @param observer + * the observer to register + * @param eventType + * the event type the observer observes + * @param bindings + * event bindings to further restrict the events observed + * @return the manager the observer was registered with + * @throws IllegalArgumentException + * if a parameterized type with a type parameter or a wildcard is + * passed + * @throws IllegalArgumentException + * if an annotation which is not a binding type is passed + * @throws DuplicateBindingTypeException + * if two instances of the same binding type are passed + */ public <T> Manager addObserver(Observer<T> observer, Class<T> eventType, Annotation... bindings); - + + /** + * Register an observer with the container + * + * @param <T> + * the type of the observer + * @param observer + * the observer to register + * @param eventType + * the event type the observer observes + * @param bindings + * event bindings to further restrict the events observed + * @return the manager the observer was registered with + * @throws IllegalArgumentException + * if a parameterized type with a type parameter or a wildcard is + * passed + * @throws IllegalArgumentException + * if an annotation which is not a event binding type is passed + * @throws DuplicateBindingTypeException + * if two instances of the same binding type are passed + */ public <T> Manager addObserver(Observer<T> observer, TypeLiteral<T> eventType, Annotation... bindings); - + + /** + * Remove an observer registration + * + * @param <T> + * the type of the observer + * @param observer + * the observer to register + * @param eventType + * the event type the observer obseres + * @param bindings + * event bindings to further restrict the events observed + * @return the manager the observer was registered with + * @throws IllegalArgumentException + * if a parameterized type with a type parameter or a wildcard is + * passed + * @throws IllegalArgumentException + * if an annotation which is not a event binding type is passed + * @throws DuplicateBindingTypeException + * if two instances of the same binding type are passed + */ public <T> Manager removeObserver(Observer<T> observer, Class<T> eventType, Annotation... bindings); - + + /** + * Remove an observer registration + * + * @param <T> + * the type of the observer + * @param observer + * the observer to register + * @param eventType + * the event type the observer obseres + * @param bindings + * event bindings to further restrict the events observed + * @return the manager the observer was registered with + * @throws IllegalArgumentException + * if a parameterized type with a type parameter or a wildcard is + * passed + * @throws IllegalArgumentException + * if an annotation which is not a event binding type is passed + * @throws DuplicateBindingTypeException + * if two instances of the same binding type are passed + */ public <T> Manager removeObserver(Observer<T> observer, TypeLiteral<T> eventType, Annotation... bindings); - + + /** + * Obtains observers for an event by considering event type and bindings. + * + * @param <T> + * the type of the event to obtain + * @param event + * the event object + * @param bindings + * the bindings used to restrict the matched observers + * @return the resolved observers + * @throws IllegalArgumentException + * if a parameterized type with a type parameter or a wildcard is + * passed + * @throws IllegalArgumentException + * if an annotation which is not a event binding type is passed + * @throws DuplicateBindingTypeException + * if two instances of the same binding type are passed + */ public <T> Set<Observer<T>> resolveObservers(T event, Annotation... bindings); - + + /** + * Obtains an ordered list of enabled interceptors for a set interceptor + * bindings + * + * @param type + * the type of the interception + * @param bindings + * the bindings used to restrict the matched interceptors + * @return the resolved interceptors + * @throws IllegalArgumentException + * if no interceptor binding type is passed + * @throws IllegalArgumentException + * if an annotation which is not a interceptor binding type is + * passed + * @throws DuplicateBindingTypeException + * if two instances of the same binding type are passed + */ public List<Interceptor> resolveInterceptors(InterceptionType type, Annotation... interceptorBindings); - + + /** + * Obtains an ordered list of enabled decorators for a set of bean types and + * a set of bindings + * + * @param types + * the set of bean types of the decorated bean + * @param bindings + * the bindings declared by the decorated bean + * @return the resolved decorators + * @throws IllegalArgumentException + * if the set of bean types is empty + * @throws IllegalArgumentException + * if an annotation which is not a binding type is passed + * @throws DuplicateBindingTypeException + * if two instances of the same binding type are passed + */ public List<Decorator> resolveDecorators(Set<Type> types, Annotation... bindings); - + } Modified: ri/trunk/webbeans-api/src/main/java/javax/interceptor/Interceptor.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/interceptor/Interceptor.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/interceptor/Interceptor.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -26,7 +26,7 @@ import javax.annotation.Stereotype; /** - * Specifies that a class is a Web Beans interceptor. + * Specifies that a class is an interceptor. * * @author Gavin King * Modified: ri/trunk/webbeans-api/src/main/java/javax/interceptor/InterceptorBindingType.java =================================================================== --- ri/trunk/webbeans-api/src/main/java/javax/interceptor/InterceptorBindingType.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-api/src/main/java/javax/interceptor/InterceptorBindingType.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -25,8 +25,7 @@ import java.lang.annotation.Target; /** - * Specifies that an annotation type is a Web Beans - * interceptor binding type. + * Specifies that an annotation type is an interceptor binding type. * * @author Gavin King * @author Pete Muir Modified: ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/ManagerImpl.java =================================================================== --- ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/ManagerImpl.java 2009-01-27 09:12:17 UTC (rev 1245) +++ ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/ManagerImpl.java 2009-01-27 15:25:32 UTC (rev 1246) @@ -800,13 +800,13 @@ return this; } - public Manager createChildManager() + public Manager createActivity() { // TODO Implement hierarchical managers return this; } - public Manager setCurrent() + public Manager setCurrent(Class<? extends Annotation> scopeType) { // TODO Implement hierarchical managers return this;