You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openwebbeans.apache.org by ge...@apache.org on 2009/05/04 20:46:23 UTC
svn commit: r771394 - in
/incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax: annotation/
context/
Author: gerdogdu
Date: Mon May 4 18:46:22 2009
New Revision: 771394
URL: http://svn.apache.org/viewvc?rev=771394&view=rev
Log:
Updating the java commments.
Modified:
incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/annotation/Named.java
incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/annotation/NonBinding.java
incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/annotation/Stereotype.java
incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/ApplicationScoped.java
incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Context.java
incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/ContextNotActiveException.java
incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Contextual.java
incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Conversation.java
incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/ConversationScoped.java
incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/CreationalContext.java
incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Dependent.java
incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/RequestScoped.java
Modified: incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/annotation/Named.java
URL: http://svn.apache.org/viewvc/incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/annotation/Named.java?rev=771394&r1=771393&r2=771394&view=diff
==============================================================================
--- incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/annotation/Named.java (original)
+++ incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/annotation/Named.java Mon May 4 18:46:22 2009
@@ -21,6 +21,13 @@
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
+/**
+ * Indicates the name of the webbeans component.
+ * <p>
+ * If there is no <code>Named</code> annotation for the
+ * given webbeans component, its name is null.
+ * </p>
+ */
@Target( { TYPE, METHOD })
@Retention(RUNTIME)
@Documented
Modified: incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/annotation/NonBinding.java
URL: http://svn.apache.org/viewvc/incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/annotation/NonBinding.java?rev=771394&r1=771393&r2=771394&view=diff
==============================================================================
--- incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/annotation/NonBinding.java (original)
+++ incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/annotation/NonBinding.java Mon May 4 18:46:22 2009
@@ -16,11 +16,32 @@
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
+import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
+/**
+ * Indicates that <code>BindingType</code> annotation member
+ * is not contained in the type safe resolution algorithm.
+ *
+ * <p>
+ * Example:
+ *
+ * <pre>
+ * @BindingType
+ * public @interface Mock {
+ * @NonBinding String name;
+ * }
+ * </pre>
+ *
+ * <b>Mock</b> binding type <i>name</i> member variable is excepted from the
+ * type safe resolution algorithm while comparing the binding types.
+ *
+ * </p>
+ */
@Retention(RUNTIME)
@Target(METHOD)
+@Documented
public @interface NonBinding
{
}
Modified: incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/annotation/Stereotype.java
URL: http://svn.apache.org/viewvc/incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/annotation/Stereotype.java?rev=771394&r1=771393&r2=771394&view=diff
==============================================================================
--- incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/annotation/Stereotype.java (original)
+++ incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/annotation/Stereotype.java Mon May 4 18:46:22 2009
@@ -21,14 +21,37 @@
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
+import javax.webbeans.Model;
+
+/**
+ * Steretypes are used for inheriting the meta annotations
+ * that are defined on the stereotyped annotation from another webbeans
+ * component.
+ *
+ * <p>
+ * It defines two member variables, namely
+ * <ul>
+ * <li>supportedScopes for restricting the webbeans scope</li>
+ * <li>requiredTypes for restricting the webbeans API type</li>
+ * </ul>
+ * </p>
+ *
+ * <p>
+ * If a bean annotated with multiple stereotypes, it obeys the all of the
+ * stereotypes restrictions.
+ * </p>
+ *
+ * @see Model
+ */
@Retention(RUNTIME)
@Target(ANNOTATION_TYPE)
@Documented
public @interface Stereotype
{
-
+ /**Supported scopes of the stereotype*/
public Class<? extends Annotation>[] supportedScopes() default {};
+ /**Required API type for the webbeans*/
public Class<?>[] requiredTypes() default {};
}
Modified: incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/ApplicationScoped.java
URL: http://svn.apache.org/viewvc/incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/ApplicationScoped.java?rev=771394&r1=771393&r2=771394&view=diff
==============================================================================
--- incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/ApplicationScoped.java (original)
+++ incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/ApplicationScoped.java Mon May 4 18:46:22 2009
@@ -19,6 +19,14 @@
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+/**
+ * Defines the application scoped type.
+ *
+ * <p>
+ * Please see the <b>8.5.3 Application context lifecycle</b>
+ * of the specification.
+ * </p>
+ */
@ScopeType
@Target( { ElementType.TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
Modified: incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Context.java
URL: http://svn.apache.org/viewvc/incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Context.java?rev=771394&r1=771393&r2=771394&view=diff
==============================================================================
--- incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Context.java (original)
+++ incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Context.java Mon May 4 18:46:22 2009
@@ -15,14 +15,65 @@
import java.lang.annotation.Annotation;
-
+/**
+ * Every webbeans component has an associated context that are
+ * defined by the {@link ScopeType} annotation. Webbeans components
+ * that are contained in the context are managed by the webbeans container.
+ *
+ * <p>
+ * Every context has a well-defined lifecycle. It means that
+ * in some time, context is active and some other time context may
+ * be passive. Moreover, each context is created and destroyed by the container
+ * according to the timing requirements. For example, request context is started by every
+ * http request and destroyed at the end of the http response. According to the current thread,
+ * active context is called an thread current context.
+ * </p>
+ *
+ * <p>
+ * Context is responsible for creating and destroying the {@link Contextual} instances of the
+ * webbeans components.
+ * </p>
+ *
+ */
public interface Context
-{
+{
+ /**
+ * Returns the scope type of the context.
+ *
+ * @return the scope type of the context
+ */
public Class<? extends Annotation> getScopeType();
- public <T> T get(Contextual<T> component, CreationalContext<T> crreationalContext);
-
+ /**
+ * If the context is not active, throws {@link ContextNotActiveException}.
+ * Otherwise, it looks for the given component instance in the context map. If
+ * this context contains the given webbeans component instance, it returns the component.
+ * If the component is not found in this context map, it looks for the <code>creationalContext</code>
+ * argument. If it is null, it returns null, otherwise new webbeans instance is created
+ * and puts into the context and returns it.
+ *
+ * @param <T> type of the webbeans component
+ * @param component webbeans component
+ * @param creationalContext {@link CreationalContext} instance
+ * @return the contextual instance or null
+ */
+ public <T> T get(Contextual<T> component, CreationalContext<T> creationalContext);
+
+ /**
+ * Returns the instance of the webbeans in this context if exist otherwise return null.
+ *
+ * @param <T> type of the webbeans component
+ * @param component webbeans component
+ * @return the instance of the webbeans in this context if exist otherwise return null
+ */
public <T> T get(Contextual<T> component);
+ /**
+ * Returns true if context is active according to the current thread,
+ * returns false otherwise.
+ *
+ * @return true if context is active according to the current thread,
+ * return false otherwise
+ */
boolean isActive();
-}
+}
\ No newline at end of file
Modified: incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/ContextNotActiveException.java
URL: http://svn.apache.org/viewvc/incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/ContextNotActiveException.java?rev=771394&r1=771393&r2=771394&view=diff
==============================================================================
--- incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/ContextNotActiveException.java (original)
+++ incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/ContextNotActiveException.java Mon May 4 18:46:22 2009
@@ -15,23 +15,46 @@
import javax.inject.ExecutionException;
+/**
+ * It is used by the <code>Context</code> interface.
+ *
+ *
+ * @see Context#get(Contextual, CreationalContext)
+ * @see Context#get(Contextual)
+ */
public class ContextNotActiveException extends ExecutionException
{
private static final long serialVersionUID = 4783816486073845333L;
-
+
+ /**
+ * Creates a new exception with message.
+ *
+ * @param message message
+ */
public ContextNotActiveException(String message)
{
super(message);
}
- public ContextNotActiveException(Throwable e)
+ /**
+ * Create a new exception with the root cause.
+ *
+ * @param cause cause of the exception
+ */
+ public ContextNotActiveException(Throwable cause)
{
- super(e);
+ super(cause);
}
- public ContextNotActiveException(String message, Throwable e)
+ /**
+ * Creates a new exception with the given message and throwable cause.
+ *
+ * @param message exception message
+ * @param cause root cause of the exception
+ */
+ public ContextNotActiveException(String message, Throwable cause)
{
- super(message, e);
+ super(message, cause);
}
}
Modified: incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Contextual.java
URL: http://svn.apache.org/viewvc/incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Contextual.java?rev=771394&r1=771393&r2=771394&view=diff
==============================================================================
--- incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Contextual.java (original)
+++ incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Contextual.java Mon May 4 18:46:22 2009
@@ -13,10 +13,34 @@
*/
package javax.context;
+import javax.inject.CreationException;
+/**
+ * Each webbeans instance that is contained in the <code>Context</code>
+ * must be defined as <code>Contextual</code>.
+ *
+ * This interface defines the creating and destroying of the webbeans instances
+ * that are contained in the its {@link Context} instance.
+ *
+ * @param <T> type of the webbeans component
+ * @see Context
+ */
public interface Contextual<T>
{
+ /**
+ * Creates and returns a new instance of the webbeans component.
+ *
+ * @param context new creational context instance
+ * @return the new instance of the webbeans component
+ * @throws CreationException if any exception occurs
+ */
public T create(CreationalContext<T> context);
+ /**
+ * Destroys the instance. Any destroy logic is encapsulated
+ * in this method.
+ *
+ * @param instance already created webbeans instance
+ */
public void destroy(T instance);
}
Modified: incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Conversation.java
URL: http://svn.apache.org/viewvc/incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Conversation.java?rev=771394&r1=771393&r2=771394&view=diff
==============================================================================
--- incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Conversation.java (original)
+++ incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Conversation.java Mon May 4 18:46:22 2009
@@ -13,20 +13,61 @@
*/
package javax.context;
+/**
+ * Defines the conversation instance contract for using
+ * in the {@link ConversationScoped} webbeans components.
+ *
+ * <p>
+ * Please see the <b>8.5.4 Conversation context lifecycle</b> of the specification.
+ * </p>
+ *
+ * @see ConversationScoped
+ */
public interface Conversation
{
+ /**
+ * Starts new conversation.
+ */
public void begin();
+ /**
+ * Starts new conversation with the given id.
+ *
+ * @param id conversation id.
+ */
public void begin(String id);
+ /**
+ * Ends of the conversation.
+ */
public void end();
+ /**
+ * Returns true if conversation is marked as a long running false otherwise.
+ *
+ * @return true if conversation is marked as a long running false otherwise
+ */
public boolean isLongRunning();
+ /**
+ * Gets conversation id.
+ *
+ * @return conversation id
+ */
public String getId();
+ /**
+ * Returns conversation time out.
+ *
+ * @return conversation timeout
+ */
public long getTimeout();
+ /**
+ * Sets conversation timeout in ms.
+ *
+ * @param milliseconds timeout of the conversation
+ */
public void setTimeout(long milliseconds);
}
Modified: incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/ConversationScoped.java
URL: http://svn.apache.org/viewvc/incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/ConversationScoped.java?rev=771394&r1=771393&r2=771394&view=diff
==============================================================================
--- incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/ConversationScoped.java (original)
+++ incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/ConversationScoped.java Mon May 4 18:46:22 2009
@@ -19,6 +19,11 @@
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+/**
+ * Conversation scope type.
+ *
+ * @see Conversation
+ */
@ScopeType(passivating=true)
@Target( { ElementType.TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
Modified: incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/CreationalContext.java
URL: http://svn.apache.org/viewvc/incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/CreationalContext.java?rev=771394&r1=771393&r2=771394&view=diff
==============================================================================
--- incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/CreationalContext.java (original)
+++ incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/CreationalContext.java Mon May 4 18:46:22 2009
@@ -26,9 +26,19 @@
* @Current Foo _bar;
* }
* </code>
+ *
+ * <p>
+ * Generally it is used for prohibiting the circular references of the webbeans.
+ * </p>
+ *
*/
public interface CreationalContext<T>
{
+ /**
+ * Puts new incomplete instance into the creational context.
+ *
+ * @param incompleteInstance incomplete webbeans instance
+ */
public void push(T incompleteInstance);
}
Modified: incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Dependent.java
URL: http://svn.apache.org/viewvc/incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Dependent.java?rev=771394&r1=771393&r2=771394&view=diff
==============================================================================
--- incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Dependent.java (original)
+++ incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/Dependent.java Mon May 4 18:46:22 2009
@@ -19,6 +19,24 @@
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+/**
+ * Dependent scope type.
+ * <p>
+ * If webbeans or its stereotypes do not define its scope type,
+ * default scope type is <code>Dependent</code> scope.
+ * </p>
+ *
+ * <p>
+ * Every webbeans instance has an associated dependent context. Each dependent context
+ * is destroyed with its parent webbeans component instance.
+ * </p>
+ *
+ * <p>
+ * Please see <b>8.3 Dependent pseudo-scope</b> of the specification
+ * for getting furhter information.
+ * </p>
+ *
+ */
@ScopeType(normal = false)
@Target( { ElementType.TYPE, ElementType.METHOD, ElementType.FIELD })
@Retention(RetentionPolicy.RUNTIME)
Modified: incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/RequestScoped.java
URL: http://svn.apache.org/viewvc/incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/RequestScoped.java?rev=771394&r1=771393&r2=771394&view=diff
==============================================================================
--- incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/RequestScoped.java (original)
+++ incubator/openwebbeans/trunk/webbeans-api/src/main/java/javax/context/RequestScoped.java Mon May 4 18:46:22 2009
@@ -23,6 +23,14 @@
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
+/**
+ * Defines the request scope.
+ *
+ * <p>
+ * Please see <b>8.5.1 Request context lifecycle</b> of the specification
+ * for getting furher information
+ * </p>
+ */
@Target( { TYPE, METHOD, FIELD })
@Retention(RUNTIME)
@Documented