diff --git a/ccm-core/src/main/java/org/libreccm/files/CcmFiles.java b/ccm-core/src/main/java/org/libreccm/files/CcmFiles.java index 3928660ba..46d419337 100644 --- a/ccm-core/src/main/java/org/libreccm/files/CcmFiles.java +++ b/ccm-core/src/main/java/org/libreccm/files/CcmFiles.java @@ -49,16 +49,24 @@ public class CcmFiles { /** * Creates a {@link Reader} for the provided {@code path}. * - * @param path - * @return - * @throws org.libreccm.files.FileDoesNotExistException - * @throws org.libreccm.files.FileAccessException - * @throws org.libreccm.files.InsufficientPermissionsException + * @param path The path of the file. + * + * @return A {@link Reader} for the file identified by the provided + * {@code path}. + * + * @throws FileAccessException If an error not covered by other + * exceptions occurs. + * @throws FileDoesNotExistException If the requested file does not + * exist. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. */ public Reader createReader(final String path) - throws FileDoesNotExistException, - FileAccessException, - InsufficientPermissionsException { + throws FileAccessException, + FileDoesNotExistException, + InsufficientPermissionsException { throw new UnsupportedOperationException(); } @@ -66,13 +74,20 @@ public class CcmFiles { /** * Creates a {@link Writer} for the provided {@code path}. * - * @param path - * @return - * @throws org.libreccm.files.FileAccessException - * @throws org.libreccm.files.InsufficientPermissionsException + * @param path The path. + * + * @return A {@link Writer} for the file identified by {@code path}. + * + * @throws FileAccessException If an error not covered by other + * exceptions occurs. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. */ public Writer createWriter(final String path) - throws FileAccessException, InsufficientPermissionsException { + throws FileAccessException, + InsufficientPermissionsException { throw new UnsupportedOperationException(); } @@ -80,15 +95,22 @@ public class CcmFiles { * Creates a {@link InputStream} for the provided {@code path}. * * @param path + * * @return - * @throws org.libreccm.files.FileDoesNotExistException - * @throws org.libreccm.files.FileAccessException - * @throws org.libreccm.files.InsufficientPermissionsException + * + * @throws FileAccessException If an error not covered by + * other exceptions occurs. + * @throws FileDoesNotExistException If the requested file does not + * exist. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. */ public InputStream createInputStream(final String path) - throws FileDoesNotExistException, - FileAccessException, - InsufficientPermissionsException { + throws FileDoesNotExistException, + FileAccessException, + InsufficientPermissionsException { throw new UnsupportedOperationException(); } @@ -97,12 +119,19 @@ public class CcmFiles { * Creates a {@link OutputStream} for the provided {@code path}. * * @param path + * * @return - * @throws org.libreccm.files.FileAccessException - * @throws org.libreccm.files.InsufficientPermissionsException + * + * @throws FileAccessException If an error not covered by other + * exceptions occurs. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. */ public OutputStream createOutputStream(final String path) - throws FileAccessException, InsufficientPermissionsException { + throws FileAccessException, + InsufficientPermissionsException { throw new UnsupportedOperationException(); } @@ -110,13 +139,20 @@ public class CcmFiles { * Checks if a file exists. * * @param path + * * @return {@code true} if a file with the provided {@code path} exists, - * {@code false} otherwise. - * @throws org.libreccm.files.FileAccessException - * @throws org.libreccm.files.InsufficientPermissionsException + * {@code false} otherwise. + * + * @throws FileAccessException If an error not covered by other + * exceptions occurs. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. */ public boolean existsFile(final String path) - throws FileAccessException, InsufficientPermissionsException { + throws FileAccessException, + InsufficientPermissionsException { throw new UnsupportedOperationException(); } @@ -124,16 +160,23 @@ public class CcmFiles { * checks if the provided path points to a directory. * * @param path + * * @return {@code true} if the the file to which the provided path points - * exists and is a directory, {@code false} otherwise. - * @throws org.libreccm.files.FileAccessException - * @throws org.libreccm.files.InsufficientPermissionsException - * @throws org.libreccm.files.FileDoesNotExistException + * exists and is a directory, {@code false} otherwise. + * + * @throws FileAccessException If an error not covered by other + * exceptions occurs. + * @throws FileDoesNotExistException If the requested file does not + * exist. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. */ public boolean isDirectory(final String path) - throws FileAccessException, - FileDoesNotExistException, - InsufficientPermissionsException { + throws FileAccessException, + FileDoesNotExistException, + InsufficientPermissionsException { throw new UnsupportedOperationException(); } @@ -141,14 +184,20 @@ public class CcmFiles { * Create a directory at the provided path. * * @param path The path of the new directory. - * @throws org.libreccm.files.FileAccessException - * @throws org.libreccm.files.FileAlreadyExistsException - * @throws org.libreccm.files.InsufficientPermissionsException + * + * @throws FileAccessException If an error not covered by other + * exceptions occurs. + * @throws FileAlreadyExistsException If the requested file does not + * exist. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. */ public void createDirectory(final String path) - throws FileAccessException, - FileAlreadyExistsException, - InsufficientPermissionsException { + throws FileAccessException, + FileAlreadyExistsException, + InsufficientPermissionsException { throw new UnsupportedOperationException(); } @@ -156,15 +205,22 @@ public class CcmFiles { * List the files in a directory. * * @param path The {@code path} of the directory. + * * @return A list of the names of the files in the directory. - * @throws org.libreccm.files.FileAccessException - * @throws org.libreccm.files.FileDoesNotExistException - * @throws org.libreccm.files.InsufficientPermissionsException + * + * @throws FileAccessException If an error not covered by other + * exceptions occurs. + * @throws FileDoesNotExistException If the requested file does not + * exist. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. */ public List listFiles(final String path) - throws FileAccessException, - FileDoesNotExistException, - InsufficientPermissionsException { + throws FileAccessException, + FileDoesNotExistException, + InsufficientPermissionsException { throw new UnsupportedOperationException(); } @@ -173,16 +229,25 @@ public class CcmFiles { * be empty. * * @param path The path of the file to delete. - * @throws org.libreccm.files.FileAccessException - * @throws org.libreccm.files.FileDoesNotExistException - * @throws org.libreccm.files.DirectoryNotEmptyException - * @throws org.libreccm.files.InsufficientPermissionsException + * + * @throws FileAccessException If an error not covered by other + * exceptions occurs. + * @throws FileDoesNotExistException If the requested file does not + * exist. + * @throws DirectoryNotEmptyException If the file to delete is a non + * empty directory. To delete a + * directory recursively use + * {@link #deleteFile(java.lang.String, boolean)}. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. */ public void deleteFile(final String path) - throws FileAccessException, - FileDoesNotExistException, - DirectoryNotEmptyException, - InsufficientPermissionsException { + throws FileAccessException, + FileDoesNotExistException, + DirectoryNotEmptyException, + InsufficientPermissionsException { throw new UnsupportedOperationException(); } @@ -191,14 +256,21 @@ public class CcmFiles { * * @param path * @param recursively Delete directories recursively. - * @throws org.libreccm.files.FileAccessException - * @throws org.libreccm.files.FileDoesNotExistException - * @throws org.libreccm.files.InsufficientPermissionsException + * + * @throws FileAccessException If an error not covered by other + * exceptions occurs. + * @throws FileDoesNotExistException If the requested file does not + * exist. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. */ public void deleteFile(final String path, final boolean recursively) - throws FileAccessException, - FileDoesNotExistException, - InsufficientPermissionsException { + throws FileAccessException, + FileDoesNotExistException, + InsufficientPermissionsException { throw new UnsupportedOperationException(); } + } diff --git a/ccm-core/src/main/java/org/libreccm/files/FileSystemAdapter.java b/ccm-core/src/main/java/org/libreccm/files/FileSystemAdapter.java new file mode 100644 index 000000000..e12114b85 --- /dev/null +++ b/ccm-core/src/main/java/org/libreccm/files/FileSystemAdapter.java @@ -0,0 +1,245 @@ +/* + * Copyright (C) 2017 LibreCCM Foundation. + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, + * MA 02110-1301 USA + */ +package org.libreccm.files; + +import java.io.InputStream; +import java.io.OutputStream; +import java.io.Reader; +import java.io.Writer; +import java.util.List; + +/** + * + * @author Jens Pelzetter + */ +public interface FileSystemAdapter { + + /** + * Tests if all resources (eg JNDI resources) etc required by an + * implementation of the {@link FileSystemAdapter} are available. + * + * @return {@code true} if all resources are available and the adapter can + * be used, {@code false} if not. + */ + boolean isConfigured(); + + /** + * Creates a {@link Reader} for the provided {@code path}. + * + * @param path The path of the file. + * + * @return A {@link Reader} for the file identified by the provided + * {@code path}. + * + * @throws FileAccessException If an error not covered by other + * exceptions occurs. + * @throws FileDoesNotExistException If the requested file does not + * exist. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. + */ + Reader createReader(String path) throws FileDoesNotExistException, + FileAccessException, + InsufficientPermissionsException; + + /** + * Creates a {@link Writer} for the provided {@code path}. + * + * @param path The path. + * + * @return A {@link Writer} for the file identified by {@code path}. + * + * @throws FileAccessException If an error not covered by other + * exceptions occurs. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. + */ + Writer createWriter(String path) throws FileAccessException, + InsufficientPermissionsException; + + /** + * Creates a {@link InputStream} for the provided {@code path}. + * + * @param path + * + * @return + * + * @throws FileAccessException If an error not covered by other + * exceptions occurs. + * @throws FileDoesNotExistException If the requested file does not + * exist. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. + */ + InputStream createInputStream(String path) + throws FileDoesNotExistException, + FileAccessException, + InsufficientPermissionsException; + + /** + * Creates a {@link OutputStream} for the provided {@code path}. + * + * @param path + * + * @return + * + * @throws FileAccessException If an error not covered by other + * exceptions occurs. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. + */ + OutputStream createOutputStream(String path) + throws FileAccessException, + InsufficientPermissionsException; + + /** + * Checks if a file exists. + * + * @param path + * + * @return {@code true} if a file with the provided {@code path} exists, + * {@code false} otherwise. + * + * @throws FileAccessException If an error not covered by other + * exceptions occurs. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. + */ + boolean existsFile(String path) + throws FileAccessException, + InsufficientPermissionsException; + + /** + * checks if the provided path points to a directory. + * + * @param path + * + * @return {@code true} if the the file to which the provided path points + * exists and is a directory, {@code false} otherwise. + * + * @throws FileAccessException If an error not covered by other + * exceptions occurs. + * @throws FileDoesNotExistException If the requested file does not + * exist. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. + */ + boolean isDirectory(String path) + throws FileAccessException, + FileDoesNotExistException, + InsufficientPermissionsException; + + /** + * Create a directory at the provided path. + * + * @param path The path of the new directory. + * + * @throws FileAccessException If an error not covered by other + * exceptions occurs. + * @throws FileAlreadyExistsException If the requested file does not + * exist. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. + */ + void createDirectory(String path) + throws FileAccessException, + FileAlreadyExistsException, + InsufficientPermissionsException; + + /** + * List the files in a directory. + * + * @param path The {@code path} of the directory. + * + * @return A list of the names of the files in the directory. + * + * @throws FileAccessException If an error not covered by other + * exceptions occurs. + * @throws FileDoesNotExistException If the requested file does not + * exist. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. + */ + List listFiles(String path) + throws FileAccessException, + FileDoesNotExistException, + InsufficientPermissionsException; + + /** + * Delete a file or directory. If the file is a directory the directory must + * be empty. + * + * @param path The path of the file to delete. + * + * @throws FileAccessException If an error not covered by other + * exceptions occurs. + * @throws FileDoesNotExistException If the requested file does not + * exist. + * @throws DirectoryNotEmptyException If the file to delete is a non + * empty directory. To delete a + * directory recursively use + * {@link #deleteFile(java.lang.String, boolean)}. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. + */ + void deleteFile(String path) + throws FileAccessException, + FileDoesNotExistException, + DirectoryNotEmptyException, + InsufficientPermissionsException; + + /** + * Delete a file or directory. + * + * @param path + * @param recursively Delete directories recursively. + * + * @throws FileAccessException If an error not covered by other + * exceptions occurs. + * @throws FileDoesNotExistException If the requested file does not + * exist. + * @throws InsufficientPermissionsException If the user which runs the + * application server does not have + * the permission to access the + * requested file. + */ + void deleteFile(String path, boolean recursively) + throws FileAccessException, + FileDoesNotExistException, + InsufficientPermissionsException; + +}