1 /**************************************************************** 2 * Licensed to the Apache Software Foundation (ASF) under one * 3 * or more contributor license agreements. See the NOTICE file * 4 * distributed with this work for additional information * 5 * regarding copyright ownership. The ASF licenses this file * 6 * to you under the Apache License, Version 2.0 (the * 7 * "License"); you may not use this file except in compliance * 8 * with the License. You may obtain a copy of the License at * 9 * * 10 * http://www.apache.org/licenses/LICENSE-2.0 * 11 * * 12 * Unless required by applicable law or agreed to in writing, * 13 * software distributed under the License is distributed on an * 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY * 15 * KIND, either express or implied. See the License for the * 16 * specific language governing permissions and limitations * 17 * under the License. * 18 ****************************************************************/ 19 20 package org.apache.jsieve.commands; 21 22 import org.apache.jsieve.Arguments; 23 import org.apache.jsieve.Block; 24 import org.apache.jsieve.ExecutableCommand; 25 import org.apache.jsieve.SieveContext; 26 import org.apache.jsieve.exception.CommandException; 27 import org.apache.jsieve.exception.SieveException; 28 import org.apache.jsieve.mail.MailAdapter; 29 30 /** 31 * Abstract class AbstractCommand defines a framework of common behavior for 32 * Sieve Commands. 33 */ 34 public abstract class AbstractCommand implements ExecutableCommand { 35 36 /** 37 * Constructor for AbstractCommand. 38 */ 39 public AbstractCommand() { 40 super(); 41 } 42 43 /** 44 * Framework method validateState is invoked before a Sieve Command is 45 * executed to validate its state. Subclass methods are expected to override 46 * or extend this method to perform their own validation as appropriate. 47 * 48 * @param context 49 * <code>SieveContext</code> giving contextual information, not 50 * null 51 * @throws CommandException 52 */ 53 protected void validateState(SieveContext context) throws CommandException { 54 } 55 56 /** 57 * Framework method updateState is invoked after a Sieve Command has 58 * executed to update the Sieve state. Subclass methods are expected to 59 * override or extend this method to update state as appropriate. 60 * 61 * @param context 62 * TODO 63 */ 64 protected void updateState(SieveContext context) { 65 } 66 67 /** 68 * Framework method validateArguments is invoked before a Sieve Command is 69 * executed to validate its arguments. Subclass methods are expected to 70 * override or extend this method to perform their own validation as 71 * appropriate. 72 * 73 * @param arguments 74 * @param context 75 * <code>SieveContext</code> giving contextual information, not 76 * null 77 * @throws SieveException 78 */ 79 protected void validateArguments(Arguments arguments, SieveContext context) 80 throws SieveException { 81 if (!arguments.getArgumentList().isEmpty()) 82 throw context.getCoordinate().syntaxException( 83 "Found unexpected arguments"); 84 } 85 86 /** 87 * Framework method validateBlock is invoked before a Sieve Command is 88 * executed to validate its Block. Subclass methods are expected to override 89 * or extend this method to perform their own validation as appropriate. 90 * 91 * @param block 92 * @param context 93 * <code>ScriptCoordinate</code> giving positional information, 94 * not null 95 * @throws SieveException 96 */ 97 protected void validateBlock(Block block, SieveContext context) 98 throws SieveException { 99 if (null != block) 100 throw context.getCoordinate().syntaxException( 101 "Found unexpected Block. Missing ';'?"); 102 } 103 104 /** 105 * <p> 106 * Method execute executes a basic Sieve Command after first invoking 107 * framework methods to validate that Sieve is in a legal state to invoke 108 * the Command and that the Command arguments are legal. After invocation, a 109 * framework method is invoked to update the state. 110 * </p> 111 * 112 * <p> 113 * Also, 114 * </p> 115 * 116 * @see org.apache.jsieve.Executable#execute(MailAdapter, SieveContext) 117 */ 118 public Object execute(MailAdapter mail, Arguments arguments, Block block, 119 SieveContext context) throws SieveException { 120 validateState(context); 121 validateArguments(arguments, context); 122 validateBlock(block, context); 123 Object result = executeBasic(mail, arguments, block, context); 124 updateState(context); 125 return result; 126 } 127 128 /** 129 * Abstract method executeBasic invokes a Sieve Command. 130 * 131 * @param mail 132 * @param arguments 133 * @param block 134 * @param context 135 * <code>SieveContext</code> giving contextual information, not 136 * null 137 * @return Object 138 * @throws SieveException 139 */ 140 abstract protected Object executeBasic(MailAdapter mail, 141 Arguments arguments, Block block, SieveContext context) 142 throws SieveException; 143 144 }