Context


1   /*
2    *  SSL-Explorer
3    *
4    *  Copyright (C) 2003-2006 3SP LTD. All Rights Reserved
5    *
6    *  This program is free software; you can redistribute it and/or
7    *  modify it under the terms of the GNU General Public License
8    *  as published by the Free Software Foundation; either version 2 of
9    *  the License, or (at your option) any later version.
10   *  This program is distributed in the hope that it will be useful,
11   *  but WITHOUT ANY WARRANTY; without even the implied warranty of
12   *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13   *  GNU General Public License for more details.
14   *
15   *  You should have received a copy of the GNU General Public
16   *  License along with this program; if not, write to the Free Software
17   *  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18   */
19              
20  package com.sslexplorer.boot;
21  
22  import java.io.File  ;
23  import java.io.IOException  ;
24  import java.net.URL  ;
25  import java.util.Collection  ;
26  import java.util.prefs.Preferences  ;
27  
28  import javax.net.ssl.TrustManager;
29  import javax.servlet.http.HttpServletRequest  ;
30  import javax.servlet.http.HttpServletResponse  ;
31  
32  
33  /**
34   * Whilst SSL-Explorer is largely a standard web application, it has requirements
35   * of its environment above and beyond this.
36   * <p>
37   * Then environment that services these requires is known as the Context. There
38   * should be a single instance of the implementation of this interface and it
39   * should be registered with {@link com.sslexplorer.boot.ContextHolder#setContext(Context)}.
40   * <p>
41   * The instance of the context may then be accessed in the web application and
42   * boot classes using {@link com.sslexplorer.boot.ContextHolder#getContext()}.
43   * <p>
44   * The context responsibilities include :-
45   * <ul>
46   * <li>Service control. I.e. shutdown and restart</li>
47   * <li>Provide locations to store configuration, temporary files, logs etc</li>
48   * <li>Provide an HTTP server to serve web content and handle custom HTTP connections</li>
49   * <li>Provide and manager databases used for storing configuration and SSL-Explorer resources</li>
50   * <li>Obfuscating / deobfuscating passwords</li>
51   * <li>Configuring the class loader</li>
52   * <li>Providing storewhere to store <i>Context properties</i>, i.e. those that
53   *     are only applicable to this Context implementation</li>
54   * </ul>
55   * 
56   * @author Brett Smith <a HREF="mailto: brett@3sp.com">&lt;brett@3sp.com&gt;</a>
57   */
58  public interface Context {
59      
60      enum HandlerProtocol { HTTPS_PROTOCOL, HTTP_PROTOCOL, BOTH_PROTOCOLS };
61      
62      /**
63       * Get if the context is currently running in setup mode.
64       * 
65       * @return running in setup mode.
66       */
67      public boolean isSetupMode();
68  
69      /**
70       * Get if the context may be restarted. 
71       * 
72       * @return restart available
73       */
74      public boolean isRestartAvailableMode();
75  
76      /**
77       * Shut down the context, possibly restarting when done.
78       * 
79       * @param restart restart when shutdown complete
80       */
81      public void shutdown(boolean restart);
82  
83  
84      /**
85       * Get the current version of SSL-Explorer.
86       * 
87       * @return current version
88       */
89      public VersionInfo.Version getVersion();
90  
91      /**
92       * Get the directory when configuration files are stored.
93       * 
94       * @return configuration file directory
95       */
96      public File   getConfDirectory();
97  
98      /**
99       * Get the directory where tempory files are stored
100      * 
101      * @return temporary directory
102      */
103     public File   getTempDirectory();
104 
105     /**
106      * Get the directory where logs are stored
107      * 
108      * @return logs
109      */
110     public File   getLogDirectory();
111 
112     /**
113      * Get the directory where database files are stored.
114      * 
115      * @return database files
116      */
117     public File   getDBDirectory();
118 
119     /**
120      * Get the directory where application extensions are stored.
121      * 
122      * @return application extension directory
123      */
124     public File   getApplicationDirectory();
125 
126     /**
127      * Get the main thread.
128      * 
129      * @return main thread
130      */
131     public Thread   getMainThread();
132 
133     /**
134      * Add a new location that contains web resources. Web resources include
135      * things suchs as HTML files, Images, CSS, JSP etc.
136      * <p>
137      * When serving content, the containing web server must search any 
138      * added resource bases for the requested resource starting with the 
139      * first added resource base until something is found.
140      * <p>
141      * This is a key part of the extension architecture
142      * 
143      * @param url url to add
144      */
145     public void addResourceBase(URL   url);
146 
147     /**
148      * Remove a location from the list of locations that contains web
149      * resources.
150      * 
151      * @param url url to remove
152      * @see Context#addResourceBase(URL)
153      */
154     public void removeResourceBase(URL   url);
155     
156     /**
157      * Get the list of current resource bases
158      * 
159      * @return resources bases
160      */
161     public Collection  <URL  > getResourceBases();
162 
163     /**
164      * Return the host name on which SSL-Explorer is running.
165      * 
166      * @return hostname
167      */
168     public String   getHostname();
169     
170     /**
171      * Return the actual port SSL-Explorer is running on. This may be different
172      * to the port in the configuration if the server was invoked with the port
173      * argument.
174      * 
175      * @return port server is running on 
176      */
177     public int getPort();
178     
179     /**
180      * Add a location to the class loader. Any classes found at this location
181      * should then made available to all plugins, the core and any JSP pages.
182      * 
183      * @param u location of classes
184      */
185     public void addContextLoaderURL(URL   u);
186 
187     /**
188      * Add a custom request handler.
189      * 
190      * @param requestHandler request handler
191      */
192     public void registerRequestHandler(RequestHandler requestHandler);
193 
194     
195     /**
196      * Add a custom request handler.
197      * 
198      * @param requestHandler request handler
199      */
200     public void registerRequestHandler(RequestHandler requestHandler, HandlerProtocol protocol);
201     
202     
203     /**
204      * Remove a custom request handler
205      * 
206      * @param requestHandler request handler
207      */
208     public void deregisterRequestHandler(RequestHandler requestHandler);
209 
210     /**
211      * Obfuscate a password in a way that it be de-obfuscated with 
212      * {@link #deobfuscatePassword(String)}.
213      * 
214      * @param password password to obfuscate
215      * @return de-obfuscated password
216      */
217     public String   obfuscatePassword(String   password);
218 
219     /**
220      * De-ebfuscate a password that has been obfuscated with 
221      * {@link #obfuscatePassword(String)}.
222      * 
223      * @param password obfuscated password
224      * @return deobfuscated password
225      */
226     public String   deobfuscatePassword(String   password);
227     
228     /**
229      * Set the trust manager to use for incoming SSL connections.
230      *  
231      * @param trustManager trust manager to set
232      * @param require required
233      */
234     public void setTrustMananger(TrustManager trustManager, boolean require);
235     
236     /**
237      * Add a new web application
238      * 
239      * @param contextPathSpec path (either / or /path/*)
240      * @param webApp path to webapp or WAR file
241      * @throws IOException on any error
242      * @throws Exception 
243      */
244     public void addWebApp(String   contextPathSpec, String   webApp) throws Exception  ;
245     
246     /**
247      * Add a listener to those being notified of events from the <i>Context</i>.
248      * 
249      * @param contextListener listener to add
250      */
251     public void addContextListener(ContextListener contextListener);
252     
253     /**
254      * remove a listener from those being notified of events from the <i>Context</i>.
255      * 
256      * @param contextListener listener to remove
257      */
258     public void removeContextListener(ContextListener contextListener);
259     
260     /**
261      * Get the root preferences node. Any component of SSL-Explorer core or
262      * its plugins may use this to store configuration information.
263      * 
264      * @return root preferences node
265      */
266     public Preferences   getPreferences();
267     
268     /**
269      * Get the property class used for system configuration
270      * 
271      * @return system config property class
272      */
273     public PropertyClass getConfig();
274 
275     /**
276      * Get the list of URLs that the context loader uses as
277      * its class path
278      *  
279      * @return context loader class path
280      */
281     public URL  [] getContextLoaderClassPath();
282 
283     /**
284      * Get the context class loadeer
285      * 
286      * @return context class loader
287      */ 
288     public ClassLoader   getContextLoader();
289 
290     /**
291      * Create an alias for the given URI to the given location.
292      * 
293      * @param uri uri to alias
294      * @param location actual location
295      */
296     public void setResourceAlias(String   uri, String   location);
297 
298     /**
299      * Remove an alias for the given URI.
300      * 
301      * @param uri uri to alias
302      */
303     public void removeResourceAlias(String   uri);
304     
305     /**
306      * Get the boot progress monitor. Calling methods 
307      * on the monitor will have no effect after the server
308      * has started
309      * 
310      * @return boot progress monitor 
311      */
312     public BootProgressMonitor getBootProgressMonitor();
313     
314     /**
315      * Create a HttpServletRequest from a RequestHandlerRequest. This only works
316      * for RequestAdapter implementations as others are already HttpServletRequests.
317      * @param request
318      * @return
319      */
320     public HttpServletRequest   createServletRequest(RequestHandlerRequest request);
321 
322     /**
323      * Create a HttpServletResponse from a RequestHandlerResponse. This only works
324      * for ResponseAdapter implementations as others are already HttpServletResponse.
325      * @param response
326      * @param request
327      * @return
328      */
329     public HttpServletResponse   createServletResponse(RequestHandlerResponse response, HttpServletRequest   request);
330 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags