cedric 2003/02/27 11:19:43 Modified: src/share/org/apache/struts/tiles/xmlDefinition XmlParser.java XmlListAttribute.java XmlDefinitionsSet.java XmlDefinition.java I18nFactorySet.java FactorySet.java DefinitionsFactory.java Log: Documentation corrections and updates. No code change. Patches from Yann Cebron Revision Changes Path 1.10 +20 -20 jakarta-struts/src/share/org/apache/struts/tiles/xmlDefinition/XmlParser.java Index: XmlParser.java =================================================================== RCS file: /home/cvs/jakarta-struts/src/share/org/apache/struts/tiles/xmlDefinition/XmlParser.java,v retrieving revision 1.9 retrieving revision 1.10 diff -u -r1.9 -r1.10 --- XmlParser.java 8 Feb 2003 20:01:45 -0000 1.9 +++ XmlParser.java 27 Feb 2003 19:19:42 -0000 1.10 @@ -72,21 +72,21 @@ import org.xml.sax.SAXException; /** - *Parse an XML definitions file. + * Parse an XML definitions file. */ public class XmlParser { - /** Associated digester */ + /** Associated digester. */ protected Digester digester; /** * Should we use a validating XML parser to read the configuration file. - * Default is false. + * Default is <code>false</code>. */ protected boolean validating = false; /** - * The set of public identifiers, and corresponding resource names, for - * the versions of the configuration file DTDs that we know about. There + * The set of public identifiers, and corresponding resource names for + * the versions of the configuration file DTDs we know about. There * <strong>MUST</strong> be an even number of Strings in this list! */ protected String registrations[] = { @@ -106,7 +106,7 @@ /** * Constructor. - * Create a digester parser, and initialize syntax rules. + * Creates a digester parser and initializes syntax rules. */ public XmlParser() { @@ -145,8 +145,8 @@ /** * Init digester for components syntax. - * This is an old set of rules, left for backward compatibilities. - * + * This is an old set of rules, left for backward compatibility. + * @param digester Digester instance to use. */ private void initDigesterForComponentsDefinitionsSyntax( Digester digester ) { @@ -186,9 +186,9 @@ } /** - * Init digester for tiles syntax. + * Init digester for Tiles syntax. * Same as components, but with first element = tiles-definitions - * + * @param digester Digester instance to use. */ private void initDigesterForTilesDefinitionsSyntax( Digester digester ) { @@ -266,8 +266,8 @@ /** * Init digester in order to parse instances definition file syntax. * Instances is an old name for "definition". This method is left for - * backward compatibility. - * + * backwards compatibility. + * @param digester Digester instance to use. */ private void initDigesterForInstancesSyntax( Digester digester ) { @@ -311,7 +311,7 @@ /** * Init digester. - * + * @param digester Digester instance to use. */ protected void initDigester( Digester digester ) { @@ -321,11 +321,11 @@ } /** - * Parse input reader and add encounter definitions to definitions set. - * @param in Input stream + * Parse input reader and add encountered definitions to definitions set. + * @param in Input stream. * @param definitions Xml Definitions set to which encountered definition are added. - * @throws IOException If an error occur during file parsing. - * @throws SAXException + * @throws IOException On errors during file parsing. + * @throws SAXException On errors parsing XML. */ public void parse( InputStream in, XmlDefinitionsSet definitions ) throws IOException, SAXException { 1.2 +13 -8 jakarta-struts/src/share/org/apache/struts/tiles/xmlDefinition/XmlListAttribute.java Index: XmlListAttribute.java =================================================================== RCS file: /home/cvs/jakarta-struts/src/share/org/apache/struts/tiles/xmlDefinition/XmlListAttribute.java,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- XmlListAttribute.java 25 Jun 2002 03:15:43 -0000 1.1 +++ XmlListAttribute.java 27 Feb 2003 19:19:42 -0000 1.2 @@ -67,17 +67,17 @@ /** - * An attribute as a List. + * An attribute as a <code>List</code>. * This attribute associates a name with a list. The list can be found by the * property name. - * Element in list are retrieved using List methods. + * Elements in list are retrieved using List methods. * This class is used to read configuration files. */ public class XmlListAttribute extends XmlAttribute { /** List. - * We declare a list, to avoid cast. - * Parent "value" property point to the same list. + * We declare a List to avoid cast. + * Parent "value" property points to the same list. */ private List list; @@ -92,6 +92,8 @@ /** * Constructor. + * @param name Name. + * @param value List. */ public XmlListAttribute( String name, List value) { @@ -101,7 +103,8 @@ /** * Add an element in list. - * We use a Property, to avoid rewriting a new class. + * We use a property to avoid rewriting a new class. + * @param element XmlAttribute to add. */ public void add( XmlAttribute element ) { @@ -110,6 +113,7 @@ /** * Add an element in list. + * @param value Object to add. */ public void add( Object value ) { @@ -127,6 +131,7 @@ /** * Add an element in list. + * @param value Object to add. */ public void addObject( Object value ) { 1.2 +15 -17 jakarta-struts/src/share/org/apache/struts/tiles/xmlDefinition/XmlDefinitionsSet.java Index: XmlDefinitionsSet.java =================================================================== RCS file: /home/cvs/jakarta-struts/src/share/org/apache/struts/tiles/xmlDefinition/XmlDefinitionsSet.java,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- XmlDefinitionsSet.java 25 Jun 2002 03:15:43 -0000 1.1 +++ XmlDefinitionsSet.java 27 Feb 2003 19:19:42 -0000 1.2 @@ -69,11 +69,11 @@ import java.util.Iterator; /** - * A set of definitions red from XML definitions file + * A set of definitions read from XML definitions file. */ public class XmlDefinitionsSet { - /** defined definitions */ + /** Defined definitions. */ protected Map definitions; /** @@ -85,8 +85,8 @@ } /** - * Put definition in set - * @param definition + * Put definition in set. + * @param definition Definition to add. */ public void putDefinition(XmlDefinition definition) { @@ -94,8 +94,8 @@ } /** - * Get requested definition - * @param name definitio name + * Get requested definition. + * @param name Definition name. */ public XmlDefinition getDefinition(String name) { @@ -103,8 +103,7 @@ } /** - * Get definitions map - * @param name definitio name + * Get definitions map. */ public Map getDefinitions() { @@ -116,7 +115,7 @@ */ public void resolveInheritances() throws NoSuchDefinitionException { - // Walks throw all definitions and resolve individual inheritance + // Walk through all definitions and resolve individual inheritance Iterator i = definitions.values().iterator(); while( i.hasNext() ) { @@ -126,11 +125,10 @@ } /** - * add definitions from specified child definitions set. - * For each definition in child, look if it exist in this set. + * Add definitions from specified child definitions set. + * For each definition in child, look if it already exists in this set. * If not, add it, if yes, overload parent's definition with child definition. - * @param child definition used to overload this object. - * @return void + * @param child Definition used to overload this object. */ public void extend( XmlDefinitionsSet child ) { @@ -150,7 +148,7 @@ } // end loop } /** - * + * Get String representation. */ public String toString() { 1.3 +16 -16 jakarta-struts/src/share/org/apache/struts/tiles/xmlDefinition/XmlDefinition.java Index: XmlDefinition.java =================================================================== RCS file: /home/cvs/jakarta-struts/src/share/org/apache/struts/tiles/xmlDefinition/XmlDefinition.java,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- XmlDefinition.java 10 Oct 2002 16:32:26 -0000 1.2 +++ XmlDefinition.java 27 Feb 2003 19:19:42 -0000 1.3 @@ -70,7 +70,7 @@ import java.util.Iterator; /** - *A definition red from an XML definitions file. + *A definition read from an XML definitions file. */ public class XmlDefinition extends ComponentDefinition { @@ -83,7 +83,7 @@ protected static Log log = LogFactory.getLog(XmlDefinition.class); /** - * Use for resolving inheritance. + * Used for resolving inheritance. */ private boolean isVisited=false; @@ -99,7 +99,7 @@ } /** - * add an attribute to this component + * Add an attribute to this component. * * @param attribute Attribute to add. */ @@ -109,9 +109,9 @@ } /** - * Sets the value of the extend and path property. + * Set extends. * - * @param aPath the new value of the path property + * @param name Name of the extended definition. */ public void setExtends(String name) { @@ -119,9 +119,9 @@ } /** - * Access method for the path property. + * Get extends. * - * @return the current value of the path property + * @return Name of the extended definition. */ public String getExtends() { @@ -129,7 +129,7 @@ } /** - * Get the value of the extendproperty. + * Get extends flag. * */ public boolean isExtending( ) @@ -138,7 +138,7 @@ } /** - * Get the value of the extendproperty. + * Set isVisited. * */ public void setIsVisited( boolean isVisited ) @@ -150,8 +150,8 @@ * Resolve inheritance. * First, resolve parent's inheritance, then set path to the parent's path. * Also copy attributes setted in parent, and not set in child - * If instance doesn't extends something, do nothing. - * @throws NoSuchDefinitionException If a inheritance can be solved. + * If instance doesn't extend anything, do nothing. + * @throws NoSuchDefinitionException If an inheritance can not be solved. */ public void resolveInheritance( XmlDefinitionsSet definitionsSet ) throws NoSuchDefinitionException @@ -181,7 +181,7 @@ parent.resolveInheritance( definitionsSet ); - // Iterate on each parent's attribute, and add it if not defined in child. + // Iterate on each parent's attribute and add it if not defined in child. Iterator parentAttributes = parent.getAttributes().keySet().iterator(); while( parentAttributes.hasNext() ) { @@ -203,7 +203,7 @@ /** * Overload this definition with passed child. - * All attributes from child are copied to this definition. Previous attribute with + * All attributes from child are copied to this definition. Previous attributes with * same name are disguarded. * Special attribute 'path','role' and 'extends' are overloaded if defined in child. * @param child Child used to overload this definition. 1.6 +44 -37 jakarta-struts/src/share/org/apache/struts/tiles/xmlDefinition/I18nFactorySet.java Index: I18nFactorySet.java =================================================================== RCS file: /home/cvs/jakarta-struts/src/share/org/apache/struts/tiles/xmlDefinition/I18nFactorySet.java,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- I18nFactorySet.java 27 Dec 2002 10:35:19 -0000 1.5 +++ I18nFactorySet.java 27 Feb 2003 19:19:42 -0000 1.6 @@ -89,32 +89,32 @@ /** * Definitions factory. * This implementation allows to have a set of definition factories. - * There is a main factory, and one factory for each file associated to a Locale. + * There is a main factory and one factory for each file associated to a Locale. * - * To retrieve a definition, we first search for the appropriate factory, using - * Locale found in jsp session context. If no factory is found, use the - * default one. Then, we ask the factory for the definition. + * To retrieve a definition, we first search for the appropriate factory using + * the Locale found in session context. If no factory is found, use the + * default one. Then we ask the factory for the definition. * * A definition factory file is loaded using main filename extended with locale code - * (ex : templateDefinitions_fr.xml). If no file is found under this name, use default file. + * (ex : <code>templateDefinitions_fr.xml</code>). If no file is found under this name, use default file. */ public class I18nFactorySet extends FactorySet { /** Commons Logging instance. */ protected static Log log = LogFactory.getLog(I18nFactorySet.class); - /** Config file parameter name + /** Config file parameter name. * @deprecated use DEFINITIONS_CONFIG_PARAMETER_NAME */ public static final String INSTANCES_CONFIG_PARAMETER_NAME = "instances-config"; /** Default name */ //public static final String DEFAULT_DEFINITIONS_FILE_NAME = "/WEB-INF/componentDefinitions.xml"; - /** Config file parameter name */ + /** Config file parameter name. */ public static final String DEFINITIONS_CONFIG_PARAMETER_NAME = "definitions-config"; - /** Config file parameter name */ + /** Config file parameter name. */ public static final String PARSER_DETAILS_PARAMETER_NAME = "definitions-parser-details"; - /** Config file parameter name */ + /** Config file parameter name. */ public static final String PARSER_VALIDATE_PARAMETER_NAME = "definitions-parser-validate"; /** Possible definition filenames. */ @@ -129,21 +129,21 @@ * xmlParser is created each time we need it ;-(. */ protected transient XmlParser xmlParser; - /** Does we want validating parser. Default is false. - * Can be set from servlet config file + /** Do we want validating parser. Default is <code>false</code>. + * Can be set from servlet config file. */ protected boolean isValidatingParser = false; /** Parser detail level. Default is 0. - * Can be set from servlet config file + * Can be set from servlet config file. */ protected int parserDetailLevel = 0; /** * Maximum length of one branch of the resource search path tree. - * Used in getBundle. + * Used in getBundle(). */ private static final int MAX_BUNDLES_SEARCHED = 2; - /** Default filenames extension */ + /** Default filenames extension. */ public static final String FILENAME_EXTENSION = ".xml"; /** Names of files containing instances descriptions. */ @@ -154,7 +154,7 @@ /** * Parameterless Constructor. - * Method initFactory must be called prior to any use of created factory. + * Method [EMAIL PROTECTED] #initFactory} must be called prior to any use of created factory. */ public I18nFactorySet() { @@ -163,6 +163,8 @@ /** * Constructor. * Init the factory by reading appropriate configuration file. + * @param servletContext Servlet context. + * @param properties Map containing all properties. * @throws FactoryNotFoundException Can't find factory configuration file. */ public I18nFactorySet(ServletContext servletContext, Map properties ) @@ -281,8 +283,7 @@ /** * Create default factory . * Create InstancesMapper for specified Locale. - * If creation failed, use default mapper, and output an error message in - * console. + * If creation failes, use default mapper and log error message. * @param servletContext Current servlet context. Used to open file. * @return Created default definition factory. * @throws DefinitionsFactoryException If an error occur while creating factory. @@ -311,8 +312,8 @@ * Extract key that will be used to get the sub factory. * @param name Name of requested definition * @param request Current servlet request. - * @param servletContext Current servlet context - * @return the key or null if not found. + * @param servletContext Current servlet context. + * @return the key or <code>null</code> if not found. */ protected Object getDefinitionsFactoryKey(String name, ServletRequest request, ServletContext servletContext) { @@ -334,9 +335,10 @@ /** * Create a factory for specified key. - * If creation failed, return default factory, and output an error message in - * console. - * @param key + * If creation failes, return default factory and log an error message. + * @param key The key. + * @param request Servlet request. + * @param servletContext Servlet context. * @return Definition factory for specified key. * @throws DefinitionsFactoryException If an error occur while creating factory. */ @@ -404,10 +406,11 @@ /** * Calculate the postixes along the search path from the base bundle to the - * bundle specified by baseName and locale. - * Method copied from java.util.ResourceBundle - * @param baseName the base bundle name - * @param locale the locale + * bundle specified by <code>baseName</code> and <code>locale</code>. + * Method copied from java.util.ResourceBundle. + * @param baseName The base bundle name. + * @param locale The locale. + * @return List containing postixes. */ private static List calculatePostixes(String baseName, Locale locale) { final List result = new ArrayList(MAX_BUNDLES_SEARCHED); @@ -443,12 +446,12 @@ * the XmlDefinitionsSet description. * The XmlDefinitionsSet description is created only if there is a definition file. * Inheritance is not resolved in the returned XmlDefinitionsSet. - * If no description file can be opened, and no definiion set is provided, return null. + * If no description file can be opened and no definiion set is provided, return <code>null</code>. * @param postfix Postfix to add to each description file. - * @param xmlDefinitions Definitions set to which definitions will be added. If null, a definitions + * @param xmlDefinitions Definitions set to which definitions will be added. If <code>null</code>, a definitions * set is created on request. * @return XmlDefinitionsSet The definitions set created or passed as parameter. - * @throws DefinitionsFactoryException If an error happen during file parsing. + * @throws DefinitionsFactoryException On errors parsing file. */ private XmlDefinitionsSet parseXmlFiles( ServletContext servletContext, String postfix, XmlDefinitionsSet xmlDefinitions ) throws DefinitionsFactoryException @@ -469,14 +472,14 @@ /** * Parse specified xml file and add definition to specified definitions set. * This method is used to load several description files in one instances list. - * If filename exist and definition set is null, create a new set. Otherwise, return - * passed definition set (can be null). + * If filename exists and definition set is <code>null</code>, create a new set. Otherwise, return + * passed definition set (can be <code>null</code>). * @param servletContext Current servlet context. Used to open file. * @param filename Name of file to parse. * @param xmlDefinitions Definitions set to which definitions will be added. If null, a definitions * set is created on request. * @return XmlDefinitionsSet The definitions set created or passed as parameter. - * @throws DefinitionsFactoryException If an error happen during file parsing. + * @throws DefinitionsFactoryException On errors parsing file. */ private XmlDefinitionsSet parseXmlFile( ServletContext servletContext, String filename , XmlDefinitionsSet xmlDefinitions) throws DefinitionsFactoryException @@ -547,6 +550,9 @@ * Concat postfix to the name. Take care of existing filename extension. * Transform the given name "name.ext" to have "name" + "postfix" + "ext". * If there is no ext, return "name" + "postfix". + * @param name Filename. + * @param postfix Postfix to add. + * @return Concatenated filename. */ private String concatPostfix( String name, String postfix ) { @@ -566,14 +572,15 @@ } /** - * + * Return String representation. + * @return String representation. */ public String toString() { StringBuffer buff = new StringBuffer( "I18nFactorySet : \n" ); buff.append( "--- default factory ---\n" ); buff.append( defaultFactory.toString() ); - buff.append( "\n--- others factories ---\n" ); + buff.append( "\n--- other factories ---\n" ); Iterator i = factories.values().iterator(); while( i.hasNext() ) { 1.2 +24 -23 jakarta-struts/src/share/org/apache/struts/tiles/xmlDefinition/FactorySet.java Index: FactorySet.java =================================================================== RCS file: /home/cvs/jakarta-struts/src/share/org/apache/struts/tiles/xmlDefinition/FactorySet.java,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- FactorySet.java 25 Jun 2002 03:15:43 -0000 1.1 +++ FactorySet.java 27 Feb 2003 19:19:42 -0000 1.2 @@ -68,17 +68,17 @@ import org.apache.struts.tiles.DefinitionsFactoryException; import org.apache.struts.tiles.FactoryNotFoundException; -import javax.servlet.ServletRequest; import javax.servlet.ServletContext; -import java.util.Map; +import javax.servlet.ServletRequest; import java.util.HashMap; import java.util.Iterator; +import java.util.Map; /** * Component Definitions factory. * This factory contains several factories identified by a key. The - * getDefinition() method first look for the factory key, retrieve or create this - * factory and then call getDefinition() on the found factory. + * getDefinition() method first looks for the factory key, retrieves or creates this + * factory and then calls its getDefinition(). */ public abstract class FactorySet implements ComponentDefinitionsFactory { @@ -88,26 +88,27 @@ /** * Extract key that will be used to get the sub factory. - * @param name Name of requested definition + * @param name Name of requested definition. * @param request Current servlet request. - * @param servletContext Current servlet context + * @param servletContext Current servlet context. + * @return Object. */ abstract protected Object getDefinitionsFactoryKey(String name, ServletRequest request, ServletContext servletContext); /** * Get default factory. - * @return Default factory + * @return Default factory. */ abstract protected DefinitionsFactory getDefaultFactory(); /** * Get a factory by its key. - * If key is null, return defaultFactory. - * Search in loaded factory. If not found, call create factory, and store return value in + * If key is <code>null</code>, return defaultFactory. + * Search in loaded factories. If not found, create factory and store return value in * loaded factories. - * @param key Key of requested definition + * @param key Key of requested definition. * @param request Current servlet request. - * @param servletContext Current servlet context + * @param servletContext Current servlet context. * @throws DefinitionsFactoryException If an error occur while creating factory. */ protected DefinitionsFactory getFactory(Object key, ServletRequest request, ServletContext servletContext) @@ -137,11 +138,10 @@ /** * Get a definition by its name. - * @throws DefinitionsFactoryException An error occur while getting - * definition. - * @param name Name of requested definition + * + * @param name Name of requested definition. * @param request Current servlet request. - * @param servletContext Current servlet context + * @param servletContext Current servlet context. * @throws NoSuchDefinitionException No definition found for specified name * @throws DefinitionsFactoryException General exception */ @@ -159,9 +159,9 @@ /** * Create a factory for specified key. * This method is called by getFactory() when the requested factory doesn't already exist. - * Must return a factory, even a default one. - * Real implementation need to provide this method. - * @param key Key of requested definition + * Must return a factory, or a default one. + * Real implementation needs to provide this method. + * @param key Key of requested definition. * @param request Current servlet request. * @param servletContext Current servlet context * @throws DefinitionsFactoryException If an error occur while creating factory. @@ -178,7 +178,7 @@ throws DefinitionsFactoryException; /** - * + * Constructor. */ public FactorySet() { @@ -186,7 +186,8 @@ } /** - * + * Return String representation. + * @return String representation. */ public String toString() { 1.3 +14 -10 jakarta-struts/src/share/org/apache/struts/tiles/xmlDefinition/DefinitionsFactory.java Index: DefinitionsFactory.java =================================================================== RCS file: /home/cvs/jakarta-struts/src/share/org/apache/struts/tiles/xmlDefinition/DefinitionsFactory.java,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- DefinitionsFactory.java 16 Nov 2002 07:22:55 -0000 1.2 +++ DefinitionsFactory.java 27 Feb 2003 19:19:42 -0000 1.3 @@ -80,16 +80,19 @@ */ public class DefinitionsFactory implements Serializable { - /** */ + /** Underlying map containing all definitions.*/ protected Map definitions; /** * Get a definition by its name. + * @param name Name of the definition. + * @param request Servlet request. + * @param servletContext Servlet context. * @throws DefinitionsFactoryException An error occur while getting * definition. * @throws NoSuchDefinitionException No definition found for specified name * Implementation can throw more accurate exception as a subclass of this - * exception + * exception. */ public ComponentDefinition getDefinition(String name, ServletRequest request, ServletContext servletContext) throws NoSuchDefinitionException, DefinitionsFactoryException @@ -98,8 +101,8 @@ } /** - * Put definition in set - * @param definition + * Put definition in set. + * @param definition Definition to put. */ public void putDefinition(ComponentDefinition definition) { @@ -108,8 +111,8 @@ /** * Constructor. - * Create a factory initialized with definitions from XmlDefinitionsSet. - * @param xmlDefinitions resolved definition from XmlDefinitionSet. + * Create a factory initialized with definitions from [EMAIL PROTECTED] XmlDefinitionsSet}. + * @param xmlDefinitions Resolved definition from XmlDefinitionSet. * @throws NoSuchDefinitionException If an error occurs while resolving inheritance */ public DefinitionsFactory(XmlDefinitionsSet xmlDefinitions) @@ -129,7 +132,8 @@ } // end loop } /** - * + * Return String representation. + * @return String representation. */ public String toString() {
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]