src/main/java/org/apache/sling/testing/serversetup/ServerSetup.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements. See the NOTICE file distributed with this
 * work for additional information regarding copyright ownership. The ASF
 * licenses this file to You 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.apache.sling.testing.serversetup;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Properties;
import java.util.Set;

import junit.framework.AssertionFailedError;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;


/** This is an evolution of the SlingTestBase/JarExecutor 
 *  combination that we had at revision 1201491, used
 *  to control the server side of integration tests.
 *  
 *  This class allows a number of startup and shutdown phases
 *  to be defined, and executes some or all of them in a specified
 *  order, according to a property which lists their names.
 *  
 *  Flexibility in those startup/shutdown phases allows for 
 *  creating test scenarios like automated testing of
 *  system upgrades, where you would for example:
 *  
 *  <pre>
 *  1. Start the old runnable jar
 *  2. Wait for it to be ready
 *  3. Install some bundles and wait for them to be ready
 *  4. Create some content in that version
 *  5. Stop that jar
 *  6. Start the new runnable jar
 *  7. Wait for it to be ready
 *  8. Run tests against that new jar to verify the upgrade 
 *  </pre>
 *
 *  Running the whole thing might take a long time, so when
 *  debugging the upgrade or the tests you might want to 
 *  restart from a state saved at step 5, and only run steps
 *  6 to 8, for example.
 *  
 *  Those steps are SetupPhase objects identified by
 *  their name, and specifying a partial list of names allows you
 *  to run only some of them in a given test run, speeding up
 *  development and troubleshooting as much as possible.
 *  
 *  TODO: the companion samples/integration-tests module 
 *  should be updated to use this class to setup the Sling server
 *  that it tests, instead of the SlingTestBase class that it
 *  currently uses.
 */
public class ServerSetup {
    private final Logger log = LoggerFactory.getLogger(getClass());
    
    /** Context that our SetupPhase objects can use to exchange data */
    private final Map<String, Object> context = new HashMap<String, Object>();
    
    private final List<String> phasesToRun = new ArrayList<String>();
    
    /** Our configuration */
    private Properties config;
    
    /** Prefix used for our property names */
    public static final String PROP_NAME_PREFIX = "server.setup";
    
    /** Config property name: comma-separated list of phases to run */
    public static final String PHASES_TO_RUN_PROP = PROP_NAME_PREFIX + ".phases";
    
    /** Standard suffix for shutdown tasks IDs */
    public static final String SHUTDOWN_ID_SUFFIX = ".shutdown";
    
    /** Our SetupPhases, keyed by their id which must be unique */
    private final Map<String, SetupPhase> phases = new HashMap<String, SetupPhase>();
    
    /** List of phases that already ran */
    private final Set<String> donePhases = new HashSet<String>();
    
    /** List of phases that failed */
    private final Set<String> failedPhases = new HashSet<String>();
    
    /** Context attribute: server access URL */
    public static final String SERVER_BASE_URL = "server.base.url";
    
    /** Shutdown hook thread */
    private Thread shutdownHook;
    
    @SuppressWarnings("serial")
    public static class SetupException extends Exception {
        public SetupException(String reason) {
            super(reason);
        }
        
        public SetupException(String reason, Throwable cause) {
            super(reason, cause);
        }
    };
    
    /** Runs all startup phases that have not run yet,
     *  and throws an Exception or call Junit's fail()
     *  method if one of them fails or failed in a 
     *  previous call of this method.
     *  
     *  This can be called several times, will only run
     *  setup phases that have not run yet.
     */
    public synchronized void setupTestServer() throws Exception {
        
        // On the first call, list our available phases
        if(donePhases.isEmpty()) {
            if(log.isInfoEnabled()) {
                final List<String> ids = new ArrayList<String>();
                ids.addAll(phases.keySet());
                Collections.sort(ids);
                log.info("Will run SetupPhases {} out of {}", phasesToRun, ids);
            }
        }
        
        // Run all startup phases that didn't run yet
        runRemainingPhases(true);
        
        // And setup our shutdown hook
        if(shutdownHook == null) {
            shutdownHook = new Thread(getClass().getSimpleName() + "Shutdown") {
                public void run() {
                    try {
                        shutdown();
                    } catch(Exception e) {
                        log.warn("Exception in shutdown hook", e);
                    }
                    
                }
            };
            Runtime.getRuntime().addShutdownHook(shutdownHook);
            log.info("Shutdown hook added to run shutdown phases");
        }
    }
    
    /** Run phases that haven't run yet */
    private void runRemainingPhases(boolean isStartup) throws Exception {
        final String mode = isStartup ? "startup" : "shutdown";
        
        // In startup mode, fail if any phases failed previously
        // (in shutdown mode it's probably safer to try to run cleanup phases)
        if(isStartup && !failedPhases.isEmpty()) {
            throw new SetupException("Some SetupPhases previously failed: " + failedPhases);
        }
        
        for(String id : phasesToRun) {
            final SetupPhase p = phases.get(id);
            
            if(donePhases.contains(id)) {
                log.debug("SetupPhase ({}) with id {} already ran, ignored", mode, id);
                continue;
            }
            
            if(p == null) {
                log.info("SetupPhase ({}) with id {} not found, ignored", mode, id);
                donePhases.add(id);
                continue;
            }
            
            if(p.isStartupPhase() == isStartup) {
                log.info("Executing {} phase: {}", mode, p); 
                try {
                    p.run(this);
                } catch(Exception e) {
                    failedPhases.add(id);
                    throw e;
                } catch (AssertionFailedError ae) {
                    // Some of our tools throw this, might not to avoid it in the future
                    failedPhases.add(id);
                    throw new Exception("AssertionFailedError in runRemainingPhases", ae);
                } finally {
                    donePhases.add(id);
                }
            }
        }
    }
    
    /** Called by a shutdown hook to run
     *  all shutdown phases, but can also
     *  be called explicitly, each shutdown
     *  phase only runs once anyway.
     */
    public void shutdown() throws Exception {
        runRemainingPhases(false);
    }
    
    /** Return a context that {@SetupPhase} can use to 
     *  communicate among them and with the outside.
     */
    public Map<String, Object> getContext() {
        return context;
    }
    
    /** Set configuration and reset our lists of phases
     *  that already ran or failed.
     */
    public void setConfig(Properties props) {
        config = props;

        final String str = props.getProperty(PHASES_TO_RUN_PROP);
        phasesToRun.clear();
        final String [] phases = str == null ? new String [] {} : str.split(",");
        for(int i=0 ; i < phases.length; i++) {
            phases[i] = phases[i].trim();
        }
        phasesToRun.addAll(Arrays.asList(phases));
        
        if(phasesToRun.isEmpty()) {
            log.warn("No setup phases defined, {} is empty, is that on purpose?", PHASES_TO_RUN_PROP);
        }
        
        donePhases.clear();
        failedPhases.clear();
    }
    
    /** Return the configuration Properties that were set
     *  by {@link #setConfig}
     */
    public Properties getConfig() {
        return config;
    }
    
    /** Return the IDs of phases that should run */
    public List<String> getPhasesToRun() {
        return Collections.unmodifiableList(phasesToRun);
    }

    /** Add a SetupPhase to our list. Its ID must be
     *  unique in that list.
     */
    public void addSetupPhase(SetupPhase p) throws SetupException {
        if(phases.containsKey(p.getId())) {
            throw new SetupException("A SetupPhase with ID=" + p.getId() + " is already in our list:" + phases.keySet());
        }
        phases.put(p.getId(), p);
    }
}