001: package org.mandarax.jdbc.server;
002:
003: /*
004: * Copyright (C) 1999-2004 <a href="mailto:mandarax@jbdietrich.com">Jens Dietrich</a>
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; either
009: * version 2 of the License, or (at your option) any later version.
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: * You should have received a copy of the GNU Lesser General Public
017: * License along with this library; if not, write to the Free Software
018: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
019: */
020:
021: import org.mandarax.jdbc.rpc.*;
022: import org.mandarax.jdbc.client.*;
023: import org.mandarax.util.logging.LogCategories;
024:
025: import java.sql.*;
026: import java.util.*;
027:
028: /**
029: * Facade for a knowledge base jdbc server. Tis class is abstract.
030: * A typical implementation could use servlets (in particular sessions).
031: * @author <A HREF="mailto:mandarax@jbdietrich.com">Jens Dietrich</A>
032: * @version 3.3.2 <29 December 2004>
033: * @since 3.0
034: */
035:
036: public abstract class ServerFacade implements LogCategories {
037:
038: // some constants that can be used as kindOfObject
039: public static final String CONNECTION = "con";
040: public static final String RESULT_SET = "rs";
041: public static final String STATEMENT = "stmnt";
042: public static final String PREPARED_STATEMENT = "prepstmnt";
043:
044: /**
045: * Convert a db url to a local url.
046: * @param a db url
047: * @return a local db url (to be used by the local driver)
048: */
049: public String convertToLocalUrl(String url) {
050: return url;
051: }
052:
053: /**
054: * Close an object (connection, statement or result set).
055: * @param id the id of the object to be closed
056: */
057: public abstract void Close(String id) throws Exception;
058:
059: /**
060: * Create a statement.
061: * @param connectionId a connection id
062: * @return a statement id.
063: */
064: public abstract String Connection_createStatement(
065: String connectionId) throws Exception;
066:
067: /**
068: * Prepare a statement.
069: * @param connectionId a connection id
070: * @param sql a sql statement (with ? as parameter placeholders)
071: * @return a statement id.
072: */
073: public abstract String Connection_prepareStatement(
074: String connectionId, String sql) throws Exception;
075:
076: /**
077: * Get the column info. Only the result set id is returned,
078: * rows are returned using next(), and the result set is assembled
079: * on the client side.
080: * @param connectionId a connection id
081: * @param sql an sql SELECT command
082: * @param catalog
083: * @param schemaPattern
084: * @param tableNamePattern
085: * @param columnNamePattern
086: * @return a result set id.
087: */
088: public abstract String Connection_getMetaData_getColumns(
089: String connectionId, String catalog, String schemaPattern,
090: String tableNamePattern, String columnNamePattern)
091: throws Exception;
092:
093: /**
094: * Retrieves a description of the tables available in the given catalog.
095: * Only the result set id is returned, rows are returned using next(), and
096: * the result set is assembled on the client side.
097: * @param connectionId a connection id
098: * @param sql an sql SELECT command
099: * @param catalog
100: * @param schemaPattern
101: * @param tableNamePattern
102: * @param types
103: * @return a result set id.
104: */
105: public abstract String Connection_getMetaData_getTables(
106: String connectionId, String catalog, String schemaPattern,
107: String tableNamePattern, String[] types) throws Exception;
108:
109: /**
110: * Create a connection.
111: * @param serverId .. currently ignored (but expected - do not remove)
112: * @param url the local database url
113: * @return a connection id.
114: */
115: public abstract String CreateConnection(String serverId, String url)
116: throws Exception;
117:
118: /**
119: * Invoke a call. No exception is thrown. Instead, all exception are
120: * caught and an ExceptionResult is returned.
121: * @param call a call
122: * @return a value
123: */
124: public abstract CallResult perform(Call call);
125:
126: /**
127: * Return the result set meta data.
128: * @param resultsetId a result set id
129: * @return result set meta data
130: */
131: public abstract ResultSetMetaData ResultSet_getMetaData(
132: String resultsetId) throws Exception;
133:
134: /**
135: * Fetch the next row from a result set.
136: * @param id the result set id
137: * @return a record or null indicating that there is no (more) row
138: */
139: public abstract Record ResultSet_next(String id) throws Exception;
140:
141: /**
142: * Fetch the next rows from a result set.
143: * This is usually more effective than fetching a single row (but can also
144: * be dangerous, e.g. in case the computation of the second result is slow).
145: * @param id the result set id
146: * @param rows the number of rows
147: * @return a list of records
148: */
149: public abstract List ResultSet_nextRows(String id, int rows)
150: throws Exception;
151:
152: /**
153: * Get the current result set. Only the result set id is returned,
154: * rows are returned using next(), and the result set is assembled
155: * on the client side.
156: * @param statementId a statement id
157: * @return a result set id.
158: */
159: public abstract String Statement_getResultSet(String statementId)
160: throws Exception;
161:
162: /**
163: * Perform a query. Only the result set id is returned,
164: * rows are returned using next(), and the result set is assembled
165: * on the client side.
166: * @param statementId a statement id
167: * @param sql an sql SELECT command
168: * @return a result set id.
169: */
170: public abstract String Statement_executeQuery(String statementId,
171: String sql) throws Exception;
172:
173: /**
174: * Perform a query.
175: * @param statementId a statement id
176: */
177: public abstract void Statement_execute(String statementId)
178: throws Exception;
179:
180: /**
181: * Perform a query. Only the result set id is returned,
182: * rows are returned using next(), and the result set is assembled
183: * on the client side.
184: * @param statementId a statement id
185: * @return a result set id.
186: */
187: public abstract String PreparedStatement_executeQuery(
188: String statementId) throws Exception;
189:
190: /**
191: * Set the object on a certain index.
192: * @param statementId a statement id
193: * @param parameterIndex the index
194: * @param x the object
195: */
196: public abstract void PreparedStatement_setObject(
197: String statementId, int parameterIndex, Object x)
198: throws SQLException;
199:
200: /**
201: * Clear the parameters.
202: * @param statementId a statement id
203: */
204: public abstract void PreparedStatement_clearParameters(
205: String statementId) throws Exception;
206:
207: /**
208: * Release all resources.
209: */
210: public abstract void release() throws Exception;
211: }
|