| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| package org.apache.openjpa.jdbc.sql; |
| |
| import java.io.InputStream; |
| import java.io.Reader; |
| import java.math.BigDecimal; |
| import java.math.BigInteger; |
| import java.sql.Array; |
| import java.sql.Blob; |
| import java.sql.Clob; |
| import java.sql.Ref; |
| import java.sql.SQLException; |
| import java.sql.Time; |
| import java.sql.Timestamp; |
| import java.util.Calendar; |
| import java.util.Date; |
| import java.util.Locale; |
| import java.util.Map; |
| |
| import org.apache.openjpa.jdbc.kernel.JDBCFetchConfiguration; |
| import org.apache.openjpa.jdbc.kernel.JDBCStore; |
| import org.apache.openjpa.jdbc.meta.ClassMapping; |
| import org.apache.openjpa.jdbc.meta.FieldMapping; |
| import org.apache.openjpa.jdbc.meta.JavaSQLTypes; |
| import org.apache.openjpa.jdbc.schema.Column; |
| import org.apache.openjpa.lib.util.Closeable; |
| |
| /** |
| * A result from the execution of a query or stored procedure. This |
| * interface is aligned closely with the {@link java.sql.ResultSet}, so you |
| * can expect like-named methods to have similar semantics. However, the |
| * interface has been distilled and simplified, so a result object could |
| * easily mask information sources other than a result set. |
| * For more flexible customization of data loading, see the |
| * {@link org.apache.openjpa.kernel.PCResultObjectProvider}. |
| * |
| * @author Abe White |
| * @see ResultSetResult |
| */ |
| public interface Result |
| extends Closeable { |
| |
| /** |
| * The eager result for the given key, or null if none. |
| */ |
| public Object getEager(FieldMapping key); |
| |
| /** |
| * The eager result for the given key, or null if none. |
| */ |
| public void putEager(FieldMapping key, Object res); |
| |
| /** |
| * Return a new joins instance to use for traversing to related data. |
| */ |
| public Joins newJoins(); |
| |
| /** |
| * Free the resources used by this result; do <strong>not</strong> |
| * close the SQL connection. |
| */ |
| public void close(); |
| |
| /** |
| * If true, then any results loaded from this Result |
| * will be locked in the database. |
| */ |
| public boolean isLocking(); |
| |
| /** |
| * Return true if the result supports random access. |
| */ |
| public boolean supportsRandomAccess() |
| throws SQLException; |
| |
| /** |
| * Move to the given <strong>0-based</strong> row in the result, or |
| * return false if the row does not exist. This method will only be |
| * called if the result supports random access. |
| */ |
| public boolean absolute(int row) |
| throws SQLException; |
| |
| /** |
| * Advance to the next row, or return false if there are no more rows |
| * in the result. |
| */ |
| public boolean next() |
| throws SQLException; |
| |
| /** |
| * Push back the last result. In other words, just ignore the next call |
| * to {@link #next}. After the first time this method is called, |
| * additional calls before a call to {@link #next} or {@link #absolute} |
| * should have no further affect. |
| */ |
| public void pushBack() |
| throws SQLException; |
| |
| /** |
| * Return the number of rows in this result. |
| */ |
| public int size() |
| throws SQLException; |
| |
| /** |
| * Return true if the given id or column is available in the result. |
| */ |
| public boolean contains(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return true if all the given ids or columns are available in the result. |
| */ |
| public boolean containsAll(Object[] objs) |
| throws SQLException; |
| |
| /** |
| * Return true if the given column is available in the result. |
| */ |
| public boolean contains(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return true if all the given columns are available in the result. |
| */ |
| public boolean containsAll(Column[] cols, Joins joins) |
| throws SQLException; |
| |
| /** |
| * If this is the result of a UNION used to select a hierarchy of |
| * mappings, the base mapping represented by the current row. |
| * This information is not available after getting any eager results |
| * from the row. |
| */ |
| public ClassMapping getBaseMapping(); |
| |
| /** |
| * If this is the result of a UNION used to select a hierarchy of |
| * mappings, the base mapping represented by the current row. |
| * This information is not available after getting any eager results |
| * from the row. |
| */ |
| public void setBaseMapping(ClassMapping mapping); |
| |
| /** |
| * If this is the result used to select a toMany relationship, |
| * the mappedByFieldMapping is field mapping representing |
| * the inverse relationship. This is to avoid unneeded |
| * extra sql to retrieve the eager inverse field. |
| */ |
| public FieldMapping getMappedByFieldMapping(); |
| |
| /** |
| * If this is the result used to select a toMany relationship, |
| * the mappedByFieldMapping is field mapping representing |
| * the inverse relationship. This is to avoid unneeded |
| * extra sql to retrieve the eager inverse field. |
| */ |
| public void setMappedByFieldMapping(FieldMapping fieldMapping); |
| |
| /** |
| * If this is the result used to select a toMany relationship, |
| * the mappedByValue is value of the owner of the toMany relationship. |
| * This is to avoid unneeded extra sql to retrieve the eager inverse field. |
| */ |
| public Object getMappedByValue(); |
| |
| /** |
| * If this is the result used to select a toMany relationship, |
| * the mappedByValue is value of the owner of the toMany relationship. |
| * This is to avoid unneeded extra sql to retrieve the eager inverse field. |
| */ |
| public void setMappedByValue(Object mappedByValue); |
| |
| /** |
| * The index of the select within the UNION that the current row |
| * corresponds to, or 0. |
| */ |
| public int indexOf(); |
| |
| /** |
| * Load a pc object using the given store manager. |
| */ |
| public Object load(ClassMapping mapping, JDBCStore store, |
| JDBCFetchConfiguration fetch) |
| throws SQLException; |
| |
| /** |
| * Load a pc object using the given store manager. |
| */ |
| public Object load(ClassMapping mapping, JDBCStore store, |
| JDBCFetchConfiguration fetch, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public Array getArray(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public InputStream getAsciiStream(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id. |
| */ |
| public BigDecimal getBigDecimal(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id. |
| */ |
| public BigInteger getBigInteger(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public InputStream getBinaryStream(Object obj) |
| throws SQLException; |
| |
| public InputStream getLOBStream(JDBCStore store, Object obj) |
| throws SQLException; |
| /** |
| * Return the value stored in the given column or id; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public Blob getBlob(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id. |
| */ |
| public boolean getBoolean(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id. |
| */ |
| public byte getByte(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public byte[] getBytes(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id. |
| */ |
| public Calendar getCalendar(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id. |
| */ |
| public char getChar(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public Reader getCharacterStream(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public Clob getClob(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id. |
| */ |
| public Date getDate(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public java.sql.Date getDate(Object obj, Calendar cal) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id. |
| */ |
| public double getDouble(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id. |
| */ |
| public float getFloat(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id. |
| */ |
| public int getInt(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id. |
| */ |
| public Locale getLocale(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id. |
| */ |
| public long getLong(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id. |
| */ |
| public Number getNumber(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id. |
| * |
| * @param obj the column or id whose data to fetch |
| * @param metaType the type code from {@link org.apache.openjpa.meta.JavaTypes} or |
| * {@link JavaSQLTypes} for the type of the data; if |
| * <code>obj</code> is a column, you may specify -1 |
| * to use the column's recorded java type |
| * @param arg some JDBC data access methods use an argument, such |
| * as a {@link Calendar} or {@link Map} |
| */ |
| public Object getObject(Object obj, int metaType, Object arg) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public Object getSQLObject(Object obj, Map map) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public Ref getRef(Object obj, Map map) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id. |
| */ |
| public short getShort(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id. |
| */ |
| public String getString(Object obj) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public Time getTime(Object obj, Calendar cal) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column or id; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public Timestamp getTimestamp(Object obj, Calendar cal) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public Array getArray(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public InputStream getAsciiStream(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column. |
| */ |
| public BigDecimal getBigDecimal(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column. |
| */ |
| public BigInteger getBigInteger(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public InputStream getBinaryStream(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public Blob getBlob(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column. |
| */ |
| public boolean getBoolean(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column. |
| */ |
| public byte getByte(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public byte[] getBytes(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column. |
| */ |
| public Calendar getCalendar(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column. |
| */ |
| public char getChar(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public Reader getCharacterStream(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public Clob getClob(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column. |
| */ |
| public Date getDate(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public java.sql.Date getDate(Column col, Calendar cal, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column. |
| */ |
| public double getDouble(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column. |
| */ |
| public float getFloat(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column. |
| */ |
| public int getInt(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column. |
| */ |
| public Locale getLocale(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column. |
| */ |
| public long getLong(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column. |
| */ |
| public Number getNumber(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column. |
| * |
| * @param col the column whose data to fetch |
| * @param arg some JDBC data access methods use an argument, such |
| * as a {@link Calendar} or {@link Map} |
| */ |
| public Object getObject(Column col, Object arg, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public Object getSQLObject(Column col, Map map, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public Ref getRef(Column col, Map map, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column. |
| */ |
| public short getShort(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column. |
| */ |
| public String getString(Column col, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public Time getTime(Column col, Calendar cal, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return the value stored in the given column; may not be supported |
| * by results that are not backed by a SQL result set. |
| */ |
| public Timestamp getTimestamp(Column col, Calendar cal, Joins joins) |
| throws SQLException; |
| |
| /** |
| * Return true if the last value fetched was null. |
| */ |
| public boolean wasNull() |
| throws SQLException; |
| |
| /** |
| * Informs this receiver about the application element for which a |
| * subsequent data request will be made. |
| */ |
| public void startDataRequest(Object mapping); |
| |
| /** |
| * Ends a data request. Must be called in conjunction with |
| * {@link #startDataRequest}. The calls can be nested as follws<br /> |
| * <pre> startDataRequest (relation); startDataRequest (relationsField); |
| * getObject("COLUMN_Y"); endDataRequest (); endDataRequest (); |
| * </pre> |
| */ |
| public void endDataRequest(); |
| } |