com.github.aliteralmind.codelet.util

Class FilenameBlackWhiteList

java.lang.Object

com.github.aliteralmind.codelet.util.FilenameBlackWhiteList

Direct Known Subclasses:

FilenameBlacklist, FilenameWhitelist

public class FilenameBlackWhiteList
extends Object

For black- or white-listing file paths or fully-qualified class names, with overrides. This is based on org.apache.commons.io.FilenameUtils.wildcardMatch(String, String, IOCase), with the exception paths and all wildcard patterns must be non-null and non-empty.

Source code

   import  com.github.aliteralmind.codelet.util.FilenameBlacklist;
   import  com.github.aliteralmind.codelet.util.FilenameWhitelist;
   import  org.apache.commons.io.IOCase;
public class BlackWhiteListForJavaClasses  {
   public static final void main(String[] ignored)  {

      FilenameBlacklist blackList = new FilenameBlacklist(IOCase.INSENSITIVE,
         //Propers:
            (new String[]{"xbn.io.*", "xbn.text.*"}),
         //Overrides:
            (new String[]{"xbn.text.line.*", "xbn.io.IOUtil.java"}),
         null);  //Debugging. on=System.out, off=null
      System.out.println(blackList.doAccept("xbn.io.IOUtil.java"));
      System.out.println(blackList.doAccept("xbn.io.TextAppenter.java"));
      System.out.println(blackList.doAccept("xbn.list.listify.Listify"));
      System.out.println(blackList.doAccept("xbn.text.UtilString.java"));
      System.out.println(blackList.doAccept("xbn.text.line.LineFilter.java"));

      System.out.println();

      FilenameWhitelist whiteList = new FilenameWhitelist(blackList, IOCase.INSENSITIVE,
         null);  //Debugging. On=System.out, off=null
      System.out.println(whiteList.doAccept("xbn.io.IOUtil.java"));
      System.out.println(whiteList.doAccept("xbn.io.TextAppenter.java"));
      System.out.println(whiteList.doAccept("xbn.list.listify.Listify"));
      System.out.println(whiteList.doAccept("xbn.text.UtilString.java"));
      System.out.println(whiteList.doAccept("xbn.text.line.LineFilter.java"));
   }
}

Output:

true
false
true
false
true

false
true
false
true
false

Since:

0.1.0

Author:

Copyright (C) 2014, Jeff Epstein (aliteralmind __DASH__ github __AT__ yahoo __DOT__ com), dual-licensed under the LGPL (version 3.0 or later) or the ASL (version 2.0). See source code for details. http://codelet.aliteralmind.com, https://github.com/aliteralmind/codelet

Constructor Summary

Constructors

Constructor and Description
FilenameBlackWhiteList(BlackOrWhite type, IOCase case_sensitivity, String[] proper_items, String[] override_items, Appendable dbgAccept_ifNonNull) Create a new instance.
FilenameBlackWhiteList(FilenameBlackWhiteList to_copyItemsFrom, BlackOrWhite type, IOCase case_sensitivity, Appendable dbgAccept_ifNonNull) Create a new instance from the lists in an existing FilenameBlackWhiteList.

Method Summary

Methods

Modifier and Type	Method and Description
StringBuilder	appendToString(StringBuilder to_appendTo)
boolean	areFieldsEqual(FilenameBlackWhiteList to_compareTo) Are all fields equal?.
boolean	doAccept(String path) Is the path (or fully-qualified class name) accepted?.
boolean	equals(Object to_compareTo)
IOCase	getCaseSensitivity() Is case ignored, required, or system-determined?.
List<String>	getImmutableOverrideList() The unmodifiable list of wildcard items that, when matched, override the "proper" finding.
List<String>	getImmutableProperList() The unmodifiable list of wildcard items that, when matched--and not overridden--are either acceptable (white-listed) or unacceptable (black-listed).
boolean	isMatchedByOverride(String path) Does the path match an override item?.
boolean	isMatchedByProper(String path) Does the path match a main item?.
boolean	isWhitelist() Is this a whitelist?.
static FilenameBlackWhiteList	newForAcceptAll(Appendable dbgAccept_ifNonNull) A new instance that accepts everything.
static FilenameBlackWhiteList	newFromConfigStringVars(String black_white_off, String ignore_require_system, String separator, String separated_propers, String separated_overrides, Appendable dbgLoading_ifNonNull, Appendable dbgAccept_ifNonNull) Creates a new white-or-blacklist from a set of string-variables as found in a configuration text file.
static FilenameBlackWhiteList	newFromProperties(Properties props, String separator, String black_white_offName, String ignore_require_systemName, String separated_propersName, String separated_overridesName, Appendable dbgLoading_ifNonNull, Appendable dbgAccept_ifNonNull) Creates a new white-or-blacklist from a set of properties.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

FilenameBlackWhiteList

public FilenameBlackWhiteList(BlackOrWhite type,
                      IOCase case_sensitivity,
                      String[] proper_items,
                      String[] override_items,
                      Appendable dbgAccept_ifNonNull)

Create a new instance.

Parameters:

type - May not be null. Get with isWhitelist().

case_sensitivity - May not be null. Get with getCaseSensitivity().

proper_items - The wildcard-match strings that define this black-or-white list. May not be null or empty, or contain null or duplicate elements.

override_items - If non-null and non-empty, the wildcard-match strings that should trump any proper items. When non-null, may not contain any null or duplicate elements, and each item should be a valid subset of those items in proper_items.

See Also:

FilenameBlackWhiteList(FilenameBlackWhiteList, BlackOrWhite, IOCase, Appendable)

FilenameBlackWhiteList

public FilenameBlackWhiteList(FilenameBlackWhiteList to_copyItemsFrom,
                      BlackOrWhite type,
                      IOCase case_sensitivity,
                      Appendable dbgAccept_ifNonNull)

Create a new instance from the lists in an existing FilenameBlackWhiteList.

Parameters:

to_copyItemsFrom - May not be null.

type - May not be null. Get with isWhitelist().

case_sensitivity - May not be null. Get with getCaseSensitivity().

See Also:

FilenameBlackWhiteList(BlackOrWhite, IOCase, String[], String[], Appendable)

Method Detail

isWhitelist

public boolean isWhitelist()

Is this a whitelist?.

Returns:

• true: Proper matching paths, when not overridden, are accepted
• false: Proper matching paths, when not overridden, are not accepted.

See Also:

FilenameBlackWhiteList(BlackOrWhite, IOCase, String[], String[], Appendable)

getCaseSensitivity

public IOCase getCaseSensitivity()

Is case ignored, required, or system-determined?.

Returns:

• IOCase.INSENSITIVE: If case is ignored.
• IOCase.SENSITIVE: If case is not ignored.
• IOCase.SYSTEM: If the underlying operation system determines case sensitivity.

See Also:

isMatchedByProper(s), isMatchedByOverride(s), FilenameUtils.wildcardMatchOnSystem(String, String)

getImmutableProperList

public List<String> getImmutableProperList()

The unmodifiable list of wildcard items that, when matched--and not overridden--are either acceptable (white-listed) or unacceptable (black-listed).

See Also:

getImmutableOverrideList(), isMatchedByProper(s), FilenameBlackWhiteList(bow,ioc,s[],s[])

getImmutableOverrideList

public List<String> getImmutableOverrideList()

The unmodifiable list of wildcard items that, when matched, override the "proper" finding. This is ignored when no proper item is matched.

See Also:

getImmutableProperList(), isMatchedByOverride(s), FilenameBlackWhiteList(bow,ioc,s[],s[])

toString

public String toString()

Overrides:

toString in class Object

appendToString

public StringBuilder appendToString(StringBuilder to_appendTo)

doAccept

public boolean doAccept(String path)

Is the path (or fully-qualified class name) accepted?.

Parameters:

path - May not be null or empty.

Returns:

isMatchedByProper(path)	isMatchedByOverride(path)	isWhitelist()	Returned
true	true	true	false
true	true	false	true
true	false	true	true
true	false	false	false
false	n/a	true	false
false	n/a	false	true

See Also:

FilenameUtils

isMatchedByProper

public boolean isMatchedByProper(String path)

Does the path match a main item?.

For each item in the proper-list, this calls

FilenameUtils.wildcardMatch(path, [proper-item], getCaseSensitivity())

If this returns true for any element, this function returns true. If it returns false for every element, this function returns false.

See Also:

doAccept(String)

isMatchedByOverride

public boolean isMatchedByOverride(String path)

Does the path match an override item?. This should only be used after a proper item is matched.

For each item in the override-list, this calls

FilenameUtils.wildcardMatch(path, [proper-item], getCaseSensitivity())

If this returns true for any element, this function returns true. If it returns false for every element, this function returns false.

See Also:

doAccept(String)

equals

public boolean equals(Object to_compareTo)

Overrides:

equals in class Object

Returns:

true If to_compareTo is non-null, a FilenameBlackWhiteList, and all its fields are equal. This is implemented as suggested by Joshua Bloch in "Effective Java" (2nd ed, item 8, page 46).

areFieldsEqual

public boolean areFieldsEqual(FilenameBlackWhiteList to_compareTo)

Are all fields equal?.

Parameters:

to_compareTo - May not be null.

newFromProperties

public static final FilenameBlackWhiteList newFromProperties(Properties props,
                                       String separator,
                                       String black_white_offName,
                                       String ignore_require_systemName,
                                       String separated_propersName,
                                       String separated_overridesName,
                                       Appendable dbgLoading_ifNonNull,
                                       Appendable dbgAccept_ifNonNull)

Creates a new white-or-blacklist from a set of properties.

All "Name" parameters must be the name of existing properties in props.

Parameters:

props - May not be null, and must contain properties named as in the "*Name" parameters.

Returns:

newFromConfigStringVars(black_white_off, ignore_require_system, separator, separated_propers, separated_overrides, dbgLoading_ifNonNull, dbgAccept_ifNonNull)
Where all variables (except separator) are the values of the properties with an empty-string default. Such as
String ignore_require_system = props.getProperty(ignore_require_systemName, "")

newFromConfigStringVars

public static final FilenameBlackWhiteList newFromConfigStringVars(String black_white_off,
                                             String ignore_require_system,
                                             String separator,
                                             String separated_propers,
                                             String separated_overrides,
                                             Appendable dbgLoading_ifNonNull,
                                             Appendable dbgAccept_ifNonNull)

Creates a new white-or-blacklist from a set of string-variables as found in a configuration text file.

Parameters:

black_white_off - Is this a blacklist, whitelist, or nothing? Must be "black", "white", or "off" (the case of this parameter's value is ignored). If "off", this function returns a new FilenameBlackWhiteList that accepts everything.

ignore_require_system - Should case be ignored, not ignored, or determined by the operating system? Must be "ignore", "require", or "system" (the case of this parameter's value is ignored).

separator - The character used to separate each proper and override value. Such as a comma (","), line-separator ("\r\n"), or tab ("\t"). May not be null, empty, or contain any letters, digits, underscores ('_'), question-marks ('?'), or asterisks ('*').

separated_propers - The separated list of "proper" items. Must be separated by separator, and otherwise must conform to the restrictions for the proper_items constructor parameter.

separated_overrides - The separated list of override items. Must be non-null (if none, this must be the empty string: ""), separated by separator, and otherwise must conform to the restrictions for the override_items constructor parameter.

See Also:

newFromProperties

newForAcceptAll

public static final FilenameBlackWhiteList newForAcceptAll(Appendable dbgAccept_ifNonNull)

A new instance that accepts everything.

Returns:

new FilenameBlackWhiteList(BlackOrWhite.WHITE, IOCase.INSENSITIVE, (new String[]{"*"}), (new String[]{}), dbgAccept_ifNonNull).