Source code: com/sun/xacml/cond/FunctionFactory.java
1
2 /*
3 * @(#)FunctionFactory.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.ParsingException;
40 import com.sun.xacml.UnknownIdentifierException;
41
42 import java.net.URI;
43
44 import java.util.Set;
45
46 import org.w3c.dom.Node;
47
48
49 /**
50 * Factory used to create all functions. There are three kinds of factories:
51 * general, condition, and target. These provide functions that can be used
52 * anywhere, only in a condition's root and only in a target (respectively).
53 * <p>
54 * Note that all functions, except for abstract functions, are singletons, so
55 * any instance that is added to a factory will be the same one returned
56 * from the create methods. This is done because most functions don't have
57 * state, so there is no need to have more than one, or to spend the time
58 * creating multiple instances that all do the same thing.
59 *
60 * @since 1.0
61 * @author Marco Barreno
62 * @author Seth Proctor
63 */
64 public abstract class FunctionFactory
65 {
66
67 // the proxies used to get the default factorys
68 private static FunctionFactoryProxy defaultFactoryProxy;
69
70 /**
71 * static intialiazer that sets up the default factory proxies
72 * NOTE: this will change when the right setup mechanism is in place
73 */
74 static {
75 defaultFactoryProxy = new FunctionFactoryProxy() {
76 public FunctionFactory getTargetFactory() {
77 return StandardFunctionFactory.getTargetFactory();
78 }
79 public FunctionFactory getConditionFactory() {
80 return StandardFunctionFactory.getConditionFactory();
81 }
82 public FunctionFactory getGeneralFactory() {
83 return StandardFunctionFactory.getGeneralFactory();
84 }
85 };
86 };
87
88 /**
89 * Default constructor. Used only by subclasses.
90 */
91 protected FunctionFactory() {
92
93 }
94
95 /**
96 * Returns the default FunctionFactory that will only provide those
97 * functions that are usable in Target matching.
98 *
99 * @return a <code>FunctionFactory</code> for target functions
100 */
101 public static final FunctionFactory getTargetInstance() {
102 return defaultFactoryProxy.getTargetFactory();
103 }
104
105 /**
106 * Returns the default FuntionFactory that will only provide those
107 * functions that are usable in the root of the Condition. These Functions
108 * are a superset of the Target functions.
109 *
110 * @return a <code>FunctionFactory</code> for condition functions
111 */
112 public static final FunctionFactory getConditionInstance() {
113 return defaultFactoryProxy.getConditionFactory();
114 }
115
116 /**
117 * Returns the default FunctionFactory that provides access to all the
118 * functions. These Functions are a superset of the Condition functions.
119 *
120 * @return a <code>FunctionFactory</code> for all functions
121 */
122 public static final FunctionFactory getGeneralInstance() {
123 return defaultFactoryProxy.getGeneralFactory();
124 }
125
126 /**
127 * Sets the default factory. Note that this is just a placeholder for
128 * now, and will be replaced with a more useful mechanism soon.
129 */
130 public static final void setDefaultFactory(FunctionFactoryProxy proxy) {
131 defaultFactoryProxy = proxy;
132 }
133
134 /**
135 * Adds the function to the factory. Most functions have no state, so
136 * the singleton model used here is typically desireable. The factory will
137 * not enforce the requirement that a Target or Condition matching function
138 * must be boolean.
139 *
140 * @param function the <code>Function</code> to add to the factory
141 *
142 * @throws IllegalArgumentException if the function's identifier is already
143 * used
144 */
145 public abstract void addFunction(Function function);
146
147 /**
148 * Adds the abstract function proxy to the factory. This is used for
149 * those functions which have state, or change behavior (for instance
150 * the standard map function, which changes its return type based on
151 * how it is used).
152 *
153 * @param proxy the <code>FunctionProxy</code> to add to the factory
154 * @param identity the function's identifier
155 *
156 * @throws IllegalArgumentException if the function's identifier is already
157 * used
158 */
159 public abstract void addAbstractFunction(FunctionProxy proxy,
160 URI identity);
161
162 /**
163 * Adds a target function.
164 *
165 * @deprecated As of version 1.2, replaced by
166 * {@link #addFunction(Function)}.
167 * The new factory system requires you to get a factory
168 * instance and then call the non-static methods on that
169 * factory. The static versions of these methods have been
170 * left in for now, but are slower and will be removed in
171 * a future version.
172 *
173 * @param function the function to add
174 *
175 * @throws IllegalArgumentException if the name is already in use
176 */
177 public static void addTargetFunction(Function function) {
178 getTargetInstance().addFunction(function);
179 }
180
181 /**
182 * Adds an abstract target function.
183 *
184 * @deprecated As of version 1.2, replaced by
185 * {@link #addAbstractFunction(FunctionProxy,URI)}.
186 * The new factory system requires you to get a factory
187 * instance and then call the non-static methods on that
188 * factory. The static versions of these methods have been
189 * left in for now, but are slower and will be removed in
190 * a future version.
191 *
192 * @param proxy the function proxy to add
193 * @param identity the name of the function
194 *
195 * @throws IllegalArgumentException if the name is already in use
196 */
197 public static void addAbstractTargetFunction(FunctionProxy proxy,
198 URI identity) {
199 getTargetInstance().addAbstractFunction(proxy, identity);
200 }
201
202 /**
203 * Adds a condition function.
204 *
205 * @deprecated As of version 1.2, replaced by
206 * {@link #addFunction(Function)}.
207 * The new factory system requires you to get a factory
208 * instance and then call the non-static methods on that
209 * factory. The static versions of these methods have been
210 * left in for now, but are slower and will be removed in
211 * a future version.
212 *
213 * @param function the function to add
214 *
215 * @throws IllegalArgumentException if the name is already in use
216 */
217 public static void addConditionFunction(Function function) {
218 getConditionInstance().addFunction(function);
219 }
220
221 /**
222 * Adds an abstract condition function.
223 *
224 * @deprecated As of version 1.2, replaced by
225 * {@link #addAbstractFunction(FunctionProxy,URI)}.
226 * The new factory system requires you to get a factory
227 * instance and then call the non-static methods on that
228 * factory. The static versions of these methods have been
229 * left in for now, but are slower and will be removed in
230 * a future version.
231 *
232 * @param proxy the function proxy to add
233 * @param identity the name of the function
234 *
235 * @throws IllegalArgumentException if the name is already in use
236 */
237 public static void addAbstractConditionFunction(FunctionProxy proxy,
238 URI identity) {
239 getConditionInstance().addAbstractFunction(proxy, identity);
240 }
241
242 /**
243 * Adds a general function.
244 *
245 * @deprecated As of version 1.2, replaced by
246 * {@link #addFunction(Function)}.
247 * The new factory system requires you to get a factory
248 * instance and then call the non-static methods on that
249 * factory. The static versions of these methods have been
250 * left in for now, but are slower and will be removed in
251 * a future version.
252 *
253 * @param function the function to add
254 *
255 * @throws IllegalArgumentException if the name is already in use
256 */
257 public static void addGeneralFunction(Function function) {
258 getGeneralInstance().addFunction(function);
259 }
260
261 /**
262 * Adds an abstract general function.
263 *
264 * @deprecated As of version 1.2, replaced by
265 * {@link #addAbstractFunction(FunctionProxy,URI)}.
266 * The new factory system requires you to get a factory
267 * instance and then call the non-static methods on that
268 * factory. The static versions of these methods have been
269 * left in for now, but are slower and will be removed in
270 * a future version.
271 *
272 * @param proxy the function proxy to add
273 * @param identity the name of the function
274 *
275 * @throws IllegalArgumentException if the name is already in use
276 */
277 public static void addAbstractGeneralFunction(FunctionProxy proxy,
278 URI identity) {
279 getGeneralInstance().addAbstractFunction(proxy, identity);
280 }
281
282 /**
283 * Returns the function identifiers supported by this factory.
284 *
285 * @return a <code>Set</code> of <code>String</code>s
286 */
287 public abstract Set getSupportedFunctions();
288
289 /**
290 * Tries to get an instance of the specified function.
291 *
292 * @param identity the name of the function
293 *
294 * @throws UnknownIdentifierException if the name isn't known
295 * @throws FunctionTypeException if the name is known to map to an
296 * abstract function, and should therefore
297 * be created through createAbstractFunction
298 */
299 public abstract Function createFunction(URI identity)
300 throws UnknownIdentifierException, FunctionTypeException;
301
302 /**
303 * Tries to get an instance of the specified function.
304 *
305 * @param identity the name of the function
306 *
307 * @throws UnknownIdentifierException if the name isn't known
308 * @throws FunctionTypeException if the name is known to map to an
309 * abstract function, and should therefore
310 * be created through createAbstractFunction
311 */
312 public abstract Function createFunction(String identity)
313 throws UnknownIdentifierException, FunctionTypeException;
314
315 /**
316 * Tries to get an instance of the specified abstract function.
317 *
318 * @param identity the name of the function
319 * @param root the DOM root containing info used to create the function
320 *
321 * @throws UnknownIdentifierException if the name isn't known
322 * @throws FunctionTypeException if the name is known to map to a
323 * concrete function, and should therefore
324 * be created through createFunction
325 * @throws ParsingException if the function can't be created with the
326 * given inputs
327 */
328 public abstract Function createAbstractFunction(URI identity, Node root)
329 throws UnknownIdentifierException, ParsingException,
330 FunctionTypeException;
331
332 /**
333 * Tries to get an instance of the specified abstract function.
334 *
335 * @param identity the name of the function
336 * @param root the DOM root containing info used to create the function
337 * @param xpathVersion the version specified in the contianing policy, or
338 * null if no version was specified
339 *
340 * @throws UnknownIdentifierException if the name isn't known
341 * @throws FunctionTypeException if the name is known to map to a
342 * concrete function, and should therefore
343 * be created through createFunction
344 * @throws ParsingException if the function can't be created with the
345 * given inputs
346 */
347 public abstract Function createAbstractFunction(URI identity, Node root,
348 String xpathVersion)
349 throws UnknownIdentifierException, ParsingException,
350 FunctionTypeException;
351
352 /**
353 * Tries to get an instance of the specified abstract function.
354 *
355 * @param identity the name of the function
356 * @param root the DOM root containing info used to create the function
357 *
358 * @throws UnknownIdentifierException if the name isn't known
359 * @throws FunctionTypeException if the name is known to map to a
360 * concrete function, and should therefore
361 * be created through createFunction
362 * @throws ParsingException if the function can't be created with the
363 * given inputs
364 */
365 public abstract Function createAbstractFunction(String identity, Node root)
366 throws UnknownIdentifierException, ParsingException,
367 FunctionTypeException;
368
369 /**
370 * Tries to get an instance of the specified abstract function.
371 *
372 * @param identity the name of the function
373 * @param root the DOM root containing info used to create the function
374 * @param xpathVersion the version specified in the contianing policy, or
375 * null if no version was specified
376 *
377 * @throws UnknownIdentifierException if the name isn't known
378 * @throws FunctionTypeException if the name is known to map to a
379 * concrete function, and should therefore
380 * be created through createFunction
381 * @throws ParsingException if the function can't be created with the
382 * given inputs
383 */
384 public abstract Function createAbstractFunction(String identity, Node root,
385 String xpathVersion)
386 throws UnknownIdentifierException, ParsingException,
387 FunctionTypeException;
388
389 }