001: /*
002: * GeoTools - OpenSource mapping toolkit
003: * http://geotools.org
004: * (C) 2004-2006, GeoTools Project Managment Committee (PMC)
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Lesser General Public
008: * License as published by the Free Software Foundation;
009: * version 2.1 of the License.
010: *
011: * This library is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * Lesser General Public License for more details.
015: */
016: package org.geotools.data.jdbc.fidmapper;
017:
018: import org.geotools.feature.Feature;
019: import java.io.IOException;
020: import java.io.Serializable;
021: import java.sql.Connection;
022: import java.sql.Statement;
023:
024: /**
025: * <p>
026: * The FIDMapper interface manages the mapping of feature id to the identifiers
027: * provided in a database.
028: * </p>
029: *
030: * <p>
031: * Basically a FIDMapper must:
032: *
033: * <ul>
034: * <li>
035: * generate the FID (a String) given the set of values that compose the primary
036: * key in the database
037: * </li>
038: * <li>
039: * turn the FID into the primary key values, or generate them should the FID be
040: * null
041: * </li>
042: * <li>
043: * provide notice wheter the identifier values should be included as attributes
044: * in the feature or not (this is necessary when reverse engineering the
045: * feature type from the database metadata)
046: * </li>
047: * <li>
048: * describe the primary key columns, if any (this is necessary when creating
049: * the table that describes the feature type in a table)
050: * </li>
051: * </ul>
052: * </p>
053: *
054: * <p>
055: * Concrete instances of this class should provide support for the most common
056: * primary key mapping and generation strategis, such as pk with business
057: * meaning, serials, sequences, and so on
058: * </p>
059: *
060: * <p>
061: * Classes that implement this interface should ovveride equals to provide a
062: * state based comparison.
063: * </p>
064: *
065: * @author Dani Daniele Franzoni
066: * @author aaime Andrea Aime
067: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/library/jdbc/src/main/java/org/geotools/data/jdbc/fidmapper/FIDMapper.java $
068: */
069: public interface FIDMapper extends Serializable {
070: /**
071: * This method will be called by JDBCDataStore when creating new tables to
072: * give the FID mapper an opportunity to initialize needed data
073: * structures, such as support tables, sequences, and so on.
074: */
075: public void initSupportStructures();
076:
077: /**
078: * Returns the FID given the values of the prymary key attributes
079: *
080: * @param attributes DOCUMENT ME!
081: *
082: */
083: public String getID(Object[] attributes);
084:
085: /**
086: * Creates the value for the PK attributes given the feature. If the FID is
087: * null, will throw an IOException if not possible. If null is returned,
088: * no primary key value needs to be specified, which is what we want for
089: * auto-increment fields.
090: *
091: * @param FID The feature ID is going to be parsed
092: *
093: *
094: * @throws IOException
095: */
096: public Object[] getPKAttributes(String FID) throws IOException;
097:
098: /**
099: * Creates a new ID for a feature. <br>
100: * This is done either by querying the database (for auto-increment like
101: * types, for example sequences) or by inspecting the Feature (for
102: * example, for primary keys with business meaning that whose attributes
103: * are included in the Feature ones).
104: *
105: * @param conn - the database connection
106: * @param feature - the feature that needs the new FID
107: * @param statement - the statement used to insert the feature into the
108: * database
109: *
110: *
111: * @throws IOException
112: */
113: public String createID(Connection conn, Feature feature,
114: Statement statement) throws IOException;
115:
116: /**
117: * If true the primary key columns will be returned as attributes. This is
118: * fundamental for primary key with businnes meaning.
119: *
120: */
121: public boolean returnFIDColumnsAsAttributes();
122:
123: /**
124: * Returns the number of columns in the primary keys handled by this mapper
125: *
126: */
127: public int getColumnCount();
128:
129: /**
130: * Returns the name of the specified column in the primary key
131: *
132: * @param colIndex
133: *
134: */
135: public String getColumnName(int colIndex);
136:
137: /**
138: * Returns the column type by using a constant available in the
139: * java.sql.Types interface
140: *
141: * @param colIndex
142: *
143: */
144: public int getColumnType(int colIndex);
145:
146: /**
147: * Returns the size of a primary key column as it would be provided by the
148: * database metadata. Some fields requires a size specification, such as
149: * VARCHAR or NUMBER, whilst other don't have or don't need it (for
150: * example, an INTEGER or a TEXT field).
151: *
152: * @param colIndex
153: *
154: */
155: public int getColumnSize(int colIndex);
156:
157: /**
158: * Provides the number of decimal digits for this column. This is relevant
159: * in particular when the column is a scaled integer such as a NUMBER
160: * column
161: *
162: * @param colIndex
163: *
164: */
165: public int getColumnDecimalDigits(int colIndex);
166:
167: /**
168: * Returns true if the column is of serial type, that is, its value is
169: * automatically generated by the database if the user does not provide
170: * one
171: *
172: * @param colIndex
173: *
174: */
175: public boolean isAutoIncrement(int colIndex);
176:
177: /**
178: * Returns true if at least one column is of auto-increment type
179: *
180: */
181: public boolean hasAutoIncrementColumns();
182:
183: /**
184: * Returns true it the FID generated by this mapper are volatile, that is,
185: * if asking twice for the same Feature will not provide the same FID.
186: *
187: * <p>
188: * This is usually true for mappers that try to generate a FID for tables
189: * without primary keys.
190: * </p>
191: *
192: * <p>
193: * When this method returns true, it's up to the datastore to decide what
194: * to do, but a sane policy may be to prevent Feature writing
195: * </p>
196: *
197: */
198: public boolean isVolatile();
199: }
|