001    package org.cumulus4j.store.datastoreversion;
002    
003    import javax.jdo.PersistenceManager;
004    
005    import org.cumulus4j.store.model.KeyStoreRef;
006    
007    /**
008     * Command for managing a datastore version (change).
009     * <p>
010     * A new instance of a class implementing this interface is created for each run of
011     * {@link DatastoreVersionManager#applyOnce(org.cumulus4j.store.crypto.CryptoContext)}. Therefore, implementations
012     * do not need to be thread-safe and can share data in fields across implementation methods.
013     * <p>
014     * Implementations should subclass {@link AbstractDatastoreVersionCommand} instead of directly implementing
015     * this interface.
016     * <p>
017     * Implementations must be manually registered in {@link org.cumulus4j.store.datastoreversion.DatastoreVersionManager}!
018     * @author Marco หงุ่ยตระกูล-Schulze - marco at nightlabs dot de
019     */
020    public interface DatastoreVersionCommand {
021            String getCommandID();
022    
023            /**
024             * Get the version of this command.
025             * <p>
026             * This version must be incremented, if this command is modified!
027             * <p>
028             * Note, that a {@link #isFinal() final} command cannot be modified!!! You can only modify a final command
029             * if this command was newly introduced in the current SNAPSHOT. <b><u>Never</u> modify a command after it
030             * was released!!!</b>
031             * @return the version of this command.
032             */
033            int getCommandVersion();
034    
035            /**
036             * Perform the upgrade or do whatever this command has to do.
037             * @param commandApplyParam various arguments bundled for better compatibility with future extensions. Never <code>null</code>.
038             */
039            void apply(CommandApplyParam commandApplyParam);
040    
041            /**
042             * Is this command final, i.e. applied only once, or should this command be applied again, when the commandVersion
043             * was incremented?
044             * @return <code>true</code>, if this command is final; <code>false</code> otherwise.
045             */
046            boolean isFinal();
047    
048            /**
049             * Is this command dependent on the key-store? If yes, it is applied separately for every key-store, i.e. with different
050             * {@link KeyStoreRef#getKeyStoreRefID() keyStoreRefID}s. If no, it is applied only once
051             * {@link KeyStoreRef#GLOBAL_KEY_STORE_REF_ID globally}.
052             * @return <code>true</code>, if this command should be applied once per key-store (and per underlying {@link PersistenceManager}
053             * [there might be two if data and index is stored separately]); <code>false</code> otherwise.
054             */
055            boolean isKeyStoreDependent();
056    }