Author: nickarls
Date: 2008-11-18 05:20:12 -0500 (Tue, 18 Nov 2008)
New Revision: 323
Modified:
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/AbstractContext.java
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/ApplicationContext.java
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/BeanMap.java
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/ConversationContext.java
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/DependentContext.java
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/PrivateContext.java
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/RequestContext.java
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/SessionBeanMap.java
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/SessionContext.java
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/SharedContext.java
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/SimpleBeanMap.java
Log:
JavaDocs for contexts
Modified:
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/AbstractContext.java
===================================================================
---
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/AbstractContext.java 2008-11-18
09:40:49 UTC (rev 322)
+++
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/AbstractContext.java 2008-11-18
10:20:12 UTC (rev 323)
@@ -74,6 +74,8 @@
/**
* Set the context active, internal API for WBRI
+ *
+ * @param active The new state
*/
public void setActive(boolean active) {
getActive().set(active);
Modified:
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/ApplicationContext.java
===================================================================
---
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/ApplicationContext.java 2008-11-18
09:40:49 UTC (rev 322)
+++
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/ApplicationContext.java 2008-11-18
10:20:12 UTC (rev 323)
@@ -2,6 +2,11 @@
import javax.webbeans.ApplicationScoped;
+/**
+ * The Application context
+ *
+ * @author Nicklas Karlsson
+ */
public class ApplicationContext extends SharedContext {
public ApplicationContext()
Modified: ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/BeanMap.java
===================================================================
--- ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/BeanMap.java 2008-11-18
09:40:49 UTC (rev 322)
+++ ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/BeanMap.java 2008-11-18
10:20:12 UTC (rev 323)
@@ -2,11 +2,54 @@
import javax.webbeans.manager.Bean;
+/**
+ * Interface for different implementations of Bean to Bean instance
+ * storage. Used primarily by the contexts.
+ *
+ * @author Nicklas Karlsson
+ *
+ */
+
public interface BeanMap
{
+ /**
+ * Gets an instance of a bean from the storage.
+ *
+ * @param bean The bean whose instance to return
+ *
+ * @return The instance. Null if not found
+ */
public abstract <T extends Object> T get(Bean<? extends T> bean);
+
+ /**
+ * Removes an instance of a bean from the storage
+ *
+ * @param bean The bean whose instance to remove
+ *
+ * @return The removed instance. Null if not found in storage.
+ */
public abstract <T extends Object> T remove(Bean<? extends T> bean);
+
+ /**
+ * Clears the storage of any bean instances
+ */
public abstract void clear();
+
+ /**
+ * Returns an Iterable over the current keys in the storage
+ *
+ * @return An Iterable over the keys in the storage
+ */
public abstract Iterable<Bean<? extends Object>> keySet();
+
+ /**
+ * Adds a bean instance to the storage
+ *
+ * @param bean The bean type. Used as key
+ *
+ * @param instance The instance to add
+ *
+ * @return The instance added
+ */
public abstract <T extends Object> T put(Bean<? extends T> bean, T
instance);
}
\ No newline at end of file
Modified:
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/ConversationContext.java
===================================================================
---
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/ConversationContext.java 2008-11-18
09:40:49 UTC (rev 322)
+++
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/ConversationContext.java 2008-11-18
10:20:12 UTC (rev 323)
@@ -2,7 +2,11 @@
import javax.webbeans.ConversationScoped;
-
+/**
+ * The conversation context
+ *
+ * @author Nicklas Karlsson
+ */
public class ConversationContext extends PrivateContext {
public ConversationContext()
Modified:
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/DependentContext.java
===================================================================
---
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/DependentContext.java 2008-11-18
09:40:49 UTC (rev 322)
+++
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/DependentContext.java 2008-11-18
10:20:12 UTC (rev 323)
@@ -4,12 +4,18 @@
import javax.webbeans.Dependent;
import javax.webbeans.manager.Bean;
+/**
+ * The dependent context
+ *
+ * @author Nicklas Karlsson
+ */
public class DependentContext extends PrivateContext
{
public DependentContext()
{
super(Dependent.class);
+ // TODO starts as non-active?
setActive(false);
}
@@ -20,7 +26,7 @@
{
throw new ContextNotActiveException();
}
-
+ // Dependent contexts don't really use any BeanMap storage
return create == false ? null : bean.create();
}
Modified:
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/PrivateContext.java
===================================================================
---
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/PrivateContext.java 2008-11-18
09:40:49 UTC (rev 322)
+++
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/PrivateContext.java 2008-11-18
10:20:12 UTC (rev 323)
@@ -3,6 +3,13 @@
import java.lang.annotation.Annotation;
import java.util.concurrent.atomic.AtomicBoolean;
+/**
+ * The abstraction of a private context, on that operates on a ThreadLocal
+ * BeanMap and ThreadLocal active state
+ *
+ * @author Nicklas Karlsson
+ *
+ */
public class PrivateContext extends AbstractContext
{
private ThreadLocal<AtomicBoolean> active;
Modified:
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/RequestContext.java
===================================================================
---
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/RequestContext.java 2008-11-18
09:40:49 UTC (rev 322)
+++
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/RequestContext.java 2008-11-18
10:20:12 UTC (rev 323)
@@ -2,6 +2,11 @@
import javax.webbeans.RequestScoped;
+/**
+ * The request context
+ *
+ * @author Nicklas Karlsson
+ */
public class RequestContext extends PrivateContext
{
Modified:
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/SessionBeanMap.java
===================================================================
---
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/SessionBeanMap.java 2008-11-18
09:40:49 UTC (rev 322)
+++
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/SessionBeanMap.java 2008-11-18
10:20:12 UTC (rev 323)
@@ -9,6 +9,12 @@
import org.jboss.webbeans.ManagerImpl;
+/**
+ * A BeanMap that uses a HTTP session as backing map
+ *
+ * @author Nicklas Karlsson
+ *
+ */
public class SessionBeanMap implements BeanMap
{
private static final String KEY_PREFIX = "SessionScoped#";
@@ -21,20 +27,54 @@
{
super();
this.manager = manager;
+ // A "normal" BeanMap is used as cache
cache = new SimpleBeanMap();
}
+ /**
+ * The SessionBeanMap requires a HTTP session to work. It is created without one
+ * so this method must be called before it can be operated upon
+ *
+ * @param session The session to use as a backing map
+ */
public void setSession(HttpSession session)
{
this.session = session;
}
+ /**
+ * Used to check if the session has been set and throws an exception if it's
null.
+ */
private void checkSession() {
if (session == null) {
throw new IllegalArgumentException("Session has not been initialized in
SessionBeanMap");
}
}
+ /**
+ * Returns a map key to a bean. Uses a known prefix and appends the index of the Bean
+ * in the Manager bean list.
+ *
+ * @param bean The bean to generate a key for.
+ *
+ * @return A unique key;
+ */
+ @SuppressWarnings("unused")
+ private String getBeanKey(Bean<?> bean) {
+ // TODO Append scope to in order to make class usable by multiple contexts
+ return KEY_PREFIX + manager.getBeans().indexOf(bean);
+ }
+
+ /**
+ * Gets a bean from the session
+ *
+ * First, checks that the session is present. Then tries to get the instance from the
cache and
+ * return it if found. It determines an ID for the bean which and looks for it in the
session.
+ * If the instance is found in, it is added to the cache. The bean instance is
returned (null
+ * if not found in the session).
+ *
+ * @param bean The bean to get from the session
+ */
@SuppressWarnings("unchecked")
public <T> T get(Bean<? extends T> bean)
{
@@ -44,7 +84,7 @@
{
return instance;
}
- String id = KEY_PREFIX + manager.getBeans().indexOf(bean);
+ String id = getBeanKey(bean);
instance = (T) session.getAttribute(id);
if (instance != null)
{
@@ -53,16 +93,32 @@
return instance;
}
+ /**
+ * Removes a bean instance from the session
+ *
+ * First, checks that the session is present. Then, tries to get the bean instance
from the cache.
+ * It determines an ID for the bean and that key is then removed from the session and
the cache, whether
+ * they were present in the first place or not.
+ *
+ * @param bean The bean whose instance to remove.
+ */
public <T> T remove(Bean<? extends T> bean)
{
checkSession();
T instance = get(bean);
- String id = KEY_PREFIX + manager.getBeans().indexOf(bean);
+ String id = getBeanKey(bean);
session.removeAttribute(id);
cache.remove(bean);
return instance;
}
+ /**
+ * Clears the session of any beans.
+ *
+ * First, checks that the session is present. Then, iterates
+ * over the attribute names in the session and removes them if they start with the
know prefix.
+ * Finally, clears the cache.
+ */
@SuppressWarnings("unchecked")
public void clear()
{
@@ -75,6 +131,16 @@
cache.clear();
}
+ /**
+ * Gets an iterable over the beans present in the storage.
+ *
+ * Iterates over the names
+ * in the session. If a name starts with the known prefix, strips it out to get the
+ * index to the bean in the manager bean list. Retrieves the bean from that list and
+ * puts it in the result-list. Finally, returns the list.
+ *
+ * @return An Iterable to the beans in the storage
+ */
@SuppressWarnings("unchecked")
public Iterable<Bean<? extends Object>> keySet()
{
@@ -95,10 +161,22 @@
return beans;
}
+ /**
+ * Puts a bean instance in the session
+ *
+ * First, checks that the session is present. Generates a bean map key, puts the
instance in the
+ * session under that key and adds the bean instance to the cache.
+ *
+ * @param bean The bean to use as key
+ *
+ * @param instance The bean instance to add
+ *
+ * @return The instance added
+ */
public <T> T put(Bean<? extends T> bean, T instance)
{
checkSession();
- String id = KEY_PREFIX + manager.getBeans().indexOf(bean);
+ String id = getBeanKey(bean);
session.setAttribute(id, instance);
return cache.put(bean, instance);
}
Modified:
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/SessionContext.java
===================================================================
---
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/SessionContext.java 2008-11-18
09:40:49 UTC (rev 322)
+++
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/SessionContext.java 2008-11-18
10:20:12 UTC (rev 323)
@@ -5,11 +5,17 @@
import org.jboss.webbeans.ManagerImpl;
+/**
+ * The session context
+ *
+ * @author Nicklas Karlsson
+ */
public class SessionContext extends PrivateContext {
public SessionContext(ManagerImpl manager)
{
super(SessionScoped.class);
+ // Replaces the BeanMap implementation with a session-based one
beans.set(new SessionBeanMap(manager));
}
@@ -19,6 +25,11 @@
return "Session context";
}
+ /**
+ * Sets the session in the session bean map
+ *
+ * @param session The session to set
+ */
public void setSession(HttpSession session) {
((SessionBeanMap)getBeanMap()).setSession(session);
}
Modified:
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/SharedContext.java
===================================================================
---
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/SharedContext.java 2008-11-18
09:40:49 UTC (rev 322)
+++
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/SharedContext.java 2008-11-18
10:20:12 UTC (rev 323)
@@ -3,6 +3,12 @@
import java.lang.annotation.Annotation;
import java.util.concurrent.atomic.AtomicBoolean;
+/**
+ * The abstraction of a shared context with common beans but
+ * with a private active state
+ *
+ * @author Nicklas Karlsson
+ */
public class SharedContext extends AbstractContext
{
private BeanMap beans;
Modified:
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/SimpleBeanMap.java
===================================================================
---
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/SimpleBeanMap.java 2008-11-18
09:40:49 UTC (rev 322)
+++
ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/contexts/SimpleBeanMap.java 2008-11-18
10:20:12 UTC (rev 323)
@@ -8,6 +8,12 @@
import com.google.common.collect.ForwardingMap;
+/**
+ * A BeanMap that uses a simple forwarding HashMap as backing map
+ *
+ * @author Nicklas Karlsson
+ *
+ */
public class SimpleBeanMap extends ForwardingMap<Bean<? extends Object>,
Object> implements BeanMap
{