FileOwnerAttributeView.java revision 12581:6f3a2d6e646b 
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
26package java.nio.file.attribute;
27
28import java.io.IOException;
29
30/**
31 * A file attribute view that supports reading or updating the owner of a file.
32 * This file attribute view is intended for file system implementations that
33 * support a file attribute that represents an identity that is the owner of
34 * the file. Often the owner of a file is the identity of the entity that
35 * created the file.
36 *
37 * <p> The {@link #getOwner getOwner} or {@link #setOwner setOwner} methods may
38 * be used to read or update the owner of the file.
39 *
40 * <p> The {@link java.nio.file.Files#getAttribute getAttribute} and
41 * {@link java.nio.file.Files#setAttribute setAttribute} methods may also be
42 * used to read or update the owner. In that case, the owner attribute is
43 * identified by the name {@code "owner"}, and the value of the attribute is
44 * a {@link UserPrincipal}.
45 *
46 * @since 1.7
47 */
48
49public interface FileOwnerAttributeView
50    extends FileAttributeView
51{
52    /**
53     * Returns the name of the attribute view. Attribute views of this type
54     * have the name {@code "owner"}.
55     */
56    @Override
57    String name();
58
59    /**
60     * Read the file owner.
61     *
62     * <p> It it implementation specific if the file owner can be a {@link
63     * GroupPrincipal group}.
64     *
65     * @return  the file owner
66     *
67     * @throws  IOException
68     *          if an I/O error occurs
69     * @throws  SecurityException
70     *          In the case of the default provider, a security manager is
71     *          installed, and it denies {@link
72     *          RuntimePermission}{@code ("accessUserInformation")} or its
73     *          {@link SecurityManager#checkRead(String) checkRead} method
74     *          denies read access to the file.
75     */
76    UserPrincipal getOwner() throws IOException;
77
78    /**
79     * Updates the file owner.
80     *
81     * <p> It it implementation specific if the file owner can be a {@link
82     * GroupPrincipal group}. To ensure consistent and correct behavior
83     * across platforms it is recommended that this method should only be used
84     * to set the file owner to a user principal that is not a group.
85     *
86     * @param   owner
87     *          the new file owner
88     *
89     * @throws  IOException
90     *          if an I/O error occurs, or the {@code owner} parameter is a
91     *          group and this implementation does not support setting the owner
92     *          to a group
93     * @throws  SecurityException
94     *          In the case of the default provider, a security manager is
95     *          installed, and it denies {@link
96     *          RuntimePermission}{@code ("accessUserInformation")} or its
97     *          {@link SecurityManager#checkWrite(String) checkWrite} method
98     *          denies write access to the file.
99     */
100    void setOwner(UserPrincipal owner) throws IOException;
101}
102