001/*
002 * Copyright 2002-2018 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
022import org.springframework.lang.Nullable;
023
024/**
025 * A simple instance filter that checks if a given instance match based on
026 * a collection of includes and excludes element.
027 *
028 * <p>Subclasses may want to override {@link #match(Object, Object)} to provide
029 * a custom matching algorithm.
030 *
031 * @author Stephane Nicoll
032 * @since 4.1
033 * @param <T> the instance type
034 */
035public class InstanceFilter<T> {
036
037        private final Collection<? extends T> includes;
038
039        private final Collection<? extends T> excludes;
040
041        private final boolean matchIfEmpty;
042
043
044        /**
045         * Create a new instance based on includes/excludes collections.
046         * <p>A particular element will match if it "matches" the one of the element in the
047         * includes list and  does not match one of the element in the excludes list.
048         * <p>Subclasses may redefine what matching means. By default, an element match with
049         * another if it is equals according to {@link Object#equals(Object)}
050         * <p>If both collections are empty, {@code matchIfEmpty} defines if
051         * an element matches or not.
052         * @param includes the collection of includes
053         * @param excludes the collection of excludes
054         * @param matchIfEmpty the matching result if both the includes and the excludes
055         * collections are empty
056         */
057        public InstanceFilter(@Nullable Collection<? extends T> includes,
058                        @Nullable Collection<? extends T> excludes, boolean matchIfEmpty) {
059
060                this.includes = (includes != null ? includes : Collections.emptyList());
061                this.excludes = (excludes != null ? excludes : Collections.emptyList());
062                this.matchIfEmpty = matchIfEmpty;
063        }
064
065
066        /**
067         * Determine if the specified {code instance} matches this filter.
068         */
069        public boolean match(T instance) {
070                Assert.notNull(instance, "Instance to match must not be null");
071
072                boolean includesSet = !this.includes.isEmpty();
073                boolean excludesSet = !this.excludes.isEmpty();
074                if (!includesSet && !excludesSet) {
075                        return this.matchIfEmpty;
076                }
077
078                boolean matchIncludes = match(instance, this.includes);
079                boolean matchExcludes = match(instance, this.excludes);
080                if (!includesSet) {
081                        return !matchExcludes;
082                }
083                if (!excludesSet) {
084                        return matchIncludes;
085                }
086                return matchIncludes && !matchExcludes;
087        }
088
089        /**
090         * Determine if the specified {@code instance} is equal to the
091         * specified {@code candidate}.
092         * @param instance the instance to handle
093         * @param candidate a candidate defined by this filter
094         * @return {@code true} if the instance matches the candidate
095         */
096        protected boolean match(T instance, T candidate) {
097                return instance.equals(candidate);
098        }
099
100        /**
101         * Determine if the specified {@code instance} matches one of the candidates.
102         * <p>If the candidates collection is {@code null}, returns {@code false}.
103         * @param instance the instance to check
104         * @param candidates a list of candidates
105         * @return {@code true} if the instance match or the candidates collection is null
106         */
107        protected boolean match(T instance, Collection<? extends T> candidates) {
108                for (T candidate : candidates) {
109                        if (match(instance, candidate)) {
110                                return true;
111                        }
112                }
113                return false;
114        }
115
116        @Override
117        public String toString() {
118                StringBuilder sb = new StringBuilder(getClass().getSimpleName());
119                sb.append(": includes=").append(this.includes);
120                sb.append(", excludes=").append(this.excludes);
121                sb.append(", matchIfEmpty=").append(this.matchIfEmpty);
122                return sb.toString();
123        }
124
125}