001/**
002 *
003 * Copyright (c) 2014, the Railo Company Ltd. All rights reserved.
004 *
005 * This library is free software; you can redistribute it and/or
006 * modify it under the terms of the GNU Lesser General Public
007 * License as published by the Free Software Foundation; either 
008 * version 2.1 of the License, or (at your option) any later version.
009 * 
010 * This library is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
013 * Lesser General Public License for more details.
014 * 
015 * You should have received a copy of the GNU Lesser General Public 
016 * License along with this library.  If not, see <http://www.gnu.org/licenses/>.
017 * 
018 **/
019package lucee.runtime.util;
020
021import java.io.File;
022import java.io.FileNotFoundException;
023import java.io.IOException;
024
025import lucee.commons.io.res.Resource;
026import lucee.commons.io.res.filter.ResourceFilter;
027import lucee.commons.io.res.filter.ResourceNameFilter;
028import lucee.runtime.PageContext;
029import lucee.runtime.exp.PageException;
030
031public interface ResourceUtil {
032        
033                
034                /**
035             * Field <code>FILE_SEPERATOR</code>
036             */
037            public static final char FILE_SEPERATOR=File.separatorChar; 
038            /**
039             * Field <code>FILE_ANTI_SEPERATOR</code>
040             */
041            public static final char FILE_ANTI_SEPERATOR=(FILE_SEPERATOR=='/')?'\\':'/';
042            
043            /**
044             * Field <code>TYPE_DIR</code>
045             */
046            public static final short TYPE_DIR=0;
047            
048            /**
049             * Field <code>TYPE_FILE</code>
050             */
051            public static final short TYPE_FILE=1;
052
053            /**
054             * Field <code>LEVEL_FILE</code>
055             */
056            public static final short LEVEL_FILE=0;
057            /**
058             * Field <code>LEVEL_PARENT_FILE</code>
059             */
060            public static final short LEVEL_PARENT_FILE=1;
061            /**
062             * Field <code>LEVEL_GRAND_PARENT_FILE</code>
063             */
064            public static final short LEVEL_GRAND_PARENT_FILE=2;
065                
066            /**
067             * cast a String (argument destination) to a File Object, 
068             * if destination is not a absolute, file object will be relative to current position (get from PageContext)
069             * file must exist otherwise throw exception
070             * @param pc Page Context to et actuell position in filesystem
071             * @param path relative or absolute path for file object
072             * @return file object from destination
073             * @throws ExpressionException
074             */
075            public Resource toResourceExisting(PageContext pc ,String path) throws PageException;
076            
077
078            /**
079             * cast a String (argument destination) to a File Object, 
080             * if destination is not a absolute, file object will be relative to current position (get from PageContext)
081             * at least parent must exist
082             * @param pc Page Context to et actuell position in filesystem
083             * @param destination relative or absolute path for file object
084             * @return file object from destination
085             * @throws ExpressionException
086             */
087            public Resource toResourceExistingParent(PageContext pc ,String destination) throws PageException;
088            
089            /**
090             * cast a String (argument destination) to a File Object, 
091             * if destination is not a absolute, file object will be relative to current position (get from PageContext)
092             * existing file is prefered but dont must exist
093             * @param pc Page Context to et actuell position in filesystem
094             * @param destination relative or absolute path for file object
095             * @return file object from destination
096             */
097            public Resource toResourceNotExisting(PageContext pc ,String destination);
098                        
099            /**
100             * create a file if possible, return file if ok, otherwise return null 
101             * @param res file to touch 
102             * @param level touch also parent and grand parent
103             * @param type is file or directory
104             * @return file if exists, otherwise null
105             */
106            public Resource createResource(Resource res, short level, short type);
107            
108                /**
109                 * sets a attribute to the resource
110                 * @param res
111                 * @param attributes
112                 * @throws IOException
113                 */
114                public void setAttribute(Resource res,String attributes) throws IOException;
115                
116            /**
117             * return the mime type of a file, does not check the extension of the file, it checks the header
118             * @param res
119             * @param defaultValue 
120             * @return mime type of the file
121             */
122            public String getMimeType(Resource res, String defaultValue);
123
124            /**
125             * return the mime type of a byte array
126             * @param barr
127             * @param defaultValue 
128             * @return mime type of the file
129             */
130            public String getMimeType(byte[] barr, String defaultValue);
131            
132                /**
133                 * check if file is a child of given directory
134                 * @param file file to search
135                 * @param dir directory to search
136                 * @return is inside or not
137                 */
138                public boolean isChildOf(Resource file, Resource dir);
139                
140                /**
141                 * return diffrents of one file to a other if first is child of second otherwise return null
142                 * @param file file to search
143                 * @param dir directory to search
144                 */
145                public String getPathToChild(Resource file, Resource dir);
146                
147            /**
148             * get the Extension of a file resource
149             * @param res
150             * @return extension of file
151             * @deprecated use instead <code>getExtension(Resource res, String defaultValue);</code>
152             */
153            public String getExtension(Resource res);
154
155            /**
156             * get the Extension of a file resource
157             * @param res
158             * @return extension of file
159             */
160            public String getExtension(Resource res, String defaultValue);
161
162            /**
163             * get the Extension of a file
164             * @param strFile
165             * @return extension of file
166             * @deprecated use instead <code>getExtension(String strFile, String defaultValue);</code>
167             */
168            public String getExtension(String strFile);
169
170            /**
171             * get the Extension of a file resource
172             * @param res
173             * @return extension of file
174             */
175            public String getExtension(String strFile, String defaultValue);
176            
177
178            /**
179             * copy a file or directory recursive (with his content)
180             * @param file file or directory to delete
181             * @throws IOException 
182             * @throws FileNotFoundException 
183             */
184            public void copyRecursive(Resource src,Resource trg) throws IOException;
185            
186            
187            /**
188             * copy a file or directory recursive (with his content)
189             * @param src
190             * @param trg
191             * @param filter
192             * @throws IOException 
193             * @throws FileNotFoundException 
194             */
195            public void copyRecursive(Resource src,Resource trg,ResourceFilter filter) throws IOException;
196            
197            public void removeChildren(Resource res) throws IOException;
198
199                public void removeChildren(Resource res,ResourceNameFilter filter) throws IOException;
200                
201                public void removeChildren(Resource res,ResourceFilter filter) throws IOException;
202                
203                public void moveTo(Resource src, Resource dest) throws IOException;
204
205
206                /**
207                 * return if Resource is empty, means is directory and has no children or a empty file,
208                 * if not exist return false.
209                 * @param res
210                 */
211                public boolean isEmpty(Resource res);
212
213                public boolean isEmptyDirectory(Resource res);
214                
215                public boolean isEmptyFile(Resource res);
216                
217                public String translatePath(String path, boolean slashAdBegin, boolean slashAddEnd);
218                
219                public String[] translatePathName(String path);
220                
221                public String merge(String parent, String child);
222                
223                public String removeScheme(String scheme, String path);
224                
225                /**
226                 * check if directory creation is ok with the rules for the Resource interface, to not change this rules.
227                 * @param resource
228                 * @param createParentWhenNotExists
229                 * @throws IOException
230                 */
231                public void checkCreateDirectoryOK(Resource resource, boolean createParentWhenNotExists) throws IOException;
232
233
234                /**
235                 * check if file creating is ok with the rules for the Resource interface, to not change this rules.
236                 * @param resource
237                 * @param createParentWhenNotExists
238                 * @throws IOException
239                 */
240                public void checkCreateFileOK(Resource resource, boolean createParentWhenNotExists) throws IOException;
241
242                /**
243                 * check if copying a file is ok with the rules for the Resource interface, to not change this rules.
244                 * @param source
245                 * @param target
246                 * @throws IOException
247                 */
248                public void checkCopyToOK(Resource source, Resource target) throws IOException;
249
250                /**
251                 * check if moveing a file is ok with the rules for the Resource interface, to not change this rules.
252                 * @param source
253                 * @param target
254                 * @throws IOException
255                 */
256                public void checkMoveToOK(Resource source, Resource target) throws IOException;
257
258                /**
259                 * check if getting a inputstream of the file is ok with the rules for the Resource interface, to not change this rules.
260                 * @param resource
261                 * @throws IOException
262                 */
263                public void checkGetInputStreamOK(Resource resource) throws IOException;
264
265                /**
266                 * check if getting a outputstream of the file is ok with the rules for the Resource interface, to not change this rules.
267                 * @param resource
268                 * @throws IOException
269                 */
270                public void checkGetOutputStreamOK(Resource resource) throws IOException;
271
272                /**
273                 * check if removing the file is ok with the rules for the Resource interface, to not change this rules.
274                 * @param resource
275                 * @throws IOException
276                 */
277                public void checkRemoveOK(Resource resource) throws IOException;
278
279
280                public String toString(Resource r, String charset) throws IOException;
281
282
283                public String contractPath(PageContext pc, String path);
284
285}