View Javadoc

1   /*
2    * Copyright 2004-2005, 2007 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  import java.util.Locale;
19  
20  import net.sf.morph.transform.TransformationException;
21  
22  /**
23   * <p>
24   * Extends the capabilities of a Language by adding the capabilities of a
25   * Converter.
26   * </p>
27   * 
28   * <p>
29   * <em>You should not directly implement this interface, because additional
30   * methods may be introduced in later versions of Morph.  Instead, implement the
31   * Language interface and use the LanguageDecorator to expose this interface.</em>
32   * </p>
33   * 
34   * 
35   * @author Matt Sgarlata
36   * @since Nov 27, 2004
37   */
38  public interface DecoratedLanguage extends Language {
39  	
40  	/**
41  	 * Retrieve the information indicated by <code>expression</code> from
42  	 * <code>target</code> as the type indicated by
43  	 * <code>destinationClass</code>.
44  	 * 
45  	 * @param target
46  	 *            the object from which information will be retrieved
47  	 * @param expression
48  	 *            an expression specifying which information to retrieve
49  	 * @param destinationClass
50  	 *            indicates the type that should be returned by this method
51  	 * @return the information indicated by <code>expression</code> from
52  	 *         <code>target</code>
53  	 * @throws TransformationException
54  	 *             if an error occurs while converting the requested information
55  	 *             to the type indicated by <code>destinationClass</code>
56  	 * @throws LanguageException
57  	 *             if <code>target</code> is <code>null</code> or <br>
58  	 *             an error occurrs while evaluating an otherwise valid
59  	 *             expression
60  	 * @throws InvalidExpressionException
61  	 *             if <code>expression</code> is empty or not a valid
62  	 *             expression
63  	 */
64  	public Object get(Object target, String expression, Class destinationClass)
65  		throws LanguageException, TransformationException;
66  
67  	/**
68  	 * Retrieve the information indicated by <code>expression</code> from
69  	 * <code>target</code> as the type indicated by
70  	 * <code>destinationClass</code>.
71  	 * 
72  	 * @param target
73  	 *            the object from which information will be retrieved
74  	 * @param expression
75  	 *            an expression specifying which information to retrieve
76  	 * @param destinationClass
77  	 *            indicates the type that should be returned by this method
78  	 * @param locale
79  	 *            indicates the locale in which the conversion to type
80  	 *            <code>destinationClass</code> should be performed, if
81  	 *            applicable
82  	 * @return the information indicated by <code>expression</code> from
83  	 *         <code>target</code>
84  	 * @throws TransformationException
85  	 *             if an error occurs while converting the requested information
86  	 *             to the type indicated by <code>destinationClass</code>
87  	 * @throws LanguageException
88  	 *             if <code>target</code> is <code>null</code> or <br>
89  	 *             an error occurrs while evaluating an otherwise valid
90  	 *             expression
91  	 * @throws InvalidExpressionException
92  	 *             if <code>expression</code> is empty or not a valid
93  	 *             expression
94  	 */
95  	public Object get(Object target, String expression, Class destinationClass,
96  		Locale locale) throws LanguageException, TransformationException;
97  
98  	/**
99  	 * Retrieve the information indicated by <code>expression</code> from
100 	 * <code>target</code> as the type indicated by
101 	 * <code>destinationClass</code>.
102 	 * 
103 	 * @param target
104 	 *            the object from which information will be retrieved
105 	 * @param expression
106 	 *            an expression specifying which information to retrieve
107 	 * @param locale
108 	 *            indicates the locale in which the conversion to type
109 	 *            <code>destinationClass</code> should be performed, if
110 	 *            applicable
111 	 * @param destinationClass
112 	 *            indicates the type that should be returned by this method
113 	 * @return the information indicated by <code>expression</code> from
114 	 *         <code>target</code>
115 	 * @throws TransformationException
116 	 *             if an error occurs while converting the requested information
117 	 *             to the type indicated by <code>destinationClass</code>
118 	 * @throws LanguageException
119 	 *             if <code>target</code> is <code>null</code> or <br>
120 	 *             an error occurrs while evaluating an otherwise valid
121 	 *             expression
122 	 * @throws InvalidExpressionException
123 	 *             if <code>expression</code> is empty or not a valid
124 	 *             expression
125 	 * @deprecated why would we need both signatures (Object, String, Locale, Class) and (Object, String, Class, Locale)?
126 	 */
127 	public Object get(Object target, String expression, Locale locale,
128 		Class destinationClass) throws LanguageException, TransformationException;
129 
130 	/**
131 	 * Sets the information indicated by <code>expression</code> on
132 	 * <code>target</code>.<code>value</code> will be automatically
133 	 * converted to a type appropriate for the given <code>expression</code>.
134 	 * 
135 	 * @param target
136 	 *            the object that will be modified
137 	 * @param expression
138 	 *            an expression specifying which information will be modified
139 	 * @param value
140 	 *            the information to be changed
141 	 * @throws TransformationException
142 	 *             if an error occurs while converting <code>value</code> to
143 	 *             the appropriate type
144 	 * @throws LanguageException
145 	 *             if <code>target</code> is <code>null</code> or <br>
146 	 *             an error occurrs while evaluating an otherwise valid
147 	 *             expression
148 	 * @throws InvalidExpressionException
149 	 *             if <code>expression</code> is empty or not a valid
150 	 *             expression
151 	 */
152 	public void set(Object target, String expression, Object value)
153 		throws LanguageException, TransformationException;
154 
155 	/**
156 	 * Sets the information indicated by <code>expression</code> on
157 	 * <code>target</code>.<code>value</code> will be automatically
158 	 * converted to a type appropriate for the given <code>expression</code>.
159 	 * 
160 	 * @param target
161 	 *            the object that will be modified
162 	 * @param expression
163 	 *            an expression specifying which information will be modified
164 	 * @param value
165 	 *            the information to be changed
166 	 * @param locale
167 	 *            indicates the locale in which the conversion to type
168 	 *            <code>destinationClass</code> should be performed, if
169 	 *            applicable
170 	 * @throws TransformationException
171 	 *             if an error occurs while converting <code>value</code> to
172 	 *             the appropriate type
173 	 * @throws LanguageException
174 	 *             if <code>target</code> is <code>null</code> or <br>
175 	 *             an error occurrs while evaluating an otherwise valid
176 	 *             expression
177 	 * @throws InvalidExpressionException
178 	 *             if <code>expression</code> is empty or not a valid
179 	 *             expression
180 	 */
181 	public void set(Object target, String expression, Object value,
182 		Locale locale) throws LanguageException, TransformationException;
183 
184 }