View Javadoc

1   /*
2    * $Id: Action.java 121 2004-11-01 13:05:23Z josem $
3    *
4    * Tarsis
5    * Copyright (C) 2002 Talika Open Source Group
6    *
7    * This program is free software; you can redistribute it and/or modify
8    * it under the terms of the GNU General Public License as published by
9    * the Free Software Foundation; either version 2 of the License, or
10   * (at your option) any later version.
11   *
12   * This program is distributed in the hope that it will be useful,
13   * but WITHOUT ANY WARRANTY; without even the implied warranty of
14   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15   * GNU General Public License for more details.
16   *
17   * You should have received a copy of the GNU General Public License
18   * along with this program; if not, write to the Free Software
19   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
20   *
21   */
22  
23  package org.talika.tarsis.command.action;
24  
25  import org.talika.tarsis.command.Request;
26  import org.talika.tarsis.command.Response;
27  import org.talika.tarsis.context.Context;
28  
29  /**
30   * Interface that defines a command action in Tarsis MVC Framework.<br>
31   * <br>
32   * The command action is the piece of software responsible of bussines logic.
33   * Action is executed when the command is invoked.<br>
34   * The interface define methods to initialize an action, validate a request, service
35   * a request and to put action out of service. These are known as life-cycle methods
36   * and are called in the following sequence:
37   * <ol>
38   * <li>
39   *     The action is instatiated and then initialized calling <code>init</code>
40   *     method.
41   * </li>
42   * <li>
43   *     Everytime command is invoked, if the command is validable then the
44   *     <code>validate</code> is called to validate request and then the
45   *     <code>execute</code> method is invoked.
46   * </li>
47   * <li>
48   *     The action is taken out of service, then destroyed with the
49   *     <code>destroy</code> method, then garbage collected and finalized.
50   * </li>
51   * </ol>
52   *
53   * @author  Jose M. Palomar
54   * @version $Revision: 121 $
55   * @see org.talika.tarsis.command.Command
56   * @see org.talika.tarsis.command.view.View
57   */
58  public interface Action {
59  
60      // Methods
61      /**
62       * Called by Tarsis MVC Framework to initialize action.<br>
63       * <br>
64       * This method should be used to initialize any static resource needed by action.
65       *
66       * @param context Context contex of Tarsis MVC Framework.
67       * @throws ActionException if an exception has occurred that interferes with the
68       * action's normal operation.
69       * @see UnrecoverableException
70       */
71      void init(Context context) throws ActionException;
72  
73      /**
74       * Called by Tarsis MVC Framework to validate request everytime command is
75       * invoked.<br>
76       * <br>
77       * This method is called only if command is validable.
78       *
79       * @param request Request object representing client's request.
80       * @throws ActionException if an exception has occurred that interferes with the
81       * action's normal operation.
82       */
83      void validate(Request request) throws ActionException;
84  
85      /**
86       * Called by Tarsis MVC Framework to handle request everytime command is
87       * invoked.<br>
88       *
89       * @param request Request object representing client's request.
90       * @param response Response object representing client's reponse.
91       * @return String the name of view to be forwarded or <code>null</code> for
92       * default view.
93       * @throws ActionException if an exception has occurred that interferes with the
94       * action's normal operation.
95       */
96      String execute(Request request, Response response) throws ActionException;
97  
98      /**
99       * Called by Tarsis MVC Framework to destroy action.
100      */
101     void destroy();
102 
103 }