AutoControllerElement


1   /* ====================================================================
2    * The Jcorporate Apache Style Software License, Version 1.2 05-07-2002
3    *
4    * Copyright (c) 1995-2002 Jcorporate Ltd. All rights reserved.
5    *
6    * Redistribution and use in source and binary forms, with or without
7    * modification, are permitted provided that the following conditions
8    * are met:
9    *
10   * 1. Redistributions of source code must retain the above copyright
11   *    notice, this list of conditions and the following disclaimer.
12   *
13   * 2. Redistributions in binary form must reproduce the above copyright
14   *    notice, this list of conditions and the following disclaimer in
15   *    the documentation and/or other materials provided with the
16   *    distribution.
17   *
18   * 3. The end-user documentation included with the redistribution,
19   *    if any, must include the following acknowledgment:
20   *       "This product includes software developed by Jcorporate Ltd.
21   *        (http://www.jcorporate.com/)."
22   *    Alternately, this acknowledgment may appear in the software itself,
23   *    if and wherever such third-party acknowledgments normally appear.
24   *
25   * 4. "Jcorporate" and product names such as "Expresso" must
26   *    not be used to endorse or promote products derived from this
27   *    software without prior written permission. For written permission,
28   *    please contact info@jcorporate.com.
29   *
30   * 5. Products derived from this software may not be called "Expresso",
31   *    or other Jcorporate product names; nor may "Expresso" or other
32   *    Jcorporate product names appear in their name, without prior
33   *    written permission of Jcorporate Ltd.
34   *
35   * 6. No product derived from this software may compete in the same
36   *    market space, i.e. framework, without prior written permission
37   *    of Jcorporate Ltd. For written permission, please contact
38   *    partners@jcorporate.com.
39   *
40   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
41   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
42   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
43   * DISCLAIMED.  IN NO EVENT SHALL JCORPORATE LTD OR ITS CONTRIBUTORS
44   * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
45   * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
46   * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
47   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
48   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
49   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
50   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
51   * SUCH DAMAGE.
52   * ====================================================================
53   *
54   * This software consists of voluntary contributions made by many
55   * individuals on behalf of the Jcorporate Ltd. Contributions back
56   * to the project(s) are encouraged when you make modifications.
57   * Please send them to support@jcorporate.com. For more information
58   * on Jcorporate Ltd. and its products, please see
59   * <http://www.jcorporate.com/>.
60   *
61   * Portions of this software are based upon other open source
62   * products and are subject to their respective licenses.
63   */
64  
65  package com.jcorporate.expresso.services.controller.ui;
66  
67  import com.jcorporate.expresso.core.controller.Block;
68  import com.jcorporate.expresso.core.controller.ControllerException;
69  import com.jcorporate.expresso.core.controller.ControllerRequest;
70  import com.jcorporate.expresso.core.controller.ControllerResponse;
71  import com.jcorporate.expresso.core.controller.ErrorCollection;
72  import com.jcorporate.expresso.core.controller.Input;
73  import com.jcorporate.expresso.core.dataobjects.DataObject;
74  
75  /**
76   * This interface is for objects that provide an automatic rendering capability
77   * to the system.  It's in sort of a way a bridge between DBObjects and
78   * ControllerElements
79   *
80   * @author Michael Rimov, portions from Adam Rossi, Michael Nash, Shash Chatterjee
81   * @since Expresso 5.0
82   */
83  public interface AutoControllerElement {
84  
85  
86      /**
87       * Renders an Input in a update method per field name.
88       *
89       * @param response     a ControllerResponse Object
90       * @param dbobj        A DBObject to transform into an Input
91       * @param fieldName    the name of the field to render
92       * @param defaultValue the default value to use in the field
93       * @param readOnly     true if the Input should be a read only input.
94       * @return an instantiated Input object
95       */
96      public Input renderDBObjectField(ControllerResponse response,
97                                       DataObject dbobj,
98                                       String   fieldName,
99                                       String   defaultValue,
100                                      boolean readOnly) throws ControllerException;
101 
102 
103     /**
104      * Creates a DBObject Block that contains all the non-secret fields for
105      * the DBObject.  The Block will have a nested Output that matches DBObject's
106      * description unless one is not supplied in which case the nested Output will
107      * have the title "Untitled"
108      *
109      * @param response a <code>ControllerResponse</code> Object
110      * @param request  The <code>ControllerRequest</code> Object
111      * @param dbobj    The dbObject to automatically render.
112      * @return an instantiated DBObject block based upon the parameters
113      * @throws ControllerException if there's an error rendering the DBObject
114      */
115     public Block createDBObjectBlock(ControllerRequest request,
116                                      ControllerResponse response,
117                                      DataObject dbobj)
118             throws ControllerException;
119 
120 
121     /**
122      * Creates a DBObject Block that contains all the non-secret fields for
123      * the DBObject.
124      *
125      * @param response a <code>ControllerResponse</code> Object
126      * @param request  The <code>ControllerRequest</code> Object
127      * @param title    The title to give this block.  The system renders a nested
128      *                 Output called "block-title" for the block that contains this data.
129      * @param dbobj    The dbObject to automatically render.
130      * @return an instantiated DBObject block based upon the parameters
131      * @throws ControllerException if there's an error rendering the DBObject
132      */
133     public Block createDBObjectBlock(ControllerRequest request,
134                                      ControllerResponse response,
135                                      String   title,
136                                      DataObject dbobj) throws ControllerException;
137 
138     /**
139      * Convienence method if you only expect one DBObject to be returned from
140      * a particular form.
141      *
142      * @param request   The ControllerRequest object handed down by the framework
143      * @param oneObject A single DBObject to fill into fill out from the block.
144      * @param ec        An instantiated ErrorCollection that is filled in with any error
145      * @return an instatiated <code>DBObject</code>
146      * @throws ControllerException      if there's an error parsing the block or communicating
147      *                                  with the underlying DBObject
148      * @throws IllegalArgumentException if request, DBObjectNames, or ec is null
149      */
150     public DataObject parseBlock(ControllerRequest request,
151                                  DataObject oneObject,
152                                  ErrorCollection ec) throws ControllerException;
153 
154     /**
155      * Convienence method if you only expect one DBObject to be returned from
156      * a particular form, and unlike the ParseBlock, there is no DBOBject name
157      * prefix attached to the parameter names.  This is similar to the ControllerRequest
158      * validateDBObject functionality, but we're consolodating things here.
159      *
160      * @param request   The ControllerRequest object handed down by the framework
161      * @param oneObject a Single DBObject to fill out.
162      * @param ec        An instantiated ErrorCollection that is filled in with any error
163      * @return an instatiated <code>DBObject</code>
164      * @throws ControllerException      if there's an error parsing the block or communicating
165      *                                  with the underlying DBObject
166      * @throws IllegalArgumentException if request, DBObjectNames, or ec is null
167      */
168     public DataObject parseDBObject(ControllerRequest request,
169                                     DataObject oneObject,
170                                     ErrorCollection ec) throws ControllerException;
171 
172 
173     public DataObject parseDBObject(ControllerRequest request,
174                                     DataObject oneObject, ErrorCollection ec,
175                                     boolean validate)
176             throws ControllerException;
177 
178     /**
179      * Parses the appropriate DBObject from the block.  Returns the fully constructed
180      * DBOBject including any errors in the DBObject
181      *
182      * @param request    The ControllerRequest object handed down by the framework
183      * @param theObjects A pre-instantiated group of DBObjects in which you expect
184      *                   to have the fields overwritten/filled.  By using instantiated DBObjects,
185      *                   you can pre-fill any potentially blank fields and thus remove any Errors.
186      * @param ec         An instantiated ErrorCollection that is filled in with any error
187      * @return an array of  <code>DBObject</code>s
188      * @throws ControllerException if there's an error parsing the block or communicating
189      *                             with the underlying DBObject
190      */
191     public DataObject[] parseBlocks(ControllerRequest request,
192                                     DataObject[] theObjects,
193                                     ErrorCollection ec) throws ControllerException;
194 
195 
196     /**
197      * Takes the Controller Request and appropriately parses a string for a
198      * particular field.  If the field is a Date, then it parses it as such,
199      * if it is money, then it perses it as such.  Etc.
200      *
201      * @param request       the ControllerRequest object
202      * @param fieldName     the name of the field to parse
203      * @param dbobj         The DBObject for which we're going to put the field to
204      * @param parameterName The name of the http paramter to parse  May be null
205      *                      in which case, the funciton will by default use the fieldName as the
206      *                      parameter name.
207      * @param ec            An instantiated ErrorCollection object that gets filled out
208      *                      by the function.
209      * @return an properly parsed String
210      * @throws ControllerException if there's an error parsing the block or communicating
211      *                             with the underlying DBObject
212      */
213     public String   parseSingleInput(ControllerRequest request,
214                                    DataObject dbobj,
215                                    String   fieldName,
216                                    String   parameterName,
217                                    ErrorCollection ec) throws ControllerException;
218 
219     /**
220      * Allows for easy overriding of the style name for special customization
221      *
222      * @return a String naming the CSS class to use under normal circumstanes.
223      */
224     public String   getNormalStyle() throws ControllerException;
225 
226     /**
227      * Allows for easy overriding fo the style name for special customization.
228      *
229      * @return a String naming the CSS class to use to render required fields.
230      */
231     public String   getRequiredStyle() throws ControllerException;
232 
233     /**
234      * Allows for easy overriding fo the style name for special customization.
235      *
236      * @return the class name that is used for error conditions.
237      */
238     public String   getErrorStyle() throws ControllerException;
239 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags