001: ///////////////////////////////
002: // Makumba, Makumba tag library
003: // Copyright (C) 2000-2003 http://www.makumba.org
004: //
005: // This library is free software; you can redistribute it and/or
006: // modify it under the terms of the GNU Lesser General Public
007: // License as published by the Free Software Foundation; either
008: // version 2.1 of the License, or (at your option) any later version.
009: //
010: // This library is distributed in the hope that it will be useful,
011: // but WITHOUT ANY WARRANTY; without even the implied warranty of
012: // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013: // Lesser General Public License for more details.
014: //
015: // You should have received a copy of the GNU Lesser General Public
016: // License along with this library; if not, write to the Free Software
017: // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
018: //
019: // -------------
020: // $Id: Transaction.java 2111 2007-11-21 17:05:01Z manuel_gay $
021: // $Name$
022: /////////////////////////////////////
023:
024: package org.makumba;
025:
026: import org.makumba.db.makumba.Query;
027: import org.makumba.providers.TransactionProviderInterface;
028:
029: /** This class models operations with a database. To obtain such an object, use methods from {@link MakumbaSystem}. <p>
030: Stricly speaking this class represents a database connection (later on, transaction). Obtaining more such objects for the same database configurations will result in opening more connections. Connections must be given back to the system using the {@link #close()} method. That will be done automatically by the object's finalizer. In makumba business logic, connections passed to the BL methods are automatically closed by the system after the BL operations (including eventual automatic DB acceses) were completed. To open a "sibling" of a connection <i>conn</i> of this type, use MakumbaSystem.getConnectionTo(<i>conn</i>.getName()). In most cases, you will have to close the sibling yourself.<p>
031: * At the level of this API, data is represented as java.util.Dictionary, both for reading and writing. Most methods throw {@link DBError} if a fatal database error occurs. If the connection to the database is lost, an attempt is made to reconnect before throwing a {@link DBError}.<P>
032: * All methods throw subclasses of either Error or RuntimeException, so nothing needs to be caught explicitely.
033: * @see org.makumba.MakumbaSystem#getDefaultDataSourceName()
034: * @see org.makumba.MakumbaSystem#getDefaultDatabaseName(java.lang.String)
035: * @see org.makumba.MakumbaSystem#getConnectionTo(java.lang.String)
036: * @since makumba-0.5
037: */
038: public interface Transaction extends Database {
039: /** Read fields of a record.
040: * Database querying is logged (see {@link java.util.logging.Logger}, {@link org.makumba.MakumbaSystem#setLoggingRoot(java.lang.String)}) in the <b><code>"db.query.compilation", "db.query.execution", "db.query.performance"</code></b> loggers, with {@link java.util.logging.Level#INFO} logging level. "db.query.execution" also logs {@link java.util.logging.Level#SEVERE} fatal errors.
041: * @param ptr the pointer to the record
042: * @param fields the fields to read, or null to read all fields. Can be a String, String[], Enumeration or a Vector
043: * @return a Dictionary, containing a name-value pair for each non-null field, or null if the record doesn't exist
044: * @exception InvalidValueException if the fields argument is not String, String[], Enumeration or Vector
045: * @exception org.makumba.DBError if a fatal database error occurs
046: * @exception IllegalStateException if the connection was already closed
047: */
048: public java.util.Dictionary read(Pointer ptr, Object fields);
049:
050: /** Get the name of the database in the form host[_port]_dbprotocol_dbname */
051: public String getName();
052:
053: /** Execute a parametrized OQL query.
054: * Queries are pre-compiled and cached in the database, so they should be parametrized as much as possible.
055: * Database querying is logged (see {@link java.util.logging.Logger}, {@link org.makumba.MakumbaSystem#setLoggingRoot(java.lang.String)}) in the <b><code>"db.query.compilation", "db.query.execution", "db.query.performance"</code></b> loggers, with {@link java.util.logging.Level#INFO} logging level. "db.query.execution" also logs {@link java.util.logging.Level#SEVERE} fatal errors.<br>
056: * @param query the query to execute. Refers to parameters as $1, $2 ...
057: * @param arguments the arguments of the queries. Should be null if there are none. If there is only one parameter, it can be indicated directly. If there are more parameters, they can be indicated in a Object[] or a java.util.Vector. Named parameters can be indicated in a Map.
058: * @param limit the maximum number of records to return, -1 for all
059: * @param offset the offset of the first record to return, 0 for first
060: * @return a Dictionary, containing a name-value pair for each non-null SELECT column. If a certain SELECT column is not named using AS, it will be automatically named like col1, col2, etc.
061: * @exception org.makumba.DBError if a fatal database error occurs
062: * @exception org.makumba.OQLParseError if the OQL is not correct
063: * @exception InvalidValueException in case of makumba type conflict between a pointer value passed as parameter and the type expected in the respective OQL expression
064: * @exception IllegalStateException if the connection was already closed
065: */
066: public java.util.Vector executeQuery(String query,
067: Object arguments, int offset, int limit);
068:
069: /** Execute query without limiting the results.
070: * @see org.makumba.Transaction#executeQuery(java.lang.String,java.lang.Object,int,int)
071: */
072: public java.util.Vector executeQuery(String query, Object arguments);
073:
074: /** Insert a record of the given type. <BR>
075: * Database update is logged (see {@link java.util.logging.Logger}, {@link org.makumba.MakumbaSystem#setLoggingRoot(java.lang.String)}) in the <b><code>"db.update.execution", "db.update.performance"</code></b> loggers, with {@link java.util.logging.Level#INFO} logging level. "db.update.execution" also logs {@link java.util.logging.Level#SEVERE} fatal errors.
076: <p>Special makumba fields are treated as follows:<ul>
077: <li> External sets (sets of records in other tables), as well as sets of int and char can be inserted as Vectors.<BR>
078: <li> Base records and subrecords can be inserted as well. Base records are indicated by fixed, notnull pointers and the record constitutes logical extensions of its base records (this is called subtyping in database theory).
079: <li>Subrecords are indicated by 1-1 pointers, and are a logical extension of the record.
080: <li>Both base record fields and subrecord fields can be referred to via their pointer, like P.field, where P is a pointer to the base record or a 1-1 pointer. By extension P1.P2.field notations can exist.
081: </ul>
082: * @param type the makumba type to create a new record for
083: * @param data the field-value mapping for the new record. <br>
084: The ommitted fields will be set to null.<br>
085: To insert an set of integets (set int {...}) pass a Vector of Integers. (or null, or an empty vector).<br>
086: To insert an set of strings (set char {...}) pass a Vector of String. (or null, or an empty vector). <br>
087: To refer to a field of base record or subrecord, indicate the pointer that leads to the record, and the respective field, like ptr1.ptr2.field. Every mentioned base record and subrecord will be inserted.
088: * @return a Pointer to the inserted record
089: * @exception DBError if a fatal database error occurs
090: * @exception DataDefinitionNotFoundError if the indicated type is not found
091: * @exception InvalidValueException if a certain field does not accept the given value
092: * @exception InvalidValueException in case of makumba type conflict between a pointer value passed and the definition of the respective field
093: * @exception java.lang.ClassCastException in case of java type conflict between a value passed and the definition of the respective field
094: * @exception IllegalStateException if the connection was already closed
095: */
096: public Pointer insert(String type, java.util.Dictionary data);
097:
098: /** Insert a record in a subset (1-N set) of the given record. <br>
099: * Database update is logged (see {@link java.util.logging.Logger}, {@link org.makumba.MakumbaSystem#setLoggingRoot(java.lang.String)}) in the <b><code>"db.update.execution", "db.update.performance"</code></b> loggers, with {@link java.util.logging.Level#INFO} logging level. "db.update.execution" also logs {@link java.util.logging.Level#SEVERE} fatal errors.<br
100: <p>Special makumba fields are treated as follows:<ul>
101: <li>The new member's external sets (sets of records in other tables) as well as sets of int and char can be inserted as Vectors.<BR>
102: <li>The new member can have subrecords, but cannot have base records.
103: </ul>
104: * @return a Pointer to the inserted record
105: * @param host a pointer to the host record, to which a subrecord will be added
106: * @param subsetField the name of the subrecord field.
107: * @param data the field-value mapping for the new subrecord. <br>
108: The ommitted fields will be set to null. <br>
109: To insert an external set, pass a Vector of Pointers (or null, or an empty vector). <br>
110: To insert an set of integets (set int {...}) pass a Vector of Integers. (or null, or an empty vector).<br>
111: To insert an set of strings (set char {...}) pass a Vector of String. (or null, or an empty vector). <br>
112: To refer to a field of a subrecord (subset members cannot have base records), indicate the pointer that leads to the record, and the respective field, like ptr1.ptr2.field.
113: * @exception DBError if a fatal database error occurs
114: * @exception InvalidValueException if a certain value is not valid for a field
115: * @exception InvalidValueException in case of makumba type conflict between a pointer value passed and the definition of the respective field
116: * @exception java.lang.ClassCastException in case of java type conflict between a value passed and the definition of the respective field
117: * @exception IllegalStateException if the connection was already closed
118: */
119: public Pointer insert(Pointer host, String subsetField,
120: java.util.Dictionary data);
121:
122: /** Insert the results of the query in the given type. Generates an INSERT...SELECT. The labels of the OQL query must match field names of the given type.
123: * @param type the type where to insert
124: * @param OQL the OQL query to execute. Refers to parameters as $1, $2 ...
125: * @param parameterValues the parameter values. Should be null if there are no parameters. If there is only one parameter, it can be indicated directly. If there are more parameters, they can be indicated in a Object[] or a java.util.Vector
126: * @return the number of records inserted */
127: public int insertFromQuery(String type, String OQL,
128: Object parameterValues);
129:
130: /** Change the record pointed by the given pointer. Only fields indicated as keys in fieldsToChange are changed to the respective values. <BR>
131: * Database update is logged (see {@link java.util.logging.Logger}, {@link org.makumba.MakumbaSystem#setLoggingRoot(java.lang.String)}) in the <b><code>"db.update.execution", "db.update.performance"</code></b> loggers, with {@link java.util.logging.Level#INFO} logging level. "db.update.execution" also logs {@link java.util.logging.Level#SEVERE} fatal errors.<br>
132: <p>Special makumba fields are treated as follows:<ul>
133: <li>External sets (sets of records in other tables), as well as sets of intger or char, can be indicated for change as Vectors.<BR>
134: <li>Base records and subrecords can be changed as well. Base records are indicated by fixed, notnull pointers and the record constitutes logical extensions of its base records (this is called subtyping in database theory).
135: <li>Subrecords are indicated by 1-1 pointers, and are a logical extension of the record. Both base record fields and subrecord fields can be referred to via their pointer, like P.field, where P is a pointer to the base record or a 1-1 pointer. By extension P1.P2.field notations can exist.
136: </ul>
137: * @param ptr pointer to the record to update
138: * @param fieldsToChange key-value pairs for the fields to modify. <br>
139: To nullify a field, pass the respective Null value from the Pointer class. <br>
140: To change an external set, pass a Vector of Pointers (an empty vector will empty the set). <br>
141: To change a set of integrers (set int{...}), pass a Vector of Integers (an empty vector will empty the set). <br>
142: To change a set of integrers (set char{...}), pass a Vector of Strings (an empty vector will empty the set). <br>
143: To refer to a field of a base record or subrecord, indicate the pointer that leads to the record, and the respective field, like ptr1.ptr2.field.
144: * @exception DBError if a fatal database error occurs
145: * @exception InvalidValueException if a certain value is not valid for a field
146: * @exception InvalidValueException in case of makumba type conflict between a pointer value passed and the definition of the respective field
147: * @exception java.lang.ClassCastException in case of java type conflict between a value passed and the definition of the respective field
148: * @exception IllegalStateException if the connection was already closed
149: * @see Pointer#Null
150: * @see Pointer#NullInteger
151: * @see Pointer#NullString
152: * @see Pointer#NullText
153: * @see Pointer#NullDate
154: * @see Pointer#NullSet
155: */
156: public void update(Pointer ptr, java.util.Dictionary fieldsToChange);
157:
158: /** Update in the form <code>update("general.Person p", "p.birthdate=$1", "p=$2", params)</code> . <br>
159: * Database update is logged (see {@link java.util.logging.Logger}, {@link org.makumba.MakumbaSystem#setLoggingRoot(java.lang.String)}) in the <b><code>"db.update.execution", "db.update.performance"</code></b> loggers, with {@link java.util.logging.Level#INFO} logging level. "db.update.execution" also logs {@link java.util.logging.Level#SEVERE} fatal errors.<br>
160: * NOTE that this method does not delete subrecords if their pointers are nullified
161: * @exception IllegalStateException if the connection was already closed
162: * @exception DBError if a fatal database error occurs
163: * @param from a makumba type in which update will take place, for example "general.Person p"
164: * @param set the assignments made by the update, as OQL expression e.g. "p.birthdate=$1". Use "nil" for null assignments.
165: * @param where the OQL conditions selecting the objects on which the update will be made, e.g. "p=$2"
166: * @param parameterValues the parameter values. Should be null if there are no parameters. If there is only one parameter, it can be indicated directly. If there are more parameters, they can be indicated in a Object[] or a java.util.Vector
167: * @return the number of records affected
168: * @since makumba-0.5.5
169: */
170: public int update(String from, String set, String where,
171: Object parameterValues);
172:
173: /** Delete the record pointed by the given pointer. If the pointer is a 1-1, the pointer in the base record is set to null. All the subrecords and subsets are automatically deleted. <br>
174: * Database update is logged (see {@link java.util.logging.Logger}, {@link org.makumba.MakumbaSystem#setLoggingRoot(java.lang.String)}) in the <b><code>"db.update.execution", "db.update.performance"</code></b> loggers, with {@link java.util.logging.Level#INFO} logging level. "db.update.execution" also logs {@link java.util.logging.Level#SEVERE} fatal errors.<br>
175: * @exception DBError if a fatal database error occurs
176: * @exception IllegalStateException if the connection was already closed
177: * @param ptr the pointer to the record to be deleted
178: */
179: public void delete(Pointer ptr);
180:
181: /** Delete in the form <code>delete("general.Person p", "p=$1", params)</code> . <br>
182: * Database update is logged (see {@link java.util.logging.Logger}, {@link org.makumba.MakumbaSystem#setLoggingRoot(java.lang.String)}) in the <b><code>"db.update.execution", "db.update.performance"</code></b> loggers, with {@link java.util.logging.Level#INFO} logging level. "db.update.execution" also logs {@link java.util.logging.Level#SEVERE} fatal errors.<br>
183: * NOTE that this method does not delete subsets and subrecords
184: * @return the number of records affected
185: * @param from a makumba type in which delete will take place, for example "general.Person p"
186: * @param where the OQL conditions selecting the objects to be deleted, e.g. "p=$1"
187: * @param parameterValues the parameter values. Should be null if there are no parameters. If there is only one parameter, it can be indicated directly. If there are more parameters, they can be indicated in a Object[] or a java.util.Vector
188: * @return the number of records affected
189: * @exception DBError if a fatal database error occurs
190: * @exception IllegalStateException if the connection was already closed
191: * @since makumba-0.5.5
192: */
193: public int delete(String from, String where, Object parameterValues);
194:
195: /** Commit the transaction associated with this connection. Normally, simply closing the connection will do, but more often committs may be needed. The business logic manager will close (and therefore commit) all transaction that it provides for usage.*/
196: public void commit();
197:
198: /** Give this connection back to the system. This will automatically commit the transaction if it was not committed. A connection cannot be used after closing.
199: * @exception DBError if a fatal database error occurs
200: * @exception IllegalStateException if the connection was already closed
201: */
202: public void close();
203:
204: /** Rollback the transaction associated with this connection. Typically rollback should be doneif an error occurs in a business logic operation. The business logic manager will rollback a transaction that it provided for usage if it catches any exception during the business logic execution.*/
205: public void rollback();
206:
207: /** Acquire a lock associated to the given application-specific symbol. This method will block as long as the lock is already taken on another Database object. The commit() and rollback() methods unlcok all locks acquired on this connection */
208: public void lock(String symbol);
209:
210: /** Free the lock on the given symbol, if any exists. This will allow the continuation of a thread that needs a lock on the same symbol and uses another Database object*/
211: public void unlock(String symbol);
212:
213: /** Returns the TransactionProvider which created this Transaction **/
214: public TransactionProviderInterface getTransactionProvider();
215:
216: /** Returns the name of the data source to which this Transaction is connected **/
217: public String getDataSource();
218:
219: }
|