001: /*
002: * Copyright 2006-2007 The Scriptella Project Team.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package scriptella.spi;
017:
018: /**
019: * Represents a connection to the system provided by {@link ScriptellaDriver}.
020: * <p>The implementations are not required to be thread safe.
021: * <p>For most cases {@link AbstractConnection} may be used as a base for driver connection implementation.
022: *
023: * @author Fyodor Kupolov
024: * @version 1.0
025: */
026: public interface Connection {
027: /**
028: * This method returns a language dialect identifier for this connection.
029: *
030: * @return dialect identifier.
031: * @throws ProviderException if driver failed to determine a language dialect.
032: */
033: DialectIdentifier getDialectIdentifier() throws ProviderException;
034:
035: /**
036: * Executes a script specified by its content.
037: * <p>scriptContent may be used as a key for caching purposes, i.e.
038: * provider may precompile scripts and use compiled versions for subsequent executions.
039: * Please note that <em>only inline {@link scriptella.configuration.StringResource text resources}
040: * can be safely cached</em>.
041: *
042: * @param scriptContent script content. Cannot be null.
043: * @param parametersCallback callback to get parameter values. Cannot be null.
044: * @throws ProviderException if script execution failed.
045: */
046: void executeScript(Resource scriptContent,
047: ParametersCallback parametersCallback)
048: throws ProviderException;
049:
050: /**
051: * Executes a query specified by its content.
052: * <p/>
053: *
054: * @param queryContent query content. Cannot be null.
055: * @param parametersCallback callback to get parameter values. Cannot be null.
056: * @param queryCallback callback to call for each result set element produced by this query. Cannot be null.
057: * @throws ProviderException if query execution failed.
058: * @see #executeScript(scriptella.spi.Resource,scriptella.spi.ParametersCallback)
059: */
060: void executeQuery(Resource queryContent,
061: ParametersCallback parametersCallback,
062: QueryCallback queryCallback) throws ProviderException;
063:
064: /**
065: * This method returns the number of executed statements or 0 if this feature is unsupported.
066: * <p>If possible the connection should collect statistics about the number of executed statement.
067: * It's recommended to provide the most actual execution statistics, i.e. increment internal statements
068: * counter during a script or a query execution, so the monitoring tools would be able to track progress.
069: *
070: * @return number of executed statements or 0 if this feature is unsupported.
071: */
072: long getExecutedStatementsCount();
073:
074: /**
075: * Commits a current transaction (if any).
076: * <p>Throwing an error during commit phase cause {@link #rollback() rollback}.
077: *
078: * @throws ProviderException if a problem occured during commit phase.
079: */
080: void commit() throws ProviderException;
081:
082: /**
083: * Rolls back a current transaction (if any).
084: *
085: * @throws ProviderException if driver fails to roll back a transaction.
086: * @throws UnsupportedOperationException if transactions are not supported
087: */
088: void rollback() throws ProviderException,
089: UnsupportedOperationException;
090:
091: /**
092: * Closes the connection and releases all related resources.
093: *
094: * @throws ProviderException if a critical failure occured.
095: */
096: void close() throws ProviderException;
097:
098: /**
099: * @return meaningful label for connection
100: */
101: String toString();
102: }
|