1 /**
2 * Copyright 2014 Internet2
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package edu.internet2.middleware.subject;
17
18 import java.io.Serializable;
19 import java.util.Map;
20 import java.util.Set;
21
22 /**
23 * <pre>
24 * A Subject represents an entity, such as a person, group, or organization.
25 * This class provides common characteristics and behaviors across these entities.
26 * Note, implementations of this interface shouldnt hold onto sources, since they
27 * arent serializable, they should lookup with AllSources
28 *
29 * Implementors should probably subclass SubjectImpl instead of implement this directly.
30 *
31 * Also, implementors should implement toString, equals and hashcode like Subject (based on
32 * sourceId and subjectId). There are static methods in subjectImpl which can be used as helper
33 * methods
34 * </pre>
35 */
36 public interface Subject extends Serializable {
37
38 /**
39 * Gets this Subject's ID.
40 * @return string
41 */
42 public String getId();
43
44 /**
45 * Gets this Subject's type.
46 * @return subject type
47 */
48 public SubjectType getType();
49
50 /**
51 * get the type name
52 * @return the type name
53 */
54 public String getTypeName();
55
56 /**
57 * get the source id of a subject
58 * @return the source id
59 */
60 public String getSourceId();
61
62 /**
63 * Gets this Subject's name.
64 * @return name or null if not there
65 */
66 public String getName();
67
68 /**
69 * Gets this Subject's description.
70 * @return description or null if not there
71 */
72 public String getDescription();
73
74 /**
75 * Returns the value of a single-valued attribute.
76 * If multivalued, this returns the first value.
77 * This does not return values for internal attributes.
78 * Note, the keys are case-insensitive
79 * @param attributeName
80 * @return value or null if not found
81 */
82 public String getAttributeValue(String attributeName);
83
84 /**
85 * Returns the values of a multi-valued attribute, or a set of size one for a single valued attribute.
86 * Note the returned set should not be changed.
87 * This does not return values for internal attributes.
88 * Note, the keys are case-insensitive
89 * @param attributeName
90 * @return set or empty set or null if not there
91 */
92 public java.util.Set<String> getAttributeValues(String attributeName);
93
94 /**
95 * Returns the attribute value if single-valued, or
96 * if multi-valued, throws an exception. Implementors
97 * can use the static helper in SubjectImpl.
98 * This does not return values for internal attributes.
99 * Note, the keys are case-insensitive
100 * @param attributeName
101 * @return value or null if not there
102 */
103 public String getAttributeValueSingleValued(String attributeName);
104
105 /**
106 * <pre>
107 * Returns the attribute value if single-valued, or
108 * if multi-valued, returns the values comma separated (with a space too).
109 * So if the values are: a b c; this would return the string: "a, b, c"
110 * Implementors can use the static helper in SubjectImpl.
111 * This does not return values for internal attributes.
112 * Note, the keys are case-insensitive
113 * </pre>
114 * @param attributeName
115 * @return value or values or null if not there
116 */
117 public String getAttributeValueOrCommaSeparated(String attributeName);
118
119 /**
120 * Gets a map attribute names and values. The map's key
121 * contains the attribute name and the map's value
122 * contains a Set of attribute value(s).
123 * This does not return internal attributes.
124 * Note, the keys are case-insensitive
125 *
126 * @return map or empty map or null if not there
127 */
128 public java.util.Map<String, Set<String>> getAttributes();
129
130 /**
131 * Returns the value of a single-valued attribute.
132 * If multivalued, this returns the first value.
133 * Note, the keys are case-insensitive
134 * @param attributeName
135 * @param excludeInternalAttributes if true, values for internal attributes are not returned
136 * @return value or null if not found
137 */
138 public String getAttributeValue(String attributeName, boolean excludeInternalAttributes);
139
140 /**
141 * Returns the values of a multi-valued attribute, or a set of size one for a single valued attribute.
142 * Note the returned set should not be changed.
143 * Note, the keys are case-insensitive
144 * @param attributeName
145 * @param excludeInternalAttributes if true, values for internal attributes are not returned
146 * @return set or empty set or null if not there
147 */
148 public java.util.Set<String> getAttributeValues(String attributeName, boolean excludeInternalAttributes);
149
150 /**
151 * Returns the attribute value if single-valued, or
152 * if multi-valued, throws an exception. Implementors
153 * can use the static helper in SubjectImpl.
154 * Note, the keys are case-insensitive
155 * @param attributeName
156 * @param excludeInternalAttributes if true, values for internal attributes are not returned
157 * @return value or null if not there
158 */
159 public String getAttributeValueSingleValued(String attributeName, boolean excludeInternalAttributes);
160
161 /**
162 * <pre>
163 * Returns the attribute value if single-valued, or
164 * if multi-valued, returns the values comma separated (with a space too).
165 * So if the values are: a b c; this would return the string: "a, b, c"
166 * Implementors can use the static helper in SubjectImpl.
167 * Note, the keys are case-insensitive
168 * </pre>
169 * @param attributeName
170 * @param excludeInternalAttributes if true, values for internal attributes are not returned
171 * @return value or values or null if not there
172 */
173 public String getAttributeValueOrCommaSeparated(String attributeName, boolean excludeInternalAttributes);
174
175 /**
176 * Gets a map attribute names and values. The map's key
177 * contains the attribute name and the map's value
178 * contains a Set of attribute value(s). The returned Map can be augmented or changed.
179 * Note, the keys are case-insensitive
180 * @param excludeInternalAttributes if true, internal attributes are not returned
181 * @return map or empty map or null if not there
182 */
183 public java.util.Map<String, Set<String>> getAttributes(boolean excludeInternalAttributes);
184
185 /**
186 * Returns the Source of this Subject.
187 * @return source
188 */
189 public Source getSource();
190
191 /**
192 * we want to resolve virtual translated attributes when they are needed so store a map of subject and source attributes for that translation
193 * @return
194 */
195 public Map<String, Object> getTranslationMap();
196
197 /**
198 * we want to resolve virtual translated attributes when they are needed so store a map of subject and source attributes for that translation
199 * @param translationMap
200 */
201 public void setTranslationMap(Map<String, Object> translationMap);
202
203 /**
204 * @return true if resolved from source (rather than cache)
205 */
206 public boolean isResolvedFromSource();
207
208 /**
209 * true if resolved from source (rather than cache)
210 * @param isResolvedFromSource
211 */
212 public void setResolvedFromSource(boolean isResolvedFromSource);
213 }