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 not null 62 */ 63 protected void updateState(SieveContext context) { 64 } 65 66 /** 67 * Framework method validateArguments is invoked before a Sieve Command is 68 * executed to validate its arguments. Subclass methods are expected to 69 * override or extend this method to perform their own validation as 70 * appropriate. 71 * 72 * @param arguments 73 * @param context 74 * <code>SieveContext</code> giving contextual information, not 75 * null 76 * @throws SieveException 77 */ 78 protected void validateArguments(Arguments arguments, SieveContext context) 79 throws SieveException { 80 if (!arguments.getArgumentList().isEmpty()) 81 throw context.getCoordinate().syntaxException( 82 "Found unexpected arguments"); 83 } 84 85 /** 86 * Framework method validateBlock is invoked before a Sieve Command is 87 * executed to validate its Block. Subclass methods are expected to override 88 * or extend this method to perform their own validation as appropriate. 89 * 90 * @param block 91 * @param context 92 * <code>ScriptCoordinate</code> giving positional information, 93 * not null 94 * @throws SieveException 95 */ 96 protected void validateBlock(Block block, SieveContext context) 97 throws SieveException { 98 if (null != block) 99 throw context.getCoordinate().syntaxException( 100 "Found unexpected Block. Missing ';'?"); 101 } 102 103 /** 104 * <p> 105 * Method execute executes a basic Sieve Command after first invoking 106 * framework methods to validate that Sieve is in a legal state to invoke 107 * the Command and that the Command arguments are legal. After invocation, a 108 * framework method is invoked to update the state. 109 * </p> 110 * 111 * <p> 112 * Also, 113 * </p> 114 * 115 * @see org.apache.jsieve.Executable#execute(MailAdapter, SieveContext) 116 */ 117 public Object execute(MailAdapter mail, Arguments arguments, Block block, 118 SieveContext context) throws SieveException { 119 validateState(context); 120 validateArguments(arguments, context); 121 validateBlock(block, context); 122 Object result = executeBasic(mail, arguments, block, context); 123 updateState(context); 124 return result; 125 } 126 127 /** 128 * Abstract method executeBasic invokes a Sieve Command. 129 * 130 * @param mail 131 * @param arguments 132 * @param block 133 * @param context 134 * <code>SieveContext</code> giving contextual information, not 135 * null 136 * @return Object 137 * @throws SieveException 138 */ 139 abstract protected Object executeBasic(MailAdapter mail, 140 Arguments arguments, Block block, SieveContext context) 141 throws SieveException; 142 143 }