KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > kohsuke > stapler > StaplerRequest


1 package org.kohsuke.stapler;
2
3 import org.apache.commons.beanutils.BeanUtils;
4 import org.apache.commons.beanutils.ConvertUtils;
5
6 import javax.servlet.RequestDispatcher JavaDoc;
7 import javax.servlet.ServletContext JavaDoc;
8 import javax.servlet.http.HttpServletRequest JavaDoc;
9 import javax.servlet.http.HttpServletResponse JavaDoc;
10 import java.io.IOException JavaDoc;
11 import java.util.Calendar JavaDoc;
12 import java.util.Date JavaDoc;
13 import java.util.List JavaDoc;
14
15 /**
16  * Defines additional parameters/operations made available by Stapler.
17  *
18  * @author Kohsuke Kawaguchi
19  */
20 public interface StaplerRequest extends HttpServletRequest JavaDoc {
21     /**
22      * Returns the additional URL portion that wasn't used by the stapler,
23      * excluding the query string.
24      *
25      * <p>
26      * For example, if the requested URL is "foo/bar/zot/abc?def=ghi" and
27      * "foo/bar" portion matched <tt>bar.jsp</tt>, this method returns
28      * "/zot/abc".
29      *
30      * @return
31      * can be empty string, but never null.
32      */
33     String JavaDoc getRestOfPath();
34
35     /**
36      * Returns the {@link ServletContext} object given to the stapler
37      * dispatcher servlet.
38      */
39     ServletContext JavaDoc getServletContext();
40
41     /**
42      * Gets the {@link RequestDispatcher} that represents a specific view
43      * for the given object.
44      *
45      * This support both JSP and Jelly.
46      *
47      * @param viewName
48      * If this name is relative name like "foo.jsp" or "bar/zot.jelly",
49      * then the corresponding "side file" is searched by this name.
50      * <p>
51      * For Jelly, this also accepts absolute path name that starts
52      * with '/', such as "/foo/bar/zot.jelly". In this case,
53      * <tt>it.getClass().getClassLoader()</tt> is searched for this script.
54      *
55      * @return null
56      * if neither JSP nor Jelly is not found by the given name.
57      */
58     RequestDispatcher JavaDoc getView(Object JavaDoc it,String JavaDoc viewName) throws IOException JavaDoc;
59
60     /**
61      * Gets the part of the request URL from protocol up to the context path.
62      * So typically it's something like <tt>http://foobar:8080/something</tt>
63      */
64     String JavaDoc getRootPath();
65
66     /**
67      * Returns a list of ancestor objects that lead to the "it" object.
68      * The returned list contains {@link Ancestor} objects sorted in the
69      * order from root to the "it" object.
70      *
71      * <p>
72      * For example, if the URL was "foo/bar/zot" and the "it" object
73      * was determined as <code>root.getFoo().getBar("zot")</code>,
74      * then this list will contain the following 3 objects in this order:
75      * <ol>
76      * <li>the root object
77      * <li>root.getFoo() object
78      * <li>root.getFoo().getBar("zot") object (the "it" object)
79      * </ol>
80      * <p>
81      *
82      *
83      * @return
84      * list of {@link Ancestor}s. Can be empty, but always non-null.
85      */
86     List JavaDoc getAncestors();
87
88     /**
89      * Gets the {@link HttpServletRequest#getRequestURI() request URI}
90      * of the original request, so that you can access the value even from
91      * JSP.
92      */
93     String JavaDoc getOriginalRequestURI();
94
95     /**
96      * Checks "If-Modified-Since" header and returns false
97      * if the resource needs to be served.
98      *
99      * <p>
100      * This method can behave in three ways.
101      *
102      * <ol>
103      * <li>If <tt>timestampOfResource</tt> is 0 or negative,
104      * this method just returns false.
105      *
106      * <li>If "If-Modified-Since" header is sent and if it's bigger than
107      * <tt>timestampOfResource</tt>, then this method sets
108      * {@link HttpServletResponse#SC_NOT_MODIFIED} as the response code
109      * and returns true.
110      *
111      * <li>Otherwise, "Last-Modified" header is added with <tt>timestampOfResource</tt> value,
112      * and this method returns false.
113      * </ol>
114      *
115      * @param timestampOfResource
116      * The time stamp of the resource.
117      * @param rsp
118      * This object is updated accordingly to simplify processing.
119      *
120      * @return
121      * false to indicate that the caller has to serve the actual resource.
122      * true to indicate that the caller should just quit processing right there
123      * (and send back {@link HttpServletResponse#SC_NOT_MODIFIED}.
124      */
125     boolean checkIfModified(long timestampOfResource, StaplerResponse rsp);
126
127     /**
128      * @see #checkIfModified(long, StaplerResponse)
129      */
130     boolean checkIfModified(Date JavaDoc timestampOfResource, StaplerResponse rsp);
131
132     /**
133      * @see #checkIfModified(long, StaplerResponse)
134      */
135     boolean checkIfModified(Calendar JavaDoc timestampOfResource, StaplerResponse rsp);
136
137     /**
138      * Binds form parameters to a bean by using introspection.
139      *
140      * For example, if there's a parameter called 'foo' that has value 'abc',
141      * then <tt>bean.setFoo('abc')</tt> will be invoked. This will be repeated
142      * for all parameters. Parameters that do not have corresponding setters will
143      * be simply ignored.
144      *
145      * <p>
146      * Values are converted into the right type. See {@link ConvertUtils#convert(String, Class)}.
147      *
148      * @see BeanUtils#setProperty(Object, String, Object)
149      *
150      * @param bean
151      * The object which will be filled out.
152      */
153     void bindParameters( Object JavaDoc bean );
154
155     /**
156      * Binds form parameters to a bean by using introspection.
157      *
158      * This method works like {@link #bindParameters(Object)}, but it performs a
159      * pre-processing on property names. Namely, only property names that start
160      * with the given prefix will be used for binding, and only the portion of the
161      * property name after the prefix is used.
162      *
163      * So for example, if the prefix is "foo.", then property name "foo.bar" with value
164      * "zot" will invoke <tt>bean.setBar("zot")</tt>.
165      */
166     void bindParameters( Object JavaDoc bean, String JavaDoc prefix );
167
168     /**
169      * Binds collection form parameters to beans by using introspection.
170      *
171      * <p>
172      * This method works like {@link #bindParameters(Object,String)}, but it assumes
173      * that form parameters have multiple-values, and use individual values to
174      * fill in multiple beans.
175      *
176      * <p>
177      * For example, if <tt>getParameterValues("foo")=={"abc","def"}</tt>
178      * and <tt>getParameterValues("bar")=={"5","3"}</tt>, then this method will
179      * return two objects (the first with "abc" and "5", the second with
180      * "def" and "3".)
181      *
182      * @param type
183      * Type of the bean to be created. This class must have the default no-arg
184      * constructor.
185      *
186      * @param prefix
187      * See {@link #bindParameters(Object, String)} for details.
188      *
189      * @return
190      * Can be empty but never null.
191      */
192     <T>
193     List JavaDoc<T> bindParametersToList( Class JavaDoc<T> type, String JavaDoc prefix );
194 }
195
Popular Tags