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