View Javadoc

1   package org.apache.torque.util.functions;
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  /***
23   * Define the basic methods that classes that support SQL Functions
24   * need to implement for Classes that use them.  This is intended to 
25   * allow code to be written before functions are fully integrated 
26   * with the DBAdaptors.  As well as allowing for functions to
27   * expand as needed. 
28   * 
29   * @see FunctionFactory
30   * 
31   * @author <a href="mailto:greg.monroe@dukece.com">Greg Monroe</a>
32   * @version $Id
33   */
34  public interface SQLFunction
35  {
36      /***
37       * This should return the SQL string that can be used
38       * when constructing the query.  E.g. "AVG( table.column )" or
39       * CONCAT(table.column, " foobar");
40       *  
41       * @return The SQL String.
42       */
43      public abstract String toSQL();
44      
45      /***
46       * Return a string representation of the function parameters
47       * at index i.  Should be null if parameter does not exist.
48       * 
49       * @param i The 0 based parameter to get.
50       * @return A String representation of the parameter.  Null if one does not
51       *         exist.
52       */
53      public abstract String getArgument( int i );
54      
55      /***
56       * Return all the parameters as an object array. This allow for 
57       * processing of the parameters in their original format rather
58       * than just in String format.  E.g. a parameter might be specified
59       * as a Date object, or a Column object.
60       * 
61       * @return Should return a valid Object array and not null.  E.g. 
62       *  implementors should return new Object[0] if there are no parameters.
63       */
64      public abstract Object[] getArguments();
65      
66      /***
67       * Sets the function specific arguments.  Note, this should generally 
68       * only be called by FunctionFactory.
69       * 
70       * @param args The function specific arguments.
71       */
72      public abstract void setArguments( Object[] args );
73      
74      /***
75       * Get the name of the Torque Database associated with this function.
76       * 
77       * @return The DB name.  Should not be null (use default DB in this case).
78       * @exception IllegalStateException If Torque has not been initialized and
79       *   the default DB name can not be determined.
80       */
81      public abstract String getDBName() throws IllegalStateException;
82      
83      /***
84       * Sets the Torque DB name this function is being used with.
85       * 
86       * @param dbName The DB name, if null, the getDBName will return default DB
87       *               name (if it can be determined).
88       */
89      public abstract void setDBName( String dbName );
90  
91  }