Source Code Cross Referenced for ELResolver.java in  » Scripting » JUEL » javax » el » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Java Source Code / Java Documentation
1. 6.0 JDK Core
2. 6.0 JDK Modules
3. 6.0 JDK Modules com.sun
4. 6.0 JDK Modules com.sun.java
5. 6.0 JDK Modules sun
6. 6.0 JDK Platform
7. Ajax
8. Apache Harmony Java SE
9. Aspect oriented
10. Authentication Authorization
11. Blogger System
12. Build
13. Byte Code
14. Cache
15. Chart
16. Chat
17. Code Analyzer
18. Collaboration
19. Content Management System
20. Database Client
21. Database DBMS
22. Database JDBC Connection Pool
23. Database ORM
24. Development
25. EJB Server geronimo
26. EJB Server GlassFish
27. EJB Server JBoss 4.2.1
28. EJB Server resin 3.1.5
29. ERP CRM Financial
30. ESB
31. Forum
32. GIS
33. Graphic Library
34. Groupware
35. HTML Parser
36. IDE
37. IDE Eclipse
38. IDE Netbeans
39. Installer
40. Internationalization Localization
41. Inversion of Control
42. Issue Tracking
43. J2EE
44. JBoss
45. JMS
46. JMX
47. Library
48. Mail Clients
49. Net
50. Parser
51. PDF
52. Portal
53. Profiler
54. Project Management
55. Report
56. RSS RDF
57. Rule Engine
58. Science
59. Scripting
60. Search Engine
61. Security
62. Sevlet Container
63. Source Control
64. Swing Library
65. Template Engine
66. Test Coverage
67. Testing
68. UML
69. Web Crawler
70. Web Framework
71. Web Mail
72. Web Server
73. Web Services
74. Web Services apache cxf 2.0.1
75. Web Services AXIS2
76. Wiki Engine
77. Workflow Engines
78. XML
79. XML UI
Java
Java Tutorial
Java Open Source
Jar File Download
Java Articles
Java Products
Java by API
Photoshop Tutorials
Maya Tutorials
Flash Tutorials
3ds-Max Tutorials
Illustrator Tutorials
GIMP Tutorials
C# / C Sharp
C# / CSharp Tutorial
C# / CSharp Open Source
ASP.Net
ASP.NET Tutorial
JavaScript DHTML
JavaScript Tutorial
JavaScript Reference
HTML / CSS
HTML CSS Reference
C / ANSI-C
C Tutorial
C++
C++ Tutorial
Ruby
PHP
Python
Python Tutorial
Python Open Source
SQL Server / T-SQL
SQL Server / T-SQL Tutorial
Oracle PL / SQL
Oracle PL/SQL Tutorial
PostgreSQL
SQL / MySQL
MySQL Tutorial
VB.Net
VB.Net Tutorial
Flash / Flex / ActionScript
VBA / Excel / Access / Word
XML
XML Tutorial
Microsoft Office PowerPoint 2007 Tutorial
Microsoft Office Excel 2007 Tutorial
Microsoft Office Word 2007 Tutorial
Java Source Code / Java Documentation » Scripting » JUEL » javax.el 
Source Cross Referenced  Class Diagram Java Document (Java Doc) 


001:        /*
002:         * The contents of this file are subject to the terms
003:         * of the Common Development and Distribution License
004:         * (the "License").  You may not use this file except
005:         * in compliance with the License.
006:         *
007:         * You can obtain a copy of the license at
008:         * glassfish/bootstrap/legal/CDDLv1.0.txt or
009:         * https://glassfish.dev.java.net/public/CDDLv1.0.html.
010:         * See the License for the specific language governing
011:         * permissions and limitations under the License.
012:         *
013:         * When distributing Covered Code, include this CDDL
014:         * HEADER in each file and include the License file at
015:         * glassfish/bootstrap/legal/CDDLv1.0.txt.  If applicable,
016:         * add the following below this CDDL HEADER, with the
017:         * fields enclosed by brackets "[]" replaced with your
018:         * own identifying information: Portions Copyright [yyyy]
019:         * [name of copyright owner]
020:         *
021:         * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
022:         */
023:
024:        package javax.el;
025:
026:        import java.util.Iterator;
027:        import java.beans.FeatureDescriptor;
028:
029:        /**
030:         * Enables customization of variable and property resolution behavior for EL
031:         * expression evaluation.
032:         *
033:         * <p>While evaluating an expression, the <code>ELResolver</code> associated
034:         * with the {@link ELContext} is consulted to do the initial resolution of 
035:         * the first variable of an expression. It is also consulted when a 
036:         * <code>.</code> or <code>[]</code> operator is encountered, except for the
037:         * last such operator in a method expression, in which case the resultion
038:         * rules are hard coded.</p>
039:         *
040:         * <p>For example, in the EL expression <code>${employee.lastName}</code>, 
041:         * the <code>ELResolver</code> determines what object <code>employee</code>
042:         * refers to, and what it means to get the <code>lastName</code> property on 
043:         * that object.</p>
044:         *
045:         * <p>Most methods in this class accept a <code>base</code> 
046:         * and <code>property</code> parameter. In the case of variable resolution
047:         * (e.g. determining what <code>employee</code> refers to in 
048:         * <code>${employee.lastName}</code>), the <code>base</code> parameter will 
049:         * be <code>null</code> and the <code>property</code> parameter will always 
050:         * be of type <code>String</code>. In this case, if the <code>property</code>
051:         * is not a <code>String</code>, the behavior of the <code>ELResolver</code>
052:         * is undefined.</p>
053:         *
054:         * <p>In the case of property resolution, the <code>base</code> parameter
055:         * identifies the base object and the <code>property</code> object identifies
056:         * the property on that base. For example, in the expression
057:         * <code>${employee.lastName}</code>, <code>base</code> is the result of the
058:         * variable resolution for <code>employee</code> and <code>property</code>
059:         * is the string <code>"lastName"</code>.  In the expression
060:         * <code>${y[x]}</code>, <code>base</code> is the result of the variable
061:         * resolution for <code>y</code> and <code>property</code> is the result of
062:         * the variable resolution for <code>x</code>.</p>
063:         *
064:         * <p>Though only a single <code>ELResolver</code> is associated with an
065:         * <code>ELContext</code>, there are usually multiple resolvers considered
066:         * for any given variable or property resolution. <code>ELResolver</code>s
067:         * are combined together using {@link CompositeELResolver}s, to define
068:         * rich semantics for evaluating an expression.</p>
069:         *
070:         * <p>For the {@link #getValue}, {@link #getType}, {@link #setValue} and
071:         * {@link #isReadOnly} methods, an <code>ELResolver</code> is not
072:         * responsible for resolving all possible (base, property) pairs. In fact,
073:         * most resolvers will only handle a <code>base</code> of a single type.
074:         * To indicate that a resolver has successfully resolved a particular
075:         * (base, property) pair, it must set the <code>propertyResolved</code>
076:         * property of the <code>ELContext</code> to <code>true</code>. If it could 
077:         * not handle the given pair, it must leave this property alone. The caller
078:         * must ignore the return value of the method if <code>propertyResolved</code>
079:         * is <code>false</code>.</p>
080:         *
081:         * <p>The {@link #getFeatureDescriptors} and {@link #getCommonPropertyType}
082:         * methods are primarily designed for design-time tool support, but must
083:         * handle invocation at runtime as well. The 
084:         * {@link java.beans.Beans#isDesignTime} method can be used to determine 
085:         * if the resolver is being consulted at design-time or runtime.</p>
086:         *
087:         * @see CompositeELResolver
088:         * @see ELContext#getELResolver
089:         * @since JSP 2.1
090:         */
091:        public abstract class ELResolver {
092:
093:            // --------------------------------------------------------- Constants
094:
095:            /**
096:             * <p>The attribute name of the named attribute in the
097:             * <code>FeatureDescriptor</code> that specifies the runtime type of
098:             * the variable or property.</p>
099:             */
100:
101:            public static final String TYPE = "type";
102:
103:            /**
104:             * <p>The attribute name of the named attribute in the
105:             * <code>FeatureDescriptor</code> that specifies whether the
106:             * variable or property can be resolved at runtime.</p>
107:             */
108:
109:            public static final String RESOLVABLE_AT_DESIGN_TIME = "resolvableAtDesignTime";
110:
111:            /**
112:             * Attempts to resolve the given <code>property</code> object on the given
113:             * <code>base</code> object.
114:             *
115:             * <p>If this resolver handles the given (base, property) pair, 
116:             * the <code>propertyResolved</code> property of the 
117:             * <code>ELContext</code> object must be set to <code>true</code>
118:             * by the resolver, before returning. If this property is not 
119:             * <code>true</code> after this method is called, the caller should ignore 
120:             * the return value.</p>
121:             *
122:             * @param context The context of this evaluation.
123:             * @param base The base object whose property value is to be returned,
124:             *     or <code>null</code> to resolve a top-level variable.
125:             * @param property The property or variable to be resolved.
126:             * @return If the <code>propertyResolved</code> property of 
127:             *     <code>ELContext</code> was set to <code>true</code>, then
128:             *     the result of the variable or property resolution; otherwise
129:             *     undefined.
130:             * @throws NullPointerException if context is <code>null</code>
131:             * @throws PropertyNotFoundException if the given (base, property) pair
132:             *     is handled by this <code>ELResolver</code> but the specified
133:             *     variable or property does not exist or is not readable.
134:             * @throws ELException if an exception was thrown while performing
135:             *     the property or variable resolution. The thrown exception
136:             *     must be included as the cause property of this exception, if
137:             *     available.
138:             */
139:            public abstract Object getValue(ELContext context, Object base,
140:                    Object property);
141:
142:            /**
143:             * For a given <code>base</code> and <code>property</code>, attempts to
144:             * identify the most general type that is acceptable for an object to be 
145:             * passed as the <code>value</code> parameter in a future call 
146:             * to the {@link #setValue} method.
147:             *
148:             * <p>If this resolver handles the given (base, property) pair, 
149:             * the <code>propertyResolved</code> property of the 
150:             * <code>ELContext</code> object must be set to <code>true</code>
151:             * by the resolver, before returning. If this property is not 
152:             * <code>true</code> after this method is called, the caller should ignore 
153:             * the return value.</p>
154:             *
155:             * <p>This is not always the same as <code>getValue().getClass()</code>.
156:             * For example, in the case of an {@link ArrayELResolver}, the
157:             * <code>getType</code> method will return the element type of the 
158:             * array, which might be a superclass of the type of the actual 
159:             * element that is currently in the specified array element.</p>
160:             *
161:             * @param context The context of this evaluation.
162:             * @param base The base object whose property value is to be analyzed,
163:             *     or <code>null</code> to analyze a top-level variable.
164:             * @param property The property or variable to return the acceptable 
165:             *     type for.
166:             * @return If the <code>propertyResolved</code> property of 
167:             *     <code>ELContext</code> was set to <code>true</code>, then
168:             *     the most general acceptable type; otherwise undefined.
169:             * @throws NullPointerException if context is <code>null</code>
170:             * @throws PropertyNotFoundException if the given (base, property) pair
171:             *     is handled by this <code>ELResolver</code> but the specified
172:             *     variable or property does not exist or is not readable.
173:             * @throws ELException if an exception was thrown while performing
174:             *     the property or variable resolution. The thrown exception
175:             *     must be included as the cause property of this exception, if
176:             *     available.
177:             */
178:            public abstract Class<?> getType(ELContext context, Object base,
179:                    Object property);
180:
181:            /**
182:             * Attempts to set the value of the given <code>property</code> 
183:             * object on the given <code>base</code> object.
184:             *
185:             * <p>If this resolver handles the given (base, property) pair, 
186:             * the <code>propertyResolved</code> property of the 
187:             * <code>ELContext</code> object must be set to <code>true</code>
188:             * by the resolver, before returning. If this property is not 
189:             * <code>true</code> after this method is called, the caller can
190:             * safely assume no value has been set.</p>
191:             *
192:             * @param context The context of this evaluation.
193:             * @param base The base object whose property value is to be set,
194:             *     or <code>null</code> to set a top-level variable.
195:             * @param property The property or variable to be set.
196:             * @param value The value to set the property or variable to.
197:             * @throws NullPointerException if context is <code>null</code>
198:             * @throws PropertyNotFoundException if the given (base, property) pair
199:             *     is handled by this <code>ELResolver</code> but the specified
200:             *     variable or property does not exist.
201:             * @throws PropertyNotWritableException if the given (base, property)
202:             *     pair is handled by this <code>ELResolver</code> but the specified
203:             *     variable or property is not writable.
204:             * @throws ELException if an exception was thrown while attempting to
205:             *     set the property or variable. The thrown exception
206:             *     must be included as the cause property of this exception, if
207:             *     available.
208:             */
209:            public abstract void setValue(ELContext context, Object base,
210:                    Object property, Object value);
211:
212:            /**
213:             * For a given <code>base</code> and <code>property</code>, attempts to
214:             * determine whether a call to {@link #setValue} will always fail.
215:             *
216:             * <p>If this resolver handles the given (base, property) pair, 
217:             * the <code>propertyResolved</code> property of the 
218:             * <code>ELContext</code> object must be set to <code>true</code>
219:             * by the resolver, before returning. If this property is not 
220:             * <code>true</code> after this method is called, the caller should ignore 
221:             * the return value.</p>
222:             *
223:             * @param context The context of this evaluation.
224:             * @param base The base object whose property value is to be analyzed,
225:             *     or <code>null</code> to analyze a top-level variable.
226:             * @param property The property or variable to return the read-only status
227:             *     for.
228:             * @return If the <code>propertyResolved</code> property of 
229:             *     <code>ELContext</code> was set to <code>true</code>, then
230:             *     <code>true</code> if the property is read-only or
231:             *     <code>false</code> if not; otherwise undefined.
232:             * @throws NullPointerException if context is <code>null</code>
233:             * @throws PropertyNotFoundException if the given (base, property) pair
234:             *     is handled by this <code>ELResolver</code> but the specified
235:             *     variable or property does not exist.
236:             * @throws ELException if an exception was thrown while performing
237:             *     the property or variable resolution. The thrown exception
238:             *     must be included as the cause property of this exception, if
239:             *     available.
240:             */
241:            public abstract boolean isReadOnly(ELContext context, Object base,
242:                    Object property);
243:
244:            /**
245:             * Returns information about the set of variables or properties that 
246:             * can be resolved for the given <code>base</code> object. One use for
247:             * this method is to assist tools in auto-completion.
248:             *
249:             * <p>If the <code>base</code> parameter is <code>null</code>, the 
250:             * resolver must enumerate the list of top-level variables it can 
251:             * resolve.</p>
252:             *
253:             * <p>The <code>Iterator</code> returned must contain zero or more 
254:             * instances of {@link java.beans.FeatureDescriptor}, in no guaranteed 
255:             * order. In the case of primitive types such as <code>int</code>, the 
256:             * value <code>null</code> must be returned. This is to prevent the 
257:             * useless iteration through all possible primitive values. A 
258:             * return value of <code>null</code> indicates that this resolver does 
259:             * not handle the given <code>base</code> object or that the results 
260:             * are too complex to represent with this method and the 
261:             * {@link #getCommonPropertyType} method should be used instead.</p>
262:             *
263:             * <p>Each <code>FeatureDescriptor</code> will contain information about
264:             * a single variable or property. In addition to the standard
265:             * properties, the <code>FeatureDescriptor</code> must have two
266:             * named attributes (as set by the <code>setValue</code> method):
267:             * <ul>
268:             *   <li>{@link #TYPE} - The value of this named attribute must be 
269:             *       an instance of <code>java.lang.Class</code> and specify the 
270:             *       runtime type of the variable or property.</li>
271:             *   <li>{@link #RESOLVABLE_AT_DESIGN_TIME} - The value of this 
272:             *       named attribute must be an instance of 
273:             *       <code>java.lang.Boolean</code> and indicates whether it is safe 
274:             *       to attempt to resolve this property at design-time. For 
275:             *       instance, it may be unsafe to attempt a resolution at design 
276:             *       time if the <code>ELResolver</code> needs access to a resource 
277:             *       that is only available at runtime and no acceptable simulated 
278:             *       value can be provided.</li>
279:             * </ul></p>
280:             *
281:             * <p>The caller should be aware that the <code>Iterator</code> 
282:             * returned might iterate through a very large or even infinitely large 
283:             * set of properties. Care should be taken by the caller to not get 
284:             * stuck in an infinite loop.</p>
285:             *
286:             * <p>This is a "best-effort" list.  Not all <code>ELResolver</code>s
287:             * will return completely accurate results, but all must be callable
288:             * at both design-time and runtime (i.e. whether or not
289:             * <code>Beans.isDesignTime()</code> returns <code>true</code>),
290:             * without causing errors.</p>
291:             *
292:             * <p>The <code>propertyResolved</code> property of the 
293:             * <code>ELContext</code> is not relevant to this method.
294:             * The results of all <code>ELResolver</code>s are concatenated
295:             * in the case of composite resolvers.</p>
296:             * 
297:             * @param context The context of this evaluation.
298:             * @param base The base object whose set of valid properties is to
299:             *     be enumerated, or <code>null</code> to enumerate the set of
300:             *     top-level variables that this resolver can evaluate.
301:             * @return An <code>Iterator</code> containing zero or more (possibly
302:             *     infinitely more) <code>FeatureDescriptor</code> objects, or 
303:             *     <code>null</code> if this resolver does not handle the given 
304:             *     <code>base</code> object or that the results are too complex to 
305:             *     represent with this method
306:             * @see java.beans.FeatureDescriptor
307:             */
308:            public abstract Iterator<FeatureDescriptor> getFeatureDescriptors(
309:                    ELContext context, Object base);
310:
311:            /**
312:             * Returns the most general type that this resolver accepts for the
313:             * <code>property</code> argument, given a <code>base</code> object.
314:             * One use for this method is to assist tools in auto-completion.
315:             *
316:             * <p>This assists tools in auto-completion and also provides a 
317:             * way to express that the resolver accepts a primitive value, 
318:             * such as an integer index into an array. For example, the 
319:             * {@link ArrayELResolver} will accept any <code>int</code> as a 
320:             * <code>property</code>, so the return value would be 
321:             * <code>Integer.class</code>.</p>
322:             *
323:             * @param context The context of this evaluation.
324:             * @param base The base object to return the most general property
325:             *     type for, or <code>null</code> to enumerate the set of
326:             *     top-level variables that this resolver can evaluate.
327:             * @return <code>null</code> if this <code>ELResolver</code> does not
328:             *     know how to handle the given <code>base</code> object; otherwise
329:             *     <code>Object.class</code> if any type of <code>property</code>
330:             *     is accepted; otherwise the most general <code>property</code>
331:             *     type accepted for the given <code>base</code>.
332:             */
333:            public abstract Class<?> getCommonPropertyType(ELContext context,
334:                    Object base);
335:
336:        }
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.