History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/java/nio/file/SecureDirectoryStream.java (1 of 18352 files). Show all

Unified · Split

java/pkg/java/nio/file/SecureDirectoryStream.java+306−0
@@ -0,0 +1,306 @@
1+/*
2+ * Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+package java.nio.file;
26+
27+import java.nio.file.attribute.*;
28+import java.nio.channels.SeekableByteChannel;
29+import java.util.Set;
30+import java.io.IOException;
31+
32+/**
33+ * A {@code DirectoryStream} that defines operations on files that are located
34+ * relative to an open directory. A {@code SecureDirectoryStream} is intended
35+ * for use by sophisticated or security sensitive applications requiring to
36+ * traverse file trees or otherwise operate on directories in a race-free manner.
37+ * Race conditions can arise when a sequence of file operations cannot be
38+ * carried out in isolation. Each of the file operations defined by this
39+ * interface specify a relative path. All access to the file is relative
40+ * to the open directory irrespective of if the directory is moved or replaced
41+ * by an attacker while the directory is open. A {@code SecureDirectoryStream}
42+ * may also be used as a virtual <em>working directory</em>.
43+ *
44+ * <p> A {@code SecureDirectoryStream} requires corresponding support from the
45+ * underlying operating system. Where an implementation supports this features
46+ * then the {@code DirectoryStream} returned by the {@link Files#newDirectoryStream
47+ * newDirectoryStream} method will be a {@code SecureDirectoryStream} and must
48+ * be cast to that type in order to invoke the methods defined by this interface.
49+ *
50+ * <p> In the case of the default {@link java.nio.file.spi.FileSystemProvider
51+ * provider}, and a security manager is set, then the permission checks are
52+ * performed using the path obtained by resolving the given relative path
53+ * against the <i>original path</i> of the directory (irrespective of if the
54+ * directory is moved since it was opened).
55+ *
56+ * @since 1.7
57+ */
58+
59+public interface SecureDirectoryStream<T>
60+ extends DirectoryStream<T>
61+{
62+ /**
63+ * Opens the directory identified by the given path, returning a {@code
64+ * SecureDirectoryStream} to iterate over the entries in the directory.
65+ *
66+ * <p> This method works in exactly the manner specified by the {@link
67+ * Files#newDirectoryStream(Path) newDirectoryStream} method for the case that
68+ * the {@code path} parameter is an {@link Path#isAbsolute absolute} path.
69+ * When the parameter is a relative path then the directory to open is
70+ * relative to this open directory. The {@link
71+ * LinkOption#NOFOLLOW_LINKS NOFOLLOW_LINKS} option may be used to
72+ * ensure that this method fails if the file is a symbolic link.
73+ *
74+ * <p> The new directory stream, once created, is not dependent upon the
75+ * directory stream used to create it. Closing this directory stream has no
76+ * effect upon newly created directory stream.
77+ *
78+ * @param path
79+ * the path to the directory to open
80+ * @param options
81+ * options indicating how symbolic links are handled
82+ *
83+ * @return a new and open {@code SecureDirectoryStream} object
84+ *
85+ * @throws ClosedDirectoryStreamException
86+ * if the directory stream is closed
87+ * @throws NotDirectoryException
88+ * if the file could not otherwise be opened because it is not
89+ * a directory <i>(optional specific exception)</i>
90+ * @throws IOException
91+ * if an I/O error occurs
92+ * @throws SecurityException
93+ * In the case of the default provider, and a security manager is
94+ * installed, the {@link SecurityManager#checkRead(String) checkRead}
95+ * method is invoked to check read access to the directory.
96+ */
97+ SecureDirectoryStream<T> newDirectoryStream(T path, LinkOption... options)
98+ throws IOException;
99+
100+ /**
101+ * Opens or creates a file in this directory, returning a seekable byte
102+ * channel to access the file.
103+ *
104+ * <p> This method works in exactly the manner specified by the {@link
105+ * Files#newByteChannel Files.newByteChannel} method for the
106+ * case that the {@code path} parameter is an {@link Path#isAbsolute absolute}
107+ * path. When the parameter is a relative path then the file to open or
108+ * create is relative to this open directory. In addition to the options
109+ * defined by the {@code Files.newByteChannel} method, the {@link
110+ * LinkOption#NOFOLLOW_LINKS NOFOLLOW_LINKS} option may be used to
111+ * ensure that this method fails if the file is a symbolic link.
112+ *
113+ * <p> The channel, once created, is not dependent upon the directory stream
114+ * used to create it. Closing this directory stream has no effect upon the
115+ * channel.
116+ *
117+ * @param path
118+ * the path of the file to open open or create
119+ * @param options
120+ * options specifying how the file is opened
121+ * @param attrs
122+ * an optional list of attributes to set atomically when creating
123+ * the file
124+ *
125+ * @throws ClosedDirectoryStreamException
126+ * if the directory stream is closed
127+ * @throws IllegalArgumentException
128+ * if the set contains an invalid combination of options
129+ * @throws UnsupportedOperationException
130+ * if an unsupported open option is specified or the array contains
131+ * attributes that cannot be set atomically when creating the file
132+ * @throws FileAlreadyExistsException
133+ * if a file of that name already exists and the {@link
134+ * StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified
135+ * <i>(optional specific exception)</i>
136+ * @throws IOException
137+ * if an I/O error occurs
138+ * @throws SecurityException
139+ * In the case of the default provider, and a security manager is
140+ * installed, the {@link SecurityManager#checkRead(String) checkRead}
141+ * method is invoked to check read access to the path if the file
142+ * is opened for reading. The {@link SecurityManager#checkWrite(String)
143+ * checkWrite} method is invoked to check write access to the path
144+ * if the file is opened for writing.
145+ */
146+ SeekableByteChannel newByteChannel(T path,
147+ Set<? extends OpenOption> options,
148+ FileAttribute<?>... attrs)
149+ throws IOException;
150+
151+ /**
152+ * Deletes a file.
153+ *
154+ * <p> Unlike the {@link Files#delete delete()} method, this method does
155+ * not first examine the file to determine if the file is a directory.
156+ * Whether a directory is deleted by this method is system dependent and
157+ * therefore not specified. If the file is a symbolic link, then the link
158+ * itself, not the final target of the link, is deleted. When the
159+ * parameter is a relative path then the file to delete is relative to
160+ * this open directory.
161+ *
162+ * @param path
163+ * the path of the file to delete
164+ *
165+ * @throws ClosedDirectoryStreamException
166+ * if the directory stream is closed
167+ * @throws NoSuchFileException
168+ * if the file does not exist <i>(optional specific exception)</i>
169+ * @throws IOException
170+ * if an I/O error occurs
171+ * @throws SecurityException
172+ * In the case of the default provider, and a security manager is
173+ * installed, the {@link SecurityManager#checkDelete(String) checkDelete}
174+ * method is invoked to check delete access to the file
175+ */
176+ void deleteFile(T path) throws IOException;
177+
178+ /**
179+ * Deletes a directory.
180+ *
181+ * <p> Unlike the {@link Files#delete delete()} method, this method
182+ * does not first examine the file to determine if the file is a directory.
183+ * Whether non-directories are deleted by this method is system dependent and
184+ * therefore not specified. When the parameter is a relative path then the
185+ * directory to delete is relative to this open directory.
186+ *
187+ * @param path
188+ * the path of the directory to delete
189+ *
190+ * @throws ClosedDirectoryStreamException
191+ * if the directory stream is closed
192+ * @throws NoSuchFileException
193+ * if the directory does not exist <i>(optional specific exception)</i>
194+ * @throws DirectoryNotEmptyException
195+ * if the directory could not otherwise be deleted because it is
196+ * not empty <i>(optional specific exception)</i>
197+ * @throws IOException
198+ * if an I/O error occurs
199+ * @throws SecurityException
200+ * In the case of the default provider, and a security manager is
201+ * installed, the {@link SecurityManager#checkDelete(String) checkDelete}
202+ * method is invoked to check delete access to the directory
203+ */
204+ void deleteDirectory(T path) throws IOException;
205+
206+ /**
207+ * Move a file from this directory to another directory.
208+ *
209+ * <p> This method works in a similar manner to {@link Files#move move}
210+ * method when the {@link StandardCopyOption#ATOMIC_MOVE ATOMIC_MOVE} option
211+ * is specified. That is, this method moves a file as an atomic file system
212+ * operation. If the {@code srcpath} parameter is an {@link Path#isAbsolute
213+ * absolute} path then it locates the source file. If the parameter is a
214+ * relative path then it is located relative to this open directory. If
215+ * the {@code targetpath} parameter is absolute then it locates the target
216+ * file (the {@code targetdir} parameter is ignored). If the parameter is
217+ * a relative path it is located relative to the open directory identified
218+ * by the {@code targetdir} parameter. In all cases, if the target file
219+ * exists then it is implementation specific if it is replaced or this
220+ * method fails.
221+ *
222+ * @param srcpath
223+ * the name of the file to move
224+ * @param targetdir
225+ * the destination directory
226+ * @param targetpath
227+ * the name to give the file in the destination directory
228+ *
229+ * @throws ClosedDirectoryStreamException
230+ * if this or the target directory stream is closed
231+ * @throws FileAlreadyExistsException
232+ * if the file already exists in the target directory and cannot
233+ * be replaced <i>(optional specific exception)</i>
234+ * @throws AtomicMoveNotSupportedException
235+ * if the file cannot be moved as an atomic file system operation
236+ * @throws IOException
237+ * if an I/O error occurs
238+ * @throws SecurityException
239+ * In the case of the default provider, and a security manager is
240+ * installed, the {@link SecurityManager#checkWrite(String) checkWrite}
241+ * method is invoked to check write access to both the source and
242+ * target file.
243+ */
244+ void move(T srcpath, SecureDirectoryStream<T> targetdir, T targetpath)
245+ throws IOException;
246+
247+ /**
248+ * Returns a new file attribute view to access the file attributes of this
249+ * directory.
250+ *
251+ * <p> The resulting file attribute view can be used to read or update the
252+ * attributes of this (open) directory. The {@code type} parameter specifies
253+ * the type of the attribute view and the method returns an instance of that
254+ * type if supported. Invoking this method to obtain a {@link
255+ * BasicFileAttributeView} always returns an instance of that class that is
256+ * bound to this open directory.
257+ *
258+ * <p> The state of resulting file attribute view is intimately connected
259+ * to this directory stream. Once the directory stream is {@link #close closed},
260+ * then all methods to read or update attributes will throw {@link
261+ * ClosedDirectoryStreamException ClosedDirectoryStreamException}.
262+ *
263+ * @param type
264+ * the {@code Class} object corresponding to the file attribute view
265+ *
266+ * @return a new file attribute view of the specified type bound to
267+ * this directory stream, or {@code null} if the attribute view
268+ * type is not available
269+ */
270+ <V extends FileAttributeView> V getFileAttributeView(Class<V> type);
271+
272+ /**
273+ * Returns a new file attribute view to access the file attributes of a file
274+ * in this directory.
275+ *
276+ * <p> The resulting file attribute view can be used to read or update the
277+ * attributes of file in this directory. The {@code type} parameter specifies
278+ * the type of the attribute view and the method returns an instance of that
279+ * type if supported. Invoking this method to obtain a {@link
280+ * BasicFileAttributeView} always returns an instance of that class that is
281+ * bound to the file in the directory.
282+ *
283+ * <p> The state of resulting file attribute view is intimately connected
284+ * to this directory stream. Once the directory stream {@link #close closed},
285+ * then all methods to read or update attributes will throw {@link
286+ * ClosedDirectoryStreamException ClosedDirectoryStreamException}. The
287+ * file is not required to exist at the time that the file attribute view
288+ * is created but methods to read or update attributes of the file will
289+ * fail when invoked and the file does not exist.
290+ *
291+ * @param path
292+ * the path of the file
293+ * @param type
294+ * the {@code Class} object corresponding to the file attribute view
295+ * @param options
296+ * options indicating how symbolic links are handled
297+ *
298+ * @return a new file attribute view of the specified type bound to a
299+ * this directory stream, or {@code null} if the attribute view
300+ * type is not available
301+ *
302+ */
303+ <V extends FileAttributeView> V getFileAttributeView(T path,
304+ Class<V> type,
305+ LinkOption... options);
306+}