View Javadoc

1   /*
2    * $Id: ConfigHelperInterface.java 421119 2006-07-12 04:49:11Z wsmoak $
3    *
4    * Copyright 1999-2004 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * 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, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  package org.apache.struts.config;
19  
20  import org.apache.struts.action.ActionForm;
21  import org.apache.struts.action.ActionFormBean;
22  import org.apache.struts.action.ActionForward;
23  import org.apache.struts.action.ActionMapping;
24  import org.apache.struts.action.ActionMessages;
25  import org.apache.struts.upload.MultipartRequestWrapper;
26  import org.apache.struts.util.MessageResources;
27  
28  /***
29   * <p> NOTE: THIS CLASS IS UNDER ACTIVE DEVELOPMENT. THE CURRENT CODE IS
30   * WRITTEN FOR CLARITY NOT EFFICIENCY. NOT EVERY API FUNCTION HAS BEEN
31   * IMPLEMENTED YET. </p><p> A helper object to expose the Struts shared
32   * resources, which are be stored in the application, session, or request
33   * contexts, as appropriate. </p><p> An instance should be created for each
34   * request processed. The  methods which return resources from the request or
35   * session contexts are not thread-safe. </p><p> Provided for use by other
36   * servlets in the application so they can easily access the Struts shared
37   * resources. </p><p> The resources are stored under attributes in the
38   * application, session, or request contexts. </p><p> The ActionConfig methods
39   * simply return the resources from under the context and key used by the
40   * Struts ActionServlet when the resources are created. </p>
41   *
42   * @version $Rev: 421119 $ $Date: 2005-05-07 12:11:38 -0400 (Sat, 07 May 2005)
43   *          $
44   * @since Struts 1.1
45   */
46  public interface ConfigHelperInterface {
47      // ------------------------------------------------ Application Context
48  
49      /***
50       * <p> The <code>org.apache.struts.action.ActionFormBeans</code>
51       * collection for this application. </p>
52       */
53      public ActionMessages getActionMessages();
54  
55      /***
56       * <p> The application resources for this application. </p>
57       */
58      public MessageResources getMessageResources();
59  
60      /***
61       * <p> The path-mapped pattern (<code>/action/*</code>) or extension
62       * mapped pattern ((<code>*.do</code>) used to determine our Action URIs
63       * in this application. </p>
64       */
65      public String getServletMapping();
66  
67      // ---------------------------------------------------- Session Context
68  
69      /***
70       * <p> The transaction token stored in this session, if it is used. </p>
71       */
72      public String getToken();
73  
74      // ---------------------------------------------------- Request Context
75  
76      /***
77       * <p> The runtime JspException that may be been thrown by a Struts tag
78       * extension, or compatible presentation extension, and placed in the
79       * request. </p>
80       */
81      public Throwable getException();
82  
83      /***
84       * <p> The multipart object for this request. </p>
85       */
86      public MultipartRequestWrapper getMultipartRequestWrapper();
87  
88      /***
89       * <p> The <code>org.apache.struts.ActionMapping</code> instance for this
90       * request. </p>
91       */
92      public ActionMapping getMapping();
93  
94      // ---------------------------------------------------- Utility Methods
95  
96      /***
97       * <p> Return true if a message string for the specified message key is
98       * present for the user's Locale. </p>
99       *
100      * @param key Message key
101      */
102     public boolean isMessage(String key);
103 
104     /***
105      * <p> Retrieve and return the <code>ActionForm</code> bean associated
106      * with this mapping, creating and stashing one if necessary.  If there is
107      * no form bean associated with this mapping, return <code>null</code>.
108      * </p>
109      */
110     public ActionForm getActionForm();
111 
112     /***
113      * <p> Return the form bean definition associated with the specified
114      * logical name, if any; otherwise return <code>null</code>. </p>
115      *
116      * @param name Logical name of the requested form bean definition
117      */
118     public ActionFormBean getFormBean(String name);
119 
120     /***
121      * <p> Return the forwarding associated with the specified logical name,
122      * if any; otherwise return <code>null</code>. </p>
123      *
124      * @param name Logical name of the requested forwarding
125      */
126     public ActionForward getActionForward(String name);
127 
128     /***
129      * <p> Return the mapping associated with the specified request path, if
130      * any; otherwise return <code>null</code>. </p>
131      *
132      * @param path Request path for which a mapping is requested
133      */
134     public ActionMapping getActionMapping(String path);
135 
136     /***
137      * <p> Return the form action converted into an action mapping path.  The
138      * value of the <code>action</code> property is manipulated as follows in
139      * computing the name of the requested mapping:
140      *
141      * <ul>
142      *
143      * <li>Any filename extension is removed (on the theory that extension
144      * mapping is being used to select the controller servlet).</li>
145      *
146      * <li>If the resulting value does not start with a slash, then a slash is
147      * prepended.</li>
148      *
149      * </ul> <p> :FIXME: Bad assumption =:o) </p>
150      */
151     public String getActionMappingName(String action);
152 
153     /***
154      * <p> Return the form action converted into a server-relative URL. </p>
155      */
156     public String getActionMappingURL(String action);
157 
158     /***
159      * <p> Return the url encoded to maintain the user session, if any. </p>
160      */
161     public String getEncodeURL(String url);
162 
163     // ------------------------------------------------ Presentation API
164 
165     /***
166      * <p> Renders the reference for a HTML <base> element </p>
167      */
168     public String getOrigRef();
169 
170     /***
171      * <p> Renders the reference for a HTML <base> element </p>
172      */
173     public String getBaseRef();
174 
175     /***
176      * <p> Return the path for the specified forward, otherwise return
177      * <code>null</code>. </p>
178      *
179      * @param name Name given to local or global forward.
180      */
181     public String getLink(String name);
182 
183     /***
184      * <p> Return the localized message for the specified key, otherwise
185      * return <code>null</code>. </p>
186      *
187      * @param key Message key
188      */
189     public String getMessage(String key);
190 
191     /***
192      * <p> Look up and return a message string, based on the specified
193      * parameters. </p>
194      *
195      * @param key  Message key to be looked up and returned
196      * @param args Replacement parameters for this message
197      */
198     public String getMessage(String key, Object[] args);
199 
200     /***
201      * <p> Return the URL for the specified ActionMapping, otherwise return
202      * <code>null</code>. </p>
203      *
204      * @param path Name given to local or global forward.
205      */
206     public String getAction(String path);
207 }