001    package railo.commons.io.res;
002    import java.io.IOException;
003    import java.io.InputStream;
004    import java.io.OutputStream;
005    import java.io.Serializable;
006    
007    import railo.commons.io.res.filter.ResourceFilter;
008    import railo.commons.io.res.filter.ResourceNameFilter;
009    
010    
011    /**
012     * a Resource handle connection to different resources in a abstract form
013     */
014    public interface Resource extends Serializable {
015            
016    
017            public static final short ATTRIBUTE_HIDDEN=1; 
018        public static final short ATTRIBUTE_SYSTEM=2; 
019        public static final short ATTRIBUTE_ARCHIVE=4; 
020            
021            /**
022         * Tests whether the application can read the resource denoted by this
023         * abstract pathname.
024         *
025         * @return  <code>true</code> if and only if the resource specified by this
026         *          abstract pathname exists <em>and</em> can be read by the
027         *          application; <code>false</code> otherwise
028         *
029         */
030            public abstract boolean isReadable();
031            
032            /**
033         * Tests whether the application can read the resource denoted by this
034         * abstract pathname.
035         *
036         * @return  <code>true</code> if and only if the resource specified by this
037         *          abstract pathname exists <em>and</em> can be read by the
038         *          application; <code>false</code> otherwise
039         * @deprecated use instead <code>#isReadable()</code>
040         */
041            public abstract boolean canRead();
042    
043        /**
044         * Tests whether the application can modify the resource denoted by this
045         * abstract pathname.
046         *
047         * @return  <code>true</code> if and only if the resource system actually
048         *          contains a resource denoted by this abstract pathname <em>and</em>
049         *          the application is allowed to write to the resource;
050         *          <code>false</code> otherwise.
051         *
052         */
053            public abstract boolean isWriteable();
054    
055        /**
056         * Tests whether the application can modify the resource denoted by this
057         * abstract pathname.
058         *
059         * @return  <code>true</code> if and only if the resource system actually
060         *          contains a resource denoted by this abstract pathname <em>and</em>
061         *          the application is allowed to write to the resource;
062         *          <code>false</code> otherwise.
063         * @deprecated use instead <code>#isWriteable()</code>
064         */
065            public abstract boolean canWrite();
066    
067    
068        /**
069         * Deletes the resource denoted by this abstract pathname.  If
070         * this pathname denotes a directory, then the directory must be empty, 
071         * when argument "force" is set to false, when argument "force" is set to true,
072         * also the children of the directory will be deleted.
073         * @param force 
074         *
075         * @throws  IOException
076         *          if the file doesn't exists or can't delete
077         */
078            public abstract void remove(boolean force) throws IOException;
079    
080            /**
081         * Deletes the resource denoted by this abstract pathname.  If
082         * this pathname denotes a directory, then the directory must be empty, 
083         * when argument "force" is set to false, when argument "force" is set to true,
084         * also the children oif the directory will be deleted.
085         *
086         * @throws  IOException
087         *          if the file doesn't exists or can't delete
088         *@deprecated replaced with method remove(boolean)
089         */
090            public boolean delete();
091            
092            /**
093         * Tests whether the resource denoted by this abstract pathname
094         * exists.
095         *
096         * @return  <code>true</code> if and only if the resource denoted
097         *          by this abstract pathname exists; <code>false</code> otherwise
098         */
099            public abstract boolean exists();
100    
101        /**
102         * Returns the absolute form of this abstract pathname.  
103         *
104         * @return  The absolute abstract pathname denoting the same resource  as this abstract pathname
105         */
106            public abstract Resource getAbsoluteResource();
107    
108        /**
109         * Returns the absolute pathname string of this abstract pathname.
110         *
111         * <p> If this abstract pathname is already absolute, then the pathname
112         * string is simply returned as if by the <code>{@link #getPath}</code>
113         * method.  
114         *
115         * @return  The absolute pathname string denoting the same resource as this abstract pathname
116         *
117         */
118            public abstract String getAbsolutePath();
119    
120        /**
121         * Returns the canonical form of this abstract pathname.  
122         *
123         * @return  The canonical pathname string denoting the same resource as this abstract pathname
124         *
125         * @throws  IOException
126         *          If an I/O error occurs, which is possible because the
127         *          construction of the canonical pathname may require
128         *          filesystem queries
129         *
130         */
131            public abstract Resource getCanonicalResource() throws IOException;
132    
133            /**
134         * Returns the canonical pathname string of this abstract pathname.
135         *
136         * <p> A canonical pathname is both absolute and unique.  The precise
137         * definition of canonical form is system-dependent.  This method first
138         * converts this pathname to absolute form if necessary, as if by invoking the
139         * {@link #getAbsolutePath} method, and then maps it to its unique form in a
140         * system-dependent way.  This typically involves removing redundant names
141         * such as <tt>"."</tt> and <tt>".."</tt> from the pathname.
142         *
143         * <p> Every pathname that denotes an existing file or directory has a
144         * unique canonical form.  Every pathname that denotes a nonexistent resource 
145         * also has a unique canonical form.  The canonical form of
146         * the pathname of a nonexistent file or directory may be different from
147         * the canonical form of the same pathname after the resource is
148         * created.  Similarly, the canonical form of the pathname of an existing
149         * resource may be different from the canonical form of the same
150         * pathname after the resource is deleted.
151         *
152         * @return  The canonical pathname string denoting the same file or
153         *          directory as this abstract pathname
154         *
155         * @throws  IOException
156         *          If an I/O error occurs, which is possible because the
157         *          construction of the canonical pathname may require
158         *          filesystem queries
159         *
160         */
161        public abstract String getCanonicalPath() throws IOException;
162    
163        /**
164         * Returns the name of the resource denoted by this abstract
165         * pathname.  This is just the last name in the pathname's name
166         * sequence.  If the pathname's name sequence is empty, then the empty
167         * string is returned.
168         *
169         * @return  The name of the resource denoted by this abstract
170         *          pathname, or the empty string if this pathname's name sequence
171         *          is empty
172         */
173            public abstract String getName();
174            
175        /**
176         * Returns the pathname string of this abstract pathname's parent, or
177         * <code>null</code> if this pathname does not name a parent directory.
178         *
179         * <p> The <em>parent</em> of an abstract pathname consists of the
180         * pathname's prefix, if any, and each name in the pathname's name
181         * sequence except for the last.  If the name sequence is empty then
182         * the pathname does not name a parent directory.
183         *
184         * @return  The pathname string of the parent directory named by this
185         *          abstract pathname, or <code>null</code> if this pathname
186         *          does not name a parent
187         */
188            public abstract String getParent();
189            
190        /**
191         * Returns the abstract pathname of this abstract pathname's parent,
192         * or <code>null</code> if this pathname does not name a parent
193         * directory.
194         *
195         * <p> The <em>parent</em> of an abstract pathname consists of the
196         * pathname's prefix, if any, and each name in the pathname's name
197         * sequence except for the last.  If the name sequence is empty then
198         * the pathname does not name a parent directory.
199         *
200         * @return  The abstract pathname of the parent directory named by this
201         *          abstract pathname, or <code>null</code> if this pathname
202         *          does not name a parent
203         *
204         */
205            public abstract Resource getParentResource();
206    
207            /**
208             * returns a resource  path that is relative to the current resource
209             * @param realpath
210             * @return relative resource path to the current
211             */
212            public String getReal(String realpath);
213            
214            /**
215             * returns a resource that is relative to the current resource
216             * @param realpath
217             * @return relative resource to the current
218             */
219            public Resource getRealResource(String realpath);
220    
221            /**
222         * Converts this abstract pathname into a pathname string.  
223         *
224         * @return  The string form of this abstract pathname
225         */
226            public abstract String getPath();
227    
228            /**
229         * Tests whether this abstract pathname is absolute. 
230         *
231         * @return  <code>true</code> if this abstract pathname is absolute,
232         *          <code>false</code> otherwise
233         */
234        public abstract boolean isAbsolute();
235    
236        /**
237         * Tests whether the resource denoted by this abstract pathname is a
238         * directory.
239         *
240         * @return <code>true</code> if and only if the file denoted by this
241         *          abstract pathname exists <em>and</em> is a directory;
242         *          <code>false</code> otherwise
243         */
244        public abstract boolean isDirectory();
245    
246        /**
247         * Tests whether the file denoted by this abstract pathname is a normal
248         * file.  A file is <em>normal</em> if it is not a directory and, in
249         * addition, satisfies other system-dependent criteria.  Any non-directory
250         * file created by a Java application is guaranteed to be a normal file.
251         *
252         * @return  <code>true</code> if and only if the file denoted by this
253         *          abstract pathname exists <em>and</em> is a normal file;
254         *          <code>false</code> otherwise
255         */
256        public abstract boolean isFile();
257    
258        /**
259         * Tests whether the resource named by this abstract pathname is a hidden
260         * resource. 
261         *
262         * @return  <code>true</code> if and only if the file denoted by this
263         *          abstract pathname is hidden
264         * @deprecated use instead <code>{@link #getAttribute(short)}</code>
265             */
266        public abstract boolean isHidden();
267        
268        /**
269         * Tests whether the resource named by this abstract pathname is a archive
270         * resource. 
271         *
272         * @return  <code>true</code> if and only if the file denoted by this
273         *          abstract pathname is a archive
274         * @deprecated use instead <code>{@link #getAttribute(short)}</code>
275             */
276        public abstract boolean isArchive();
277        
278        /**
279         * Tests whether the resource named by this abstract pathname is a system
280         * resource. 
281         *
282         * @return  <code>true</code> if and only if the file denoted by this
283         *          abstract pathname is a system resource
284         * @deprecated use instead <code>{@link #getAttribute(short)}</code>
285             */
286        public abstract boolean isSystem();
287    
288        /**
289         * Returns the time that the resource denoted by this abstract pathname was
290         * last modified.
291         *
292         * @return  A <code>long</code> value representing the time the file was
293         *          last modified, measured in milliseconds since the epoch
294         *          (00:00:00 GMT, January 1, 1970), or <code>0L</code> if the
295         *          file does not exist or if an I/O error occurs
296         *
297         */
298        public abstract long lastModified();
299    
300        /**
301         * Returns the length of the resource denoted by this abstract pathname.
302         * The return value is unspecified if this pathname denotes a directory.
303         *
304         * @return  The length, in bytes, of the resource denoted by this abstract
305         *          pathname, or <code>0L</code> if the resource does not exist
306         *
307         */
308        public abstract long length();
309    
310        /**
311         * Returns an array of strings naming the files and directories in the
312         * directory denoted by this abstract pathname.
313         *
314         * <p> If this abstract pathname does not denote a directory, then this
315         * method returns <code>null</code>.  Otherwise an array of strings is
316         * returned, one for each file or directory in the directory.  Names
317         * denoting the directory itself and the directory's parent directory are
318         * not included in the result.  Each string is a file name rather than a
319         * complete path.
320         *
321         * <p> There is no guarantee that the name strings in the resulting array
322         * will appear in any specific order; they are not, in particular,
323         * guaranteed to appear in alphabetical order.
324         *
325         * @return  An array of strings naming the files and directories in the
326         *          directory denoted by this abstract pathname.  The array will be
327         *          empty if the directory is empty.  Returns <code>null</code> if
328         *          this abstract pathname does not denote a directory, or if an
329         *          I/O error occurs.
330         */
331        public abstract String[] list();
332    
333        /**
334         * Returns an array of strings naming the files and directories in the
335         * directory denoted by this abstract pathname that satisfy the specified
336         * filter.  The behavior of this method is the same as that of the
337         * <code>{@link #list()}</code> method, except that the strings in the
338         * returned array must satisfy the filter.  If the given
339         * <code>filter</code> is <code>null</code> then all names are accepted.
340         * Otherwise, a name satisfies the filter if and only if the value
341         * <code>true</code> results when the <code>{@link
342         * ResourceNameFilter#accept}</code> method of the filter is invoked on this
343         * abstract pathname and the name of a file or directory in the directory
344         * that it denotes.
345         *
346         * @param  filter  A resourcename filter
347         *
348         * @return  An array of strings naming the files and directories in the
349         *          directory denoted by this abstract pathname that were accepted
350         *          by the given <code>filter</code>.  The array will be empty if
351         *          the directory is empty or if no names were accepted by the
352         *          filter.  Returns <code>null</code> if this abstract pathname
353         *          does not denote a directory, or if an I/O error occurs.
354         *
355         */
356        public abstract String[] list(ResourceNameFilter filter);
357            
358            public abstract String[] list(ResourceFilter filter);
359    
360            /**
361         * Returns an array of abstract pathnames denoting the files in the
362         * directory denoted by this abstract pathname.
363         *
364         * <p> If this abstract pathname does not denote a directory, then this
365         * method returns <code>null</code>.  Otherwise an array of
366         * <code>File</code> objects is returned, one for each file or directory in
367         * the directory.   Therefore if this pathname
368         * is absolute then each resulting pathname is absolute; if this pathname
369         * is relative then each resulting pathname will be relative to the same
370         * directory.
371         *
372         * <p> There is no guarantee that the name strings in the resulting array
373         * will appear in any specific order; they are not, in particular,
374         * guaranteed to appear in alphabetical order.
375         *
376         * @return  An array of abstract pathnames denoting the files and
377         *          directories in the directory denoted by this abstract
378         *          pathname.  The array will be empty if the directory is
379         *          empty.  Returns <code>null</code> if this abstract pathname
380         *          does not denote a directory, or if an I/O error occurs.
381         */
382        public abstract Resource[] listResources();
383    
384        /**
385         * Returns an array of abstract pathnames denoting the files and
386         * directories in the directory denoted by this abstract pathname that
387         * satisfy the specified filter.  The behavior of this method is the
388         * same as that of the <code>{@link #listResources()}</code> method, except
389         * that the pathnames in the returned array must satisfy the filter.
390         * If the given <code>filter</code> is <code>null</code> then all
391         * pathnames are accepted.  Otherwise, a pathname satisfies the filter
392         * if and only if the value <code>true</code> results when the
393         * <code>{@link ResourceFilter#accept(Resource)}</code> method of
394         * the filter is invoked on the pathname.
395         *
396         * @param  filter  A resource filter
397         *
398         * @return  An array of abstract pathnames denoting the files and
399         *          directories in the directory denoted by this abstract
400         *          pathname.  The array will be empty if the directory is
401         *          empty.  Returns <code>null</code> if this abstract pathname
402         *          does not denote a directory, or if an I/O error occurs.
403         *          
404         */
405        
406        public abstract Resource[] listResources(ResourceFilter filter);
407    
408            /**
409         * Returns an array of abstract pathnames denoting the files and
410         * directories in the directory denoted by this abstract pathname that
411         * satisfy the specified filter.  The behavior of this method is the
412         * same as that of the <code>{@link #listResources()}</code> method, except
413         * that the pathnames in the returned array must satisfy the filter.
414         * If the given <code>filter</code> is <code>null</code> then all
415         * pathnames are accepted.  Otherwise, a pathname satisfies the filter
416         * if and only if the value <code>true</code> results when the
417         * <code>{@link ResourceNameFilter#accept}</code> method of the filter is
418         * invoked on this abstract pathname and the name of a file or
419         * directory in the directory that it denotes.
420         *
421         * @param  filter  A resourcename filter
422         *
423         * @return  An array of abstract pathnames denoting the files and
424         *          directories in the directory denoted by this abstract
425         *          pathname.  The array will be empty if the directory is
426         *          empty.  Returns <code>null</code> if this abstract pathname
427         *          does not denote a directory, or if an I/O error occurs.
428         *          
429         */
430        public abstract Resource[] listResources(ResourceNameFilter filter);
431    
432        
433        /**
434         * Move/renames the file denoted by this abstract pathname.
435         * 
436         * <p> Many aspects of the behavior of this method are inherently
437         * platform-dependent: The rename operation might not be able to move a
438         * file from one filesystem to another, it might not be atomic, and it
439         * might not succeed if a file with the destination abstract pathname
440         * already exists. 
441         *
442         * @param  dest  The new abstract pathname for the named file
443         * @return has successfull renamed or not
444         * 
445         * @deprecated use instead <code>#moveTo(Resource)</code>
446         */ 
447        public boolean renameTo(Resource dest);
448        
449        
450        /**
451         * Move/renames the file denoted by this abstract pathname.
452         * 
453         * <p> Many aspects of the behavior of this method are inherently
454         * platform-dependent: The rename operation might not be able to move a
455         * file from one filesystem to another, it might not be atomic, and it
456         * might not succeed if a file with the destination abstract pathname
457         * already exists. 
458         *
459         * @param  dest  The new abstract pathname for the named file
460         * @throws IOException throwed when operation not done sucessfull
461         * 
462         *
463         */
464        public abstract void moveTo(Resource dest) throws IOException;
465            
466    
467        /**
468         * Sets the last-modified time of the file or directory named by this
469         * abstract pathname.
470         *
471         * <p> All platforms support file-modification times to the nearest second,
472         * but some provide more precision.  The argument will be truncated to fit
473         * the supported precision.  If the operation succeeds and no intervening
474         * operations on the file take place, then the next invocation of the
475         * <code>{@link #lastModified}</code> method will return the (possibly
476         * truncated) <code>time</code> argument that was passed to this method.
477         *
478         * @param  time  The new last-modified time, measured in milliseconds since
479         *               the epoch (00:00:00 GMT, January 1, 1970)
480         *
481         * @return <code>true</code> if and only if the operation succeeded;
482         *          <code>false</code> otherwise
483         *
484         *
485         */
486        public abstract boolean setLastModified(long time);
487    
488        /**
489         * Marks the file or directory named by this abstract pathname so that
490         * only read operations are allowed.  After invoking this method the file
491         * or directory is guaranteed not to change until it is either deleted or
492         * marked to allow write access.  Whether or not a read-only file or
493         * directory may be deleted depends upon the underlying system.
494         *
495         * @return <code>true</code> if and only if the operation succeeded;
496         *          <code>false</code> otherwise
497         * @deprecated use instead <code>{@link #setWritable(boolean)}</code>
498         *
499         */
500        public boolean setReadOnly();
501        
502        //public void setWritable(boolean value) throws IOException;
503        public boolean setWritable(boolean writable);
504        
505        //public void setReadable(boolean value) throws IOException;
506        public boolean setReadable(boolean readable);
507        
508            /**
509         * Creates a new, empty file named by this abstract pathname if
510         * and only if a file with this name does not yet exist.  The check for the
511         * existence of the file and the creation of the file if it does not exist
512         * are a single operation that is atomic with respect to all other
513         * filesystem activities that might affect the file.
514         *
515         * @return  <code>true</code> if the named file does not exist and was
516         *          successfully created; <code>false</code> if the named file
517         *          already exists
518         *
519         * @throws  IOException
520         *          If an I/O error occurred
521         * @deprecated use instead <code>#createFile(boolean)</code>
522         */
523        public boolean createNewFile();
524            
525        /**
526         * Creates a new, empty file named by this abstract pathname if
527         * and only if a file with this name does not yet exist.  The check for the
528         * existence of the file and the creation of the file if it does not exist
529         * are a single operation that is atomic with respect to all other
530         * filesystem activities that might affect the file.
531         * @param createParentWhenNotExists 
532         *
533         *
534         * @throws  IOException
535         *          If an I/O error occurred
536         */
537        public void createFile(boolean createParentWhenNotExists) throws IOException;
538    
539            
540            
541            /**
542         * Creates the directory named by this abstract pathname.
543         *
544         * @return  <code>true</code> if and only if the directory was
545         *          created; <code>false</code> otherwise
546         * @deprecated use <code>#createDirectory(boolean)</code>
547         */
548        public boolean mkdir();
549    
550        /**
551         * Creates the directory named by this abstract pathname, including any
552         * necessary but nonexistent parent directories.  Note that if this
553         * operation fails it may have succeeded in creating some of the necessary
554         * parent directories.
555         *
556         * @return  <code>true</code> if and only if the directory was created,
557         *          along with all necessary parent directories; <code>false</code>
558         *          otherwise
559         * @deprecated use <code>#createDirectory(boolean)</code>
560         */
561        public boolean mkdirs();
562            
563            
564        /**
565         * Creates the directory named by this abstract pathname, including any
566         * necessary but nonexistent parent directories if flag "createParentWhenNotExists" is set to true.  
567         * Note that if this operation fails it may have succeeded in creating some of the necessary
568         * parent directories.
569         * @param createParentWhenNotExists throws Exception when can't create directory
570         * @throws IOException 
571         *
572         */
573        public void createDirectory(boolean createParentWhenNotExists) throws IOException;
574    
575            public InputStream getInputStream() throws IOException;
576    
577            public OutputStream getOutputStream() throws IOException;
578            
579            /**
580             * copy current resource data to given resource
581             * @param res
582             * @throws IOException
583             */
584            public void copyTo(Resource res,boolean append) throws IOException;
585            
586            /**
587             * copy data of given resource to current
588             * @param res
589             * @throws IOException
590             */
591            public void copyFrom(Resource res,boolean append) throws IOException;
592    
593            public OutputStream getOutputStream(boolean append) throws IOException;
594    
595            public abstract ResourceProvider getResourceProvider();
596            
597            public int getMode();
598            
599            public void setMode(int mode) throws IOException;
600    
601            /**
602             * sets hidden attribute of the resource
603             * @param value 
604             * @throws IOException throwed when no access to change the value or the resource doesn't exists
605             * @deprecated use instead <code>{@link #setAttribute(short, boolean)}</code>
606             */
607            public void setHidden(boolean value) throws IOException;
608            
609            /**
610             * sets system attribute of the resource
611             * @param value 
612             * @throws IOException throwed when no access to change the value or the resource doesn't exists
613             * @deprecated use instead <code>{@link #setAttribute(short, boolean)}</code>
614             */
615            public void setSystem(boolean value) throws IOException;        
616            
617            /**
618             * sets archive attribute of the resource
619             * @param value 
620             * @throws IOException throwed when no access to change the value or the resource doesn't exists
621             * @deprecated use instead <code>{@link #setAttribute(short, boolean)}</code>
622             */
623            public void setArchive(boolean value) throws IOException;
624            
625            
626    
627        /** 
628         * sets a attribute on the resource if supported otherwise it will ign 
629         * @param attribute wich attrbute (Resource.ATTRIBUTE_*) 
630         * @param value 
631         * @throws IOException throwed when no access to change the value, 
632         * when attributes are not supported  or 
633         * the resource doesn't exists 
634         */ 
635        public void setAttribute(short attribute, boolean value) throws IOException; 
636        
637        /** 
638         * return value of a specific attribute 
639         * @param attribute 
640         * @return value of the attribute 
641         * @throws IOException throwed when attributes are not supported  or 
642         * the resource doesn't exists 
643         */ 
644        public boolean getAttribute(short attribute); 
645    }