Docs

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

webbeans-ri/src/main/java/org/jboss/webbeans/bean/proxy/ProxyMethodHandler.java

@@ -1,3 +1,20 @@
+/*
+* 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 org.jboss.webbeans.bean.proxy;
 
 import java.io.Serializable;
@@ -11,6 +28,15 @@
 import org.jboss.webbeans.ManagerImpl;
 import org.jboss.webbeans.util.Reflections;
 
+/**
+ * A Javassist MethodHandler that delegates method calls to a proxied bean.
+ * If the transient bean has become null, it is looked up from the manager
+ * bean list before the invocation.
+ * 
+ * @author Nicklas Karlsson
+ * 
+ * @see org.jboss.webbeans.bean.proxy.ProxyPool
+ */
 public class ProxyMethodHandler implements MethodHandler, Serializable
 {
    private static final long serialVersionUID = -5391564935097267888L;
@@ -19,13 +45,31 @@ public class ProxyMethodHandler implements MethodHandler, Serializable
    private int beanIndex;
    private static ManagerImpl manager;
 
+   /**
+    * Constructor
+    * 
+    * @param bean The bean to proxy
+    * @param beanIndex The index to the bean in the manager bean list
+    * @param manager The manager implementation
+    */
    public ProxyMethodHandler(Bean<?> bean, int beanIndex, ManagerImpl manager)
    {
       this.bean = bean;
       this.beanIndex = beanIndex;
       ProxyMethodHandler.manager = manager;
    }
 
+   /**
+    * The method proxy
+    * 
+    * Uses reflection to look up the corresponding method on the proxy and executes 
+    * that method with the same parameters.
+    * 
+    *  @param self A reference to the proxy
+    *  @param method The method to execute
+    *  @param process The next method to proceed to
+    *  @param args The method calling arguments 
+    */
    public Object invoke(Object self, Method method, Method proceed, Object[] args) throws Throwable
    {
       if (bean == null)

webbeans-ri/src/main/java/org/jboss/webbeans/bean/proxy/ProxyPool.java

@@ -1,3 +1,20 @@
+/*
+* 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 org.jboss.webbeans.bean.proxy;
 
 import java.io.Serializable;
@@ -17,8 +34,20 @@
 
 import com.google.common.collect.ForwardingMap;
 
+/**
+ * A proxy pool for holding scope adaptors (client proxies)
+ * 
+ * @author Nicklas Karlsson
+ * 
+ * @see org.jboss.webbeans.bean.proxy.ProxyMethodHandler
+ */
 public class ProxyPool
 {
+   /**
+    * A container/cache for previously created proxies
+    * 
+    * @author Nicklas Karlsson
+    */
    private class Pool extends ForwardingMap<Bean<?>, Object>
    {
 
@@ -51,11 +80,26 @@ public ProxyPool(ManagerImpl manager)
       this.pool = new Pool();
    }
 
+   /**
+    * Type info (interfaces and superclasses) for a class
+    * 
+    * @author Nicklas Karlsson
+    */
    private class TypeInfo {
       Class<?>[] interfaces;
       Class<?> superclass;
    }
 
+   /**
+    * Gets the type info for a class
+    * 
+    * Looks through the give methods and organizes it into a TypeInfo object
+    * containing an array of interfaces and the most common superclass. Adds
+    * Serializable to the interfaces list also.
+    * 
+    * @param types A set of types (interfaces and superclasses) of a class
+    * @return The TypeInfo with categorized information
+    */
    private TypeInfo getTypeInfo(Set<Class<?>> types) 
    {
       TypeInfo typeInfo = new TypeInfo();
@@ -78,6 +122,18 @@ else if (superclass == null || (type != Object.class && superclass.isAssignableF
       return typeInfo;
    }
 
+   /**
+    * Creates a Javassist scope adaptor (client proxy) for a bean
+    * 
+    * Creates a Javassist proxy factory. Gets the type info. Sets the interfaces
+    * and superclass to the factory. Hooks in the MethodHandler and creates the proxy.
+    * 
+    * @param bean The bean to proxy
+    * @param beanIndex The index to the bean in the manager bean list
+    * @return A Javassist proxy
+    * @throws InstantiationException When the proxy couldn't be created
+    * @throws IllegalAccessException When the proxy couldn't be created
+    */
    private <T> T createClientProxy(Bean<T> bean, int beanIndex) throws InstantiationException, IllegalAccessException 
    {
       ProxyFactory proxyFactory = new ProxyFactory();
@@ -90,6 +146,14 @@ private <T> T createClientProxy(Bean<T> bean, int beanIndex) throws Instantiatio
       return clientProxy;
    }
 
+   /**
+    * Gets a client proxy for a bean
+    * 
+    * Looks for a proxy in the pool. If not found, one is created and added to the pool
+    *  
+    * @param bean
+    * @return
+    */
    public Object getClientProxy(Bean<?> bean)
    {
       Object clientProxy = pool.get(bean);