Skip to content

Commit c3f651f

Browse files
augustdaugustd
committed
Added JavaDoc stubs
1 parent 283560d commit c3f651f

File tree

1 file changed

+133
-5
lines changed

1 file changed

+133
-5
lines changed

‎src/org/owasp/fileio/FileValidator.java‎

Lines changed: 133 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
import java.io.File;
1717
import java.io.IOException;
1818
import java.util.ArrayList;
19+
import java.util.Arrays;
1920
import java.util.Iterator;
2021
import java.util.List;
2122
import java.util.regex.Pattern;
@@ -63,6 +64,7 @@ public FileValidator() {
6364

6465
/**
6566
* Initialize file validator with an appropriate set of codecs
67+
* @param encoder
6668
*/
6769
public FileValidator(Encoder encoder) {
6870
fileEncoder = encoder;
@@ -109,6 +111,13 @@ public void setFileEncoder(Encoder fileEncoder) {
109111
*
110112
* <p><b>Note:</b> On platforms that support symlinks, this function will fail canonicalization if directorypath is a symlink. For example, on MacOS X, /etc is actually /private/etc. If you mean
111113
* to use /etc, use its real path (/private/etc), not the symlink (/etc).</p>
114+
*
115+
* @param context
116+
* @param input
117+
* @param parent
118+
* @param allowNull
119+
*
120+
* @return true if no validation exceptions are thrown
112121
*/
113122
public boolean isValidDirectoryPath(String context, String input, File parent, boolean allowNull) {
114123
try {
@@ -124,6 +133,15 @@ public boolean isValidDirectoryPath(String context, String input, File parent, b
124133
*
125134
* <p><b>Note:</b> On platforms that support symlinks, this function will fail canonicalization if directorypath is a symlink. For example, on MacOS X, /etc is actually /private/etc. If you mean
126135
* to use /etc, use its real path (/private/etc), not the symlink (/etc).</p>
136+
*
137+
* @param context A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the
138+
* value passed in.
139+
* @param input The actual input data to validate.
140+
* @param parent
141+
* @param allowNull If allowNull is true then an input that is NULL or an empty string will be legal. If allowNull is false then NULL or an empty String will throw a ValidationException.
142+
* @param errors
143+
*
144+
* @return true if no validation exceptions are thrown
127145
*/
128146
public boolean isValidDirectoryPath(String context, String input, File parent, boolean allowNull, List<ValidationException> errors) {
129147
try {
@@ -144,6 +162,7 @@ public boolean isValidDirectoryPath(String context, String input, File parent, b
144162
* @param context A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the
145163
* value passed in.
146164
* @param input The actual input data to validate.
165+
* @param parent
147166
* @param allowNull If allowNull is true then an input that is NULL or an empty string will be legal. If allowNull is false then NULL or an empty String will throw a ValidationException.
148167
*
149168
* @return A valid directory path
@@ -192,6 +211,14 @@ public String getValidDirectoryPath(String context, String input, File parent, b
192211

193212
/**
194213
* Calls getValidDirectoryPath with the supplied error List to capture ValidationExceptions
214+
*
215+
* @param context
216+
* @param input
217+
* @param parent
218+
* @param allowNull
219+
* @param errors
220+
*
221+
* @return
195222
*/
196223
public String getValidDirectoryPath(String context, String input, File parent, boolean allowNull, List<ValidationException> errors) {
197224

@@ -206,20 +233,40 @@ public String getValidDirectoryPath(String context, String input, File parent, b
206233

207234
/**
208235
* Calls getValidFileName with the default list of allowedExtensions
236+
*
237+
* @param context
238+
* @param input
239+
* @param allowNull
240+
*
241+
* @return true if no validation exceptions occur
209242
*/
210243
public boolean isValidFileName(String context, String input, boolean allowNull) {
211244
return isValidFileName(context, input, null, allowNull);
212245
}
213246

214247
/**
215248
* Calls getValidFileName with the default list of allowedExtensions
249+
*
250+
* @param context
251+
* @param input
252+
* @param allowNull
253+
* @param errors
254+
*
255+
* @return true if no validation exceptions occur
216256
*/
217257
public boolean isValidFileName(String context, String input, boolean allowNull, List<ValidationException> errors) {
218258
return isValidFileName(context, input, null, allowNull, errors);
219259
}
220260

221261
/**
222262
* Calls getValidFileName with the default list of allowedExtensions
263+
*
264+
* @param context
265+
* @param input
266+
* @param allowedExtensions
267+
* @param allowNull
268+
*
269+
* @return true if no validation exceptions occur
223270
*/
224271
public boolean isValidFileName(String context, String input, List<String> allowedExtensions, boolean allowNull) {
225272
try {
@@ -232,6 +279,14 @@ public boolean isValidFileName(String context, String input, List<String> allowe
232279

233280
/**
234281
* Calls getValidFileName with the default list of allowedExtensions
282+
*
283+
* @param context
284+
* @param input
285+
* @param allowedExtensions
286+
* @param allowNull
287+
* @param errors
288+
*
289+
* @return true if no validation exceptions occur
235290
*/
236291
public boolean isValidFileName(String context, String input, List<String> allowedExtensions, boolean allowNull, List<ValidationException> errors) {
237292
try {
@@ -253,6 +308,7 @@ public boolean isValidFileName(String context, String input, List<String> allowe
253308
* @param context A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the
254309
* value passed in.
255310
* @param input The actual input data to validate.
311+
* @param allowedExtensions
256312
* @param allowNull If allowNull is true then an input that is NULL or an empty string will be legal. If allowNull is false then NULL or an empty String will throw a ValidationException.
257313
*
258314
* @return A valid file name
@@ -306,6 +362,14 @@ public String getValidFileName(String context, String input, List<String> allowe
306362

307363
/**
308364
* Calls getValidFileName with the supplied List to capture ValidationExceptions
365+
*
366+
* @param context
367+
* @param input
368+
* @param allowedParameters
369+
* @param allowNull
370+
* @param errors
371+
*
372+
* @return
309373
*/
310374
public String getValidFileName(String context, String input, List<String> allowedParameters, boolean allowNull, List<ValidationException> errors) {
311375
try {
@@ -322,6 +386,18 @@ public String getValidFileName(String context, String input, List<String> allowe
322386
*
323387
* <p><b>Note:</b> On platforms that support symlinks, this function will fail canonicalization if directorypath is a symlink. For example, on MacOS X, /etc is actually /private/etc. If you mean
324388
* to use /etc, use its real path (/private/etc), not the symlink (/etc).</p>
389+
*
390+
* @param context
391+
* @param directorypath
392+
* @param filename
393+
* @param parent
394+
* @param content
395+
* @param maxBytes
396+
* @param allowNull
397+
*
398+
* @return true if no validation exceptions are thrown
399+
*
400+
* @throws org.owasp.fileio.ValidationException
325401
*/
326402
public boolean isValidFileUpload(String context, String directorypath, String filename, File parent, byte[] content, int maxBytes, boolean allowNull) throws ValidationException {
327403
return (isValidFileName(context, filename, allowNull)
@@ -334,6 +410,18 @@ && isValidDirectoryPath(context, directorypath, parent, allowNull)
334410
*
335411
* <p><b>Note:</b> On platforms that support symlinks, this function will fail canonicalization if directorypath is a symlink. For example, on MacOS X, /etc is actually /private/etc. If you mean
336412
* to use /etc, use its real path (/private/etc), not the symlink (/etc).</p>
413+
*
414+
* @param context A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the
415+
* value passed in.
416+
* @param directorypath
417+
* @param filename
418+
* @param parent
419+
* @param content
420+
* @param maxBytes
421+
* @param allowNull If allowNull is true then an input that is NULL or an empty string will be legal. If allowNull is false then NULL or an empty String will throw a ValidationException.
422+
* @param errors
423+
*
424+
* @return true if no validation exceptions are thrown
337425
*/
338426
public boolean isValidFileUpload(String context, String directorypath, String filename, File parent, byte[] content, int maxBytes, boolean allowNull, List<ValidationException> errors) {
339427
return (isValidFileName(context, filename, allowNull, errors)
@@ -346,10 +434,12 @@ && isValidDirectoryPath(context, directorypath, parent, allowNull, errors)
346434
*
347435
* @param context A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the
348436
* value passed in.
349-
* @param filepath The file path of the uploaded file.
437+
* @param directorypath The file path of the uploaded file.
350438
* @param filename The filename of the uploaded file
439+
* @param parent
351440
* @param content A byte array containing the content of the uploaded file.
352441
* @param maxBytes The max number of bytes allowed for a legal file upload.
442+
* @param allowedExtensions
353443
* @param allowNull If allowNull is true then an input that is NULL or an empty string will be legal. If allowNull is false then NULL or an empty String will throw a ValidationException.
354444
*
355445
* @throws ValidationException
@@ -362,9 +452,18 @@ public void assertValidFileUpload(String context, String directorypath, String f
362452

363453
/**
364454
* Calls getValidFileUpload with the supplied List to capture ValidationExceptions
455+
*
456+
* @param context
457+
* @param filepath
458+
* @param filename
459+
* @param parent
460+
* @param content
461+
* @param maxBytes
462+
* @param allowedExtensions
463+
* @param allowNull
464+
* @param errors
365465
*/
366-
public void assertValidFileUpload(String context, String filepath, String filename, File parent, byte[] content, int maxBytes, List<String> allowedExtensions, boolean allowNull, List<ValidationException> errors)
367-
throws ValidationException {
466+
public void assertValidFileUpload(String context, String filepath, String filename, File parent, byte[] content, int maxBytes, List<String> allowedExtensions, boolean allowNull, List<ValidationException> errors) {
368467
try {
369468
assertValidFileUpload(context, filepath, filename, parent, content, maxBytes, allowedExtensions, allowNull);
370469
} catch (ValidationException e) {
@@ -374,8 +473,15 @@ public void assertValidFileUpload(String context, String filepath, String filena
374473

375474
/**
376475
* Calls getValidFileContent and returns true if no exceptions are thrown.
476+
*
477+
* @param context
478+
* @param input
479+
* @param maxBytes
480+
* @param allowNull
481+
*
482+
* @return true if no validation exceptions occur
377483
*/
378-
public boolean isValidFileContent(String context, byte[] input, int maxBytes, boolean allowNull) throws ValidationException {
484+
public boolean isValidFileContent(String context, byte[] input, int maxBytes, boolean allowNull) {
379485
try {
380486
getValidFileContent(context, input, maxBytes, allowNull);
381487
return true;
@@ -386,6 +492,14 @@ public boolean isValidFileContent(String context, byte[] input, int maxBytes, bo
386492

387493
/**
388494
* Calls getValidFileContent and returns true if no exceptions are thrown.
495+
*
496+
* @param context
497+
* @param input
498+
* @param maxBytes
499+
* @param allowNull
500+
* @param errors
501+
*
502+
* @return true if no validation exceptions occur
389503
*/
390504
public boolean isValidFileContent(String context, byte[] input, int maxBytes, boolean allowNull, List<ValidationException> errors) {
391505
try {
@@ -434,7 +548,7 @@ public byte[] getValidFileContent(String context, byte[] input, long maxBytes, b
434548
if (allowNull) {
435549
return null;
436550
}
437-
throw new ValidationException(context + ": Input required", "Input required: context=" + context + ", input=" + input, context);
551+
throw new ValidationException(context + ": Input required", "Input required: context=" + context + ", input=" + Arrays.toString(input), context);
438552
}
439553

440554
if (input.length > maxBytes) {
@@ -446,6 +560,16 @@ public byte[] getValidFileContent(String context, byte[] input, long maxBytes, b
446560

447561
/**
448562
* Calls getValidFileContent with the supplied List to capture ValidationExceptions
563+
*
564+
* @param context
565+
* @param input
566+
* @param maxBytes
567+
* @param allowNull
568+
* @param errors
569+
*
570+
* @return
571+
*
572+
* @throws org.owasp.fileio.ValidationException
449573
*/
450574
public byte[] getValidFileContent(String context, byte[] input, int maxBytes, boolean allowNull, List<ValidationException> errors) throws ValidationException {
451575
try {
@@ -466,7 +590,9 @@ public byte[] getValidFileContent(String context, byte[] input, int maxBytes, bo
466590
* @param type The regular expression name which maps to the actual regular expression from "ESAPI.properties".
467591
* @param maxLength The maximum post-canonicalized String length allowed.
468592
* @param allowNull If allowNull is true then a input that is NULL or an empty string will be legal. If allowNull is false then NULL or an empty String will throw a ValidationException.
593+
*
469594
* @return The canonicalized user input.
595+
*
470596
* @throws ValidationException
471597
*/
472598
public String getValidInput(String context, String input, String type, int maxLength, boolean allowNull) throws ValidationException {
@@ -482,7 +608,9 @@ public String getValidInput(String context, String input, String type, int maxLe
482608
* @param maxLength The maximum String length allowed. If input is canonicalized per the canonicalize argument, then maxLength must be verified after canonicalization
483609
* @param allowNull If allowNull is true then a input that is NULL or an empty string will be legal. If allowNull is false then NULL or an empty String will throw a ValidationException.
484610
* @param canonicalize If canonicalize is true then input will be canonicalized before validation
611+
*
485612
* @return The user input, may be canonicalized if canonicalize argument is true
613+
*
486614
* @throws ValidationException
487615
*/
488616
public String getValidInput(String context, String input, String type, int maxLength, boolean allowNull, boolean canonicalize) throws ValidationException {

0 commit comments

Comments
 (0)