javadoc

git-svn-id: http://anonsvn.jboss.org/repos/weld/ri/trunk@1246 1c488680-804c-0410-94cd-c6b725194a0e

webbeans-api/src/main/java/javax/annotation/Named.java

@@ -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 "";
 
 }

webbeans-api/src/main/java/javax/annotation/Stereotype.java

@@ -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 {};
 
 }

webbeans-api/src/main/java/javax/context/ApplicationScoped.java

@@ -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
  */
 

webbeans-api/src/main/java/javax/context/Context.java

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

webbeans-api/src/main/java/javax/context/ContextNotActiveException.java

@@ -33,6 +33,8 @@
 public class ContextNotActiveException extends ExecutionException
 {
 
+   private static final long serialVersionUID = -3599813072560026919L;
+
    public ContextNotActiveException()
    {
       super();

webbeans-api/src/main/java/javax/context/Contextual.java

@@ -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);
 }

webbeans-api/src/main/java/javax/context/Conversation.java

@@ -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);
 }

webbeans-api/src/main/java/javax/context/ConversationScoped.java

@@ -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

webbeans-api/src/main/java/javax/context/Dependent.java

@@ -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

webbeans-api/src/main/java/javax/context/RequestScoped.java

@@ -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

webbeans-api/src/main/java/javax/context/ScopeType.java

@@ -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;

webbeans-api/src/main/java/javax/context/SessionScoped.java

@@ -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

webbeans-api/src/main/java/javax/decorator/Decorates.java

@@ -30,7 +30,6 @@
  * @author Gavin King
  * @author Pete Muir
  */
-
 @Target(FIELD)
 @Retention(RUNTIME)
 @Documented

webbeans-api/src/main/java/javax/decorator/Decorator.java

@@ -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

webbeans-api/src/main/java/javax/event/AfterTransactionCompletion.java

@@ -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
  * 

webbeans-api/src/main/java/javax/event/AfterTransactionFailure.java

@@ -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
  * 

webbeans-api/src/main/java/javax/event/AfterTransactionSuccess.java

@@ -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
  * 

webbeans-api/src/main/java/javax/event/BeforeTransactionCompletion.java

@@ -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
  * 

webbeans-api/src/main/java/javax/event/Event.java

@@ -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);
 
 }

webbeans-api/src/main/java/javax/event/IfExists.java

@@ -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