001    
002    /*
003     * Copyright (C) 2011 Archie L. Cobbs. All rights reserved.
004     *
005     * $Id: SchemaUpdate.java 211 2012-01-14 18:28:54Z archie.cobbs $
006     */
007    
008    package org.dellroad.stuff.schema;
009    
010    import java.util.List;
011    import java.util.Set;
012    
013    /**
014     * A one-time database schema update. Instances typically perform changes to the database schema, though non-schema updates
015     * that just manipulate the data in the database are perfectly valid as well.
016     *
017     * <p>
018     * Each {@link SchemaUpdate} has a unique name among all updates ever applied to a single database, and zero
019     * or more required predecessors, which are other dependent updates that must be applied first.
020     * </p>
021     *
022     * <p>
023     * Once an update has been applied to a database, it must not be changed; otherwise, inconsistencies
024     * can exist between databases that were updated using the old version vs. databases that were
025     * updated using the new version. If an update has been applied but had the wrong behavior, instead of
026     * changing the update, it's better to create a new update that depends on the first as a predecessor
027     * and corrects the mistake.
028     * </p>
029     *
030     * <p>
031     * If you do have to change an update after it has been applied, then those databases that have
032     * already seen the previous version of the update must be manually corrected so they are in the
033     * same state that the new version of the update would have left them.
034     * </p>
035     *
036     * @param <T> database transaction type
037     */
038    public interface SchemaUpdate<T> {
039    
040        /**
041         * Get the unique name of this update. This name must be unique among all updates ever applied to the database
042         * and must never change once this update has been applied to any database.
043         *
044         * @return the name of this update; must not be the empty string
045         */
046        String getName();
047    
048        /**
049         * Get the the other updates (if any) that must be applied <b>before</b> this update may be applied.
050         *
051         * @return set of zero or more other updates
052         * @see #getName
053         */
054        Set<SchemaUpdate<T>> getRequiredPredecessors();
055    
056        /**
057         * Get the action(s) that comprise this update. Ideally, individual actions should be atomic database operations, i.e.,
058         * each one should either finish completely, or else leave the database in a state where it can be tried again.
059         * In any case, each action will be applied within its own transaction when transactions are supported by the database
060         * unless {@link #isSingleAction} returns true.
061         *
062         * @return a list of zero or more actions to apply
063         * @see #isSingleAction
064         */
065        List<? extends DatabaseAction<T>> getDatabaseActions();
066    
067        /**
068         * Determine whether, if this instance contains multiple individual actions, should they be applied in a single
069         * transaction and recorded as a single update. Normally this is false. If true, partially completed updates
070         * can result if one of the action fails.
071         */
072        boolean isSingleAction();
073    }
074