struts-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hus...@apache.org
Subject svn commit: r478167 - in /struts/struts2/trunk/core/src/main/java/org/apache/struts2: config/ClasspathConfigurationProvider.java config/DelegatingSettings.java config/Settings.java dispatcher/Dispatcher.java
Date Wed, 22 Nov 2006 14:19:54 GMT
Author: husted
Date: Wed Nov 22 06:19:53 2006
New Revision: 478167

URL: http://svn.apache.org/viewvc?view=rev&rev=478167
Log:
WW-1483 Javadoc and IDEA refactorings only. No functional changes. 

Modified:
    struts/struts2/trunk/core/src/main/java/org/apache/struts2/config/ClasspathConfigurationProvider.java
    struts/struts2/trunk/core/src/main/java/org/apache/struts2/config/DelegatingSettings.java
    struts/struts2/trunk/core/src/main/java/org/apache/struts2/config/Settings.java
    struts/struts2/trunk/core/src/main/java/org/apache/struts2/dispatcher/Dispatcher.java

Modified: struts/struts2/trunk/core/src/main/java/org/apache/struts2/config/ClasspathConfigurationProvider.java
URL: http://svn.apache.org/viewvc/struts/struts2/trunk/core/src/main/java/org/apache/struts2/config/ClasspathConfigurationProvider.java?view=diff&rev=478167&r1=478166&r2=478167
==============================================================================
--- struts/struts2/trunk/core/src/main/java/org/apache/struts2/config/ClasspathConfigurationProvider.java
(original)
+++ struts/struts2/trunk/core/src/main/java/org/apache/struts2/config/ClasspathConfigurationProvider.java
Wed Nov 22 06:19:53 2006
@@ -25,7 +25,6 @@
 import java.net.URL;
 import java.util.HashMap;
 import java.util.Map;
-import java.util.Properties;
 import java.util.Set;
 
 import org.apache.commons.logging.Log;
@@ -47,28 +46,94 @@
 import com.opensymphony.xwork2.util.location.LocatableProperties;
 
 /**
- * Loads the configuration by scanning the classpath looking for classes that end in
- * 'Action'.
+ * ClasspathConfigurationProvider loads the configuration
+ * by scanning the classpath or selected packages for Action classes.
+ * <p>
+ * This provider is only invoked if one or more action packages are passed to the dispatcher,
+ * usually from the web.xml.
+ * Configurations are created for objects that either implement Action or have classnames
that end with "Action".
  */
 public class ClasspathConfigurationProvider implements ConfigurationProvider {
 
+    /**
+     * The default page prefix (or "path").
+     * Some applications may place pages under "/WEB-INF" as an extreme security precaution.
+     */
     private static final String DEFAULT_PAGE_PREFIX = "struts.configuration.classpath.defaultPagePrefix";
+
+    /**
+     * The default page prefix (none).
+     */
+    private String defaultPagePrefix = "";
+
+    /**
+     * The default page extension,  to use in place of ".jsp".
+     */
     private static final String DEFAULT_PAGE_EXTENSION = "struts.configuration.classpath.defaultPageExtension";
+
+    /**
+     * The defacto default page extension, usually associated with JavaServer Pages.
+     */
+    private String defaultPageExtension = ".jsp";
+
+    /**
+     * A setting to indicate a custom default parent package,
+     * to use in place of "struts-default".
+     */
     private static final String DEFAULT_PARENT_PACKAGE = "struts.configuration.classpath.defaultParentPackage";
-    private static final String ACTION = "Action";
-    private String[] packages;
+
+    /**
+     * Name of the framework's default configuration package,
+     * that application configuration packages automatically inherit.
+     */
     private String defaultParentPackage = "struts-default";
-    private String defaultPageExtension = ".jsp";
-    private String defaultPagePrefix = "";
+
+    /**
+     * Default suffix that can be used to indicate POJO "Action" classes.
+     */
+    private static final String ACTION = "Action";
+
+    /**
+     * Helper class to scan class path for server pages.
+     */
     private PageLocator pageLocator = new ClasspathPageLocator();
+
+    /**
+     * Flag to indicate the packages have been loaded.
+     *
+     * @see #loadPackages
+     * @see #needsReload
+     */
     private boolean initialized = false;
 
+    /**
+     * The list of packages to scan for Action classes.
+     */
+    private String[] packages;
+
+    /**
+     * The package configurations for scanned Actions.
+     *
+     * @see #loadPackageConfig
+     */
     private Map<String,PackageConfig> loadedPackageConfigs = new HashMap<String,PackageConfig>();
 
+    /**
+     * Logging instance for this class.
+     */
     private static final Log LOG = LogFactory.getLog(ClasspathConfigurationProvider.class);
 
+    /**
+     * The XWork Configuration for this application.
+     *
+     * @see #init
+     */
     private Configuration configuration;
 
+    /**
+     * Create instance utilizing a list of packages to scan for Action classes.
+     * @param pkgs List of pacaktges to scan for Action Classes.
+     */
     public ClasspathConfigurationProvider(String[] pkgs) {
         this.packages = pkgs;
 
@@ -122,7 +187,7 @@
     }
 
     /**
-     * @param pkgs
+     * @param pkgs A set of packages to load
      */
     protected void loadPackages(String[] pkgs) {
 
@@ -136,7 +201,7 @@
             }
             
         }, pkgs);
-        Set actionClasses = resolver.getClasses();
+        Set<? extends Class<? extends Class>> actionClasses = resolver.getClasses();
         for (Object obj : actionClasses) {
            Class cls = (Class) obj;
            if (!Modifier.isAbstract(cls.getModifiers())) {
@@ -149,6 +214,11 @@
         }
     }
 
+    /**
+     *
+     * @param cls Action or POJO instance to process
+     * @param pkgs Set of packages to scan for Actions
+     */
     protected void processActionClass(Class cls, String[] pkgs) {
         String name = cls.getName();
         String actionPackage = cls.getPackage().getName();
@@ -188,7 +258,7 @@
             }
         }
 
-        // Cut off the Action suffix if found
+        // Truncate Action suffix if found
         if (actionName.endsWith(ACTION)) {
             actionName = actionName.substring(0, actionName.length() - ACTION.length());
         }
@@ -212,7 +282,8 @@
     }
 
     /**
-     * @param actionPackage
+     * @param actionPackage The Java package containing our Action classes
+     * @return
      */
     protected PackageConfig loadPackageConfig(String actionNamespace, String actionPackage,
Class actionClass) {
         PackageConfig parent = null;
@@ -306,7 +377,7 @@
         }
 
         protected ResultConfig createResultConfig(Result result) {
-            Class cls = result.type();
+            Class<? extends Object> cls = result.type();
             if (cls == NullResult.class) {
                 cls = null;
             }
@@ -315,9 +386,9 @@
 
         public V get(Object key) {
 
-            Object result = super.get(key);
+            V result = super.get(key);
             if (result != null) {
-                return (V) result;
+                return result;
             } else {
 
                 // TODO: This code never is actually used, do to how the runtime configuration
@@ -340,8 +411,8 @@
          * @param location
          * @return
          */
-        private ResultConfig createResultConfig(Object key, Class resultClass, String location)
{
-            Map configParams = null;
+        private ResultConfig createResultConfig(Object key, Class<? extends Object>
resultClass, String location) {
+            Map<? extends Object, ? extends Object> configParams = null;
             if (resultClass == null) {
                 String defaultResultType = pkgConfig.getFullDefaultResultType();
                 ResultTypeConfig resultType = (ResultTypeConfig) pkgConfig.getAllResultTypeConfigs().get(defaultResultType);

Modified: struts/struts2/trunk/core/src/main/java/org/apache/struts2/config/DelegatingSettings.java
URL: http://svn.apache.org/viewvc/struts/struts2/trunk/core/src/main/java/org/apache/struts2/config/DelegatingSettings.java?view=diff&rev=478167&r1=478166&r2=478167
==============================================================================
--- struts/struts2/trunk/core/src/main/java/org/apache/struts2/config/DelegatingSettings.java
(original)
+++ struts/struts2/trunk/core/src/main/java/org/apache/struts2/config/DelegatingSettings.java
Wed Nov 22 06:19:53 2006
@@ -26,89 +26,72 @@
 
 
 /**
- * A Settings implementation which stores an internal list of settings objects. Each time
- * a config method is called (get, set, list, etc..) this class will go through the list
of settingss
- * and call the method until successful.
+ * DelegatingSettings stores an internal list of {@link Settings} objects
+ * to update settings or retrieve settings values.
+ * <p>
+ * Each time a Settings method is called (get, set, list, and so forth),
+ * this class goes through the list of Settings objects
+ * and calls that method for each delegate,
+ * withholding any exception until all delegates have been called.
  *
  */
 class DelegatingSettings extends Settings {
 
-    Settings[] configList;
-
-
     /**
-     * Creates a new DelegatingSettings object given a list of {@link Settings} implementations.
-     *
-     * @param aConfigList a list of Settings implementations.
+     * The Settings objects.
      */
-    public DelegatingSettings(Settings[] aConfigList) {
-        configList = aConfigList;
-    }
-
+    Settings[] delegates;
 
     /**
-     * Sets the given property - calls setImpl(String, Object) method on config objects in
the config
-     * list until successful.
+     * Creates a new DelegatingSettings object utilizing the list of {@link Settings} objects.
      *
-     * @see #set(String, String)
+     * @param delegates The Settings objects to use as delegates
      */
+    public DelegatingSettings(Settings[] delegates) {
+        this.delegates = delegates;
+    }
+
+    // See superclass for Javadoc
     public void setImpl(String name, String value) throws IllegalArgumentException, UnsupportedOperationException
{
-        // Determine which config to use by using get
-        // Delegate to the other settingss
         IllegalArgumentException e = null;
 
-        for (int i = 0; i < configList.length; i++) {
+        for (Settings delegate : delegates) {
             try {
-                configList[i].getImpl(name);
-
-                // Found it, now try setting
-                configList[i].setImpl(name, value);
-
-                // Worked, now return
-                return;
+                delegate.getImpl(name); // Throws exception if not found
+                delegate.setImpl(name, value); // Found it
+                return; // Done
             } catch (IllegalArgumentException ex) {
                 e = ex;
 
-                // Try next config
+                // Try next delegate
             }
         }
 
         throw e;
     }
 
-    /**
-     * Gets the specified property - calls getImpl(String) method on config objects in config
list
-     * until successful.
-     *
-     * @see #get(String)
-     */
+    // See superclass for Javadoc
     public String getImpl(String name) throws IllegalArgumentException {
-        // Delegate to the other settings
+
         IllegalArgumentException e = null;
 
-        for (int i = 0; i < configList.length; i++) {
+        for (Settings delegate : delegates) {
             try {
-                return configList[i].getImpl(name);
+                return delegate.getImpl(name);  // Throws exception if not found
             } catch (IllegalArgumentException ex) {
                 e = ex;
 
-                // Try next config
+                // Try next delegate
             }
         }
 
         throw e;
     }
 
-    /**
-     * Determines if a paramter has been set - calls the isSetImpl(String) method on each
config object
-     * in config list. Returns <tt>true</tt> when one of the config implementations
returns true. Returns
-     * <tt>false</tt> otherwise.
-     *
-     * @see #isSet(String)
-     */
+    // See superclass for Javadoc
     public boolean isSetImpl(String aName) {
-        for (int i = 0; i < configList.length; i++) {
-            if (configList[i].isSetImpl(aName)) {
+        for (Settings delegate : delegates) {
+            if (delegate.isSetImpl(aName)) {
                 return true;
             }
         }
@@ -116,21 +99,16 @@
         return false;
     }
 
-    /**
-     * Returns a list of all property names - returns a list of all property names in all
config
-     * objects in config list.
-     *
-     * @see #list()
-     */
+    // See superclass for Javadoc
     public Iterator listImpl() {
         boolean workedAtAll = false;
 
         Set<Object> settingList = new HashSet<Object>();
         UnsupportedOperationException e = null;
 
-        for (int i = 0; i < configList.length; i++) {
+        for (Settings delegate : delegates) {
             try {
-                Iterator list = configList[i].listImpl();
+                Iterator list = delegate.listImpl();
 
                 while (list.hasNext()) {
                     settingList.add(list.next());
@@ -140,7 +118,7 @@
             } catch (UnsupportedOperationException ex) {
                 e = ex;
 
-                // Try next config
+                // Try next delegate
             }
         }
 

Modified: struts/struts2/trunk/core/src/main/java/org/apache/struts2/config/Settings.java
URL: http://svn.apache.org/viewvc/struts/struts2/trunk/core/src/main/java/org/apache/struts2/config/Settings.java?view=diff&rev=478167&r1=478166&r2=478167
==============================================================================
--- struts/struts2/trunk/core/src/main/java/org/apache/struts2/config/Settings.java (original)
+++ struts/struts2/trunk/core/src/main/java/org/apache/struts2/config/Settings.java Wed Nov
22 06:19:53 2006
@@ -33,61 +33,94 @@
 
 
 /**
- * Handles all Struts config properties. Implementation of this class is pluggable (the
- * default implementation is {@link DefaultSettings}). This gives developers to ability to
customize how
- * Struts properties are set and retrieved. As an example, a developer may wish to check
a separate property
- * store before delegating to the Struts one. <p>
- * <p/>
- * Key methods: <ul>
- * <p/>
+ * Settings retrieves and exposes default values used by the framework.
+ * An application can override a factory default and provide its own value for a setting.
+ * <p>
+ * Implementation of the class is pluggable (the default implementation is {@link DefaultSettings}).
+ * Pluggability gives applications to ability to customize how settings are retrieved.
+ * As an example, an application may wish to check some custom property store
+ * before delegating to the usual configuration and property files.
+ * <p>
+ * Key methods:
+ * <ul>
  * <li>{@link #getLocale()}</li>
  * <li>{@link #get(String)}</li>
  * <li>{@link #set(String, String)}</li>
- * <li>{@link #list()}</li></ul>
- * <p/>
- * Key methods for subclassers: <ul>
- * <p/>
+ * <li>{@link #list()}</li>
+ * </ul>
+ * <p>
+ * Key methods for subclasses (plugins):
+ * <ul>
  * <li>{@link #getImpl(String)}</li>
  * <li>{@link #setImpl(String, String)}</li>
  * <li>{@link #listImpl()}</li>
- * <li>{@link #isSetImpl(String)}</li></ul>
+ * <li>{@link #isSetImpl(String)}</li>
+ * </ul>
  */
 class Settings {
 
+
+    /**
+     * A pluggable implementation of Settings,
+     * provided through the {@link #setInstance} method.
+     */
     static Settings settingsImpl;
+
+    /**
+     * An instance of {@link DefaultSettings}
+     * to use when another implementation is not provided (plugged in).
+     */
     static Settings defaultImpl;
-    static Locale locale; // Cached locale
-    private static final Log LOG = LogFactory.getLog(Settings.class);
 
+    /**
+     * An instance of the default locale as specified by the <code>struts.locale</code>
 setting.
+     *
+     * @see #getLocale
+     */
+    static Locale locale;
+
+    /**
+     * The Logging instance for this class.
+     */
+    private static final Log LOG = LogFactory.getLog(Settings.class);
 
     /**
-     * Sets the current settings implementation. Can only be called once.
+     * Registers a custom Settings implementation (plugin),
+     * and resets the cached locale.
+     * <p>
+     * This method can only be called once.
      *
      * @param config a Settings implementation
      * @throws IllegalStateException if an error occurs when setting the settings implementation.
      */
     public static void setInstance(Settings config) throws IllegalStateException {
         settingsImpl = config;
-        locale = null; // Reset cached locale
+        locale = null;
     }
 
     /**
-     * Gets the current settings implementation.
+     * Provides the Settings object.
+     * <p>
+     * This method will substitute the default instance if another instance is not registered.
      *
-     * @return the current settings implementation.
+     * @return the Settings object.
      */
     public static Settings getInstance() {
         return (settingsImpl == null) ? getDefaultInstance() : settingsImpl;
     }
 
     /**
-     * Returns the Struts locale. Keys off the property <tt>struts.locale</tt>
which should be set
-     * as the Java {@link java.util.Locale#toString() toString()} representation of a Locale
object (i.e.,
-     * "en", "de_DE", "_GB", "en_US_WIN", "de__POSIX", "fr_MAC", etc). <p>
-     * <p/>
-     * If no locale is specified then the default VM locale is used ({@link java.util.Locale#getDefault()}).
+     * Provides the Struts default locale.
+     * <p>
+     * This method utilizes the <code>struts.locale</code> setting, which should
be given
+     * as the Java {@link java.util.Locale#toString() toString()} representation of a Locale
object
+     * ("en", "de_DE", "_GB", "en_US_WIN", "de__POSIX", "fr_MAC", and so forth).
+     * <p>
+     * If a <code>struts.locale</code> setting is not registered,
+     * then the default virtual machine locale is substituted and cached.
      *
-     * @return the Struts locale if specified or the VM default locale.
+     * @return the Struts default locale if specified or the VM default locale.
+     * @see java.util.Locale#getDefault()
      */
     public static Locale getLocale() {
         if (locale == null) {
@@ -107,7 +140,7 @@
                 locale = new Locale(lang, country);
             } catch (Throwable t) {
                 // Default
-                LOG.warn("Setting locale to the default locale");
+                LOG.warn("Settings: Could not parse struts.locale setting, substituting default
VM locale");
                 locale = Locale.getDefault();
             }
         }
@@ -116,46 +149,50 @@
     }
 
     /**
-     * Determines whether or not a value has been set. Useful for testing for the existance
of parameter without
+     * Determines whether or not a setting has a registered value.
+     * <p>
+     * This method is useful for testing for the existance of setting without
      * throwing an IllegalArgumentException.
      *
-     * @param name the name of the property to test.
-     * @return <tt>true</tt> if the property exists and has a value, <tt>false</tt>
otherwise.
+     * @param name the name of a setting to test.
+     * @return <code>true</code> if the setting exists and has a value, <code>false</code>
otherwise.
      */
     public static boolean isSet(String name) {
         return getInstance().isSetImpl(name);
     }
 
     /**
-     * Returns a property as an Object. This will throw an <tt>IllegalArgumentException</tt>
if an error occurs
+     * Provides a setting value as a String.
+     * <p>
+     * The method will throw an <code>IllegalArgumentException</code> if an error
occurs
      * while retrieveing the property or if the property doesn't exist.
      *
-     * @param name the name of the property to get.
-     * @return the property as an Object.
+     * @param name the name of the setting to retrieve.
+     * @return the setting value as a String.
      * @throws IllegalArgumentException if an error occurs retrieving the property or the
property does not exist.
      */
     public static String get(String name) throws IllegalArgumentException {
-        String val = getInstance().getImpl(name);
-
-        return val;
+        return getInstance().getImpl(name);
     }
-    
+
     /**
-     * Returns the location of a a property. This will throw an <tt>IllegalArgumentException</tt>
if an error occurs
-     * while retrieveing the property or if the property doesn't exist.
+     * Provides the Location of a setting.
+     * <p>
+     * The Location is utilized as part of precise error reporting.
+     * <p>
+      * This method will throw an <code>IllegalArgumentException</code> if an
error occurs
+     * while retrieving the value or if the setting doesn't exist.
      *
      * @param name the name of the property to get.
      * @return the Location of a property.
      * @throws IllegalArgumentException if an error occurs retrieving the property or the
property does not exist.
      */
     public static Location getLocation(String name) throws IllegalArgumentException {
-        Location loc = getInstance().getLocationImpl(name);
-
-        return loc;
+        return getInstance().getLocationImpl(name);
     }
 
     /**
-     * Returns an Iterator of all properties names.
+     * Provides an Iterator of all properties names.
      *
      * @return an Iterator of all properties names.
      */
@@ -164,8 +201,10 @@
     }
 
     /**
-     * Implementation of the {@link #isSet(String)} method.
+     * Implements the {@link #isSet(String)} method.
      *
+     * @param name Identifier for the setting value to change
+     * @return True if the setting exists and has a value, false otherwise.
      * @see #isSet(String)
      */
     public boolean isSetImpl(String name) {
@@ -175,39 +214,51 @@
     }
 
     /**
-     * Sets a property. Throws an exception if an error occurs when setting the property
or if the
-     * Settings implementation does not support setting properties.
-     *
-     * @param name  the name of the property to set.
-     * @param value the property to set.
-     * @throws IllegalArgumentException      if an error occurs when setting the property.
-     * @throws UnsupportedOperationException if the config implementation does not support
setting properties.
+     * Registers a value for a setting.
+     * <p>
+     * This method raises an exception if an error occurs when setting the value or if the
+     * settings implementation does not support setting values.
+     *
+     * @param name  the name of the setting.
+     * @param value the value to register for the setting.
+     * @throws IllegalArgumentException      if an error occurs when setting the value.
+     * @throws UnsupportedOperationException if the config implementation does not support
setting values.
      */
     public static void set(String name, String value) throws IllegalArgumentException, UnsupportedOperationException
{
         getInstance().setImpl(name, value);
     }
 
     /**
-     * Implementation of the {@link #set(String, String)} method.
+     * Implements the {@link #set(String, String)} method.
      *
+     * @param name Identifer for the setting to change.
+     * @param value The new value for the setting.
+     * @throws IllegalArgumentException      if an error occurs when setting the value.
+     * @throws UnsupportedOperationException if the config implementation does not support
setting values.
      * @see #set(String, String)
      */
     public void setImpl(String name, String value) throws IllegalArgumentException, UnsupportedOperationException
{
-        throw new UnsupportedOperationException("This settings does not support updating
a setting");
+        throw new UnsupportedOperationException("Settings: This implementation does not support
setting a value.");
     }
 
     /**
-     * Implementation of the {@link #get(String)} method.
+     * Implements the {@link #get(String)} method.
      *
+     * @param aName The name of the setting value to retreive
+     * @return The setting value as a String
+     * @throws IllegalArgumentException if an error occurs when retrieving the value
      * @see #get(String)
      */
     public String getImpl(String aName) throws IllegalArgumentException {
         return null;
     }
-    
+
     /**
-     * Implementation of the {@link #getLocation(String)} method.
+     * Implements the {@link #getLocation(String)} method.
      *
+     * @return The location  of the setting
+     * @param aName Name of the setting to locate
+     * @throws IllegalArgumentException if an error occurs when retrieving the value
      * @see #getLocation(String)
      */
     public Location getLocationImpl(String aName) throws IllegalArgumentException {
@@ -215,14 +266,23 @@
     }
 
     /**
-     * Implementation of the {@link #list()} method.
+     * Implements the {@link #list()} method.
      *
      * @see #list()
+     * @return A list of the settings as an iterator
      */
     public Iterator listImpl() {
-        throw new UnsupportedOperationException("This settings does not support listing the
settings");
+        throw new UnsupportedOperationException("Settings: This implementation does not support
listing the registered settings");
     }
 
+    /**
+     * Creates a default Settings object.
+     * <p>
+     * A default implementation may be specified by the <code>struts.configuration</code>
setting;
+     * otherwise, this method instantiates {@link DefaultSettings} as the default implementation.
+     *
+     * @return A default Settings object.
+     */
     private static Settings getDefaultInstance() {
         if (defaultImpl == null) {
             // Create bootstrap implementation
@@ -237,7 +297,7 @@
                         // singleton instances shouldn't be built accessing request or session-specific
context data
                         defaultImpl = (Settings) ObjectFactory.getObjectFactory().buildBean(Thread.currentThread().getContextClassLoader().loadClass(className),
null);
                     } catch (Exception e) {
-                        LOG.error("Could not instantiate settings", e);
+                        LOG.error("Settings: Could not instantiate the struts.configuration
object, substituting the default implementation.", e);
                     }
                 }
             } catch (IllegalArgumentException ex) {
@@ -248,6 +308,9 @@
         return defaultImpl;
     }
 
+    /**
+     * Resets the default and any plugin Setting instance to null.
+     */
     public static void reset() {
         defaultImpl = null;
         settingsImpl = null;

Modified: struts/struts2/trunk/core/src/main/java/org/apache/struts2/dispatcher/Dispatcher.java
URL: http://svn.apache.org/viewvc/struts/struts2/trunk/core/src/main/java/org/apache/struts2/dispatcher/Dispatcher.java?view=diff&rev=478167&r1=478166&r2=478167
==============================================================================
--- struts/struts2/trunk/core/src/main/java/org/apache/struts2/dispatcher/Dispatcher.java
(original)
+++ struts/struts2/trunk/core/src/main/java/org/apache/struts2/dispatcher/Dispatcher.java
Wed Nov 22 06:19:53 2006
@@ -29,7 +29,6 @@
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
-import java.util.Properties;
 
 import javax.servlet.ServletContext;
 import javax.servlet.ServletException;



Mime
View raw message