001/*
002 * Copyright 2008 The Kuali Foundation
003 * 
004 * Licensed under the Educational Community License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 * 
008 * http://www.opensource.org/licenses/ecl2.php
009 * 
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.kuali.ole.sys.document.validation;
017
018import java.util.List;
019import java.util.Map;
020
021import org.apache.commons.lang.StringUtils;
022import org.kuali.ole.sys.document.validation.event.AttributedDocumentEvent;
023
024/**
025 * An abstract class that creates an easy way to branch between validations.  Basically,
026 * extenders set a branch map - a map where the key is the name of the branch and the value
027 * is the validation to perform to check on that branch.  Extenders also implement the
028 * determineBranch method, which returns the name of the branch to validate against;
029 * if null is returned, then no validation will occur.
030 */
031public abstract class BranchingValidation extends ParameterizedValidation implements Validation {
032    protected Map<String, Validation> branchMap;
033    protected List<ValidationFieldConvertible> parameterProperties;
034    protected boolean shouldQuitOnFail = false;
035
036    /**
037     * Determines which branch, if any, within the branchMap should be used as the validation to take.
038     * @param event the event which triggered this validation
039     * @return the name of the branch to take, or a null or empty string to not take any branch and simply pass validation as true
040     */
041    protected abstract String determineBranch(AttributedDocumentEvent event);
042    
043    /**
044     * Note: these parameter properties only help determine what branching should take place; these properties will not affect in anyway the branch children
045     * @see org.kuali.ole.sys.document.validation.Validation#getParameterProperties()
046     */
047    public List<ValidationFieldConvertible> getParameterProperties() {
048        return this.parameterProperties;
049    }
050
051    /**
052     * Sets the parameterProperties attribute value.
053     * @param parameterProperties The parameterProperties to set.
054     */
055    public void setParameterProperties(List<ValidationFieldConvertible> parameterProperties) {
056        this.parameterProperties = parameterProperties;
057    }
058
059    /**
060     * @see org.kuali.ole.sys.document.validation.Validation#shouldQuitOnFail()
061     */
062    public boolean shouldQuitOnFail() {
063        return shouldQuitOnFail;
064    }
065
066    /**
067     * Sets the shouldQuitOnFail attribute value.
068     * @param shouldQuitOnFail The shouldQuitOnFail to set.
069     */
070    public void setShouldQuitOnFail(boolean shouldQuitOnFail) {
071        this.shouldQuitOnFail = shouldQuitOnFail;
072    }
073
074    /**
075     * 
076     * @see org.kuali.ole.sys.document.validation.Validation#stageValidation(org.kuali.ole.sys.document.validation.event.AttributedDocumentEvent)
077     */
078    public boolean stageValidation(AttributedDocumentEvent event) {
079        populateParametersFromEvent(event);
080        return validate(event);
081    }
082
083    /**
084     * Using the branch name returned by determineBranch(), validates the event against the corresponding
085     * branch in the branch map.  If a null or empty string is returned from determineBrach(), this method
086     * simply returns true; if there is no validation in the branchMap for the given name, an IllegalStateException
087     * is thrown.
088     * @see org.kuali.ole.sys.document.validation.Validation#validate(org.kuali.ole.sys.document.validation.event.AttributedDocumentEvent)
089     */
090    public boolean validate(AttributedDocumentEvent event) {
091        String branchName = determineBranch(event);
092        if (!StringUtils.isBlank(branchName)) {
093            Validation validation = branchMap.get(branchName);
094            if (validation == null) {
095                throw new IllegalStateException("Branching Validation "+this.getClass().getName()+" cannot find a branch named "+branchName);
096            }
097            return validation.stageValidation(event);
098        } else {
099            return true;
100        }
101    }
102
103    /**
104     * Gets the branchMap attribute. 
105     * @return Returns the branchMap.
106     */
107    public Map<String, Validation> getBranchMap() {
108        return branchMap;
109    }
110
111    /**
112     * Sets the branchMap attribute value.
113     * @param branchMap The branchMap to set.
114     */
115    public void setBranchMap(Map<String, Validation> branchMap) {
116        this.branchMap = branchMap;
117    }
118
119}