Source code: com/sun/xacml/cond/Function.java
1
2 /*
3 * @(#)Function.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.cond;
38
39 import com.sun.xacml.EvaluationCtx;
40
41 import com.sun.xacml.attr.AttributeValue;
42
43 import java.net.URI;
44
45 import java.util.List;
46
47
48 /**
49 * Interface that all functions in the system must implement.
50 *
51 * @since 1.0
52 * @author Seth Proctor
53 */
54 public interface Function
55 {
56
57 /**
58 * Evaluates the <code>Function</code> using the given inputs.
59 * The <code>List</code> contains <code>Evaluatable<code>s which are all
60 * of the correct type if the <code>Function</code> has been created as
61 * part of an <code>Apply</code> or <code>TargetMatch</code>, but which
62 * may otherwise be invalid. Each parameter should be evaluated by the
63 * <code>Function</code>, unless this is a higher-order function (in
64 * which case the <code>Apply</code> has already evaluated the inputs
65 * to check for any INDETERMINATE conditions), or the <code>Function</code>
66 * doesn't need to evaluate all inputs to determine a result (as in the
67 * case of the or function). The order of the <code>List</code> is
68 * significant, so a <code>Function</code> should have a very good reason
69 * if it wants to evaluate the inputs in a different order.
70 * <p>
71 * Note that if this is a higher-order function, like any-of, then
72 * the first argument in the <code>List</code> will actually be a Function
73 * object representing the function to apply to some bag. In this case,
74 * the second and any subsequent entries in the list are
75 * <code>AttributeValue</code> objects (no INDETERMINATE values are
76 * allowed, so the function is not given the option of dealing with
77 * attributes that cannot be resolved). A function needs to know if it's
78 * a higher-order function, and therefore whether or not to look for
79 * this case. Also, a higher-order function is responsible for checking
80 * that the inputs that it will pass to the <code>Function</code>
81 * provided as the first parameter are valid, ie. it must do a
82 * <code>checkInputs</code> on its sub-function when
83 * <code>checkInputs</code> is called on the higher-order function.
84 *
85 * @param inputs the <code>List</code> of inputs for the function
86 * @param context the representation of the request
87 *
88 * @return a result containing the <code>AttributeValue</code> computed
89 * when evaluating the function, or <code>Status</code>
90 * specifying some error condition
91 */
92 public EvaluationResult evaluate(List inputs, EvaluationCtx context);
93
94 /**
95 * Returns the identifier of this function as known by the factories.
96 * In the case of the standard XACML functions, this will be one of the
97 * URIs defined in the standard namespace. This function must always
98 * return the complete namespace and identifier of this function.
99 *
100 * @return the function's identifier
101 */
102 public URI getIdentifier();
103
104 /**
105 * Provides the type of <code>AttributeValue</code> that this function
106 * returns from <code>evaluate</code> in a successful evaluation.
107 *
108 * @return the type returned by this function
109 */
110 public URI getReturnType();
111
112 /**
113 * Tells whether this function will return a bag of values or just a
114 * single value.
115 *
116 * @return true if evaluation will return a bag, false otherwise
117 */
118 public boolean returnsBag();
119
120 /**
121 * Checks that the given inputs are of the right types, in the right
122 * order, and are the right number for this function to evaluate. If
123 * the function cannot accept the inputs for evaluation, an
124 * <code>IllegalArgumentException</code> is thrown.
125 *
126 * @param inputs a <code>List</code> of <code>Evaluatable</code>s, with
127 * the first argument being a <code>Function</code> if
128 * this is a higher-order function
129 *
130 * @throws IllegalArgumentException if the inputs do match what the
131 * function accepts for evaluation
132 */
133 public void checkInputs(List inputs) throws IllegalArgumentException;
134
135 /**
136 * Checks that the given inputs are of the right types, in the right
137 * order, and are the right number for this function to evaluate. If
138 * the function cannot accept the inputs for evaluation, an
139 * <code>IllegalArgumentException</code> is thrown. Unlike the other
140 * <code>checkInput</code> method in this interface, this assumes that
141 * the parameters will never provide bags of values. This is useful if
142 * you're considering a target function which has a designator or
143 * selector in its input list, but which passes the values from the
144 * derived bags one at a time to the function, so the function doesn't
145 * have to deal with the bags that the selector or designator
146 * generates.
147 *
148 * @param inputs a <code>List</code> of <code>Evaluatable</code>s, with
149 * the first argument being a <code>Function</code> if
150 * this is a higher-order function
151 *
152 * @throws IllegalArgumentException if the inputs do match what the
153 * function accepts for evaluation
154 */
155 public void checkInputsNoBag(List inputs) throws IllegalArgumentException;
156
157 }