001    /**
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.fusesource.hawtdb.api;
018    
019    
020    
021    /**
022     * Provides transactional access to a {@link Paged} resource.
023     * The transaction provides snapshot isolation.  The snapshot view
024     * of the entire page file is obtained the first time you read data 
025     * from a page.  Committed page updates from concurrent transactions will
026     * not be visible to the snapshot.
027     * 
028     * The snapshot view of the page file is released once the transaction 
029     * commits or is rolled back.  Avoid holding a snapshot view for a long time.
030     * The page file cannot reclaim temporary processing space associated with
031     * a snapshot and subsequent snapshots while the snapshot is in use.
032     * 
033     * Pages are optimistically updated, which means they are not locked for 
034     * update.  Updating a page or committing the transaction may fail 
035     * with an {@line OptimisticUpdateException} if another committed transaction
036     * has updated the same page this transaction was trying to update.
037     * 
038     * @author <a href="http://hiramchirino.com">Hiram Chirino</a>
039     */
040    public interface Transaction extends Paged {
041        
042        /**
043         * @return true if no updates have been performed by this transaction.
044         */
045        boolean isReadOnly();
046        
047        /**
048         * @throws OptimisticUpdateException 
049         *      is thrown if the update would conflict with a concurrent 
050         *      updated performed by another thread.
051         */
052        void commit() throws OptimisticUpdateException;
053        
054        /**
055         * 
056         */
057            void rollback();
058    
059        /**
060         * Closes a transaction object.  Throws an assertion error
061         * if the transaction is not already committed or rolledback.
062         *
063         * Attempts to use this transaction again will throw assertion errors.
064         */
065        void close();
066    
067        /**
068         * Committed transactions do not get written to physical media immediately, they get
069         * batched up with other Transaction to increase update throughput.
070         *
071         * Call this method with a Runnable if you want to get a callback when
072         * the transactions' updates are secured to physical media and therefore are known to
073         * survive a machine reboot.
074         *
075         * @param runnable
076         */
077        void onFlush(Runnable runnable);
078            
079    }