I_CmsResourceLoader


1   /*
2    * File   : $Source: /usr/local/cvs/opencms/src/org/opencms/loader/I_CmsResourceLoader.java,v $
3    * Date   : $Date: 2006/03/27 14:52:37 $
4    * Version: $Revision: 1.38 $
5    *
6    * This library is part of OpenCms -
7    * the Open Source Content Mananagement System
8    *
9    * Copyright (c) 2005 Alkacon Software GmbH (http://www.alkacon.com)
10   *
11   * This library is free software; you can redistribute it and/or
12   * modify it under the terms of the GNU Lesser General Public
13   * License as published by the Free Software Foundation; either
14   * version 2.1 of the License, or (at your option) any later version.
15   *
16   * This library is distributed in the hope that it will be useful,
17   * but WITHOUT ANY WARRANTY; without even the implied warranty of
18   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19   * Lesser General Public License for more details.
20   *
21   * For further information about Alkacon Software GmbH, please see the
22   * company website: http://www.alkacon.com
23   *
24   * For further information about OpenCms, please see the
25   * project website: http://www.opencms.org
26   * 
27   * You should have received a copy of the GNU Lesser General Public
28   * License along with this library; if not, write to the Free Software
29   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
30   */
31  
32  package org.opencms.loader;
33  
34  import org.opencms.configuration.I_CmsConfigurationParameterHandler;
35  import org.opencms.file.CmsObject;
36  import org.opencms.file.CmsResource;
37  import org.opencms.main.CmsException;
38  
39  import java.io.IOException  ;
40  import java.util.Locale  ;
41  
42  import javax.servlet.ServletException  ;
43  import javax.servlet.ServletRequest  ;
44  import javax.servlet.ServletResponse  ;
45  import javax.servlet.http.HttpServletRequest  ;
46  import javax.servlet.http.HttpServletResponse  ;
47  
48  /**
49   * This interface describes a resource loader for OpenCms, 
50   * a class that can load a resource from the VFS, 
51   * process it's contents and deliver the result to the user.<p>
52   *
53   * The I_CmsResourceLoader operates with Request and Response in 
54   * much the same way as a standard Java web application.<p>
55   * 
56   * This interface uses a standard servlet
57   * {@link javax.servlet.http.HttpServletRequestWrapper} / {@link javax.servlet.http.HttpServletResponseWrapper}
58   * that provide access to a special implementation of the {@link javax.servlet.RequestDispatcher}.
59   * The handling of the output written to the response is done by this 
60   * dispatcher. The results are then passed back to OpenCms which 
61   * will deliver them to the requesting user.<p>
62   *
63   * @author  Alexander Kandzior 
64   * 
65   * @version $Revision: 1.38 $ 
66   * 
67   * @since 6.0.0 
68   * 
69   * @see org.opencms.flex.CmsFlexRequest
70   * @see org.opencms.flex.CmsFlexResponse
71   * @see org.opencms.flex.CmsFlexRequestDispatcher
72   */
73  public interface I_CmsResourceLoader extends I_CmsConfigurationParameterHandler {
74  
75      /** Request parameter to force element selection. */
76      String   PARAMETER_ELEMENT = "__element";
77  
78      /** 
79       * Destroys this ResourceLoder.<p>
80       */
81      void destroy();
82  
83      /**
84       * Dumps the processed content of the the requested file (and it's sub-elements) to a byte array.<p>
85       * 
86       * Dumping the content is like calling "load" where the result is 
87       * not written to the response stream, but to the returned byte array.
88       * Dumping is different from an export because the export might actually require 
89       * that the content is handled or modified in a special way, or set special http headers.<p>
90       * 
91       * Moreover, if the page type is template based, calling "dump" will not trigger the 
92       * template but directly deliver the contents from the selected element.<p>
93       * 
94       * @param cms used to access the OpenCms VFS
95       * @param resource the requested resource in the VFS
96       * @param element the element in the file to display
97       * @param locale the locale to display
98       * @param req the servlet request
99       * @param res the servlet response
100      * 
101      * @return the content of the processed file
102      * 
103      * @throws ServletException might be thrown by the servlet environment
104      * @throws IOException might be thrown by the servlet environment
105      * @throws CmsException in case of errors acessing OpenCms functions
106      */
107     byte[] dump(
108         CmsObject cms,
109         CmsResource resource,
110         String   element,
111         Locale   locale,
112         HttpServletRequest   req,
113         HttpServletResponse   res) throws ServletException  , IOException  , CmsException;
114 
115     /**
116      * Static exports the contents of the requested file and it's sub-elements.<p>
117      *
118      * During static export, the resource content may be written to 2 streams: 
119      * The export stream, and the http response output stream.
120      * Which stream is actually used depends wether the export is in "on demand" 
121      * or "after publish" mode. In "on demand" mode, the resource needs to 
122      * be written both to the response stream and to the file stream. In 
123      * "after publish" mode, it's usually only written to the file stream, 
124      * but sometimes it's required to write to the response stream as well.<p> 
125      *
126      * @param cms the initialized CmsObject which provides user permissions
127      * @param resource the requested OpenCms VFS resource
128      * @param req the servlet request
129      * @param res the servlet response
130      * 
131      * @throws ServletException might be thrown in the process of including the sub element
132      * @throws IOException might be thrown in the process of including the sub element
133      * @throws CmsException in case something goes wrong
134      * @return the contents to export, or <code>null</code> if no export is required
135      */
136     byte[] export(CmsObject cms, CmsResource resource, HttpServletRequest   req, HttpServletResponse   res)
137     throws ServletException  , IOException  , CmsException;
138 
139     /**
140      * Returns the id of the ResourceLoader.<p>
141      * 
142      * @return the id of the ResourceLoader
143      */
144     int getLoaderId();
145 
146     /** 
147      * Returns a String describing the ResourceLoader.<p>
148      * 
149      * @return a String describing the ResourceLoader
150      */
151     String   getResourceLoaderInfo();
152 
153     /**
154      * Signals if the loader implementation supports static export of resources.<p>
155      * 
156      * @return true if static export is supported, false otherwise
157      */
158     boolean isStaticExportEnabled();
159 
160     /**
161      * Signals if the loader implementation requires processing during static export of resources.<p>
162      * 
163      * @return true if static export processing is required, false otherwise
164      */
165     boolean isStaticExportProcessable();
166 
167     /**
168      * Signals if the loader implementation is usable for creating templates.<p>
169      * 
170      * @return true  if the loader implementation is usable for creating templates, false otherwise
171      */
172     boolean isUsableForTemplates();
173 
174     /**
175      * Signals if a loader that supports templates must be invoked on the 
176      * template URI or the resource URI.<p>
177      * 
178      * @return true if the resource URI is to be used, false if the template URI is to be used
179      */
180     boolean isUsingUriWhenLoadingTemplate();
181 
182     /**
183      * Basic top-page processing method for a I_CmsResourceLoader,
184      * this method is called if the page is called as a sub-element 
185      * on a page not already loded with a I_CmsResourceLoader.<p>
186      *
187      * @param cms the initialized CmsObject which provides user permissions
188      * @param resource the requested OpenCms VFS resource
189      * @param req the servlet request
190      * @param res the servlet response
191      * 
192      * @throws ServletException might be thrown by the servlet environment
193      * @throws IOException might be thrown by the servlet environment
194      * @throws CmsException in case of errors acessing OpenCms functions
195      * 
196      * @see #service(CmsObject, CmsResource, ServletRequest, ServletResponse)
197      */
198     void load(CmsObject cms, CmsResource resource, HttpServletRequest   req, HttpServletResponse   res)
199     throws ServletException  , IOException  , CmsException;
200 
201     /**
202      * Does the job of including the requested resource, 
203      * this method is called directly if the element is 
204      * called as a sub-element from another I_CmsResourceLoader.<p>
205      * 
206      * @param cms used to access the OpenCms VFS
207      * @param resource the reqested resource in the VFS
208      * @param req the servlet request
209      * @param res the servlet response
210      * 
211      * @throws ServletException might be thrown by the servlet environment
212      * @throws IOException might be thrown by the servlet environment
213      * @throws CmsException in case of errors acessing OpenCms functions
214      * 
215      * @see org.opencms.flex.CmsFlexRequestDispatcher
216      */
217     void service(CmsObject cms, CmsResource resource, ServletRequest   req, ServletResponse   res)
218     throws ServletException  , IOException  , CmsException;
219 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Free Books Free Magazines
Popular Tags