01: /*
02: * Licensed to the Apache Software Foundation (ASF) under one
03: * or more contributor license agreements. See the NOTICE file
04: * distributed with this work for additional information
05: * regarding copyright ownership. The ASF licenses this file
06: * to you under the Apache License, Version 2.0 (the
07: * "License"); you may not use this file except in compliance
08: * with the License. You may obtain a copy of the License at
09: *
10: * http://www.apache.org/licenses/LICENSE-2.0
11: *
12: * Unless required by applicable law or agreed to in writing,
13: * software distributed under the License is distributed on an
14: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15: * KIND, either express or implied. See the License for the
16: * specific language governing permissions and limitations
17: * under the License.
18: */
19: package org.apache.openjpa.kernel.exps;
20:
21: import java.io.Serializable;
22:
23: import org.apache.openjpa.kernel.StoreContext;
24:
25: /**
26: * A filter listener extends expression filters with custom functionality.
27: *
28: * @author Steve Kim
29: * @author Abe White
30: */
31: public interface FilterListener extends Serializable {
32:
33: /**
34: * Return the tag that this extension listens for.
35: */
36: public String getTag();
37:
38: /**
39: * Return true if this extension expects arguments to act on. Some
40: * extensions may not need arguments; for example, an extension to
41: * switch a string to upper case might be of the form:
42: * <code>field.ext:toUpperCase ()</code>.
43: */
44: public boolean expectsArguments();
45:
46: /**
47: * Return true if this extension expects a target to act on. Some
48: * extensions act on a field or object value; others stand alone.
49: * <code>field.ext:toUpperCase ()</code> acts on the target
50: * <code>field</code> but has no arguments, while another possible form,
51: * <code>ext:toUpperCase (field)</code> has no target but does have an
52: * argument.
53: */
54: public boolean expectsTarget();
55:
56: /**
57: * Evaluate the given expression. This method is used when
58: * evaluating in-memory expressions. The method used when evaluating
59: * data store expressions will change depending on the data store in use.
60: *
61: * @param target the target object / field value to act on; will be
62: * null if this extension does not expect a target
63: * @param targetClass the expected class of the target; given in case
64: * the target evaluates to null and typing is needed
65: * @param args the values of the arguments given in the filter;
66: * will be null if this extension does not expect an argument
67: * @param argClasses the expected classes of the arguments; given in case
68: * an argument evaluates to null and typing is needed
69: * @param candidate the candidate object being evaluated
70: * @param ctx the persistence context
71: * @return the value of the extension for this candidate; if
72: * this extension is an expression, this method should
73: * return {@link Boolean#TRUE} or {@link Boolean#FALSE}
74: * @throws org.apache.openjpa.util.UserException if this extension does not
75: * support in-memory operation
76: */
77: public Object evaluate(Object target, Class targetClass,
78: Object[] args, Class[] argClasses, Object candidate,
79: StoreContext ctx);
80:
81: /**
82: * Return the expected type of the result of this listener.
83: *
84: * @param targetClass the expected class of the target, or null if no target
85: * @param argClasses the expected classes of the arguments, or null if
86: * no arguments
87: */
88: public Class getType(Class targetClass, Class[] argClasses);
89: }
|