Package: ResourceFile

ResourceFile

Coverage

1: /*
2: * #%L
3: * *********************************************************************************************************************
4: *
5: * NorthernWind - lightweight CMS
6: * http://northernwind.tidalwave.it - git clone https://bitbucket.org/tidalwave/northernwind-src.git
7: * %%
8: * Copyright (C) 2011 - 2023 Tidalwave s.a.s. (http://tidalwave.it)
9: * %%
10: * *********************************************************************************************************************
11: *
12: * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
13: * the License. You may obtain a copy of the License at
14: *
15: * http://www.apache.org/licenses/LICENSE-2.0
16: *
17: * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
18: * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
19: * specific language governing permissions and limitations under the License.
20: *
21: * *********************************************************************************************************************
22: *
23: *
24: * *********************************************************************************************************************
25: * #L%
26: */
27: package it.tidalwave.northernwind.core.model;
28:
29: import javax.annotation.Nonnull;
30: import java.time.ZonedDateTime;
31: import java.io.File;
32: import java.io.FileNotFoundException;
33: import java.io.IOException;
34: import java.io.InputStream;
35: import it.tidalwave.util.As;
36: import it.tidalwave.util.spi.ExtendedFinderSupport;
37: import it.tidalwave.role.Composite;
38:
39: /***********************************************************************************************************************
40: *
41: * A file backing a {@link Resource}. There can be various implementations of this interface: plain files on the local
42: * disk, items in a zip file, elements of a repository such as Mercurial or Git, objects stored within a database,
43: * etc...
44: *
45: * @author Fabrizio Giudici
46: *
47: **********************************************************************************************************************/
48: public interface ResourceFile extends As, Composite<ResourceFile, ResourceFile.Finder>
49: {
50: /*******************************************************************************************************************
51: *
52: * A {@link Finder} for retrieving children of {@link ResourceFile}.
53: *
54: ******************************************************************************************************************/
55: public static interface Finder extends ExtendedFinderSupport<ResourceFile, Finder>
56: {
57: /*******************************************************************************************************************
58: *
59: * Sets the recursion mode for search.
60: *
61: * @param recursion whether the search must be recursive
62: * @return a cloned finder
63: *
64: ******************************************************************************************************************/
65: @Nonnull
66: public Finder withRecursion (boolean recursion);
67:
68: /*******************************************************************************************************************
69: *
70: * Sets the name of the child to find.
71: *
72: * @param name the name of the file
73: * @return a cloned finder
74: *
75: ******************************************************************************************************************/
76: @Nonnull
77: public Finder withName (@Nonnull String name);
78:
79: public String getName();
80:
81: public boolean isRecursive();
82: }
83:
84: /*******************************************************************************************************************
85: *
86: * Returns the {@link ResourceFileSystem} this file belongs to.
87: *
88: * @return the {@code ResourceFileSystem}
89: *
90: ******************************************************************************************************************/
91: @Nonnull
92: public ResourceFileSystem getFileSystem();
93:
94: /*******************************************************************************************************************
95: *
96: * Returns the name of this file (it doesn't include the full path).
97: *
98: * @return the name of the file
99: *
100: ******************************************************************************************************************/
101: @Nonnull
102: public String getName();
103:
104: /*******************************************************************************************************************
105: *
106: * Returns the full path of this file.
107: * FIXME: the root object returns "" in place of "/" - this will change in future
108: *
109: * @return the full path of the file
110: *
111: ******************************************************************************************************************/
112: @Nonnull
113: public ResourcePath getPath();
114:
115: /*******************************************************************************************************************
116: *
117: * Returns {@code true} whether this file is a folder.
118: *
119: * @return {@code true} for a folder
120: *
121: ******************************************************************************************************************/
122: public boolean isFolder();
123:
124: /*******************************************************************************************************************
125: *
126: * Returns {@code true} whether this file is a plain file.
127: *
128: * @return {@code true} for a file
129: *
130: ******************************************************************************************************************/
131: public boolean isData();
132:
133: /*******************************************************************************************************************
134: *
135: * Returns the MIME type associated to the contents of this file. The value is achieved by querying the web server
136: * context.
137: *
138: * @return the MIME type
139: *
140: ******************************************************************************************************************/
141: @Nonnull
142: public String getMimeType();
143:
144: /*******************************************************************************************************************
145: *
146: * Returns an {@link InputStream} that allows to read contents of this file.
147: *
148: * @return the {@code InputStream}
149: * @throws FileNotFoundException if the physical data can't be accessed
150: *
151: ******************************************************************************************************************/
152: @Nonnull @SuppressWarnings("RedundantThrows")
153: public InputStream getInputStream()
154: throws FileNotFoundException;
155:
156: /*******************************************************************************************************************
157: *
158: * Returns the full contents of this file as text.
159: *
160: * @param encoding the content encoding
161: * @return the contents
162: * @throws IOException if an I/O error occurs
163: *
164: ******************************************************************************************************************/
165: @Nonnull @SuppressWarnings("RedundantThrows")
166: public String asText (@Nonnull String encoding)
167: throws IOException;
168:
169: /*******************************************************************************************************************
170: *
171: * Returns the full contents of this file as binary data.
172: *
173: * @return the contents
174: * @throws IOException if an I/O error occurs
175: *
176: ******************************************************************************************************************/
177: @Nonnull @SuppressWarnings("RedundantThrows")
178: public byte[] asBytes()
179: throws IOException;
180:
181: /*******************************************************************************************************************
182: *
183: * Returns the latest modification time of this file.
184: *
185: * @return the latest modification time
186: *
187: ******************************************************************************************************************/
188: @Nonnull
189: public ZonedDateTime getLatestModificationTime();
190:
191: /*******************************************************************************************************************
192: *
193: * Returns the parent of this file.
194: * FIXME: make @Nonnull, use Optional
195: *
196: * @return the parent or null if no parent
197: *
198: ******************************************************************************************************************/
199: public ResourceFile getParent();
200:
201: /*******************************************************************************************************************
202: *
203: * FIXME: drop this - it won't work with virtual file systems
204: *
205: ******************************************************************************************************************/
206: @Nonnull
207: public File toFile();
208:
209: // TODO: methods below probably can be dropped, are only used in filesystem implementations
210: /*******************************************************************************************************************
211: *
212: * Don't use
213: *
214: ******************************************************************************************************************/
215: public void delete()
216: throws IOException;
217:
218: /*******************************************************************************************************************
219: *
220: * Don't use
221: *
222: ******************************************************************************************************************/
223: @Nonnull
224: public ResourceFile createFolder (@Nonnull String name)
225: throws IOException;
226:
227: /*******************************************************************************************************************
228: *
229: * Don't use
230: *
231: ******************************************************************************************************************/
232: public void copyTo (@Nonnull ResourceFile targetFolder)
233: throws IOException;
234: }