org.identityconnectors.framework.common.objects.filter.FilterBuilder Maven / Gradle / Ivy
/*
* ====================
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright 2008-2009 Sun Microsystems, Inc. All rights reserved.
*
* The contents of this file are subject to the terms of the Common Development
* and Distribution License("CDDL") (the "License"). You may not use this file
* except in compliance with the License.
*
* You can obtain a copy of the License at
* http://IdentityConnectors.dev.java.net/legal/license.txt
* See the License for the specific language governing permissions and limitations
* under the License.
*
* When distributing the Covered Code, include this CDDL Header Notice in each file
* and include the License file at identityconnectors/legal/license.txt.
* If applicable, add the following below this CDDL Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyrighted [year] [name of copyright owner]"
* ====================
*/
package org.identityconnectors.framework.common.objects.filter;
import org.identityconnectors.framework.common.objects.Attribute;
import org.identityconnectors.framework.common.objects.ConnectorObject;
/**
* FilterBuilder creates a {@linkplain Filter filter}
* that will {@linkplain Filter#accept match} any {@code ConnectorObject}
* that satisfies all of the selection criteria
* that were specified using this builder.
*
* @author Will Droste
* @version $Revision: 1.7 $
* @since 1.0
*/
public final class FilterBuilder {
/**
* Select only an input ConnectorObject
* with a value for the specified Attribute
* that contains as a final substring
* the value of the specified Attribute.
*
* For example, if the specified Attribute were
* {"hairColor": "d"},
*
this would match any ConnectorObject
* with a value such as
*
{"hairColor": "red"} or
*
{"hairColor": "blond"}
*
* but would not match any ConnectorObject
* that contains only values such as
*
{"hairColor": "blonde"} or
*
{"hairColor": "auburn"}.
*
* This also would not match any ConnectorObject
* that contains only {"hairColor": null}
*
or that lacks the attribute "hairColor".
*
* @param attr
* Attribute containing exactly one value
* to test against each value of the corresponding
* ConnectorObject attribute.
* @return an instance of Filter whose accept() method
* will return true if at least one value
* of the corresponding attribute of the ConnectorObject
* contains as its last part
* the value of the specified Attribute;
* otherwise false.
*/
public static Filter endsWith(final Attribute attr) {
return new EndsWithFilter(attr);
}
/**
* Select only an input ConnectorObject
* with a value for the specified Attribute
* that contains as an initial substring
* the value of the specified Attribute.
*
* For example, if the specified Attribute were
* {"hairColor": "b"},
*
this would match any ConnectorObject with a value such as
*
{"hairColor": "brown"} or
*
{"hairColor": "blond"}
*
* but would not match any ConnectorObject
* that contains only values such as
*
{"hairColor": "red"} or
*
{"hairColor": "auburn"}.
*
* This also would not match any ConnectorObject
* that contains only {"hairColor": null}
*
or that lacks the attribute "hairColor".
*
* @param attr
* Attribute containing exactly one value
* to test against each value of the corresponding
* ConnectorObject attribute.
* @return an instance of Filter whose accept() method
* will return true if at least one value
* of the corresponding attribute of the ConnectorObject
* contains as its first part
* the value of the specified Attribute;
* otherwise false.
*/
public static Filter startsWith(final Attribute attr) {
return new StartsWithFilter(attr);
}
/**
* Select only an input ConnectorObject
* with a value for the specified Attribute
* that contains as any substring
* the value of the specified Attribute.
*
* For example, if the specified Attribute were
* {"hairColor": "a"},
*
this would match any ConnectorObject with a value such as
*
{"hairColor": "auburn"} or
*
{"hairColor": "gray"}
*
* but would not match any ConnectorObject
* that contains only
*
{"hairColor": "red"} or
*
{"hairColor": "grey"}.
*
* This also would not match any ConnectorObject
* that contains only {"hairColor": null}
*
or that lacks the attribute "hairColor".
*
* @param attr
* Attribute containing exactly one value
* to test against each value of the corresponding
* ConnectorObject attribute.
* @return an instance of Filter whose accept() method
* will return true if at least one value
* of the corresponding attribute of the ConnectorObject
* contains anywhere within it
* the value of the specified Attribute;
* otherwise false.
*/
public static Filter contains(final Attribute attr) {
return new ContainsFilter(attr);
}
/**
* Select only an input ConnectorObject
* with a value for the specified Attribute
* that is lexically equal to
* the value of the specified Attribute.
*
* NOTE: Is comparison case-sensitive?
*
* For example, if the specified Attribute were
* {"hairColor": "brown"},
*
this would match any ConnectorObject with a value such as
*
{"hairColor": "brown"} or
*
{"hairColor": "BROWN"}
*
* but would not match any ConnectorObject
* that contains only
*
{"hairColor": "brownish-gray"} or
*
{"hairColor": "auburn"}.
*
* This also would not match any ConnectorObject
* that contains only {"hairColor": null}
*
or that lacks the attribute "hairColor".
*
* NOTE: Lexical comparison of two string values
* compares the characters of each value,
* even if the string values could be interpreted as numeric.
* The values "01" and "1" are unequal lexically,
* although they would be equivalent arithmetically.
*
* Two attributes with binary syntax are equal if and only if
* their constituent bytes match.
*
* @param attr
* Attribute containing exactly one value
* to test against each value of the corresponding
* ConnectorObject attribute.
* @return an instance of Filter whose accept() method
* will return true if at least one value
* of the corresponding attribute of the ConnectorObject
* matches lexically
* the value of the specified Attribute;
* otherwise false.
*/
public static Filter equalTo(final Attribute attr) {
return new EqualsFilter(attr);
}
/**
* Select only an input ConnectorObject
* with a value for the specified Attribute
* that is lexically greater than or equal to
* the value of the specified Attribute.
*
* NOTE: Is comparison case-sensitive?
*
* For example, if the specified Attribute were
* {"hairColor": "brown"},
*
this would match any ConnectorObject with a value such as
*
{"hairColor": "brown"} or
*
{"hairColor": "brownish-gray"} or
*
{"hairColor": "red"}
*
* but would not match any ConnectorObject
* that contains only
*
{"hairColor": "black"} or
*
{"hairColor": "blond"} or
*
{"hairColor": "auburn"}.
*
* This also would not match any ConnectorObject
* that contains only {"hairColor": null}
*
or that lacks the attribute "hairColor".
*
* NOTE: Lexical comparison of two string values
* compares the characters of each value,
* even if the string values could be interpreted as numeric.
*
When compared lexically, "99" is greater than "123".
*
When compared arithmetically, 99 is less than 123.
*
* @param attr
* Attribute containing exactly one value
* to test against each value of the corresponding
* ConnectorObject attribute.
* @return an instance of Filter whose accept() method
* will return true if at least one value
* of the corresponding attribute of the ConnectorObject
* matches or sorts alphabetically after
* the value of the specified Attribute;
* otherwise false.
*/
public static Filter greaterThanOrEqualTo(final Attribute attr) {
return new GreaterThanOrEqualFilter(attr);
}
/**
* Select only an input ConnectorObject
* with a value for the specified Attribute
* that is lexically less than or equal to
* the value of the specified Attribute.
*
* NOTE: Is comparison case-sensitive?
*
* For example, if the specified Attribute were
* {"hairColor": "brown"},
*
this would match any ConnectorObject with a value such as
*
{"hairColor": "brown"} or
*
{"hairColor": "black"} or
*
{"hairColor": "blond"} or
*
{"hairColor": "auburn"}
*
* but would not match any ConnectorObject
* that contains only
*
{"hairColor": "brownish-gray"} or
*
{"hairColor": "red"}
*
* This also would not match any ConnectorObject
* that contains only {"hairColor": null}
*
or that lacks the attribute "hairColor".
*
* NOTE: Lexical comparison of two string values
* compares the characters of each value,
* even if the string values could be interpreted as numeric.
*
When compared lexically, "99" is greater than "123".
*
When compared arithmetically, 99 is less than 123.
*
* @param attr
* Attribute containing exactly one value
* to test against each value of the corresponding
* ConnectorObject attribute.
* @return an instance of Filter whose accept() method
* will return true if at least one value
* of the corresponding attribute of the ConnectorObject
* matches or sorts alphabetically before
* the value of the specified Attribute;
* otherwise false.
*/
public static Filter lessThanOrEqualTo(final Attribute attr) {
return new LessThanOrEqualFilter(attr);
}
/**
* Select only an input ConnectorObject
* with a value for the specified Attribute
* that is lexically less than
* the value of the specified Attribute.
*
* NOTE: Is comparison case-sensitive?
*
* For example, if the specified Attribute were
* {"hairColor": "brown"},
*
this would match any ConnectorObject with a value such as
*
{"hairColor": "black"} or
*
{"hairColor": "blond"} or
*
{"hairColor": "auburn"}
*
* but would not match any ConnectorObject
* that contains only
*
{"hairColor": "brown"} or
*
{"hairColor": "brownish-gray"} or
*
{"hairColor": "red"}
*
* This also would not match any ConnectorObject
* that contains only {"hairColor": null}
*
or that lacks the attribute "hairColor".
*
* NOTE: Lexical comparison of two string values
* compares the characters of each value,
* even if the string values could be interpreted as numeric.
*
When compared lexically, "99" is greater than "123".
*
When compared arithmetically, 99 is less than 123.
*
* @param attr
* Attribute containing exactly one value
* to test against each value of the corresponding
* ConnectorObject attribute.
* @return an instance of Filter whose accept() method
* will return true if at least one value
* of the corresponding attribute of the ConnectorObject
* sorts alphabetically before
* the value of the specified Attribute;
* otherwise false.
*/
public static Filter lessThan(final Attribute attr) {
return new LessThanFilter(attr);
}
/**
* Select only an input ConnectorObject
* with a value for the specified Attribute
* that is lexically greater than
* the value of the specified Attribute.
*
* NOTE: Is comparison case-sensitive?
*
* For example, if the specified Attribute were
* {"hairColor": "brown"},
*
this would match any ConnectorObject with a value such as
*
{"hairColor": "brownish-gray"} or
*
{"hairColor": "red"}
*
* but would not match any ConnectorObject
* that contains only
*
{"hairColor": "brown"} or
*
{"hairColor": "black"} or
*
{"hairColor": "blond"} or
*
{"hairColor": "auburn"}.
*
* This also would not match any ConnectorObject
* that contains only {"hairColor": null}
*
or that lacks the attribute "hairColor".
*
* NOTE: Lexical comparison of two string values
* compares the characters of each value,
* even if the string values could be interpreted as numeric.
*
When compared lexically, "99" is greater than "123".
*
When compared arithmetically, 99 is less than 123.
*
* @param attr
* Attribute containing exactly one value
* to test against each value of the corresponding
* ConnectorObject attribute.
* @return an instance of Filter whose accept() method
* will return true if at least one value
* of the corresponding attribute of the ConnectorObject
* sorts alphabetically after
* the value of the specified Attribute;
* otherwise false.
*/
public static Filter greaterThan(final Attribute attr) {
return new GreaterThanFilter(attr);
}
/**
* Logically "ANDs" together the two specified instances of {@link Filter}.
* The resulting conjunct Filter is true if and only if
* both of the specified filters are true.
*
* @param leftHandSide
* left-hand-side filter.
* @param rightHandSide
* right-hand-side filter.
* @return the result of (leftHandSide && rightHandSide)
*/
public static Filter and(final Filter leftHandSide, final Filter rightHandSide) {
return new AndFilter(leftHandSide, rightHandSide);
}
/**
* Logically "OR" together the two specified instances of {@link Filter}.
* The resulting disjunct Filter is true if and only if
* at least one of the specified filters is true.
*
* @param leftHandSide
* left-hand-side filter.
* @param rightHandSide
* right-hand-side filter.
* @return the result of (leftHandSide || rightHandSide)
*/
public static Filter or(final Filter leftHandSide, final Filter rightHandSide) {
return new OrFilter(leftHandSide, rightHandSide);
}
/**
* Logically negate the specified {@link Filter}.
* The resulting Filter is true if and only if
* the specified filter is false.
*
* @param filter
* the Filter to negate.
* @return the result of (!filter).
*/
public static Filter not(final Filter filter) {
return new NotFilter(filter);
}
/**
* Select only an input {@link ConnectorObject} with a value for the
* specified Attribute that contains all the values from the
* specified Attribute.
*
* For example, if the specified {@link Attribute} were
* {"hairColor": "brown", "red"},
* this would match any ConnectorObject with values such as
*
* {"hairColor": "black", "brown", "red"}{"hairColor": "blond", "brown", "red"}{"hairColor": "auburn", "brown", "red"}
* but would not match any {@link ConnectorObject} that contains
* only
*
* {"hairColor": "brown"}{"hairColor": "brownish-gray"}{"hairColor": "red"}
* This also would not match any {@link ConnectorObject} that
* contains only {"hairColor": null}
* or that lacks the attribute "hairColor".
*
* NOTE: Lexical comparison of two string values compares
* the characters of each value, even if the string values could be
* interpreted as numeric.
*
* @param attr
* {@link Attribute} containing exactly one value to
* test against each value of the corresponding
* ConnectorObject attribute.
* @return an instance of {@link Filter} whose accept()
* method will return true if at least one value of
* the corresponding attribute of the {@link ConnectorObject}
* sorts alphabetically before the value of the specified
* {@link Attribute}; otherwise false.
*/
public static Filter containsAllValues(final Attribute attr) {
return new ContainsAllValuesFilter(attr);
}
}