// AID-GENERATED
// =========================================================================
// This class was generated by AID - Abstract Interface Definition          
// DO NOT MODIFY, but use the org.freehep.aid.Aid utility to regenerate it. 
// =========================================================================

//  This file is part of the AIDA library
//  Copyright (C) 2002 by the AIDA team.  All rights reserved.
//  This library is free software and under the terms of the
//  GNU Library General Public License described in the LGPL.txt 
package hep.aida;

import java.io.IOException;

/**
 * The creator of trees.
 *
 * @author The AIDA team (http://aida.freehep.org/)
 */
 
public interface ITreeFactory {

    /**
     * Creates a new tree that is not associated with a store.
     */
    public ITree createTree();
    /**
     * Creates a new tree that is not associated with a store.
     */
    public ITree createTree(String options);

    /**
     * Creates a new tree and associates it with a store.
     * 

     * The definition of the various modes than can be specified are:
     * 

     * 
AUTO default case: create of store does not exist 
     * 
CREATE: Create a new file (throws an exception if already exists) 
     * 
RECREATE: overwrite file if existing 
     * 
READONLY: open in read only mode 
     * 
UPDATE: read/write mode, overwriting modified objects. 
     * 
     * @param storeName The name of the store, if empty (""), the tree is created
     *                  in memory and therefore will not be associated with a file.
     * @param storeType Implementation specific string, may control store type
     * @throws IOException if the store already exists
     * @throws IllegalArgumentException
     */
    public ITree createTree(String storeName, String storeType) throws IllegalArgumentException, IOException;
    /**
     * Creates a new tree and associates it with a store.
     * 

     * The definition of the various modes than can be specified are:
     * 

     * 
AUTO default case: create of store does not exist 
     * 
CREATE: Create a new file (throws an exception if already exists) 
     * 
RECREATE: overwrite file if existing 
     * 
READONLY: open in read only mode 
     * 
UPDATE: read/write mode, overwriting modified objects. 
     * 
     * @param storeName The name of the store, if empty (""), the tree is created
     *                  in memory and therefore will not be associated with a file.
     * @param storeType Implementation specific string, may control store type
     * @param mode One of AUTO, CREATE, RECREATE, READONLY, UPDATE.
     * @throws IOException if the store already exists
     * @throws IllegalArgumentException
     */
    public ITree createTree(String storeName, String storeType, int mode) throws IllegalArgumentException, IOException;
    /**
     * Creates a new tree and associates it with a store.
     * 

     * The definition of the various modes than can be specified are:
     * 

     * 
AUTO default case: create of store does not exist 
     * 
CREATE: Create a new file (throws an exception if already exists) 
     * 
RECREATE: overwrite file if existing 
     * 
READONLY: open in read only mode 
     * 
UPDATE: read/write mode, overwriting modified objects. 
     * 
     * @param storeName The name of the store, if empty (""), the tree is created
     *                  in memory and therefore will not be associated with a file.
     * @param storeType Implementation specific string, may control store type
     * @param mode One of AUTO, CREATE, RECREATE, READONLY, UPDATE.
     * @param options Other options, currently are not specified
     * @throws IOException if the store already exists
     * @throws IllegalArgumentException
     */
    public ITree createTree(String storeName, String storeType, int mode, String options) throws IllegalArgumentException, IOException;

    /**
     * Creates a new tree which is explicitly named.
     * 

     * @param name The name of the tree.
     * @param storeName The name of the store, if empty (""), the tree is 
     *                  created in memory and therefore will not be 
     *                  associated with a file.
     * @param storeType Implementation specific string, may control store type
     * @throws IOException if the store already exists
     * @throws IllegalArgumentException
     */
    public ITree createNamedTree(String name, String storeName, String storeType) throws IllegalArgumentException, IOException;
    /**
     * Creates a new tree which is explicitly named.
     * 

     * @param name The name of the tree.
     * @param storeName The name of the store, if empty (""), the tree is 
     *                  created in memory and therefore will not be 
     *                  associated with a file.
     * @param storeType Implementation specific string, may control store type
     * @param mode One of AUTO, CREATE, RECREATE, READONLY, UPDATE.
     * @throws IOException if the store already exists
     * @throws IllegalArgumentException
     */
    public ITree createNamedTree(String name, String storeName, String storeType, int mode) throws IllegalArgumentException, IOException;
    /**
     * Creates a new tree which is explicitly named.
     * 

     * @param name The name of the tree.
     * @param storeName The name of the store, if empty (""), the tree is 
     *                  created in memory and therefore will not be 
     *                  associated with a file.
     * @param storeType Implementation specific string, may control store type
     * @param mode One of AUTO, CREATE, RECREATE, READONLY, UPDATE.
     * @param options Other options, currently are not specified
     * @throws IOException if the store already exists
     * @throws IllegalArgumentException
     */
    public ITree createNamedTree(String name, String storeName, String storeType, int mode, String options) throws IllegalArgumentException, IOException;

    /**
     * Creates a new tree that is not associated with a store.
     * Note We recommend using the alternative createTree methods for new applications.
     */
    public ITree create();

    /**
     * Creates a new tree and associates it with a store.
     * The store is assumed to be read/write.
     * The store will be created if it does not exist. 
     * Note The arguments to this method are a little confusing, so we 
     * recommend using the alternative createTree methods for new applications.
     * @param storeName The name of the store, if empty (""), the tree is created
     *                  in memory and therefore will not be associated with a file.
     * @throws IOException if the store already exists
     * @throws IllegalArgumentException
     *
     */
    public ITree create(String storeName) throws IllegalArgumentException, IOException;
    /**
     * Creates a new tree and associates it with a store.
     * The store is assumed to be read/write.
     * The store will be created if it does not exist. 
     * Note The arguments to this method are a little confusing, so we 
     * recommend using the alternative createTree methods for new applications.
     * @param storeName The name of the store, if empty (""), the tree is created
     *                  in memory and therefore will not be associated with a file.
     * @param storeType Implementation specific string, may control store type
     * @throws IOException if the store already exists
     * @throws IllegalArgumentException
     *
     */
    public ITree create(String storeName, String storeType) throws IllegalArgumentException, IOException;
    /**
     * Creates a new tree and associates it with a store.
     * The store is assumed to be read/write.
     * The store will be created if it does not exist. 
     * Note The arguments to this method are a little confusing, so we 
     * recommend using the alternative createTree methods for new applications.
     * @param storeName The name of the store, if empty (""), the tree is created
     *                  in memory and therefore will not be associated with a file.
     * @param storeType Implementation specific string, may control store type
     * @param readOnly If true the store is opened readonly, an exception if it does not exist
     * @throws IOException if the store already exists
     * @throws IllegalArgumentException
     *
     */
    public ITree create(String storeName, String storeType, boolean readOnly) throws IllegalArgumentException, IOException;
    /**
     * Creates a new tree and associates it with a store.
     * The store is assumed to be read/write.
     * The store will be created if it does not exist. 
     * Note The arguments to this method are a little confusing, so we 
     * recommend using the alternative createTree methods for new applications.
     * @param storeName The name of the store, if empty (""), the tree is created
     *                  in memory and therefore will not be associated with a file.
     * @param storeType Implementation specific string, may control store type
     * @param readOnly If true the store is opened readonly, an exception if it does not exist
     * @param createNew If false the file must exist, if true the file will be created
     * @throws IOException if the store already exists
     * @throws IllegalArgumentException
     *
     */
    public ITree create(String storeName, String storeType, boolean readOnly, boolean createNew) throws IllegalArgumentException, IOException;
    /**
     * Creates a new tree and associates it with a store.
     * The store is assumed to be read/write.
     * The store will be created if it does not exist. 
     * Note The arguments to this method are a little confusing, so we 
     * recommend using the alternative createTree methods for new applications.
     * @param storeName The name of the store, if empty (""), the tree is created
     *                  in memory and therefore will not be associated with a file.
     * @param storeType Implementation specific string, may control store type
     * @param readOnly If true the store is opened readonly, an exception if it does not exist
     * @param createNew If false the file must exist, if true the file will be created
     * @param options Other options, currently are not specified
     * @throws IOException if the store already exists
     * @throws IllegalArgumentException
     *
     */
    public ITree create(String storeName, String storeType, boolean readOnly, boolean createNew, String options) throws IllegalArgumentException, IOException;

    /**
     * Constants specifying legal values for the mode argument.
     *
     */
    public final static int AUTO = 0, CREATE = 1, RECREATE = 2, READONLY = 3, UPDATE = 4;
} // class or interface