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 }