1    /*
2     * Copyright 2005 :torweg free software group
3     * 
4     * This program is free software: you can redistribute it and/or modify
5     * it under the terms of the GNU General Public License as published by
6     * the Free Software Foundation, either version 3 of the License, or
7     * (at your option) any later version.
8     * 
9     * This program is distributed in the hope that it will be useful,
10    * but WITHOUT ANY WARRANTY; without even the implied warranty of
11    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12    * GNU General Public License for more details.
13    * 
14    * You should have received a copy of the GNU General Public License
15    * along with this program.  If not, see <http://www.gnu.org/licenses/>.
16    * 
17    */
18   package org.torweg.pulse.service.request;
19   
20   import java.util.Collection;
21   import java.util.List;
22   import java.util.Locale;
23   
24   import javax.servlet.http.HttpServletRequest;
25   import javax.servlet.http.HttpServletResponse;
26   import javax.xml.bind.annotation.XmlEnum;
27   
28   import org.torweg.pulse.accesscontrol.User;
29   import org.torweg.pulse.service.event.EventManager;
30   import org.torweg.pulse.util.geolocation.GeoLocation;
31   
32   /**
33    * The request sent to the service.
34    * 
35    * <p>
36    * The {@code ServiceRequest} contains the {@code Command} and
37    * {@code ServiceSession} associated to the request to the <em>pulse</em>
38    * service. It also provides access to {@code Cookies} and
39    * {@code TemporaryFiles} belonging to the request.
40    * </p>
41    * <p>
42    * Moreover, the {@code ServiceRequest} takes care of authenticating the
43    * {@code User}.
44    * </p>
45    * 
46    * @author Thomas Weber
47    * @version $Revision: 1873 $
48    */
49   public interface ServiceRequest {
50   
51       /**
52        * get the base URI to the servlet.
53        * 
54        * @return the base URI
55        */
56       String getBaseURI();
57   
58       /**
59        * get the {@code Command} sent to the <em>pulse</em> service.
60        * 
61        * @return the {@code Command}
62        */
63       Command getCommand();
64   
65       /**
66        * get the {@code ServiceSession} associated to the request.
67        * 
68        * @return the {@code ServiceSession}
69        */
70       ServiceSession getSession();
71   
72       /**
73        * get all files that where uploaded during the request.
74        * 
75        * @return a {@code List} of the uploaded files
76        */
77       List<IUploadedFile> getUploadedFiles();
78   
79       /**
80        * returns the currently set {@code Locale} for the request.
81        * 
82        * @return the current {@code Locale}
83        */
84       Locale getLocale();
85   
86       /**
87        * returns the {@code User} associated with the request.
88        * 
89        * @return the current {@code User}
90        */
91       User getUser();
92   
93       /**
94        * get all {@code Cookie}s sent by the browser.
95        * 
96        * @return an array of {@code Cookie}s
97        */
98       Collection<Cookie> getCookies();
99   
100      /**
101       * adds the given {@code Cookie} to the response of the <em>pulse</em>
102       * service.
103       * 
104       * 
105       * @param cookie
106       *            the {@code Cookie} to be added
107       * @see Cookie
108       */
109      void addCookie(Cookie cookie);
110  
111      /**
112       * get access to the underlying {@code HttpServletRequest}.
113       * 
114       * @return the underlying HttpServletRequest
115       */
116      HttpServletRequest getHttpServletRequest();
117  
118      /**
119       * get access to the underlying {@code HttpServletResponse}.
120       * 
121       * @return the underlying HttpServletResponse
122       */
123      HttpServletResponse getHttpServletResponse();
124  
125      /**
126       * initialises the service request from a HTTP servlet request.
127       * 
128       * @param req
129       *            the request to be used
130       * @param res
131       *            the response to be used
132       * 
133       * @return the initialised service request
134       */
135      ServiceRequest init(HttpServletRequest req, HttpServletResponse res);
136  
137      /**
138       * returns the event manager of the service request.
139       * 
140       * @return the event manager
141       */
142      EventManager getEventManager();
143  
144      /**
145       * returns the country the request is made from or {@code null}, if the
146       * country could not be resolved by
147       * {@link org.torweg.pulse.invocation.lifecycle.Lifecycle#getGeoLocationProvider()}
148       * .
149       * 
150       * @return the country the request is made from or {@code null}, if the
151       *         country could not be resolved
152       */
153      GeoLocation getRequestOrigin();
154  
155      /**
156       * indicates whether the session shall be used with URL based session IDs
157       * and Cookies or with Cookies only.
158       * 
159       * @return {@code true}, if only cookie based sessions are to be used
160       */
161      SessionMode getSessionMode();
162  
163      /**
164       * refreshes the {@code User} information from the session.
165       */
166      void refreshUser();
167  
168      /**
169       * returns the parsed accept-languages header.
170       * 
171       * @return the parsed accept-languages
172       */
173      AcceptLanguages getAcceptLanguages();
174  
175      /**
176       * returns the maximum age for a dynamic page cached using
177       * {@code IntelliCache} to be considered for <tt>304 Not Modified</tt>
178       * responses upon a stateless {@code ServiceSession}.
179       * 
180       * @return the maximum age in milliseconds
181       */
182      long getIntelliCacheMaxAge();
183  
184      /**
185       * 
186       */
187      @XmlEnum
188      public enum SessionMode {
189          /**
190           * accept only cookie based sessions.
191           */
192          COOKIES_ONLY,
193          /**
194           * accept cookie and URL based sessions.
195           */
196          ALLOW_URL_ENCODED,
197          /**
198           * also allow <em>pulse</em> to encode sessions into URL
199           */
200          USE_URL_ENCODED;
201      }
202  
203  }
204