ch.trick17.betterchecks.fluent

Class StringCheck

java.lang.Object

ch.trick17.betterchecks.fluent.BaseCheck<C>

ch.trick17.betterchecks.fluent.ObjectBaseCheck<String,StringCheck>

ch.trick17.betterchecks.fluent.StringCheck

@GwtCompatible
public final class StringCheck
extends ObjectBaseCheck<String,StringCheck>

The check class for String arguments.

While String is a very generic data type, string arguments are often used to provide a specific kind of data, for example names, URLs or even numbers. Therefore, Strings have to be validated. This class provides many check methods to simplify this.

The simple checks include methods like isNotEmpty() or hasLength(int) . But there are also more powerful checks like containsAll(CharSequence...), matches(String) or even isInt().

Author:

Michael Faes

Field Summary

Fields inherited from class ch.trick17.betterchecks.fluent.ObjectBaseCheck

arg, nullAllowed

Fields inherited from class ch.trick17.betterchecks.fluent.BaseCheck

argName, inverted

Constructor Summary

Constructors

Constructor and Description
StringCheck(String arg) For internal use only.

Method Summary

Modifier and Type	Method and Description
StringCheck	contains(CharSequence sequence) Checks that the string argument contains the given character sequence, throwing an exception otherwise.
StringCheck	containsAll(CharSequence... sequences) Checks that the string argument contains all one of the given character sequences, throwing an exception otherwise.
StringCheck	containsAny(CharSequence... sequences) Checks that the string argument contains at least one of the given character sequences, throwing an exception otherwise.
StringCheck	endsWith(String suffix) Checks that the string argument end with the given string, throwing an exception otherwise.
StringCheck	hasLength(int length) Checks that the string argument has the given length, throwing an exception otherwise.
StringCheck	hasLengthBetween(int min, int max) Checks that the string argument's length is between the two given numbers, throwing an exception otherwise.
IntCheck	hasLengthWhich() Creates an IntCheck property check for the length of the string argument.
StringCheck	is(String string) Checks that the string argument is the same string as the given one, throwing an exception otherwise.
StringCheck	isInt() Checks that the string argument is is a valid int, throwing an exception otherwise.
IntCheck	isIntWhich() First checks that the string argument is a valid int and then "converts" this check into an IntCheck and returns it.
StringCheck	isNotEmpty() Checks that the string argument is not empty, throwing an exception otherwise.
StringCheck	isNotWhitespace() Checks that the string argument is not empty and does not consist entirely of whitespace, throwing an exception otherwise.
StringCheck	isUrl() Checks that the string argument is is a valid URL, throwing an exception otherwise.
UrlCheck	isUrlWhich() First checks that the string argument is a valid URL and then "converts" this check into an UrlCheck and returns it.
StringCheck	matches(Pattern regex) Checks that the string argument matches the given compiled regular expression pattern, throwing an exception otherwise.
StringCheck	matches(String regex) Checks that the string argument matches the given regular expression, throwing an exception otherwise.
StringCheck	startsWith(String prefix) Checks that the string argument starts with the given string, throwing an exception otherwise.

Methods inherited from class ch.trick17.betterchecks.fluent.ObjectBaseCheck

check, checkNull, checkWithCause, hasClass, intPropertyCheck, isEqualTo, isInstanceOf, isNotNull, isNullOr, isSameAs, objectPropertyCheck

Methods inherited from class ch.trick17.betterchecks.fluent.BaseCheck

checkConversion, me, named, not

Methods inherited from class java.lang.Object

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

Constructor Detail

StringCheck

public StringCheck(String arg)

For internal use only.

Method Detail

isNotEmpty

public StringCheck isNotEmpty()

Checks that the string argument is not empty, throwing an exception otherwise.

The message type used for exceptions thrown by this method is MessageType.ARG_EMPTY.

Returns:

This check

Throws:

IllegalArgumentException - if the string argument is empty

isNotWhitespace

public StringCheck isNotWhitespace()

Checks that the string argument is not empty and does not consist entirely of whitespace, throwing an exception otherwise.

The message type used for exceptions thrown by this method is MessageType.ARG_WHITESPACE.

Returns:

This check

Throws:

IllegalArgumentException - if the string argument is empty or consists entirely of whitespace

hasLength

public StringCheck hasLength(int length)

Checks that the string argument has the given length, throwing an exception otherwise.

The message type used for exceptions thrown by this method is MessageType.ARG_LENGTH.

To create more sophisticated checks using the string size, use the hasLengthWhich() property check.

Parameters:

length - The length the string should have

Returns:

This check

Throws:

IllegalArgumentException - if the string argument has a size different from the given one

See Also:

hasLengthBetween(int, int)

hasLengthBetween

public StringCheck hasLengthBetween(int min,
                                    int max)

Checks that the string argument's length is between the two given numbers, throwing an exception otherwise.

The message type used for exceptions thrown by this method is MessageType.ARG_LENGTH_BETWEEN.

To create more sophisticated checks using the array length, use the hasLengthWhich() property check.

Parameters:

min - The minimum length of the string

max - The maximum length

Returns:

This check

Throws:

IllegalArgumentException - If the length of the array is strictly less than min or strictly greater than max

hasLengthWhich

public IntCheck hasLengthWhich()

Creates an IntCheck property check for the length of the string argument. It can be used to create advanced checks using the string length. For example:

Check.that(string).isNullOr().hasLengthWhich().isGreaterThan(3);

Just like a check method, this method first asserts the non-nullness of the argument, throwing an exception in case of a failure.

The returned check has the length of this check's string set as the argument and an argument name that indicates this fact. If the string reference is null and allowed to be so (like in the above example), the returned property check is completely disabled, meaning none of its check methods will throw an exception. An inversion called before this method is ignored and does not have any effect on the check methods called on the returned property check.

Returns:

A property check for the length of the string argument

startsWith

public StringCheck startsWith(String prefix)

Checks that the string argument starts with the given string, throwing an exception otherwise.

The message type used for exceptions thrown by this method is MessageType.ARG_STARTS.

Parameters:

prefix - The string the string argument of this check should start with

Returns:

This check

Throws:

IllegalArgumentException - if the string argument does not start with the given string

See Also:

endsWith(String)

endsWith

public StringCheck endsWith(String suffix)

Checks that the string argument end with the given string, throwing an exception otherwise.

The message type used for exceptions thrown by this method is MessageType.ARG_ENDS.

Parameters:

suffix - The string the string argument of this check should end with

Returns:

This check

Throws:

IllegalArgumentException - if the string argument does not end with the given string

See Also:

startsWith(String)

contains

public StringCheck contains(CharSequence sequence)

Checks that the string argument contains the given character sequence, throwing an exception otherwise. Note that this check and even more the containsAny check can be very useful in their inverted form:

Check.that(message).not().containsAny(swearWords);

The message type used for exceptions thrown by this method is MessageType.ARG_CONTAINS.

Parameters:

sequence - The sequence the string argument should contain

Returns:

This check

Throws:

IllegalArgumentException - if the string argument does not contain the given sequence

See Also:

containsAny(CharSequence...), containsAll(CharSequence...)

containsAny

public StringCheck containsAny(CharSequence... sequences)

Checks that the string argument contains at least one of the given character sequences, throwing an exception otherwise. Note that if no sequences are given (i.e. an empty array), this check always fails. Also note that this check can be very useful in its inverted form:

Check.that(message).not().containsAny(swearWords);

The message type used for exceptions thrown by this method is MessageType.ARG_CONTAINS_ANY.

Parameters:

sequences - The array of sequences of which the string argument should contain at least one

Returns:

This check

Throws:

IllegalArgumentException - if the string argument contains none of the given sequences

See Also:

containsAll(CharSequence...)

containsAll

public StringCheck containsAll(CharSequence... sequences)

Checks that the string argument contains all one of the given character sequences, throwing an exception otherwise. Note that if no sequences are given (i.e. an empty array), this check always succeeds.

The message type used for exceptions thrown by this method is MessageType.ARG_CONTAINS_ALL.

Parameters:

sequences - The sequences the string argument must contain

Returns:

This check

Throws:

IllegalArgumentException - if the string argument does not contain all the given sequences

See Also:

containsAny(CharSequence...)

matches

public StringCheck matches(String regex)

Checks that the string argument matches the given regular expression, throwing an exception otherwise. For maximum performance for non-dynamic patterns, consider reusing a Pattern object by passing it to the matches(Pattern) check.

The message type used for exceptions thrown by this method is MessageType.ARG_MATCHES.

Parameters:

regex - The regular expression the string argument must match. See Pattern for more information.

Returns:

This check

Throws:

IllegalArgumentException - if the string argument does not contain match the given regular expression

See Also:

matches(Pattern)

matches

@GwtIncompatible(value="java.util.regex.Pattern")
public StringCheck matches(Pattern regex)

Checks that the string argument matches the given compiled regular expression pattern, throwing an exception otherwise. This check is equivalent to the matches(String) check, except that it is more efficient if the same pattern object is used multiple times. Since Pattern objects are immutable (and therefore thread-safe), it is safe to pass the same pattern to multiple checks. For maximum performance, consider creating a static pattern field for each kind of matches() check.

The message type used for exceptions thrown by this method is MessageType.ARG_MATCHES.

Parameters:

regex - The regular expression the string argument must match. See Pattern for more information.

Returns:

This check

Throws:

IllegalArgumentException - if the string argument does not contain match the given regular expression

See Also:

matches(Pattern)

is

public StringCheck is(String string)

Checks that the string argument is the same string as the given one, throwing an exception otherwise. This check method exists primarily for using with a property check. See UrlCheck.hasHostWhich() for example. However, in conjunction with inversion (see BaseCheck.not()), this method can also be used to exclude a single value.

Note that this check behaves like ObjectBaseCheck.isEqualTo(Object), but is shorter, accepts only String arguments, and uses the MessageType.ARG_IS message type.

Parameters:

string - The string this argument must be equal to

Returns:

This check

Throws:

IllegalArgumentException - if the check argument is not equal to the given string

isUrl

@GwtIncompatible(value="java.net.URL")
public StringCheck isUrl()

Checks that the string argument is is a valid URL, throwing an exception otherwise. Note that this includes URLs with protocols other than http://, for example ftp:// or file://. To specify further requirements regarding the protocol, the host or the path, use the isUrlWhich() conversion check. For more information about valid URLs, see the URL class.

The message type used for exceptions thrown by this method is MessageType.ARG_URL.

Returns:

This check

Throws:

IllegalArgumentException - if the check argument is not a valid URL

isUrlWhich

@GwtIncompatible(value="java.net.URL")
public UrlCheck isUrlWhich()

First checks that the string argument is a valid URL and then "converts" this check into an UrlCheck and returns it. This can be used to create checks involving properties of the URL. For example:

Check.that(string).isUrlWhich().hasProtocol("http");

Just like a normal check method, this method first asserts the non-nullness of the argument, throwing an exception in case of a failure. Otherwise, the returned check has the same argument name as this check object and also behaves the same regarding the nullness of the argument.

The message type used for exceptions thrown by this method (not the subsequent UrlCheck checks) is MessageType.ARG_URL.

Returns:

An URL check for asserting properties of the URL represented by the string argument

Throws:

InvalidCheckException - If this check has just been inverted using BaseCheck.not(). This is prohibited as it would allow unintuitive checks.

isInt

public StringCheck isInt()

Checks that the string argument is is a valid int, throwing an exception otherwise. Note that numbers outside of the int range (given by Integer.MIN_VALUE and Integer.MAX_VALUE) are invalid. See Integer.parseInt(String) for a description of valid integer representations. To specify further requirements for the int that the string argument should represent, use the isIntWhich() conversion check.

The message type used for exceptions thrown by this method is MessageType.ARG_INT.

Returns:

This check

Throws:

IllegalArgumentException - if the check argument is not a valid int

isIntWhich

public IntCheck isIntWhich()

First checks that the string argument is a valid int and then "converts" this check into an IntCheck and returns it. This can be used to create checks involving properties of the int . For example:

Check.that(string).isIntWhich().isPositive();

Just like a normal check method, this method first asserts the non-nullness of the argument, throwing an exception in case of a failure. Otherwise, the returned check has the same argument name as this check object. Also, if this check has been modified to allow null and the argument is null, the returned check is completely disabled, meaning none of its check methods throw an exception.

The message type used for exceptions thrown by this method (not the subsequent IntCheck checks) is MessageType.ARG_INT.

Returns:

An int check for asserting properties of the int represented by the string argument

Throws:

InvalidCheckException - If this check has just been inverted using BaseCheck.not(). This is prohibited as it would allow unintuitive checks.