View Javadoc

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 }