001: /*
002: * File : $Source: /usr/local/cvs/opencms/src/org/opencms/loader/I_CmsResourceLoader.java,v $
003: * Date : $Date: 2008-02-27 12:05:32 $
004: * Version: $Revision: 1.40 $
005: *
006: * This library is part of OpenCms -
007: * the Open Source Content Management System
008: *
009: * Copyright (c) 2002 - 2008 Alkacon Software GmbH (http://www.alkacon.com)
010: *
011: * This library is free software; you can redistribute it and/or
012: * modify it under the terms of the GNU Lesser General Public
013: * License as published by the Free Software Foundation; either
014: * version 2.1 of the License, or (at your option) any later version.
015: *
016: * This library is distributed in the hope that it will be useful,
017: * but WITHOUT ANY WARRANTY; without even the implied warranty of
018: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
019: * Lesser General Public License for more details.
020: *
021: * For further information about Alkacon Software GmbH, please see the
022: * company website: http://www.alkacon.com
023: *
024: * For further information about OpenCms, please see the
025: * project website: http://www.opencms.org
026: *
027: * You should have received a copy of the GNU Lesser General Public
028: * License along with this library; if not, write to the Free Software
029: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
030: */
031:
032: package org.opencms.loader;
033:
034: import org.opencms.configuration.I_CmsConfigurationParameterHandler;
035: import org.opencms.file.CmsObject;
036: import org.opencms.file.CmsResource;
037: import org.opencms.main.CmsException;
038:
039: import java.io.IOException;
040: import java.util.Locale;
041:
042: import javax.servlet.ServletException;
043: import javax.servlet.ServletRequest;
044: import javax.servlet.ServletResponse;
045: import javax.servlet.http.HttpServletRequest;
046: import javax.servlet.http.HttpServletResponse;
047:
048: /**
049: * This interface describes a resource loader for OpenCms,
050: * a class that can load a resource from the VFS,
051: * process it's contents and deliver the result to the user.<p>
052: *
053: * The I_CmsResourceLoader operates with Request and Response in
054: * much the same way as a standard Java web application.<p>
055: *
056: * This interface uses a standard servlet
057: * {@link javax.servlet.http.HttpServletRequestWrapper} / {@link javax.servlet.http.HttpServletResponseWrapper}
058: * that provide access to a special implementation of the {@link javax.servlet.RequestDispatcher}.
059: * The handling of the output written to the response is done by this
060: * dispatcher. The results are then passed back to OpenCms which
061: * will deliver them to the requesting user.<p>
062: *
063: * @author Alexander Kandzior
064: *
065: * @version $Revision: 1.40 $
066: *
067: * @since 6.0.0
068: *
069: * @see org.opencms.flex.CmsFlexRequest
070: * @see org.opencms.flex.CmsFlexResponse
071: * @see org.opencms.flex.CmsFlexRequestDispatcher
072: */
073: public interface I_CmsResourceLoader extends
074: I_CmsConfigurationParameterHandler {
075:
076: /** Request parameter to force element selection. */
077: String PARAMETER_ELEMENT = "__element";
078:
079: /**
080: * Destroys this ResourceLoder.<p>
081: */
082: void destroy();
083:
084: /**
085: * Dumps the processed content of the the requested file (and it's sub-elements) to a byte array.<p>
086: *
087: * Dumping the content is like calling "load" where the result is
088: * not written to the response stream, but to the returned byte array.
089: * Dumping is different from an export because the export might actually require
090: * that the content is handled or modified in a special way, or set special http headers.<p>
091: *
092: * Moreover, if the page type is template based, calling "dump" will not trigger the
093: * template but directly deliver the contents from the selected element.<p>
094: *
095: * @param cms used to access the OpenCms VFS
096: * @param resource the requested resource in the VFS
097: * @param element the element in the file to display
098: * @param locale the locale to display
099: * @param req the servlet request
100: * @param res the servlet response
101: *
102: * @return the content of the processed file
103: *
104: * @throws ServletException might be thrown by the servlet environment
105: * @throws IOException might be thrown by the servlet environment
106: * @throws CmsException in case of errors acessing OpenCms functions
107: */
108: byte[] dump(CmsObject cms, CmsResource resource, String element,
109: Locale locale, HttpServletRequest req,
110: HttpServletResponse res) throws ServletException,
111: IOException, CmsException;
112:
113: /**
114: * Static exports the contents of the requested file and it's sub-elements.<p>
115: *
116: * During static export, the resource content may be written to 2 streams:
117: * The export stream, and the http response output stream.
118: * Which stream is actually used depends wether the export is in "on demand"
119: * or "after publish" mode. In "on demand" mode, the resource needs to
120: * be written both to the response stream and to the file stream. In
121: * "after publish" mode, it's usually only written to the file stream,
122: * but sometimes it's required to write to the response stream as well.<p>
123: *
124: * @param cms the initialized CmsObject which provides user permissions
125: * @param resource the requested OpenCms VFS resource
126: * @param req the servlet request
127: * @param res the servlet response
128: *
129: * @throws ServletException might be thrown in the process of including the sub element
130: * @throws IOException might be thrown in the process of including the sub element
131: * @throws CmsException in case something goes wrong
132: * @return the contents to export, or <code>null</code> if no export is required
133: */
134: byte[] export(CmsObject cms, CmsResource resource,
135: HttpServletRequest req, HttpServletResponse res)
136: throws ServletException, IOException, CmsException;
137:
138: /**
139: * Returns the id of the ResourceLoader.<p>
140: *
141: * @return the id of the ResourceLoader
142: */
143: int getLoaderId();
144:
145: /**
146: * Returns a String describing the ResourceLoader.<p>
147: *
148: * @return a String describing the ResourceLoader
149: */
150: String getResourceLoaderInfo();
151:
152: /**
153: * Signals if the loader implementation supports static export of resources.<p>
154: *
155: * @return true if static export is supported, false otherwise
156: */
157: boolean isStaticExportEnabled();
158:
159: /**
160: * Signals if the loader implementation requires processing during static export of resources.<p>
161: *
162: * @return true if static export processing is required, false otherwise
163: */
164: boolean isStaticExportProcessable();
165:
166: /**
167: * Signals if the loader implementation is usable for creating templates.<p>
168: *
169: * @return true if the loader implementation is usable for creating templates, false otherwise
170: */
171: boolean isUsableForTemplates();
172:
173: /**
174: * Signals if a loader that supports templates must be invoked on the
175: * template URI or the resource URI.<p>
176: *
177: * @return true if the resource URI is to be used, false if the template URI is to be used
178: */
179: boolean isUsingUriWhenLoadingTemplate();
180:
181: /**
182: * Basic top-page processing method for a I_CmsResourceLoader,
183: * this method is called if the page is called as a sub-element
184: * on a page not already loded with a I_CmsResourceLoader.<p>
185: *
186: * @param cms the initialized CmsObject which provides user permissions
187: * @param resource the requested OpenCms VFS resource
188: * @param req the servlet request
189: * @param res the servlet response
190: *
191: * @throws ServletException might be thrown by the servlet environment
192: * @throws IOException might be thrown by the servlet environment
193: * @throws CmsException in case of errors acessing OpenCms functions
194: *
195: * @see #service(CmsObject, CmsResource, ServletRequest, ServletResponse)
196: */
197: void load(CmsObject cms, CmsResource resource,
198: 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,
218: ServletRequest req, ServletResponse res)
219: throws ServletException, IOException, CmsException;
220: }
|