Package: ResourceFile$Finder

ResourceFile$Finder

Coverage

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