1 package org.apache.commons.ognl.enhance;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import org.apache.commons.ognl.Node;
23 import org.apache.commons.ognl.OgnlContext;
24
25 import java.lang.reflect.Method;
26
27 /**
28 * Core interface implemented by expression compiler instances.
29 */
30 public interface OgnlExpressionCompiler
31 {
32
33 /** Static constant used in conjunction with {@link OgnlContext} to store temporary references. */
34 String ROOT_TYPE = "-ognl-root-type";
35
36 /**
37 * The core method executed to compile a specific expression. It is expected that this expression always return a
38 * {@link Node} with a non null {@link org.apache.commons.ognl.Node#getAccessor()} instance - unless an exception is
39 * thrown by the method or the statement wasn't compilable in this instance because of missing/null objects in the
40 * expression. These instances may in some cases continue to call this compilation method until the expression is
41 * resolvable.
42 *
43 * @param context The context of execution.
44 * @param expression The pre-parsed root expression node to compile.
45 * @param root The root object for the expression - may be null in many instances so some implementations may exit
46 * @throws Exception If an error occurs compiling the expression and no strategy has been implemented to handle
47 * incremental expression compilation for incomplete expression members.
48 */
49 void compileExpression( OgnlContext context, Node expression, Object root )
50 throws Exception;
51
52 /**
53 * Gets a javassist safe class string for the given class instance. This is especially useful for handling array vs.
54 * normal class casting strings.
55 *
56 * @param clazz The class to get a string equivalent javassist compatible string reference for.
57 * @return The string equivalent of the class.
58 */
59 String getClassName( Class<?> clazz );
60
61 /**
62 * Used in places where the preferred {@link #getSuperOrInterfaceClass(java.lang.reflect.Method, Class)} isn't
63 * possible because the method isn't known for a class. Attempts to upcast the given class to the next available
64 * non-private accessible class so that compiled expressions can reference the interface class of an instance so as
65 * not to be compiled in to overly specific statements.
66 *
67 * @param clazz The class to attempt to find a compatible interface for.
68 * @return The same class if no higher level interface could be matched against or the interface equivalent class.
69 */
70 Class<?> getInterfaceClass( Class<?> clazz );
71
72 /**
73 * For the given {@link Method} and class finds the highest level interface class this combination can be cast to.
74 *
75 * @param m The method the class must implement.
76 * @param clazz The current class being worked with.
77 * @return The highest level interface / class that the referenced {@link Method} is declared in.
78 */
79 Class<?> getSuperOrInterfaceClass( Method m, Class<?> clazz );
80
81 /**
82 * For a given root object type returns the base class type to be used in root referenced expressions. This helps in
83 * some instances where the root objects themselves are compiled javassist instances that need more generic class
84 * equivalents to cast to.
85 *
86 * @param rootNode The root expression node.
87 * @param context The current execution context.
88 * @return The root expression class type to cast to for this node.
89 */
90 Class<?> getRootExpressionClass( Node rootNode, OgnlContext context );
91
92 /**
93 * Used primarily by AST types like {@link org.apache.commons.ognl.ASTChain} where <code>foo.bar.id</code> type
94 * references may need to be cast multiple times in order to properly resolve the members in a compiled statement.
95 * <p>
96 * This method should be using the various {@link org.apache.commons.ognl.OgnlContext#getCurrentType()} /
97 * {@link org.apache.commons.ognl.OgnlContext#getCurrentAccessor()} methods to inspect the type stack and properly
98 * cast to the right classes - but only when necessary.
99 * </p>
100 *
101 * @param context The current execution context.
102 * @param expression The node being checked for casting.
103 * @param body The java source string generated by the given node.
104 * @return The body string parameter plus any additional casting syntax needed to make the expression resolvable.
105 */
106 String castExpression( OgnlContext context, Node expression, String body );
107
108 /**
109 * Method is used for expressions where multiple inner parameter method calls in generated java source strings cause
110 * javassit failures. It is hacky and cumbersome to have to generate expressions this way but it's the only current
111 * known way to make javassist happy.
112 * <p>
113 * Takes an expression block generated by a node and creates a new method on the base object being compiled so that
114 * sufficiently complicated sub expression blocks can be broken out in to distinct methods to be referenced by the
115 * core accessor / setter methods in the base compiled root object.
116 * </p>
117 *
118 * @param context The current execution context.
119 * @param expression The java source expression to dump in to a seperate method reference.
120 * @param type The return type that should be specified for the new method.
121 * @return The method name that will be used to reference the sub expression in place of the actual sub expression
122 * itself.
123 */
124 String createLocalReference( OgnlContext context, String expression, Class<?> type );
125 }