1   /*
2    * Copyright 2003 - 2013 The eFaps Team
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of 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,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   *
16   * Revision:        $Rev$
17   * Last Changed:    $Date$
18   * Last Changed By: $Author$
19   */
20  
21  package org.efaps.admin.datamodel;
22  
23  import java.io.Serializable;
24  import java.sql.SQLException;
25  import java.util.List;
26  
27  import org.efaps.db.Instance;
28  import org.efaps.db.wrapper.SQLInsert;
29  import org.efaps.db.wrapper.SQLUpdate;
30  import org.efaps.util.EFapsException;
31  
32  /**
33   * Classes which implements this interface are used to handle the mapping of
34   * attributes between eFaps and the database.
35   *
36   * @author The eFaps Team
37   * @version $Id$
38   */
39  public interface IAttributeType
40      extends Serializable
41  {
42      /**
43       * The method prepares the statement for update the object in the database.
44       *
45       * @param _update       SQL update statement
46       * @param _attribute    attribute which is updated
47       * @param _values       new object value to set; values are localized and
48       *                      are coming from the user interface
49       * @throws SQLException if preparation for the update failed
50       */
51      void prepareUpdate(final SQLUpdate _update,
52                         final Attribute _attribute,
53                         final Object... _values)
54          throws SQLException;
55  
56      /**
57       * The method prepares the statement for insert the object in the database.
58       *
59       * @param _insert       SQL insert statement
60       * @param _attribute    attribute which is inserted
61       * @param _values       new object value to set; values are localized and
62       *                      are coming from the user interface
63       * @throws SQLException if preparation for the insert failed
64       */
65      void prepareInsert(final SQLInsert _insert,
66                         final Attribute _attribute,
67                         final Object... _values)
68          throws SQLException;
69  
70      /**
71       * Method is used to read the values, retrieved from an JDBC result set and
72       * put into the given parameter <code>_objectList</code>. This is
73       * necessary, because only in the different instances of this interface
74       * it can be determined what to do with the objects from the database. e.g.
75       * in case of DateTimeType the values will be cased into a DateTime Object
76       * and in case of a PersonLinkType a Person or Role instance will be
77       * returned. This method is called from the {@link org.efaps.db.PrintQuery}.
78       *
79       * @param _attribute    related attribute which is read
80       * @param _objectList   list of objects from the eFaps Database
81       * @return Object as needed for eFaps
82       * @throws EFapsException on error
83       */
84      Object readValue(final Attribute _attribute,
85                       final List<Object> _objectList)
86          throws EFapsException;
87  
88      /**
89       * Method is called when the value of the related attribute is used
90       * as argument in a where clause for a query. This is necessary because
91       * for the different attribute types the string representation must be
92       * generated different, e.g  a datetime must be converted in an iso string
93       * etc.
94       *
95       * @param _value    value to be returned as a string
96       * @return  string representation of the value
97       * @throws EFapsException on error
98       */
99      String toString4Where(final Object _value)
100         throws EFapsException;
101 
102     /**
103      * Method is executed on addition of an Attribute/Value pair for an Update
104      * on an Instance to validate if the value is permitted. Must throw the
105      * exception if not valid.
106      *
107      * @param _attribute    the Attribute that will be updated with the _value
108      * @param _instance     Instance that will be updated
109      * @param _value        value that will be used for the update
110      * @throws EFapsException if not valid
111      */
112     void valiate4Update(final Attribute _attribute,
113                         final Instance _instance,
114                         final Object[] _value)
115         throws EFapsException;
116 
117     /**
118      * Method is executed on addition of an Attribute/Value pair for an Insert
119      * on an Instance to validate if the value is permitted. Must throw the
120      * exception if not valid.<br/>
121      * The given instance is expected to be invalid, but must contain the type.
122      *
123      * @param _attribute    the Attribute that will be updated with the _value
124      * @param _instance     Instance that will be updated
125      * @param _value        value that will be used for the update
126      * @throws EFapsException if not valid
127      */
128     void valiate4Insert(final Attribute _attribute,
129                         final Instance _instance,
130                         final Object[] _value)
131         throws EFapsException;
132 }