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        /**
042         * Creates a new audience identifier with the specified value.
043         *
044         * @param value The audience identifier value. Must not be {@code null}
045         *              or empty string.
046         */
047        public Audience(final String value) {
048
049                super(value);
050        }
051
052
053        /**
054         * Creates a new audience identifier with the specified URI value.
055         *
056         * @param value The URI value. Must not be {@code null}.
057         */
058        public Audience(final URI value) {
059
060                super(value.toString());
061        }
062
063
064        /**
065         * Creates a new audience identifier with the specified value.
066         *
067         * @param value The value. Must not be {@code null}.
068         */
069        public Audience(final Identifier value) {
070
071                super(value.getValue());
072        }
073
074
075        /**
076         * Returns a singleton list of this audience.
077         *
078         * @return A singleton list consisting of this audience only.
079         */
080        public List<Audience> toSingleAudienceList() {
081
082                List<Audience> audienceList = new ArrayList<>(1);
083                audienceList.add(this);
084                return audienceList;
085        }
086
087
088        @Override
089        public boolean equals(final Object object) {
090        
091                return object instanceof Audience &&
092                       this.toString().equals(object.toString());
093        }
094
095
096        /**
097         * Returns a string list representation of the specified audience.
098         *
099         * @param audience The audience. May be {@code null}.
100         *
101         * @return The string list, {@code null} if the argument was
102         *         {@code null}.
103         */
104        public static List<String> toStringList(final Audience audience) {
105
106                if (audience == null) {
107                        return null;
108                }
109                return Collections.singletonList(audience.getValue());
110        }
111
112
113        /**
114         * Returns a string list representation of the specified audience list.
115         *
116         * @param audienceList The audience list. May be {@code null}.
117         *
118         * @return The string list, {@code null} if the argument was
119         *         {@code null}.
120         */
121        public static List<String> toStringList(final List<Audience> audienceList) {
122
123                if (audienceList == null) {
124                        return null;
125                }
126
127                List<String> list = new ArrayList<>(audienceList.size());
128                for (Audience aud: audienceList) {
129                        list.add(aud.getValue());
130                }
131                return list;
132        }
133
134
135        /**
136         * Creates an audience list from the specified string list
137         * representation.
138         *
139         * @param strings The string list. May be {@code null}.
140         *
141         * @return The audience list, {@code null} if the argument was
142         *         {@code null}.
143         */
144        public static List<Audience> create(final List<String> strings) {
145
146                if (strings == null) {
147                        return null;
148                }
149
150                List<Audience> audienceList = new ArrayList<>(strings.size());
151
152                for (String s: strings) {
153                        audienceList.add(new Audience(s));
154                }
155                return audienceList;
156        }
157
158
159        /**
160         * Creates an audience list from the specified string array.
161         *
162         * @param strings The strings. May be {@code null}.
163         *
164         * @return The audience list, {@code null} if the argument was
165         *         {@code null}.
166         */
167        public static List<Audience> create(final String ... strings) {
168
169                if (strings == null) {
170                        return null;
171                }
172
173                return create(Arrays.asList(strings));
174        }
175
176
177        /**
178         * Returns {@code true} if the specified collections have at at least
179         * one matching audience value.
180         *
181         * @param c1 The first audience collection. May be {@code null}.
182         * @param c2 The second audience collection. May be {@code null}.
183         *
184         * @return {@code true} if the specified collections have at at least
185         *         one matching audience value, {@code false} if there are no
186         *         matches or either collection is {@code null} or empty.
187         */
188        public static boolean matchesAny(final Collection<Audience> c1, final Collection<Audience> c2) {
189
190                if (c1 == null || c2 == null) {
191                        return false;
192                }
193
194                for (Audience aud: c1) {
195                        if (c2.contains(aud)) {
196                                return true;
197                        }
198                }
199
200                return false;
201        }
202}