1 /*
2 * Copyright (c) 2000, 2013, 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
940 * parameters need not be contained within, or even overlap, the actual
941 * underlying file. Lock regions are fixed in size; if a locked region
942 * initially contains the end of the file and the file grows beyond the
943 * region then the new portion of the file will not be covered by the lock.
944 * If a file is expected to grow in size and a lock on the entire file is
945 * required then a region starting at zero, and no smaller than the
946 * expected maximum size of the file, should be locked. The zero-argument
947 * {@link #lock()} method simply locks a region of size {@link
948 * Long#MAX_VALUE}.
949 *
950 * <p> Some operating systems do not support shared locks, in which case a
951 * request for a shared lock is automatically converted into a request for
952 * an exclusive lock. Whether the newly-acquired lock is shared or
953 * exclusive may be tested by invoking the resulting lock object's {@link
954 * FileLock#isShared() isShared} method.
955 *
956 * <p> File locks are held on behalf of the entire Java virtual machine.
957 * They are not suitable for controlling access to a file by multiple
958 * threads within the same virtual machine. </p>
959 *
960 * @param position
961 * The position at which the locked region is to start; must be
962 * non-negative
963 *
964 * @param size
965 * The size of the locked region; must be non-negative, and the sum
966 * {@code position} + {@code size} must be non-negative
967 *
968 * @param shared
969 * {@code true} to request a shared lock, in which case this
970 * channel must be open for reading (and possibly writing);
971 * {@code false} to request an exclusive lock, in which case this
972 * channel must be open for writing (and possibly reading)
973 *
974 * @return A lock object representing the newly-acquired lock
975 *
976 * @throws IllegalArgumentException
977 * If the preconditions on the parameters do not hold
978 *
979 * @throws ClosedChannelException
1067 * parameters need not be contained within, or even overlap, the actual
1068 * underlying file. Lock regions are fixed in size; if a locked region
1069 * initially contains the end of the file and the file grows beyond the
1070 * region then the new portion of the file will not be covered by the lock.
1071 * If a file is expected to grow in size and a lock on the entire file is
1072 * required then a region starting at zero, and no smaller than the
1073 * expected maximum size of the file, should be locked. The zero-argument
1074 * {@link #tryLock()} method simply locks a region of size {@link
1075 * Long#MAX_VALUE}.
1076 *
1077 * <p> Some operating systems do not support shared locks, in which case a
1078 * request for a shared lock is automatically converted into a request for
1079 * an exclusive lock. Whether the newly-acquired lock is shared or
1080 * exclusive may be tested by invoking the resulting lock object's {@link
1081 * FileLock#isShared() isShared} method.
1082 *
1083 * <p> File locks are held on behalf of the entire Java virtual machine.
1084 * They are not suitable for controlling access to a file by multiple
1085 * threads within the same virtual machine. </p>
1086 *
1087 * @param position
1088 * The position at which the locked region is to start; must be
1089 * non-negative
1090 *
1091 * @param size
1092 * The size of the locked region; must be non-negative, and the sum
1093 * {@code position} + {@code size} must be non-negative
1094 *
1095 * @param shared
1096 * {@code true} to request a shared lock,
1097 * {@code false} to request an exclusive lock
1098 *
1099 * @return A lock object representing the newly-acquired lock,
1100 * or {@code null} if the lock could not be acquired
1101 * because another program holds an overlapping lock
1102 *
1103 * @throws IllegalArgumentException
1104 * If the preconditions on the parameters do not hold
1105 *
1106 * @throws ClosedChannelException
|
1 /*
2 * Copyright (c) 2000, 2016, 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
940 * parameters need not be contained within, or even overlap, the actual
941 * underlying file. Lock regions are fixed in size; if a locked region
942 * initially contains the end of the file and the file grows beyond the
943 * region then the new portion of the file will not be covered by the lock.
944 * If a file is expected to grow in size and a lock on the entire file is
945 * required then a region starting at zero, and no smaller than the
946 * expected maximum size of the file, should be locked. The zero-argument
947 * {@link #lock()} method simply locks a region of size {@link
948 * Long#MAX_VALUE}.
949 *
950 * <p> Some operating systems do not support shared locks, in which case a
951 * request for a shared lock is automatically converted into a request for
952 * an exclusive lock. Whether the newly-acquired lock is shared or
953 * exclusive may be tested by invoking the resulting lock object's {@link
954 * FileLock#isShared() isShared} method.
955 *
956 * <p> File locks are held on behalf of the entire Java virtual machine.
957 * They are not suitable for controlling access to a file by multiple
958 * threads within the same virtual machine. </p>
959 *
960 * @implNote
961 * This implementation maintains only a {@link java.lang.ref.Reference Reference}
962 * to the created {@link FileLock}, so unless the caller ensures that the returned
963 * object remains strongly reachable, it might be reclaimed and the lock released.
964 *
965 * @param position
966 * The position at which the locked region is to start; must be
967 * non-negative
968 *
969 * @param size
970 * The size of the locked region; must be non-negative, and the sum
971 * {@code position} + {@code size} must be non-negative
972 *
973 * @param shared
974 * {@code true} to request a shared lock, in which case this
975 * channel must be open for reading (and possibly writing);
976 * {@code false} to request an exclusive lock, in which case this
977 * channel must be open for writing (and possibly reading)
978 *
979 * @return A lock object representing the newly-acquired lock
980 *
981 * @throws IllegalArgumentException
982 * If the preconditions on the parameters do not hold
983 *
984 * @throws ClosedChannelException
1072 * parameters need not be contained within, or even overlap, the actual
1073 * underlying file. Lock regions are fixed in size; if a locked region
1074 * initially contains the end of the file and the file grows beyond the
1075 * region then the new portion of the file will not be covered by the lock.
1076 * If a file is expected to grow in size and a lock on the entire file is
1077 * required then a region starting at zero, and no smaller than the
1078 * expected maximum size of the file, should be locked. The zero-argument
1079 * {@link #tryLock()} method simply locks a region of size {@link
1080 * Long#MAX_VALUE}.
1081 *
1082 * <p> Some operating systems do not support shared locks, in which case a
1083 * request for a shared lock is automatically converted into a request for
1084 * an exclusive lock. Whether the newly-acquired lock is shared or
1085 * exclusive may be tested by invoking the resulting lock object's {@link
1086 * FileLock#isShared() isShared} method.
1087 *
1088 * <p> File locks are held on behalf of the entire Java virtual machine.
1089 * They are not suitable for controlling access to a file by multiple
1090 * threads within the same virtual machine. </p>
1091 *
1092 * @implNote
1093 * This implementation maintains only a {@link java.lang.ref.Reference Reference}
1094 * to the created {@link FileLock}, so unless the caller ensures that the returned
1095 * object remains strongly reachable, it might be reclaimed and the lock released.
1096 *
1097 * @param position
1098 * The position at which the locked region is to start; must be
1099 * non-negative
1100 *
1101 * @param size
1102 * The size of the locked region; must be non-negative, and the sum
1103 * {@code position} + {@code size} must be non-negative
1104 *
1105 * @param shared
1106 * {@code true} to request a shared lock,
1107 * {@code false} to request an exclusive lock
1108 *
1109 * @return A lock object representing the newly-acquired lock,
1110 * or {@code null} if the lock could not be acquired
1111 * because another program holds an overlapping lock
1112 *
1113 * @throws IllegalArgumentException
1114 * If the preconditions on the parameters do not hold
1115 *
1116 * @throws ClosedChannelException
|