001/**
002 *
003 * Copyright (c) 2014, the Railo Company Ltd. All rights reserved.
004 *
005 * This library is free software; you can redistribute it and/or
006 * modify it under the terms of the GNU Lesser General Public
007 * License as published by the Free Software Foundation; either 
008 * version 2.1 of the License, or (at your option) any later version.
009 * 
010 * This library is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
013 * Lesser General Public License for more details.
014 * 
015 * You should have received a copy of the GNU Lesser General Public 
016 * License along with this library.  If not, see <http://www.gnu.org/licenses/>.
017 * 
018 **/
019package lucee.runtime.util;
020
021import lucee.runtime.PageContext;
022import lucee.runtime.exp.PageException;
023import lucee.runtime.type.Collection;
024import lucee.runtime.type.Struct;
025
026/**
027 * Variable Util
028 */
029public interface VariableUtil {
030
031    /**
032     * return a property from the given Object, when property doesn't exists return null
033     * @param pc
034     * @param coll Collection to check
035     * @param key to get from Collection
036     * @return value or null
037     */
038    public abstract Object getCollection(PageContext pc, Object coll,
039            String key, Object defaultValue);
040
041    /**
042     * return a property from the given Object, when property doesn't exists return null
043     * @param pc
044     * @param coll Collection to check
045     * @param key to get from Collection
046     * @return value or null
047     * @deprecated use instead <code>get(PageContext pc, Object coll, Collection.Key key, Object defaultValue);</code>
048     */
049    public abstract Object get(PageContext pc, Object coll, String key, Object defaultValue);
050    
051    /**
052     * return a property from the given Object, when property doesn't exists return null
053     * @param pc
054     * @param coll Collection to check
055     * @param key to get from Collection
056     * @return value or null
057     */
058    public abstract Object get(PageContext pc, Object coll, Collection.Key key, Object defaultValue);
059
060    /**
061     * return a property from the given Object, when property doesn't exists return null
062     * @param pc
063     * @param coll Collection to check
064     * @param key to get from Collection
065     * @return value or null
066     */
067    public abstract Object getLight(PageContext pc, Object coll, String key, Object defaultValue);
068
069    /**
070     * return a property from the given Object, when coll is a query return a Column,when property doesn't exists throw exception
071     * @param pc
072     * @param coll Collection to check
073     * @param key to get from Collection
074     * @return value value to get
075     * @throws PageException
076     */
077    public abstract Object getCollection(PageContext pc, Object coll, String key)
078            throws PageException;
079
080    /**
081     * return a property from the given Object, when property doesn't exists throw exception
082     * @param pc
083     * @param coll Collection to check
084     * @param key to get from Collection
085     * @return value value to get
086     * @throws PageException
087     */
088    public abstract Object get(PageContext pc, Object coll, String key)
089            throws PageException;
090
091    /**
092     * sets a value to the Object
093     * @param pc
094     * @param coll Collection to check
095     * @param key to get from Collection
096     * @param value Value to set
097     * @return value setted
098     * @throws PageException
099     */
100    public abstract Object set(PageContext pc, Object coll, String key,
101            Object value) throws PageException;
102    
103    // FUTURE add and set above to depr public Object set(PageContext pc, Object coll, Collection.Key key,Object value) throws PageException {
104
105    /**
106     * sets a value to the Object
107     * @param pc
108     * @param coll Collection to check
109     * @param key to get from Collection
110     * @param value Value to set
111     * @return value setted or null if can't set
112     * @deprecated use instead <code>setEL(PageContext pc, Object coll, Collection.Key key,Object value);</code>
113     */
114    public abstract Object setEL(PageContext pc, Object coll, String key,Object value);
115    
116    /**
117     * sets a value to the Object
118     * @param pc
119     * @param coll Collection to check
120     * @param key to get from Collection
121     * @param value Value to set
122     * @return value setted or null if can't set
123     */
124    public abstract Object setEL(PageContext pc, Object coll, Collection.Key key,Object value);
125
126    /**
127     * remove value from Collection
128     * @param coll
129     * @param key
130     * @return has cleared or not
131     */
132    public abstract Object removeEL(Object coll, String key);
133
134    /**
135     * clear value from Collection
136     * @param coll
137     * @param key
138     * @return has cleared or not
139     * @throws PageException
140     */
141    public abstract Object remove(Object coll, String key) throws PageException;
142
143    /**
144     * call a Function (UDF, Method) with or witout named values
145     * @param pc 
146     * @param coll Collection of the UDF Function
147     * @param key name of the function
148     * @param args arguments to call the function
149     * @return return value of the function
150     * @throws PageException
151     */
152    public abstract Object callFunction(PageContext pc, Object coll,
153            String key, Object[] args) throws PageException;
154
155    /**
156     * call a Function (UDF, Method) without Named Values
157     * @param pc 
158     * @param coll Collection of the UDF Function
159     * @param key name of the function
160     * @param args arguments to call the function
161     * @return return value of the function
162     * @throws PageException
163     * @deprecated use instead <code>callFunctionWithoutNamedValues(PageContext pc, Object coll, Collection.Key key, Object[] args)</code> 
164     */
165    public abstract Object callFunctionWithoutNamedValues(PageContext pc,
166            Object coll, String key, Object[] args) throws PageException;
167    
168    /**
169     * call a Function (UDF, Method) without Named Values
170     * @param pc 
171     * @param coll Collection of the UDF Function
172     * @param key name of the function
173     * @param args arguments to call the function
174     * @return return value of the function
175     * @throws PageException
176     */
177    public Object callFunctionWithoutNamedValues(PageContext pc, 
178                Object coll, Collection.Key key, Object[] args) throws PageException;
179
180    /**
181     * call a Function (UDF, Method) with Named Values
182     * @param pc 
183     * @param coll Collection of the UDF Function
184     * @param key name of the function
185     * @param args arguments to call the function
186     * @return return value of the function
187     * @throws PageException
188     * @deprecated use instead <code>callFunctionWithNamedValues(PageContext pc, Object coll, Collection.Key key, Object[] args)</code>
189     */
190    public abstract Object callFunctionWithNamedValues(PageContext pc,
191            Object coll, String key, Object[] args) throws PageException;
192    
193    
194
195    /**
196     * call a Function (UDF, Method) with Named Values
197     * @param pc 
198     * @param coll Collection of the UDF Function
199     * @param key name of the function
200     * @param args arguments to call the function
201     * @return return value of the function
202     * @throws PageException
203     */
204    public Object callFunctionWithNamedValues(PageContext pc, 
205                        Object coll, Collection.Key key, Object[] args) throws PageException;
206    
207    public Object callFunctionWithNamedValues(PageContext pc, 
208                Object coll, Collection.Key key, Struct args) throws PageException;
209
210}