001/*
002 * oauth2-oidc-sdk
003 *
004 * Copyright 2012-2016, Connect2id Ltd and contributors.
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use
007 * this file except in compliance with the License. You may obtain a copy of the
008 * License at
009 *
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software distributed
013 * under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
014 * CONDITIONS OF ANY KIND, either express or implied. See the License for the
015 * specific language governing permissions and limitations under the License.
016 */
017
018package com.nimbusds.oauth2.sdk.id;
019
020
021import java.net.URI;
022import java.util.*;
023
024import net.jcip.annotations.Immutable;
025
026
027/**
028 * Audience identifier.
029 *
030 * <p>Provides helper methods for:
031 *
032 * <ul>
033 *     <li>Converting to / from string arrays and collections
034 *     <li>Matching audience values
035 * </ul>
036 */
037@Immutable
038public final class Audience extends Identifier {
039        
040        
041        private static final long serialVersionUID = 9149519511538940783L;
042        
043        
044        /**
045         * Creates a new audience identifier with the specified value.
046         *
047         * @param value The audience identifier value. Must not be {@code null}
048         *              or empty string.
049         */
050        public Audience(final String value) {
051
052                super(value);
053        }
054
055
056        /**
057         * Creates a new audience identifier with the specified URI value.
058         *
059         * @param value The URI value. Must not be {@code null}.
060         */
061        public Audience(final URI value) {
062
063                super(value.toString());
064        }
065
066
067        /**
068         * Creates a new audience identifier with the specified value.
069         *
070         * @param value The value. Must not be {@code null}.
071         */
072        public Audience(final Identifier value) {
073
074                super(value.getValue());
075        }
076
077
078        /**
079         * Returns a singleton list of this audience.
080         *
081         * @return A singleton list consisting of this audience only.
082         */
083        public List<Audience> toSingleAudienceList() {
084
085                List<Audience> audienceList = new ArrayList<>(1);
086                audienceList.add(this);
087                return audienceList;
088        }
089
090
091        @Override
092        public boolean equals(final Object object) {
093        
094                return object instanceof Audience &&
095                       this.toString().equals(object.toString());
096        }
097
098
099        /**
100         * Returns a string list representation of the specified audience.
101         *
102         * @param audience The audience. May be {@code null}.
103         *
104         * @return The string list, {@code null} if the argument was
105         *         {@code null}.
106         */
107        public static List<String> toStringList(final Audience audience) {
108
109                if (audience == null) {
110                        return null;
111                }
112                return Collections.singletonList(audience.getValue());
113        }
114
115
116        /**
117         * Returns a string list representation of the specified audience list.
118         *
119         * @param audienceList The audience list. May be {@code null}.
120         *
121         * @return The string list, {@code null} if the argument was
122         *         {@code null}.
123         */
124        public static List<String> toStringList(final List<Audience> audienceList) {
125
126                if (audienceList == null) {
127                        return null;
128                }
129
130                List<String> list = new ArrayList<>(audienceList.size());
131                for (Audience aud: audienceList) {
132                        list.add(aud.getValue());
133                }
134                return list;
135        }
136
137
138        /**
139         * Creates an audience list from the specified string list
140         * representation.
141         *
142         * @param strings The string list. May be {@code null}.
143         *
144         * @return The audience list, {@code null} if the argument was
145         *         {@code null}.
146         */
147        public static List<Audience> create(final List<String> strings) {
148
149                if (strings == null) {
150                        return null;
151                }
152
153                List<Audience> audienceList = new ArrayList<>(strings.size());
154
155                for (String s: strings) {
156                        audienceList.add(new Audience(s));
157                }
158                return audienceList;
159        }
160
161
162        /**
163         * Creates an audience list from the specified string array.
164         *
165         * @param strings The strings. May be {@code null}.
166         *
167         * @return The audience list, {@code null} if the argument was
168         *         {@code null}.
169         */
170        public static List<Audience> create(final String ... strings) {
171
172                if (strings == null) {
173                        return null;
174                }
175
176                return create(Arrays.asList(strings));
177        }
178
179
180        /**
181         * Returns {@code true} if the specified collections have at at least
182         * one matching audience value.
183         *
184         * @param c1 The first audience collection. May be {@code null}.
185         * @param c2 The second audience collection. May be {@code null}.
186         *
187         * @return {@code true} if the specified collections have at at least
188         *         one matching audience value, {@code false} if there are no
189         *         matches or either collection is {@code null} or empty.
190         */
191        public static boolean matchesAny(final Collection<Audience> c1, final Collection<Audience> c2) {
192
193                if (c1 == null || c2 == null) {
194                        return false;
195                }
196
197                for (Audience aud: c1) {
198                        if (c2.contains(aud)) {
199                                return true;
200                        }
201                }
202
203                return false;
204        }
205}