View Javadoc

1   /*
2    * Copyright 2004-2005 the original author or authors.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5    * use this file except in compliance with the License. You may obtain a copy of
6    * the License at
7    * 
8    * http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations under
14   * the License.
15   */
16  package net.sf.morph.lang;
17  
18  /**
19   * <p>
20   * Defines a syntax for expressions that can be used to access and change
21   * properties (bean or indexed) inside a target object. This is similar to the
22   * expression languages found in the JSTL EL, the Spring framework, Struts, and
23   * Velocity. Below are some example expressions.
24   * </p>
25   * 
26   * <p>
27   * JSTL EL example: <br>
28   * <code>
29   * myBean.myMap.myProperty
30   * </code>
31   * </p>
32   * 
33   * <p>
34   * Spring example: <br>
35   * <code>
36   * myBean.myMap["myProperty"]
37   * </code>
38   * </p>
39   * 
40   * @author Matt Sgarlata
41   * @since Nov 14, 2004
42   */
43  public interface Language {
44  
45  	/**
46  	 * Specifies the least restrictive type that may be assigned to property
47  	 * indicated by the given <code>expression</code>. If any type can be
48  	 * assigned to the property, this method returns <code>Object.class</code>.
49  	 * 
50  	 * @param target
51  	 *            the target being analyzed
52  	 * @param expression
53  	 *            indicates the property of <code>target</code> that is to be
54  	 *            analyzed
55  	 * @return the least restrictive type that may be assigned to the property
56  	 *         identified by <code>expression</code>
57  	 * @throws LanguageException
58  	 *             if <code>target</code> is <code>null</code> or <br>
59  	 *             an error occurrs while evaluating an otherwise valid
60  	 *             expression
61  	 * @throws InvalidExpressionException
62  	 *             if <code>expression</code> not a valid expression
63  	 */
64  	public Class getType(Object target, String expression)
65  		throws LanguageException;
66  
67  	/**
68  	 * Indicates whether the given expression refers to a direct property of a
69  	 * target object.
70  	 * 
71  	 * @param expression
72  	 *            the expression to evaluate
73  	 * @return <code>true</code>, if the expression references a direct
74  	 *         property of the target object or <br>
75  	 *         <code>false</code>, otherwise
76  	 * @throws LanguageException
77  	 *             an error occurrs while evaluating an otherwise valid
78  	 *             expression
79  	 * @throws InvalidExpressionException
80  	 *             if <code>expression</code> not a valid expression
81  	 */
82  	public boolean isProperty(String expression) throws LanguageException;
83  
84  	/**
85  	 * Retrieve the property indicated by <code>expression</code> from
86  	 * <code>target</code>.
87  	 * 
88  	 * @param target
89  	 *            the object from which information will be retrieved
90  	 * @param expression
91  	 *            an expression specifying which information to retrieve
92  	 * @return the information indicated by <code>expression</code> from
93  	 *         <code>target</code>
94  	 * @throws LanguageException
95  	 *             if <code>target</code> is <code>null</code> or <br>
96  	 *             an error occurrs while evaluating an otherwise valid
97  	 *             expression
98  	 * @throws InvalidExpressionException
99  	 *             if <code>expression</code> not a valid expression
100 	 */
101 	public Object get(Object target, String expression)
102 		throws LanguageException;
103 
104 	/**
105 	 * Sets the property indicated by <code>expression</code> on
106 	 * <code>target</code>.
107 	 * 
108 	 * @param target
109 	 *            the object that will be modified
110 	 * @param expression
111 	 *            an expression specifying which information will be modified
112 	 * @param value
113 	 *            the information to be changed
114 	 * @throws LanguageException
115 	 *             if <code>target</code> is <code>null</code> or <br>
116 	 *             an error occurrs while evaluating an otherwise valid
117 	 *             expression
118 	 * @throws InvalidExpressionException
119 	 *             if <code>expression</code> not a valid expression
120 	 */
121 	public void set(Object target, String expression, Object value)
122 		throws LanguageException;
123 
124 }