Accessor


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the "License").  You may not use this file except 
5    * in compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * glassfish/bootstrap/legal/CDDLv1.0.txt or 
9    * https://glassfish.dev.java.net/public/CDDLv1.0.html. 
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * HEADER in each file and include the License file at 
15   * glassfish/bootstrap/legal/CDDLv1.0.txt.  If applicable, 
16   * add the following below this CDDL HEADER, with the 
17   * fields enclosed by brackets "[]" replaced with your 
18   * own identifying information: Portions Copyright [yyyy] 
19   * [name of copyright owner]
20   */
21  // Copyright (c) 1998, 2005, Oracle. All rights reserved.  
22  package oracle.toplink.essentials.internal.databaseaccess;
23  
24  import java.util.Vector  ;
25  import oracle.toplink.essentials.exceptions.DatabaseException;
26  import oracle.toplink.essentials.internal.sessions.AbstractSession;
27  import oracle.toplink.essentials.internal.sessions.AbstractRecord;
28  import oracle.toplink.essentials.sessions.Login;
29  import oracle.toplink.essentials.queryframework.Call;
30  
31  /**
32   * INTERNAL:
33   * Accessor defines the interface used primarily by the assorted
34   * TopLink Sessions to interact with a data store. In "normal"
35   * TopLink this data store is a relational database. But this interface
36   * also allows developers using the TopLink SDK to develop Accessors
37   * to other, non-relational, data stores.<p>
38   *
39   * Accessors must implement the following behavior: <ul>
40   *    <li>connect to and disconnect from the data store
41   *    <li>handle transaction contexts
42   * <li>execute calls that read, insert, update, and delete data
43   * <li>keep track of concurrently executing calls
44   * <li>supply metadata about the data store
45   * </ul>
46   *
47   * @see oracle.toplink.essentials.publicinterface.Session
48   * @see Call
49   *
50   * @author Big Country
51   * @since TOPLink/Java 3.0
52   */
53  public interface Accessor extends Cloneable   {
54  
55      /**
56       * To be called after JTS transaction has been completed (committed or rolled back)
57       */
58      public void afterJTSTransaction();
59  
60      /**
61       * Begin a transaction on the data store.
62       */
63      void beginTransaction(AbstractSession session) throws DatabaseException;
64  
65      /**
66       * Return a clone of the accessor.
67       */
68      Object   clone();
69  
70      /**
71       * Close the accessor's connection.
72       * This is used only for external connection pooling
73       * when it is intended for the connection to be reconnected in the future.
74       */
75      void closeConnection();
76  
77      /**
78       * Commit a transaction on the data store.
79       */
80      void commitTransaction(AbstractSession session) throws DatabaseException;
81  
82      /**
83       * Connect to the data store using the configuration
84       * information in the login.
85       */
86      void connect(Login login, AbstractSession session) throws DatabaseException;
87  
88      /**
89       * Decrement the number of calls in progress.
90       * Used for external pooling.
91       */
92      void decrementCallCount();
93  
94      /**
95       * Disconnect from the data store.
96       */
97      void disconnect(AbstractSession session) throws DatabaseException;
98  
99      /**
100      * Execute the call.
101      * The actual behavior of the execution depends on the type of call.
102      * The call may be parameterized where the arguments are in the translation row.
103      * The row will be empty if there are no parameters.
104      * @return a row, a collection of rows, a row count, or a cursor
105      */
106     Object   executeCall(Call call, AbstractRecord translationRow, AbstractSession session) throws DatabaseException;
107 
108     /**
109      * Execute any deferred select calls.  This method will generally be called
110      * after one or more select calls have been collected in a LOBValueWriter (to be
111      * executed after all insert calls are executed).
112      * Bug 2804663.
113      *
114      * @see oracle.toplink.essentials.internal.helper.LOBValueWriter#buildAndExecuteCallForLocator(DatabaseCall,Session,Accessor)
115      */
116     void flushSelectCalls(AbstractSession session);
117 
118     /**
119      * Return the number of calls currently in progress.
120      * Used for load balancing and external pooling.
121      */
122     int getCallCount();
123 
124     /**
125      * Return the column metadata for the specified
126      * selection criteria.
127      */
128     Vector   getColumnInfo(String   catalog, String   schema, String   tableName, String   columnName, AbstractSession session) throws DatabaseException;
129 
130     /**
131      * Return the JDBC connection for relational accessors.
132      * This will fail for non-relational accessors.
133      */
134     java.sql.Connection   getConnection();
135 
136     /**
137      * Return the driver level connection,
138      * this will need to be cast to the implementation class for the data access type being used.
139      */
140     Object   getDatasourceConnection();
141 
142     /**
143      * Return the table metadata for the specified
144      * selection criteria.
145      */
146     Vector   getTableInfo(String   catalog, String   schema, String   tableName, String  [] types, AbstractSession session) throws DatabaseException;
147 
148     /**
149      * Increment the number of calls in progress.
150      * Used for external pooling.
151      */
152     void incrementCallCount(AbstractSession session);
153 
154     /**
155      * Return whether the accessor is connected to the data store.
156      */
157     boolean isConnected();
158 
159     /**
160      * Reconnect to the database. This can be used if the connection was
161      * temporarily disconnected or if it timed out.
162      */
163     void reestablishConnection(AbstractSession session) throws DatabaseException;
164 
165     /**
166      * Roll back a transaction on the data store.
167      */
168     void rollbackTransaction(AbstractSession session) throws DatabaseException;
169 
170     /**
171      * Return whether the accessor uses an external
172      * transaction controller (e.g. JTS).
173      */
174     boolean usesExternalTransactionController();
175 
176     /**
177      * This method will be called after a series of writes have been issued to
178      * mark where a particular set of writes has completed.  It will be called
179      * from commitTransaction and may be called from writeChanges.   Its main
180      * purpose is to ensure that the batched statements have been executed
181      */
182     public void writesCompleted(AbstractSession session);
183 }
184
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags