1 /*
2 * Copyright (C) 2010-2014 Hamburg Sud and the contributors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.aludratest.service.file;
17
18 import java.io.BufferedReader;
19 import java.io.InputStream;
20 import java.io.Reader;
21 import java.util.List;
22
23 import org.aludratest.exception.AutomationException;
24 import org.aludratest.impl.log4testing.ElementType;
25 import org.aludratest.impl.log4testing.TechnicalLocator;
26 import org.aludratest.service.Interaction;
27
28 /**
29 * {@link Interaction} interface of the {@link FileService}.
30 * @author Volker Bergmann
31 */
32 public interface FileInteraction extends Interaction {
33
34 /** Provides the root folder of the service instance.
35 * @return the root folder of the {@link FileService}. */
36 String getRootFolder();
37
38 /** Lists all child elements of the given folder.
39 * @param filePath the path of the file of which to get children
40 * @return a {@link List} of the child objects of the given file
41 */
42 List<String> getChildren(@TechnicalLocator String filePath);
43
44 /** Lists all child elements of the given folder which match the given regular expression.
45 * @param filePath the path of the file of which to get the children
46 * @param filterRegex
47 * @return a {@link List} of the child objects of the given file
48 */
49 List<String> getChildren(@TechnicalLocator String filePath, String filterRegex);
50
51 /** Lists all child elements of the given folder which match the filter.
52 * @param filePath the path of the file of which to get the children
53 * @param filter
54 * @return a {@link List} of the child objects of the given file
55 */
56 List<String> getChildren(@TechnicalLocator String filePath, FileFilter filter);
57
58 /** Creates a directory.
59 * @param directoryPath the path of the directory to create
60 */
61 void createDirectory(@TechnicalLocator String directoryPath);
62
63 /** Renames or moves a file or folder.
64 * @param fromPath the file/folder to rename/move
65 * @param toPath the new name/location of the file/folder
66 * @param overwrite flag which indicates if an existing file may be overwritten by the operation
67 * @return true if a formerly existing file was overwritten.
68 * @throws org.aludratest.service.file.exception.FilePresentException if a file was already present and overwriting was disabled. */
69 boolean move(@TechnicalLocator String fromPath, String toPath, boolean overwrite);
70
71 /** Copies a file or folder.
72 * @param fromPath the file/folder to copy
73 * @param toPath the name/location of the copy
74 * @param overwrite flag which indicates if an existing file may be overwritten by the operation
75 * @return true if a formerly existing file was overwritten.
76 * @throws org.aludratest.service.file.exception.FilePresentException if a file was already present and overwriting was disabled. */
77 boolean copy(@TechnicalLocator String fromPath, String toPath, boolean overwrite);
78
79 /** Deletes a file or folder.
80 * @param filePath the path of the file to delete
81 */
82 void delete(@TechnicalLocator String filePath);
83
84 /** Creates a text file with the provided content.
85 * @param filePath the path of the file to save
86 * @param text the text to save as file content
87 * @param overwrite flag which indicates if an existing file may be overwritten by the operation
88 * @return true if a formerly existing file was overwritten.
89 * @throws org.aludratest.service.file.exception.FilePresentException if a file was already present and overwriting was disabled. */
90 boolean writeTextFile(@TechnicalLocator String filePath, String text, boolean overwrite);
91
92 /** Creates a text file and writes to it all content provided by the source Reader.
93 * @param filePath the path of the file to save
94 * @param source a {@link Reader} which provides the file content
95 * @param overwrite flag which indicates if an existing file may be overwritten by the operation
96 * @return true if a formerly existing file was overwritten.
97 * @throws org.aludratest.service.file.exception.FilePresentException if a file was already present and overwriting was disabled. */
98 boolean writeTextFile(@TechnicalLocator String filePath, Reader source, boolean overwrite);
99
100 /** Creates a binary file with the provided content.
101 * @param filePath the path of the file to save
102 * @param bytes the file content to write
103 * @param overwrite flag which indicates if an existing file may be overwritten by the operation
104 * @return true if a formerly existing file was overwritten.
105 * @throws org.aludratest.service.file.exception.FilePresentException if a file was already present and overwriting was disabled. */
106 boolean writeBinaryFile(@TechnicalLocator String filePath, byte[] bytes, boolean overwrite);
107
108 /** Creates a binary file and writes to it all content provided by the source {@link InputStream}.
109 * @param filePath the path of the file to save
110 * @param source an {@link InputStream} which provides the content to write to the file
111 * @param overwrite flag which indicates if an existing file may be overwritten by the operation
112 * @return true if a formerly existing file was overwritten.
113 * @throws org.aludratest.service.file.exception.FilePresentException if a file was already present and overwriting was disabled. */
114 boolean writeBinaryFile(@TechnicalLocator String filePath, InputStream source, boolean overwrite);
115
116 /** Reads a text file and provides its content as String.
117 * @param filePath the path of the file to read
118 * @return the content of the file */
119 String readTextFile(@TechnicalLocator String filePath);
120
121 /** Creates a {@link Reader} for accessing the content of a text file.
122 * @param filePath the path of the file to read
123 * @return a reader for the text file */
124 BufferedReader getReaderForTextFile(@TechnicalLocator String filePath);
125
126 /** Reads a binary file and provides its content as an array of bytes.
127 * @param filePath the path of the file to read
128 * @return the file content as byte array */
129 byte[] readBinaryFile(@TechnicalLocator String filePath);
130
131 /** Creates an {@link InputStream} for accessing the content of a file.
132 * @param filePath the path of the file for which to get an input stream
133 * @return an {@link InputStream} for accessing the file */
134 InputStream getInputStreamForFile(@TechnicalLocator String filePath);
135
136 /** Polls the file system for a given file until it is found or a timeout is exceeded.
137 * Timeout and the maximum number of polls are retrieved from the
138 * {@link org.aludratest.service.file.impl.FileServiceConfiguration}.
139 * @param elementType
140 * @param filePath the path of the file for which to wait
141 * @throws AutomationException if the file was not found within the timeout */
142 void waitUntilExists(
143 @ElementType String elementType,
144 @TechnicalLocator String filePath);
145
146 /** Polls the file system for a given file until it has disappeared or a timeout is exceeded.
147 * Timeout and the maximum number of polls are retrieved from the
148 * {@link org.aludratest.service.file.impl.FileServiceConfiguration}.
149 * @param filePath the path of the file for which to wait until absence
150 * @throws AutomationException if the file was not found within the timeout */
151 void waitUntilNotExists(@TechnicalLocator String filePath);
152
153 /** Polls the given directory until the filter finds a match or a timeout is exceeded.
154 * Timeout and the maximum number of polls are retrieved from the
155 * {@link org.aludratest.service.file.impl.FileServiceConfiguration}.
156 * @param parentPath the path of the directory in which to search for the file
157 * @param filter a filter object that decides which file is to be accepted
158 * @return the file path of the first file that was accepted by the filter
159 * @throws AutomationException if the file was not found within the timeout */
160 String waitForFirstMatch(@TechnicalLocator String parentPath, FileFilter filter);
161
162 }