Connection


1   /*
2    * Copyright 2006-2007 The Scriptella Project 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  package scriptella.spi;
17  
18  /**
19   * Represents a connection to the system provided by {@link ScriptellaDriver}.
20   * <p>The implementations are not required to be thread safe.
21   * <p>For most cases {@link AbstractConnection} may be used as a base for driver connection implementation.
22   *
23   * @author Fyodor Kupolov
24   * @version 1.0
25   */
26  public interface Connection {
27      /**
28       * @return dialect identifier for this connection.
29       */
30      DialectIdentifier getDialectIdentifier() throws ProviderException;
31  
32      /**
33       * Executes a script specified by its content.
34       * <p>scriptContent may be used as a key for caching purposes, i.e.
35       * provider may precompile scripts and use compiled versions for subsequent executions.
36       *
37       * @param scriptContent      script content. Cannot be null.
38       * @param parametersCallback callback to get parameter values. Cannot be null.
39       */
40      void executeScript(Resource scriptContent, ParametersCallback parametersCallback) throws ProviderException;
41  
42      /**
43       * Executes a query specified by its content.
44       * <p/>
45       *
46       * @param queryContent       query content. Cannot be null.
47       * @param parametersCallback callback to get parameter values. Cannot be null.
48       * @param queryCallback      callback to call for each result set element produced by this query. Cannot be null.
49       * @see #executeScript(scriptella.spi.Resource, scriptella.spi.ParametersCallback)
50       */
51      void executeQuery(Resource queryContent, ParametersCallback parametersCallback, QueryCallback queryCallback) throws ProviderException;
52  
53      /**
54       * This method returns the number of executed statements or 0 if this feature is unsupported.
55       * <p>If possible the connection should collect statistics about the number of executed statement.
56       * It's recommended to provide the most actual execution statistics, i.e. increment internal statements
57       * counter during a script or a query execution, so the monitoring tools would be able to track progress.  
58       *
59       * @return number of executed statements or 0 if this feature is unsupported.
60       */
61      long getExecutedStatementsCount();
62  
63      /**
64       * Commits a current transaction (if any).
65       */
66      void commit() throws ProviderException;
67  
68      /**
69       * Rolls back a current transaction (if any).
70       * @throws ProviderException if driver fails to roll back a transaction.
71       * @throws UnsupportedOperationException if transactions are not supported
72       */
73      void rollback() throws ProviderException, UnsupportedOperationException  ;
74  
75  
76      /**
77       * Closes the connection and releases all related resources.
78       */
79      void close() throws ProviderException;
80  
81       /**
82       * @return meaningful label for connection
83       */
84      String   toString();
85  }
86
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags