Changeset 2101 for FCKeditor.Java/trunk

Show
Ignore:
Timestamp:
2008-06-23 00:00:48 (5 months ago)
Author:
mosipov
Message:

NEW - #1968: Javadoc issues

Location:
FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor
Files:
19 modified

Legend:

Unmodified
Added
Removed

  • FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/connector/ConnectorServlet.java

    r2028 r2101  
    5151 
    5252/** 
    53  * Servlet to upload and browse files.<br> 
    54  *  
    55  * This servlet accepts 4 commands used to retrieve and create files and folders from a server 
    56  * directory. The allowed commands are: 
     53 * Servlet to upload and browse files.<br /> 
     54 *  
     55 * This servlet accepts 4 commands which interact with the server-side 
     56 * filesystem.<br /> 
     57 * The allowed commands are: 
    5758 * <ul> 
    58  * <li>GetFolders: Retrieve the list of directory under the current folder 
    59  * <li>GetFoldersAndFiles: Retrive the list of files and directory under the current folder 
    60  * <li>CreateFolder: Create a new directory under the current folder 
    61  * <li>FileUpload: Send a new file to the server (must be sent with a POST) 
     59 * <li><code>GetFolders</code>: Retrieves a list of folders in the current 
     60 * folder</li> 
     61 * <li><code>GetFoldersAndFiles</code>: Retrives a list of files and folders 
     62 * in the current folder</li> 
     63 * <li><code>CreateFolder</code>: Creates a new folder in the current folder</li> 
     64 * <li><code>FileUpload</code>: Stores an uploaded file into the current 
     65 * folder. (must be sent with POST)</li> 
    6266 * </ul> 
    6367 *  
    … …  
    7074 
    7175        /** 
    72          * Initialize the servlet.<br> 
    73          * The default directory for user files will be constructed. 
     76         * Initialize the servlet: <code>mkdir</code> &lt;DefaultUserFilesPath&gt; 
    7477         */ 
    7578        public void init() throws ServletException, IllegalArgumentException { 
    76                 // check, if 'baseDir' exists 
    7779                String realDefaultUserFilesPath = getServletContext().getRealPath( 
    7880                        ConnectorHandler.getDefaultUserFilesPath()); 
    … …  
    8183                UtilsFile.checkDirAndCreate(defaultUserFilesDir); 
    8284 
    83                 logger.info("ConnectorServlet successful initialized!"); 
     85                logger.info("ConnectorServlet successfully initialized!"); 
    8486        } 
    8587 
    8688        /** 
    87          * Manage the Get requests (GetFolders, GetFoldersAndFiles, CreateFolder).<br> 
     89         * Manage the <code>GET</code> requests (<code>GetFolders</code>, 
     90         * <code>GetFoldersAndFiles</code>, <code>CreateFolder</code>).<br/> 
    8891         *  
    89          * The servlet accepts commands sent in the following format:<br> 
    90          * connector?Command=CommandName&Type=ResourceType&CurrentFolder=FolderPath<br> 
    91          * <br> 
    92          * It executes the commands and then return the results to the client in XML format. 
    93          *  
     92         * The servlet accepts commands sent in the following format:<br/> 
     93         * <code>connector?Command=&lt;CommandName&gt;&Type=&lt;ResourceType&gt;&CurrentFolder=&lt;FolderPath&gt;</code> 
     94         * <p> 
     95         * It executes the commands and then returns the result to the client in XML 
     96         * format. 
     97         * </p> 
    9498         */ 
    9599        public void doGet(HttpServletRequest request, HttpServletResponse response) 
    … …  
    174178 
    175179        /** 
    176          * Manage the Post requests (FileUpload).<br> 
     180         * Manage the <code>POST</code> requests (<code>FileUpload</code>).<br /> 
    177181         *  
    178          * The servlet accepts commands sent in the following format:<br> 
    179          * connector?Command=FileUpload&Type=ResourceType&CurrentFolder=FolderPath<br> 
     182         * The servlet accepts commands sent in the following format:<br /> 
     183         * <code>connector?Command=&lt;FileUpload&gt;&Type=&lt;ResourceType&gt;&CurrentFolder=&lt;FolderPath&gt;</code> 
     184         * with the file in the <code>POST</code> body.<br /> 
    180185         * <br> 
    181          * It store the file (renaming it in case a file with the same name exists) and then return an 
    182          * HTML file with a javascript command in it. 
     186         * It stores an uploaded file (renames a file if another exists with the 
     187         * same name) and then returns the JavaScript callback. 
    183188         */ 
    184189        @SuppressWarnings("unchecked") 
    … …  
    202207                UploadResponse ur; 
    203208 
    204                 // if this is a QuickUpload-Request, 'commandStr' and 'currentFolderStr' are empty 
     209                // if this is a QuickUpload request, 'commandStr' and 'currentFolderStr' 
     210                // are empty 
    205211                if (Utils.isEmpty(commandStr) && Utils.isEmpty(currentFolderStr)) { 
    206212                        commandStr = "QuickUpload"; 

  • FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/FCKeditorConfig.java

    r1905 r2101  
    3434/** 
    3535 * Contains the configuration settings for the FCKEditor.<br> 
    36  * Adding element to this collection you can override the settings specified in 
    37  * the config.js file. 
     36 * By adding elements to this collection you can override the settings specified 
     37 * in the config.js file. 
    3838 *  
    3939 * @version $Id$ 
    … …  
    5252 
    5353        /** 
    54          * Generate the url parameter sequence used to pass this configuration to 
    55          * the editor. 
     54         * Generates the url parameter sequence from this configuration which is 
     55         * passed to the editor. 
    5656         *  
    57          * @return html endocode sequence of configuration parameters 
     57         * @return html encoded sequence of configuration parameters 
    5858         */ 
    5959        public String getUrlParams() { 

  • FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/FCKeditor.java

    r1682 r2101  
    3030 
    3131/** 
    32  * FCKeditor control class.<br> 
    33  *  
     32 * FCKeditor class.<br /> 
    3433 * It creates the html code for the FCKeditor based on the following things: 
    3534 * <ul> 
    36  * <li>browser's capabilities</li> 
     35 * <li>browser capabilities</li> 
    3736 * <li>different properties settings managed by the {@link PropertiesLoader}</li> 
    38  * <li>settings from the 'caller', eg. jsp-pages</li> 
     37 * <li>settings from the FCKeditor tag, template engines and other systems</li> 
    3938 * </ul> 
    4039 *  
    … …  
    5756        /** 
    5857         * Main constructor.<br> 
    59          * All important settings are done here and will be preset by there defaults taken from 
    60          * {@link PropertiesLoader}. 
     58         * All important settings are done here and will be preset by the defaults 
     59         * taken from {@link PropertiesLoader}. 
    6160         *  
    6261         * @param request 
    … …  
    116115 
    117116        /** 
    118          * Set the initial value to be edited.<br> 
    119          * In HTML code 
     117         * Set the initial value to be edited as HTML markup. 
    120118         *  
    121119         * @param value 
    … …  
    127125 
    128126        /** 
    129          * Set the dir where the FCKeditor files reside on the server.<br> 
    130          * <b>Remarks</b>:<br> 
    131          * Avoid using relative paths. It is preferable to set the base path starting from the root (/).<br> 
    132          * Always finish the path with a slash (/). 
     127         * Sets the directory where the FCKeditor resides on the server.<br /> 
     128         * <strong>Remarks</strong>: Avoid using relative paths. Use an absolute 
     129         * path from the context (e.g. /fckeditor). 
    133130         *  
    134131         * @param value 
    … …  
    170167 
    171168        /** 
    172          * Get the advanced configuation set.<br> 
    173          * Adding element to this collection you can override the settings specified in the config.js 
    174          * file. 
     169         * Get the advanced configuation set.<br /> 
     170         * By adding elements to this collection you can override the settings 
     171         * specified in the config.js file. 
    175172         *  
    176173         * @return configuration collection 
    … …  
    190187        } 
    191188 
     189        /** 
     190         * Escape base XML entities as specified <a 
     191         * href="http://en.wikipedia.org/wiki/Xml#Entity_references">here</a> 
     192         *  
     193         * @param txt 
     194         *            Text to escape. 
     195         * @return Escaped text. 
     196         */ 
    192197        private String escapeXml(String txt) { 
    193198                if (Utils.isEmpty(txt)) 
    194199                        return txt; 
     200                // TODO Strings are inefficent, use StringBuffer instead 
    195201                txt = txt.replaceAll("&", "&#38;"); 
    196202                txt = txt.replaceAll("<", "&#60;"); 
    … …  
    201207        } 
    202208 
    203         /** 
    204          * Minimum implementation, see ticket #27 for detailed information. 
     209        /* 
     210         * (non-Javadoc) 
     211         * @see #createHtml() 
    205212         */ 
    206213        public String create() { 
    207214                return createHtml(); 
    208215        } 
    209  
     216         
     217        /* 
     218         * (non-Javadoc) 
     219         * @see #createHtml() 
     220         */ 
    210221        @Override 
    211222        public String toString() { 
    … …  
    214225 
    215226        /** 
    216          * Generate the HTML Code for the editor. <br> 
    217          * Evalute the browser capabilities and generate the editor if compatible, or a simple textarea 
    218          * otherwise. 
    219          *  
    220          * @return html code 
     227         * Minimum implementation, see ticket #27 for detailed information. Generate 
     228         * the HTML Code for the editor.<br /> 
     229         * Evaluate the browser capabilities and generate the editor if compatible, 
     230         * or a simple textarea otherwise. 
     231         *  
     232         * @return FCKeditor html code 
    221233         */ 
    222234        public String createHtml() { 

  • FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/handlers/CommandHandler.java

    r1905 r2101  
    2525 
    2626/** 
    27  * Handler for the get and post commands. 
     27 * Handler for <code>GET</code> and <code>POST</code> commands. 
    2828 *  
    2929 * @version $Id$ 
    … …  
    6060         * Getter for the name. 
    6161         *  
    62          * @return name 
     62         * @return The command name 
    6363         */ 
    6464        public String getName() { 
    … …  
    7070         *  
    7171         * @param name 
    72          * @return A {@link CommandHandler} object holding the value represented by the string 
    73          *         argument. 
     72         *            A command to retrieve 
     73         * @return A {@link CommandHandler} object holding the value represented by 
     74         *         the string argument. 
    7475         * @throws IllegalArgumentException 
    75          *             If 'name' is null or can't be parsed. 
     76         *             If 'name' is <code>null</code> or does not exist. 
    7677         */ 
    7778        public static CommandHandler valueOf(final String name) throws IllegalArgumentException { 
    … …  
    8687 
    8788        /** 
    88          * Checks, if a specfied string is a valid representation of a get command. 
     89         * Checks if a specfied string represents a valid <code>GET</code> 
     90         * command. 
    8991         *  
    9092         * @param name 
    91          * @return True, if the string representation is valid, or false. 
     93         *            A command string to check 
     94         * @return <code>true</code> if the string representation is valid else 
     95         *         <code>false</code>. 
    9296         */ 
    9397        public static boolean isValidForGet(final String name) { 
    … …  
    96100 
    97101        /** 
    98          * Checks, if a specfied string is a valid representation of a post command. 
     102         * Checks if a specfied string represents a valid <code>POST</code> 
     103         * command. 
    99104         *  
    100105         * @param name 
    101          * @return True, if the string representation is valid, or false. 
     106         *            A command string to check 
     107         * @return <code>true</code> if the string representation is valid else 
     108         *         <code>false</code>. 
    102109         */ 
    103110        public static boolean isValidForPost(final String name) { 
    … …  
    107114         
    108115        /** 
    109          * A wrapper for {@link #valueOf(String)}. It returns null instead of throwing an exception. 
     116         * A wrapper for {@link #valueOf(String)}. It returns null instead of 
     117         * throwing an exception. 
    110118         *  
    111          * @param name 
    112          * @return A {@link CommandHandler} object holding the value represented by the string 
    113          *         argument, or null. 
     119         * @param name A command string to check 
     120         * @return A {@link CommandHandler} object holding the value represented by 
     121         *         the string argument, or <code>null</code>. 
    114122         */ 
    115123        public static CommandHandler getCommand(final String name) { 
    … …  
    128136        @Override 
    129137        public boolean equals(Object obj) { 
     138                if (obj == null) 
     139                        return false; 
    130140                try { 
    131141                        CommandHandler rt = (CommandHandler) obj; 

  • FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/handlers/ConnectorHandler.java

    r1905 r2101  
    2626 
    2727/** 
    28  * Handler for some base properties.<br> 
    29  * It's a kind of wrapper to some basic properties handled by the {@link PropertiesLoader}. 
     28 * Handler for Connector-related properties.<br /> 
     29 * Wraps to the {@link PropertiesLoader}. 
    3030 *  
    3131 * @version $Id$ 
    … …  
    3434 
    3535        /** 
    36      * Getter for the base dir (using for user files). 
    37      *  
    38      * @return {@link UserPathBuilder#getUserFilesPath(HttpServletRequest)} or the default base dir, if 
    39      *         {@link UserPathBuilder}} isn't set. 
    40      */ 
    41     public static String getUserFilesPath(final HttpServletRequest servletRequest) { 
    42         String userFilePath = RequestCycleHandler.getUserFilePath(servletRequest); 
     36         * Getter for the <code>UserFilesPath</code>. 
     37         *  
     38         * @return {@link UserPathBuilder#getUserFilesPath(HttpServletRequest)} or 
     39         *         the <code>DefaultUserFilePath</code> if {@link UserPathBuilder} 
     40         *         isn't set. 
     41         */ 
     42        public static String getUserFilesPath(final HttpServletRequest request) { 
     43        String userFilePath = RequestCycleHandler.getUserFilePath(request); 
    4344        return (userFilePath != null) ? userFilePath : getDefaultUserFilesPath(); 
    4445    } 
    4546 
    4647        /** 
    47          * Getter for the default handling of single extensions. 
     48         * Getter for the default handling of files with multiple extensions. 
    4849         *  
    49          * @return the forceSingleExtension 
     50         * @return <code>true</code> if single extension only should be enforced 
     51         *         else <code>false</code>. 
    5052         */ 
    5153        public static boolean isForceSingleExtension() { 
    … …  
    5456 
    5557        /** 
    56          * Getter for the value to instruct the connector to return the full URL of a file/folder in the 
    57          * XML response rather than the absolute URL. 
     58         * Getter for the value to instruct the connector to return the full URL of 
     59         * a file/folder in the XML response rather than the absolute URL. 
    5860         *  
    59          * @return Boolean value of the property 'connector.fullUrl'. 
     61         * @return <code>true</code> if the property <code>connector.fullUrl</code> is 
     62         *         set else <code>false</code>. 
    6063         */ 
    6164        public static boolean isFullUrl() { 
    … …  
    6467 
    6568        /** 
    66          * Getter for the default userFilesPath. 
     69         * Getter for the default <code>UserFilesPath</code>. 
    6770         *  
    68          * @return Default userfiles path (/userfiles) 
     71         * @return <code>DefaultUserFilesPath</code> (/userfiles) 
    6972         */ 
    7073        public static String getDefaultUserFilesPath() { 
    … …  
    7376         
    7477        /** 
    75          * Getter for the value to instruct the Connector to check, if the uploaded image is really one. 
     78         * Getter for the value to instruct the Connector to check if the uploaded 
     79         * image is really an image. 
    7680         *  
    77          * @return Boolean value of the property 'connector.secureImageUploads'. 
     81         * @return Boolean value of the property 
     82         *         <code>connector.secureImageUploads</code>. 
    7883         */ 
    7984        public static boolean isSecureImageUploads() { 

  • FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/handlers/ExtensionsHandler.java

    r1995 r2101  
    2828 
    2929/** 
    30  * Handler which manages the allowed and denied extensions for each resource type. The 
    31  * extensions are preset by the properties managed by {@link PropertiesLoader}.<br> 
    32  * <br> 
    33  * Hint: It's recommend to use either allowed or denied extensions for one file type. 
    34  * Never use both at the same time! That's why denied extensions of a file type will be  
    35  * deleted, if you set the allowed one and vice versa. 
     30 * This handler manages the allowed and denied extensions for each resource 
     31 * type. The extensions are preset by the properties managed by 
     32 * {@link PropertiesLoader}. 
     33 * <p> 
     34 * <em>Hint</em>: It's recommend to use either allowed or denied extensions for one file 
     35 * type. <strong>Never</strong> use both at the same time! That's why denied 
     36 * extensions of a file type will be deleted if you set the allowed one and vice 
     37 * versa. 
     38 * </p> 
    3639 *  
    3740 * @version $Id$ 
    … …  
    7477 
    7578        /** 
    76          * Setter for the allowed extensions of a file type. The denied extensions will be cleared.<br> 
    77          * If 'extensionsList' is null, allowed extensions kept untouched. 
     79         * Setter for the allowed extensions of a file type. The denied extensions 
     80         * will be cleared.<br /> 
     81         * If <code>extensionsList</code> is <code>null</code>, allowed 
     82         * extensions are kept untouched. 
    7883         *  
    7984         * @param type 
    80          *          The file type. 
     85         *            The file type. 
    8186         * @param extensionsList 
    82          *          Required format: <code>ext1&#124;ext2&#124;ext3</code> 
     87         *            Required format: <code>ext1&#124;ext2&#124;ext3</code> 
    8388         */ 
    8489        public static void setExtensionsAllowed(final ResourceTypeHandler type, final String extensionsList) { 
    … …  
    9398         *  
    9499         * @param type 
    95          *          The file type. 
     100         *            The file type. 
    96101         * @return Set of denied extensions or an empty set. 
    97102         */ 
    … …  
    101106 
    102107        /** 
    103          * Setter for the denied extensions of a file type. The allowed extensions will be cleared.<br> 
    104          * If 'extensionsList' is null, denied extensions kept untouched. 
     108         * Setter for the denied extensions of a file type. The allowed extensions 
     109         * will be cleared.<br /> 
     110         * If <code>extensionsList</code> is <code>null</code>, denied 
     111         * extensions are kept untouched. 
    105112         *  
    106113         * @param type 
    107          *          The file type. 
     114         *            The file type. 
    108115         * @param extensionsList 
    109          *          Required format: <code>ext1&#124;ext2&#124;ext3</code> 
     116         *            Required format: <code>ext1&#124;ext2&#124;ext3</code> 
    110117         */ 
    111118        public static void setExtensionsDenied(final ResourceTypeHandler type, final String extensionsList) { 
    … …  
    117124 
    118125        /** 
    119          * Checks, if an extension is allowed for a file type. 
     126         * Checks if an extension is allowed for a file type. 
    120127         *  
    121128         * @param type 
     129         *            The resource type you want to check. 
    122130         * @param extension 
    123          * @return True, false. False is returned too, if 'type' or 'extensions' is null. 
     131         *            The extension you want to check. 
     132         * @return <code>true</code> is extension is allowed else 
     133         *         <code>false</code>. <em>Attention</em>: <code>false</code> 
     134         *         is always returned if 'type' or 'extensions' is <code>null</code>. 
    124135         */ 
    125136        public static boolean isAllowed(final ResourceTypeHandler type, final String extension) { 

  • FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/handlers/PropertiesLoader.java

    r1685 r2101  
    2626import java.util.Properties; 
    2727 
    28 import net.fckeditor.tool.Utils; 
    29  
    3028import org.slf4j.Logger; 
    3129import org.slf4j.LoggerFactory; 
    3230 
    3331/** 
    34  * Handler to hold the basic properties.<br> 
    35  * The main default file is 'default.properties' in the deepth of the classpath and should be 
    36  * untouched. If there is a file named 'fckeditor.properties' in the root of the classpath, it will 
    37  * be loaded. Values which are loaded before, will be overwritten.<br> 
    38  * If you won't use an extra properties file to adjust the defaults, you can use 
    39  * {@link #setProperty(String, String)} instead. 
     32 * This handler gives you access to properties stored in 
     33 * <code>/net/fckeditor/handlers/default.properties</code> and 
     34 * <code>/fckeditor.properties</code>.<br /> 
     35 * This class loads the properties files as follows: 
     36 * <ol> 
     37 * <li>Load <code>default.properties</code></li> 
     38 * <li>Load <code>fckeditor.properties</code> if present.</li> 
     39 * </ol> 
     40 * <em>Attention</em>: Properties specified in 
     41 * <code>fckeditor.properties</code> will override properties loaded from 
     42 * <code>default.properties</code>. (intended behavior)<br /> 
     43 * <em>Hint</em>: You may set properties programmatically with 
     44 * {@link #setProperty(String, String)} instead or additionally. 
    4045 *  
    4146 * @version $Id$ 
    … …  
    4752        static { 
    4853                try { 
    49                         // 1. load system defaults 
     54                        // 1. load library defaults 
    5055                        properties.load(new BufferedInputStream(PropertiesLoader.class 
    5156                                .getResourceAsStream("default.properties"))); 
    … …  
    5459                        InputStream in = PropertiesLoader.class.getResourceAsStream("/fckeditor.properties"); 
    5560                        if (in == null)