001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (http://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: http://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: http://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.file.wrapper;
029
030import org.opencms.file.CmsFile;
031import org.opencms.file.CmsObject;
032import org.opencms.file.CmsProperty;
033import org.opencms.file.CmsResource;
034import org.opencms.file.CmsResource.CmsResourceCopyMode;
035import org.opencms.file.CmsResource.CmsResourceDeleteMode;
036import org.opencms.file.CmsResourceFilter;
037import org.opencms.lock.CmsLock;
038import org.opencms.main.CmsException;
039import org.opencms.main.CmsIllegalArgumentException;
040
041import java.util.List;
042
043/**
044 * Interface which is used by the {@link CmsObjectWrapper} to create a different view to the
045 * resources in the VFS.<p>
046 *
047 * It is possible to create "new" virtual resource in the view to the clients using the
048 * <code>CmsObjectWrapper</code> or to change the existing ones. For example adding the correct
049 * file extension for resources, because it is not always given that resources of type jsp have
050 * the extension ".jsp". A resource wrapper just could add this extension, so that clients can
051 * handle that resource correctly.<p>
052 *
053 * Each method in the implementing classes first have to check in every method if it is
054 * responsible for the action to execute, because the <code>CmsObjectWrapper</code> iterates
055 * through all configured resource wrappers and the first which feels responsible wins and the
056 * others won't even called.<p>
057 *
058 * @since 6.2.4
059 */
060public interface I_CmsResourceWrapper {
061
062    /**
063     * Here it is possible to add additional (virtual) child resources to those already existing
064     * in the VFS.<p>
065     *
066     * @see CmsObjectWrapper#getResourcesInFolder(String, CmsResourceFilter)
067     *
068     * @param cms the current users OpenCms context
069     * @param resourcename the full path of the resource where to add the child resources for
070     * @param filter the resource filter to use
071     *
072     * @return a list of all additionaly child <code>{@link CmsResource}</code>s
073     *
074     * @throws CmsException if something goes wrong
075     */
076    List<CmsResource> addResourcesToFolder(CmsObject cms, String resourcename, CmsResourceFilter filter)
077    throws CmsException;
078
079    /**
080     * If there is a configuration string for the wrapper, this method will be called with the configuration string
081     * before it is used.<p>
082     *
083     *  Otherwise, it will not be called.
084     *
085     * @param configuration the configuration string for the wrapper
086     */
087    void configure(String configuration);
088
089    /**
090     * Copies a resource.<p>
091     *
092     * First should be a check if the source and/or the destination are handled by this
093     * resource wrapper.<p>
094     *
095     * It is possible that the path in the source or in the destination are virtual paths and
096     * so has to be translated into valid paths existing in the VFS to copy the resource.<p>
097     *
098     * @see CmsObjectWrapper#copyResource(String, String, CmsResource.CmsResourceCopyMode)
099     * @see CmsObject#copyResource(String, String, CmsResource.CmsResourceCopyMode)
100     *
101     * @param cms the initialized CmsObject
102     * @param source the name of the resource to copy
103     * @param destination the name of the copy destination with complete path
104     * @param siblingMode indicates how to handle siblings during copy
105     *
106     * @return true if the copy action was handled by this resource wrapper otherwise false
107     *
108     * @throws CmsIllegalArgumentException if the <code>destination</code> argument is null or of length 0
109     * @throws CmsException if something goes wrong
110     */
111    boolean copyResource(CmsObject cms, String source, String destination, CmsResourceCopyMode siblingMode)
112    throws CmsException, CmsIllegalArgumentException;
113
114    /**
115     * Creates a new resource of the given resource type
116     * with the provided content and properties.<p>
117     *
118     * First should be a check if the resourcename is handled by this
119     * resource wrapper.<p>
120     *
121     * It is possible that the path in the resourcename is a virtual path and
122     * so has to be translated into a valid path existing in the VFS to create the resource.<p>
123     *
124     * @see CmsObjectWrapper#createResource(String, int, byte[], List)
125     * @see CmsObject#createResource(String, int, byte[], List)
126     *
127     * @param cms the initialized CmsObject
128     * @param resourcename the name of the resource to create (full path)
129     * @param type the type of the resource to create
130     * @param content the content for the new resource
131     * @param properties the properties for the new resource
132     *
133     * @return the created resource or null if not handled by this resource wrapper
134     *
135     * @throws CmsException if something goes wrong
136     * @throws CmsIllegalArgumentException if the <code>source</code> argument is null or of length 0
137     */
138    CmsResource createResource(
139        CmsObject cms,
140        String resourcename,
141        int type,
142        byte[] content,
143        List<CmsProperty> properties) throws CmsException, CmsIllegalArgumentException;
144
145    /**
146     * Deletes a resource given its name.<p>
147     *
148     * First should be a check if the resourcename is handled by this
149     * resource wrapper.<p>
150     *
151     * It is possible that the path in the resourcename is a virtual path and
152     * so has to be translated into a valid path existing in the VFS to delete the resource.<p>
153     *
154     * @see CmsObjectWrapper#deleteResource(String, CmsResource.CmsResourceDeleteMode)
155     * @see CmsObject#deleteResource(String, CmsResource.CmsResourceDeleteMode)
156     *
157     * @param cms the initialized CmsObject
158     * @param resourcename the name of the resource to delete
159     * @param siblingMode indicates how to handle siblings of the deleted resource
160     *
161     * @return true if the delete action was handled by this resource wrapper otherwise false
162     *
163     * @throws CmsException if something goes wrong
164     */
165    boolean deleteResource(CmsObject cms, String resourcename, CmsResourceDeleteMode siblingMode) throws CmsException;
166
167    /**
168     * Returns the lock for the resource.<p>
169     *
170     * First should be a check if the resource is handled by this
171     * resource wrapper.<p>
172     *
173     * It is possible that the path in the resource is a virtual path and
174     * so has to be translated into a valid path existing in the VFS to
175     * get the lock for the resource.<p>
176     *
177     * @see CmsObjectWrapper#getLock(CmsResource)
178     * @see CmsObject#getLock(CmsResource)
179     *
180     * @param cms the initialized CmsObject
181     * @param resource the resource to check the lock for
182     *
183     * @return the lock state of the resource or null if the action couldn't be handled by this resource wrapper
184     *
185     * @throws CmsException if something goes wrong
186     */
187    CmsLock getLock(CmsObject cms, CmsResource resource) throws CmsException;
188
189    /**
190     * Is called to check if the given resource is handled by this wrapper.<p>
191     *
192     * @see CmsObjectWrapper#getResourcesInFolder(String, CmsResourceFilter)
193     *
194     * @param cms the initialized CmsObject
195     * @param res the resource to check
196     *
197     * @return true if the resource will be handled by the wrapper otherwise false
198     */
199    boolean isWrappedResource(CmsObject cms, CmsResource res);
200
201    /**
202     * Locks a resource.<p>
203     *
204     * First should be a check if the resourcename is handled by this
205     * resource wrapper.<p>
206     *
207     * It is possible that the path in the resourcename is a virtual path and
208     * so has to be translated into a valid path existing in the VFS to lock the resource.<p>
209     *
210     * @see CmsObjectWrapper#lockResource(String)
211     * @see CmsObject#lockResource(String)
212     *
213     * @param cms the current users OpenCms context
214     * @param resourcename the name of the resource to lock (full path)
215     * @param temporary true if the resource should only be locked temporarily
216     *
217     * @return true if this request could be handled by this wrapper or false if not
218     *
219     * @throws CmsException if something goes wrong
220     */
221    boolean lockResource(CmsObject cms, String resourcename, boolean temporary) throws CmsException;
222
223    /**
224     * Moves a resource to the given destination.<p>
225     *
226     * First should be a check if the source and/or the destination are handled by this
227     * resource wrapper.<p>
228     *
229     * It is possible that the path in the source or in the destination are virtual paths and
230     * so has to be translated into valid paths existing in the VFS to move the resource.<p>
231     *
232     * @see CmsObjectWrapper#moveResource(String, String)
233     * @see CmsObject#moveResource(String, String)
234     *
235     * @param cms the current cms context
236     * @param source the name of the resource to move
237     * @param destination the destination resource name
238     *
239     * @throws CmsException if something goes wrong
240     * @throws CmsIllegalArgumentException if the <code>source</code> argument is null or of length 0
241     *
242     * @return true if the move action was handled by this resource wrapper otherwise false
243     */
244    boolean moveResource(CmsObject cms, String source, String destination)
245    throws CmsException, CmsIllegalArgumentException;
246
247    /**
248     * Reads a file resource (including it's binary content) from the VFS,
249     * using the specified resource filter.<p>
250     *
251     * First should be a check if the resourcename is handled by this
252     * resource wrapper.<p>
253     *
254     * It is possible that the path in the resourcename is a virtual path and
255     * so has to be translated into a valid path existing in the VFS to read the resource.<p>
256     *
257     * @see CmsObjectWrapper#readFile(String, CmsResourceFilter)
258     * @see CmsObject#readFile(String, CmsResourceFilter)
259     *
260     * @param cms the current users OpenCms context
261     * @param resourcename the name of the resource to read (full path)
262     * @param filter the resource filter to use while reading
263     *
264     * @return the file resource that was read or null if it could not be handled by this resource wrapper
265     *
266     * @throws CmsException if the file resource could not be read for any reason
267     */
268    CmsFile readFile(CmsObject cms, String resourcename, CmsResourceFilter filter) throws CmsException;
269
270    /**
271     * Reads a resource from the VFS, using the specified resource filter.<p>
272     *
273     * First should be a check if the resourcename is handled by this
274     * resource wrapper.<p>
275     *
276     * It is possible that the path in the resourcename is a virtual path and
277     * so has to be translated into a valid path existing in the VFS to read the resource.<p>
278     *
279     * @see CmsObjectWrapper#readResource(String, CmsResourceFilter)
280     * @see CmsObject#readResource(String, CmsResourceFilter)
281     *
282     * @param cms the current users OpenCms context
283     * @param resourcename The name of the resource to read (full path)
284     * @param filter the resource filter to use while reading
285     *
286     * @return the resource that was read or null if it could not be handled by this resource wrapper
287     *
288     * @throws CmsException if the resource could not be read for any reason
289     */
290    CmsResource readResource(CmsObject cms, String resourcename, CmsResourceFilter filter) throws CmsException;
291
292    /**
293     * Returns the link to a existing resource in the VFS for the uri.<p>
294     *
295     * Turns the virtual path into a real path to a resource in the VFS.<p>
296     *
297     * @see #rewriteLink(CmsObject, CmsResource)
298     * @see CmsObjectWrapper#restoreLink(String)
299     *
300     * @param cms the initialized CmsObject
301     * @param uri the (virtual) uri to be restored
302     *
303     * @return the uri where to find the resource in the VFS or null if the wrapper is not responsible
304     */
305    String restoreLink(CmsObject cms, String uri);
306
307    /**
308     * Returns the link how it is for the resource after using this resource wrapper.<p>
309     *
310     * For example: in the VFS: "/sites/default/index.html" and this resource wrapper
311     * adds the extension "jsp" then link returned should be "/sites/default/index.html.jsp".<p>
312     *
313     * @see #restoreLink(CmsObject, String)
314     * @see CmsObjectWrapper#rewriteLink(String)
315     *
316     * @param cms the initialized CmsObject
317     * @param res the resource where to rewrite the path
318     *
319     * @return the rewritten path or null if the wrapper is not responsible
320     */
321    String rewriteLink(CmsObject cms, CmsResource res);
322
323    /**
324     * Unlocks a resource.<p>
325     *
326     * First should be a check if the resourcename is handled by this
327     * resource wrapper.<p>
328     *
329     * It is possible that the path in the resourcename is a virtual path and
330     * so has to be translated into a valid path existing in the VFS to unlock the resource.<p>
331     *
332     * @see CmsObjectWrapper#unlockResource(String)
333     * @see CmsObject#unlockResource(String)
334     *
335     * @param cms the current users OpenCms context
336     * @param resourcename the name of the resource to unlock (full path)
337     *
338     * @return true if this request could be handled by this wrapper of false if not
339     *
340     * @throws CmsException if something goes wrong
341     */
342    boolean unlockResource(CmsObject cms, String resourcename) throws CmsException;
343
344    /**
345     * Changes the given resource based on the implementation of this wrapper.<p>
346     *
347     * For example, some resource types like {@link org.opencms.file.types.CmsResourceTypeJsp}
348     * just get a <code>.jsp</code> extension, while other types like
349     * {@link org.opencms.file.types.CmsResourceTypeXmlPage} are "exploded" into a folder /
350     * file structure.<p>
351     *
352     * @see CmsObjectWrapper#getResourcesInFolder(String, CmsResourceFilter)
353     *
354     * @param cms the current users OpenCms context
355     * @param resource the resource to wrap
356     *
357     * @return a wrapped {@link CmsResource} object or <code>null</code> to not change the resource
358     */
359    CmsResource wrapResource(CmsObject cms, CmsResource resource);
360
361    /**
362     * Writes a resource, including it's content.<p>
363     *
364     * First should be a check if the resource is handled by this
365     * resource wrapper.<p>
366     *
367     * It is possible that the path in the resource is a virtual path and
368     * so has to be translated into a valid path existing in the VFS to write the resource.<p>
369     *
370     * @see CmsObjectWrapper#writeFile(CmsFile)
371     * @see CmsObject#writeFile(CmsFile)
372     *
373     * @param cms the current cms context
374     * @param resource the resource to apply this operation to
375     *
376     * @return the written resource or null if the action could not be handled by this resource wrapper
377     *
378     * @throws CmsException if something goes wrong
379     */
380    CmsFile writeFile(CmsObject cms, CmsFile resource) throws CmsException;
381}