/** 
 * 
 * Copyright 2004 Protique Ltd
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); 
 * you may not use this file except in compliance with the License. 
 * You may obtain a copy of the License at 
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, 
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
 * See the License for the specific language governing permissions and 
 * limitations under the License. 
 * 
 **/
package org.activemq.store;

import java.util.Map;

import javax.jms.JMSException;

import org.activemq.service.Service;

/**
 * Adapter to the actual persistence mechanism used with ActiveMQ
 *
 * @version $Revision: 1.1.1.1 $
 */
public interface PersistenceAdapter extends Service {

    /**
     * Returns a map, indexed by String name, of all the {@link javax.jms.Destination}
     * objects active on startup.
     *
     * @return
     */
    public Map getInitialDestinations();


    /**
     * Factory method to create a new queue message store with the given destination name
     */
    public MessageStore createQueueMessageStore(String destinationName) throws JMSException;

    /**
     * Factory method to create a new topic message store with the given destination name
     */
    public TopicMessageStore createTopicMessageStore(String destinationName) throws JMSException;

    /**
     * Factory method to create a new persistent prepared transaction store for XA recovery
     */
    public TransactionStore createTransactionStore() throws JMSException;

    /**
     * This method starts a transaction on the persistent storage - which is nothing to
     * do with JMS or XA transactions - its purely a mechanism to perform multiple writes
     * to a persistent store in 1 transaction as a performance optimisation.
     * <p/>
     * Typically one transaction will require one disk synchronization point and so for
     * real high performance its usually faster to perform many writes within the same
     * transaction to minimise latency caused by disk synchronization. This is especially
     * true when using tools like Berkeley Db or embedded JDBC servers.
     */
    public void beginTransaction() throws JMSException;


    /**
     * Commit a persistence transaction
     *
     * @see PersistenceAdapter#beginTransaction()
     */
    public void commitTransaction() throws JMSException;

    /**
     * Rollback a persistence transaction
     *
     * @see PersistenceAdapter#beginTransaction()
     */
    public void rollbackTransaction();
}
