LibreCCM
/
libreccm
3
0
Fork 0
Code Issues 10 Pull Requests Packages Releases Wiki Activity

CCM NG/ccm-core: More documentation for the CcmFiles 

git-svn-id: https://svn.libreccm.org/ccm/ccm_ng@4706 8810af33-2d31-482b-a856-94f89814c4df
ccm-docs
jensp 2017-05-04 07:45:31 +00:00
parent b24263cf68
commit be93af8410
1 changed files with 83 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

152
ccm-core/src/main/java/org/libreccm/files/CcmFiles.java
View File

@ -35,7 +35,7 @@ import javax.faces.bean.RequestScoped;
import javax.inject.Inject; import javax.inject.Inject;
/** /**
* This class provides access to the file (local) system. If available an * This class provides access to the (local) file system. If available an
* implementation of the {@link FileSystemAdapter} interface is used. The * implementation of the {@link FileSystemAdapter} interface is used. The
* implementations of {@link FileSystemAdapter} provide a (transaction) safe way * implementations of {@link FileSystemAdapter} provide a (transaction) safe way
* to access the local file system. If no implementation of * to access the local file system. If no implementation of
@ -46,9 +46,13 @@ import javax.inject.Inject;
* {@link FileSystemAdapter} please refer the the documentation of the * {@link FileSystemAdapter} please refer the the documentation of the
* implementation. * implementation.
* *
* The method in this class encapsulate the details of the access to the local * The method in this class encapsulates the details of the access to the local
* file system. Therefore the paths to the files to read are usually provided as * file system. Therefore the paths to the files to read or write are usually
* strings. * provided as strings.
*
* This class does not provide access to the complete file system of the server.
* Instead a directory has been configured before using this class. The methods
* in this class will interpret the paths provided relative to this directory.
* *
* @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a> * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
*/ */
@ -63,6 +67,14 @@ public class CcmFiles {
@Inject @Inject
private ConfigurationManager confManager; private ConfigurationManager confManager;
/**
* A helper method for getting the {@link FileSystemAdapter} implementation
* to use.
*
* @return The implementation of the {@link FileSystemAdapter} interface to
* use. If no other implementation is available the default implementation
* {@link NIOFileSystemAdapter}.
*/
private FileSystemAdapter getFileSystemAdapter() { private FileSystemAdapter getFileSystemAdapter() {
LOGGER.debug("Trying to find FileSystemAdapter..."); LOGGER.debug("Trying to find FileSystemAdapter...");
@ -119,7 +131,8 @@ public class CcmFiles {
throw new UnexpectedErrorException( throw new UnexpectedErrorException(
"Multiple implementations of the FileSystemAdapter " "Multiple implementations of the FileSystemAdapter "
+ "interface are available but " + "interface are available but "
+ "activeFileSystemAdapter is not set."); + "activeFileSystemAdapter is not set. Please set "
+ "the FileSystemAdapter to use.");
} }
final FileSystemAdapter adapter = adapters final FileSystemAdapter adapter = adapters
@ -150,9 +163,9 @@ public class CcmFiles {
if (NIOFileSystemAdapter.class.getName().equals(adapter.getClass() if (NIOFileSystemAdapter.class.getName().equals(adapter.getClass()
.getName())) { .getName())) {
LOGGER.warn("Only the default FileSystemAdapter '{}' which " LOGGER.warn("Only the default FileSystemAdapter '{}' which "
+ "accesses the file system directly available. It is" + "accesses the file system directly is available. It is"
+ "strongly recommanded to install and configure a another " + "strongly recommanded to install and configure a another "
+ "ileSystemAdapter which accesses the FileSystem in a way" + "FileSystemAdapter which accesses the file system in a way"
+ "which complies to the Java EE specification."); + "which complies to the Java EE specification.");
} }
if (adapter.isConfigured()) { if (adapter.isConfigured()) {
@ -165,6 +178,15 @@ public class CcmFiles {
} }
} }
/**
* A helper method to create the path relative the the path of the data
* directory This method also normalises the path by removing or adding
* slashes at the end or beginning of the string as necessary.
*
* @param path The path the transform into a path relative to the data
* directories path.
* @return The absolute path.
*/
private String getDataPath(final String path) { private String getDataPath(final String path) {
final StringBuilder builder = new StringBuilder(); final StringBuilder builder = new StringBuilder();
@ -201,14 +223,12 @@ public class CcmFiles {
* @return A {@link Reader} for the file identified by the provided * @return A {@link Reader} for the file identified by the provided
* {@code path}. * {@code path}.
* *
* @throws FileAccessException If an error not covered by other * @throws FileAccessException If an error not covered by other exceptions
* exceptions occurs. * occurs.
* @throws FileDoesNotExistException If the requested file does not * @throws FileDoesNotExistException If the requested file does not exist.
* exist.
* @throws InsufficientPermissionsException If the user which runs the * @throws InsufficientPermissionsException If the user which runs the
* application server does not have * application server does not have the permission to access the requested
* the permission to access the * file.
* requested file.
*/ */
public Reader createReader(final String path) public Reader createReader(final String path)
throws FileAccessException, throws FileAccessException,
@ -225,12 +245,11 @@ public class CcmFiles {
* *
* @return A {@link Writer} for the file identified by {@code path}. * @return A {@link Writer} for the file identified by {@code path}.
* *
* @throws FileAccessException If an error not covered by other * @throws FileAccessException If an error not covered by other exceptions
* exceptions occurs. * occurs.
* @throws InsufficientPermissionsException If the user which runs the * @throws InsufficientPermissionsException If the user which runs the
* application server does not have * application server does not have the permission to access the requested
* the permission to access the * file.
* requested file.
*/ */
public Writer createWriter(final String path) public Writer createWriter(final String path)
throws FileAccessException, throws FileAccessException,
@ -246,14 +265,12 @@ public class CcmFiles {
* *
* @return * @return
* *
* @throws FileAccessException If an error not covered by other * @throws FileAccessException If an error not covered by other exceptions
* exceptions occurs. * occurs.
* @throws FileDoesNotExistException If the requested file does not * @throws FileDoesNotExistException If the requested file does not exist.
* exist.
* @throws InsufficientPermissionsException If the user which runs the * @throws InsufficientPermissionsException If the user which runs the
* application server does not have * application server does not have the permission to access the requested
* the permission to access the * file.
* requested file.
*/ */
public InputStream createInputStream(final String path) public InputStream createInputStream(final String path)
throws FileDoesNotExistException, throws FileDoesNotExistException,
@ -270,12 +287,11 @@ public class CcmFiles {
* *
* @return * @return
* *
* @throws FileAccessException If an error not covered by other * @throws FileAccessException If an error not covered by other exceptions
* exceptions occurs. * occurs.
* @throws InsufficientPermissionsException If the user which runs the * @throws InsufficientPermissionsException If the user which runs the
* application server does not have * application server does not have the permission to access the requested
* the permission to access the * file.
* requested file.
*/ */
public OutputStream createOutputStream(final String path) public OutputStream createOutputStream(final String path)
throws FileAccessException, throws FileAccessException,
@ -292,12 +308,11 @@ public class CcmFiles {
* @return {@code true} if a file with the provided {@code path} exists, * @return {@code true} if a file with the provided {@code path} exists,
* {@code false} otherwise. * {@code false} otherwise.
* *
* @throws FileAccessException If an error not covered by other * @throws FileAccessException If an error not covered by other exceptions
* exceptions occurs. * occurs.
* @throws InsufficientPermissionsException If the user which runs the * @throws InsufficientPermissionsException If the user which runs the
* application server does not have * application server does not have the permission to access the requested
* the permission to access the * file.
* requested file.
*/ */
public boolean existsFile(final String path) public boolean existsFile(final String path)
throws FileAccessException, throws FileAccessException,
@ -314,14 +329,12 @@ public class CcmFiles {
* @return {@code true} if the the file to which the provided path points * @return {@code true} if the the file to which the provided path points
* exists and is a directory, {@code false} otherwise. * exists and is a directory, {@code false} otherwise.
* *
* @throws FileAccessException If an error not covered by other * @throws FileAccessException If an error not covered by other exceptions
* exceptions occurs. * occurs.
* @throws FileDoesNotExistException If the requested file does not * @throws FileDoesNotExistException If the requested file does not exist.
* exist.
* @throws InsufficientPermissionsException If the user which runs the * @throws InsufficientPermissionsException If the user which runs the
* application server does not have * application server does not have the permission to access the requested
* the permission to access the * file.
* requested file.
*/ */
public boolean isDirectory(final String path) public boolean isDirectory(final String path)
throws FileAccessException, throws FileAccessException,
@ -336,14 +349,12 @@ public class CcmFiles {
* *
* @param path The path of the new directory. * @param path The path of the new directory.
* *
* @throws FileAccessException If an error not covered by other * @throws FileAccessException If an error not covered by other exceptions
* exceptions occurs. * occurs.
* @throws FileAlreadyExistsException If the requested file does not * @throws FileAlreadyExistsException If the requested file does not exist.
* exist.
* @throws InsufficientPermissionsException If the user which runs the * @throws InsufficientPermissionsException If the user which runs the
* application server does not have * application server does not have the permission to access the requested
* the permission to access the * file.
* requested file.
*/ */
public void createDirectory(final String path) public void createDirectory(final String path)
throws FileAccessException, throws FileAccessException,
@ -360,14 +371,12 @@ public class CcmFiles {
* *
* @return A list of the names of the files in the directory. * @return A list of the names of the files in the directory.
* *
* @throws FileAccessException If an error not covered by other * @throws FileAccessException If an error not covered by other exceptions
* exceptions occurs. * occurs.
* @throws FileDoesNotExistException If the requested file does not * @throws FileDoesNotExistException If the requested file does not exist.
* exist.
* @throws InsufficientPermissionsException If the user which runs the * @throws InsufficientPermissionsException If the user which runs the
* application server does not have * application server does not have the permission to access the requested
* the permission to access the * file.
* requested file.
*/ */
public List<String> listFiles(final String path) public List<String> listFiles(final String path)
throws FileAccessException, throws FileAccessException,
@ -383,18 +392,15 @@ public class CcmFiles {
* *
* @param path The path of the file to delete. * @param path The path of the file to delete.
* *
* @throws FileAccessException If an error not covered by other * @throws FileAccessException If an error not covered by other exceptions
* exceptions occurs. * occurs.
* @throws FileDoesNotExistException If the requested file does not * @throws FileDoesNotExistException If the requested file does not exist.
* exist. * @throws DirectoryNotEmptyException If the file to delete is a non empty
* @throws DirectoryNotEmptyException If the file to delete is a non * directory. To delete a directory recursively use
* empty directory. To delete a
* directory recursively use
* {@link #deleteFile(java.lang.String, boolean)}. * {@link #deleteFile(java.lang.String, boolean)}.
* @throws InsufficientPermissionsException If the user which runs the * @throws InsufficientPermissionsException If the user which runs the
* application server does not have * application server does not have the permission to access the requested
* the permission to access the * file.
* requested file.
*/ */
public void deleteFile(final String path) public void deleteFile(final String path)
throws FileAccessException, throws FileAccessException,
@ -411,16 +417,14 @@ public class CcmFiles {
* @param path * @param path
* @param recursively Delete directories recursively. * @param recursively Delete directories recursively.
* *
* @throws FileAccessException If an error not covered by other * @throws FileAccessException If an error not covered by other exceptions
* exceptions occurs. * occurs.
* @throws FileDoesNotExistException If the requested file does not * @throws FileDoesNotExistException If the requested file does not exist.
* exist.
* @throws DirectoryNotEmptyException If the directory is not empty * @throws DirectoryNotEmptyException If the directory is not empty
* <em>and</em> {@code recursively} is set to {@code false}. * <em>and</em> {@code recursively} is set to {@code false}.
* @throws InsufficientPermissionsException If the user which runs the * @throws InsufficientPermissionsException If the user which runs the
* application server does not have * application server does not have the permission to access the requested
* the permission to access the * file.
* requested file.
*/ */
public void deleteFile(final String path, final boolean recursively) public void deleteFile(final String path, final boolean recursively)
throws FileAccessException, throws FileAccessException,