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 [EMAIL PROTECTED] 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 [EMAIL
PROTECTED] 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 [EMAIL
PROTECTED] 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 [EMAIL PROTECTED] 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
[EMAIL PROTECTED] 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>[EMAIL PROTECTED] #getLocale()}</li>
* <li>[EMAIL PROTECTED] #get(String)}</li>
* <li>[EMAIL PROTECTED] #set(String, String)}</li>
- * <li>[EMAIL PROTECTED] #list()}</li></ul>
- * <p/>
- * Key methods for subclassers: <ul>
- * <p/>
+ * <li>[EMAIL PROTECTED] #list()}</li>
+ * </ul>
+ * <p>
+ * Key methods for subclasses (plugins):
+ * <ul>
* <li>[EMAIL PROTECTED] #getImpl(String)}</li>
* <li>[EMAIL PROTECTED] #setImpl(String, String)}</li>
* <li>[EMAIL PROTECTED] #listImpl()}</li>
- * <li>[EMAIL PROTECTED] #isSetImpl(String)}</li></ul>
+ * <li>[EMAIL PROTECTED] #isSetImpl(String)}</li>
+ * </ul>
*/
class Settings {
+
+ /**
+ * A pluggable implementation of Settings,
+ * provided through the [EMAIL PROTECTED] #setInstance} method.
+ */
static Settings settingsImpl;
+
+ /**
+ * An instance of [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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 ([EMAIL
PROTECTED] 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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] #isSet(String)} method.
+ * Implements the [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #set(String, String)} method.
+ * Implements the [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #get(String)} method.
+ * Implements the [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #getLocation(String)} method.
+ * Implements the [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #list()} method.
+ * Implements the [EMAIL PROTECTED] #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 [EMAIL PROTECTED] 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;
