001/**
002 * Powerunit - A JDK1.8 test framework
003 * Copyright (C) 2014 Mathieu Boretti.
004 *
005 * This file is part of Powerunit
006 *
007 * Powerunit is free software: you can redistribute it and/or modify
008 * it under the terms of the GNU General Public License as published by
009 * the Free Software Foundation, either version 3 of the License, or
010 * (at your option) any later version.
011 *
012 * Powerunit is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
015 * GNU General Public License for more details.
016 *
017 * You should have received a copy of the GNU General Public License
018 * along with Powerunit. If not, see <http://www.gnu.org/licenses/>.
019 */
020package ch.powerunit.rules;
021
022import java.io.IOException;
023import java.nio.file.Path;
024import java.util.Collection;
025
026/**
027 * This rule provides a way to support temporary folder.
028 * <p>
029 * This class is exposed by the {@link ch.powerunit.TestSuite#temporaryFolder()
030 * temporaryFolder()} method of the {@link ch.powerunit.TestSuite TestSuite}
031 * interface. Created file and folder by this rule (or created inside the once
032 * created by this rule) are removed after test execution.
033 *
034 * @author borettim
035 *
036 */
037public interface TemporaryFolder extends ExternalResource {
038
039    /**
040     * Create a new file with generated name.
041     * 
042     * @return the file
043     * @throws IOException
044     *             in case of error
045     */
046    Path newFile() throws IOException;
047
048    /**
049     * Create a new file with specified name.
050     * 
051     * @param fileName
052     *            the file name
053     * @return the file
054     * @throws IOException
055     *             in case of error
056     */
057    Path newFile(String fileName) throws IOException;
058
059    /**
060     * Create a new file with specified name and data.
061     * 
062     * @param fileName
063     *            the file name
064     * @param data
065     *            the byte that must be wrote into the file
066     * @return the file
067     * @throws IOException
068     *             in case of error
069     */
070    Path newFile(String fileName, byte data[]) throws IOException;
071
072    /**
073     * Create a new folder with generated name.
074     * 
075     * @return the folder
076     * @throws IOException
077     *             in case of error
078     */
079    Path newFolder() throws IOException;
080
081    /**
082     * Create a new folder with specified name.
083     * 
084     * @param folderName
085     *            the folder name
086     * @return the folder
087     * @throws IOException
088     *             in case of error
089     */
090    Path newFolder(String folderName) throws IOException;
091
092    /**
093     * Get the rootFolder.
094     * 
095     * @return the rootFolder
096     */
097    Path getRootFolder();
098
099    /**
100     * Get the initial temporary folder info
101     * 
102     * @return the initial data
103     */
104    InitialFolderEntry getInitial();
105
106    /**
107     * This is a builder for temporary folder.
108     * 
109     * @author borettim
110     *
111     */
112    interface TemporaryFolderBuilder {
113
114        /**
115         * Create a new file, in the current folder.
116         * 
117         * @param fileName
118         *            the file name
119         * @return the temporary folder builder
120         */
121        TemporaryFolderBuilder file(String fileName);
122
123        /**
124         * Create a new file, in the current folder.
125         * 
126         * @param fileName
127         *            the file name
128         * @param data
129         *            the data to be wrote in the file
130         * @return the temporary folder builder
131         */
132        TemporaryFolderBuilder file(String fileName, byte data[]);
133
134        /**
135         * Create a new folder, in the current folder.
136         * 
137         * @param folderName
138         *            the folder name
139         * @return the temporary folder builder (moved in this folder)
140         */
141        TemporaryFolderBuilder folder(String folderName);
142
143        /**
144         * Move up from this folder.
145         * 
146         * @return the builder
147         */
148        TemporaryFolderBuilder end();
149
150        /**
151         * Build the temporary folder.
152         * 
153         * @return The temporary folder rule
154         */
155        TemporaryFolder build();
156    }
157
158    /**
159     * Generic part regarding initial context of a temporary folder.
160     * 
161     * @author borettim
162     *
163     */
164    interface InitialEntry {
165        /**
166         * Get the name (file or folder)
167         * 
168         * @return the name
169         */
170        String getName();
171    }
172
173    /**
174     * An initial folder.
175     * 
176     * @author borettim
177     *
178     */
179    interface InitialFolderEntry extends InitialEntry {
180
181        /**
182         * The list of files.
183         * 
184         * @return the list of files
185         */
186        Collection<InitialFileEntry> getFiles();
187
188        /**
189         * The list of folder.
190         * 
191         * @return the list of folders.
192         */
193        Collection<InitialFolderEntry> getFolders();
194    }
195
196    /**
197     * An initial file.
198     * 
199     * @author borettim
200     *
201     */
202    interface InitialFileEntry extends InitialEntry {
203        /**
204         * the initial data of the file
205         * 
206         * @return the data (can be null).
207         */
208        byte[] getData();
209    }
210
211}