001/*
002 * Copyright 2002-2016 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.util;
018
019import java.util.Collection;
020import java.util.Collections;
021
022/**
023 * A simple instance filter that checks if a given instance match based on
024 * a collection of includes and excludes element.
025 *
026 * <p>Subclasses may want to override {@link #match(Object, Object)} to provide
027 * a custom matching algorithm.
028 *
029 * @author Stephane Nicoll
030 * @since 4.1
031 */
032public class InstanceFilter<T> {
033
034        private final Collection<? extends T> includes;
035
036        private final Collection<? extends T> excludes;
037
038        private final boolean matchIfEmpty;
039
040
041        /**
042         * Create a new instance based on includes/excludes collections.
043         * <p>A particular element will match if it "matches" the one of the element in the
044         * includes list and  does not match one of the element in the excludes list.
045         * <p>Subclasses may redefine what matching means. By default, an element match with
046         * another if it is equals according to {@link Object#equals(Object)}
047         * <p>If both collections are empty, {@code matchIfEmpty} defines if
048         * an element matches or not.
049         * @param includes the collection of includes
050         * @param excludes the collection of excludes
051         * @param matchIfEmpty the matching result if both the includes and the excludes
052         * collections are empty
053         */
054        public InstanceFilter(Collection<? extends T> includes,
055                        Collection<? extends T> excludes, boolean matchIfEmpty) {
056
057                this.includes = (includes != null ? includes : Collections.<T>emptyList());
058                this.excludes = (excludes != null ? excludes : Collections.<T>emptyList());
059                this.matchIfEmpty = matchIfEmpty;
060        }
061
062
063        /**
064         * Determine if the specified {code instance} matches this filter.
065         */
066        public boolean match(T instance) {
067                Assert.notNull(instance, "Instance to match must not be null");
068
069                boolean includesSet = !this.includes.isEmpty();
070                boolean excludesSet = !this.excludes.isEmpty();
071                if (!includesSet && !excludesSet) {
072                        return this.matchIfEmpty;
073                }
074
075                boolean matchIncludes = match(instance, this.includes);
076                boolean matchExcludes = match(instance, this.excludes);
077                if (!includesSet) {
078                        return !matchExcludes;
079                }
080                if (!excludesSet) {
081                        return matchIncludes;
082                }
083                return matchIncludes && !matchExcludes;
084        }
085
086        /**
087         * Determine if the specified {@code instance} is equal to the
088         * specified {@code candidate}.
089         * @param instance the instance to handle
090         * @param candidate a candidate defined by this filter
091         * @return {@code true} if the instance matches the candidate
092         */
093        protected boolean match(T instance, T candidate) {
094                return instance.equals(candidate);
095        }
096
097        /**
098         * Determine if the specified {@code instance} matches one of the candidates.
099         * <p>If the candidates collection is {@code null}, returns {@code false}.
100         * @param instance the instance to check
101         * @param candidates a list of candidates
102         * @return {@code true} if the instance match or the candidates collection is null
103         */
104        protected boolean match(T instance, Collection<? extends T> candidates) {
105                for (T candidate : candidates) {
106                        if (match(instance, candidate)) {
107                                return true;
108                        }
109                }
110                return false;
111        }
112
113        @Override
114        public String toString() {
115                StringBuilder sb = new StringBuilder(getClass().getSimpleName());
116                sb.append(": includes=").append(this.includes);
117                sb.append(", excludes=").append(this.excludes);
118                sb.append(", matchIfEmpty=").append(this.matchIfEmpty);
119                return sb.toString();
120        }
121
122}