Source code: com/sun/xacml/EvaluationCtx.java
1
2 /*
3 * @(#)EvaluationCtx.java
4 *
5 * Copyright 2003-2004 Sun Microsystems, Inc. All Rights Reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions are met:
9 *
10 * 1. Redistribution of source code must retain the above copyright notice,
11 * this list of conditions and the following disclaimer.
12 *
13 * 2. Redistribution in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in the
15 * documentation and/or other materials provided with the distribution.
16 *
17 * Neither the name of Sun Microsystems, Inc. or the names of contributors may
18 * be used to endorse or promote products derived from this software without
19 * specific prior written permission.
20 *
21 * This software is provided "AS IS," without a warranty of any kind. ALL
22 * EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING
23 * ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
24 * OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN MICROSYSTEMS, INC. ("SUN")
25 * AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE
26 * AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS
27 * DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST
28 * REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL,
29 * INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY
30 * OF LIABILITY, ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE,
31 * EVEN IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
32 *
33 * You acknowledge that this software is not designed or intended for use in
34 * the design, construction, operation or maintenance of any nuclear facility.
35 */
36
37 package com.sun.xacml;
38
39 import com.sun.xacml.attr.AttributeValue;
40 import com.sun.xacml.attr.DateAttribute;
41 import com.sun.xacml.attr.DateTimeAttribute;
42 import com.sun.xacml.attr.TimeAttribute;
43
44 import com.sun.xacml.cond.EvaluationResult;
45
46 import com.sun.xacml.finder.AttributeFinder;
47
48 import java.net.URI;
49
50 import org.w3c.dom.Node;
51
52
53 /**
54 * Manages the context of a single policy evaluation. Typically, an instance
55 * is instantiated whenever the PDP gets a request and needs to perform an
56 * evaluation as a result.
57 * <p>
58 * Note that this class does some optional caching for current date, time,
59 * and dateTime values (defined by a boolean flag to the constructors). The
60 * XACML specification requires that these values always be available, but it
61 * does not specify whether or not they must remain constant over the course
62 * of an evaluation if the values are being generated by the PDP (if the
63 * values are provided in the Request, then obviously they will remain
64 * constant). The default behavior is for these environment values to be
65 * cached, so that (for example) the current time remains constant over the
66 * course of an evaluation.
67 *
68 * @since 1.0
69 * @author Seth Proctor
70 */
71 public interface EvaluationCtx
72 {
73
74 /**
75 * The standard URI for listing a resource's id
76 */
77 public static final String RESOURCE_ID =
78 "urn:oasis:names:tc:xacml:1.0:resource:resource-id";
79
80 /**
81 * The standard URI for listing a resource's scope
82 */
83 public static final String RESOURCE_SCOPE =
84 "urn:oasis:names:tc:xacml:1.0:resource:scope";
85
86 /**
87 * Resource scope of Immediate (only the given resource)
88 */
89 public static final int SCOPE_IMMEDIATE = 0;
90
91 /**
92 * Resource scope of Children (the given resource and its direct
93 * children)
94 */
95 public static final int SCOPE_CHILDREN = 1;
96
97 /**
98 * Resource scope of Descendants (the given resource and all descendants
99 * at any depth or distance)
100 */
101 public static final int SCOPE_DESCENDANTS = 2;
102
103 /**
104 * Returns the <code>AttributeFinder</code> used by this context.
105 *
106 * @deprecated As of version 1.2, this method should not be used, as it
107 * provides access to a mutable interface. This method will
108 * be removed in the next major release.
109 *
110 * @return the <code>AttributeFinder</code>
111 */
112 public AttributeFinder getAttributeFinder();
113
114 /**
115 * Returns the DOM root of the original RequestType XML document, if
116 * this context is backed by an XACML Request. If this context is not
117 * backed by an XML representation, then an exception is thrown.
118 *
119 * @return the DOM root node
120 *
121 * @throws UnsupportedOperationException if the context is not backed
122 * by an XML representation
123 */
124 public Node getRequestRoot();
125
126 /**
127 * Returns the identifier for the resource being requested.
128 *
129 * @return the resource
130 */
131 public AttributeValue getResourceId();
132
133 /**
134 * Returns the resource scope, which will be one of the three fields
135 * denoting Immediate, Children, or Descendants.
136 *
137 * @return the scope of the resource
138 */
139 public int getScope();
140
141 /**
142 * Changes the value of the resource-id attribute in this context. This
143 * is useful when you have multiple resources (ie, a scope other than
144 * IMMEDIATE), and you need to keep changing only the resource-id to
145 * evaluate the different effective requests.
146 *
147 * @param resourceId the new resource-id value
148 */
149 public void setResourceId(AttributeValue resourceId);
150
151 /**
152 * Returns the cached value for the current time. If the value has never
153 * been set by a call to <code>setCurrentTime</code>, or if caching is
154 * not enabled in this instance, then this will return null.
155 *
156 * @return the current time or null
157 */
158 public TimeAttribute getCurrentTime();
159
160 /**
161 * Sets the current time for this evaluation. If caching is not enabled
162 * for this instance then the value is ignored.
163 *
164 * @param currentTime the dynamically resolved current time
165 */
166 public void setCurrentTime(TimeAttribute currentTime);
167
168 /**
169 * Returns the cached value for the current date. If the value has never
170 * been set by a call to <code>setCurrentDate</code>, or if caching is
171 * not enabled in this instance, then this will return null.
172 *
173 * @return the current date or null
174 */
175 public DateAttribute getCurrentDate();
176
177 /**
178 * Sets the current date for this evaluation. If caching is not enabled
179 * for this instance then the value is ignored.
180 *
181 * @param currentDate the dynamically resolved current date
182 */
183 public void setCurrentDate(DateAttribute currentDate);
184
185 /**
186 * Returns the cached value for the current dateTime. If the value has
187 * never been set by a call to <code>setCurrentDateTime</code>, or if
188 * caching is not enabled in this instance, then this will return null.
189 *
190 * @return the current date or null
191 */
192 public DateTimeAttribute getCurrentDateTime();
193
194 /**
195 * Sets the current dateTime for this evaluation. If caching is not enabled
196 * for this instance then the value is ignored.
197 *
198 * @param currentDateTime the dynamically resolved current dateTime
199 */
200 public void setCurrentDateTime(DateTimeAttribute currentDateTime);
201
202 /**
203 * Returns available subject attribute value(s) ignoring the issuer.
204 *
205 * @param type the type of the attribute value(s) to find
206 * @param id the id of the attribute value(s) to find
207 * @param category the category the attribute value(s) must be in
208 *
209 * @return a result containing a bag either empty because no values were
210 * found or containing at least one value, or status associated with an
211 * Indeterminate result
212 */
213 public EvaluationResult getSubjectAttribute(URI type, URI id,
214 URI category);
215
216 /**
217 * Returns available subject attribute value(s).
218 *
219 * @param type the type of the attribute value(s) to find
220 * @param id the id of the attribute value(s) to find
221 * @param issuer the issuer of the attribute value(s) to find or null
222 * @param category the category the attribute value(s) must be in
223 *
224 * @return a result containing a bag either empty because no values were
225 * found or containing at least one value, or status associated with an
226 * Indeterminate result
227 */
228 public EvaluationResult getSubjectAttribute(URI type, URI id, URI issuer,
229 URI category);
230
231 /**
232 * Returns available resource attribute value(s).
233 *
234 * @param type the type of the attribute value(s) to find
235 * @param id the id of the attribute value(s) to find
236 * @param issuer the issuer of the attribute value(s) to find or null
237 *
238 * @return a result containing a bag either empty because no values were
239 * found or containing at least one value, or status associated with an
240 * Indeterminate result
241 */
242 public EvaluationResult getResourceAttribute(URI type, URI id,
243 URI issuer);
244
245 /**
246 * Returns available action attribute value(s).
247 *
248 * @param type the type of the attribute value(s) to find
249 * @param id the id of the attribute value(s) to find
250 * @param issuer the issuer of the attribute value(s) to find or null
251 *
252 * @return a result containing a bag either empty because no values were
253 * found or containing at least one value, or status associated with an
254 * Indeterminate result
255 */
256 public EvaluationResult getActionAttribute(URI type, URI id, URI issuer);
257
258 /**
259 * Returns available environment attribute value(s).
260 *
261 * @param type the type of the attribute value(s) to find
262 * @param id the id of the attribute value(s) to find
263 * @param issuer the issuer of the attribute value(s) to find or null
264 *
265 * @return a result containing a bag either empty because no values were
266 * found or containing at least one value, or status associated with an
267 * Indeterminate result
268 */
269 public EvaluationResult getEnvironmentAttribute(URI type, URI id,
270 URI issuer);
271
272 /**
273 * Returns the attribute value(s) retrieved using the given XPath
274 * expression.
275 *
276 * @param contextPath the XPath expression to search
277 * @param namespaceNode the DOM node defining namespace mappings to use,
278 * or null if mappings come from the context root
279 * @param type the type of the attribute value(s) to find
280 * @param xpathVersion the version of XPath to use
281 *
282 * @return a result containing a bag either empty because no values were
283 * found or containing at least one value, or status associated with an
284 * Indeterminate result
285 */
286 public EvaluationResult getAttribute(String contextPath,
287 Node namespaceNode, URI type,
288 String xpathVersion);
289
290 }