8325152: Clarify specification of java.io.RandomAccessFile.setLength

Reviewed-by: alanb
This commit is contained in:
Brian Burkhalter 2024-02-06 19:35:03 +00:00
parent 96eb0390d6
commit 4b1e367eda

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 1994, 2023, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 1994, 2024, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -660,19 +660,26 @@ public class RandomAccessFile implements DataOutput, DataInput, Closeable {
* Sets the length of this file. * Sets the length of this file.
* *
* <p> If the present length of the file as returned by the * <p> If the present length of the file as returned by the
* {@code length} method is greater than the {@code newLength} * {@linkplain #length length} method is greater than the desired length
* argument then the file will be truncated. In this case, if the file * of the file specified by the {@code newLength} argument, then the file
* offset as returned by the {@code getFilePointer} method is greater * will be truncated.
* than {@code newLength} then after this method returns the offset
* will be equal to {@code newLength}.
* *
* <p> If the present length of the file as returned by the * <p> If the present length of the file is smaller than the desired length,
* {@code length} method is smaller than the {@code newLength} * then the file will be extended. The contents of the extended portion of
* argument then the file will be extended. In this case, the contents of * the file are not defined.
* the extended portion of the file are not defined. *
* <p> If the present length of the file is equal to the desired length,
* then the file and its length will be unchanged.
*
* <p> In all cases, after this method returns, the file offset as returned
* by the {@linkplain #getFilePointer getFilePointer} method will equal the
* minimum of the desired length and the file offset before this method was
* called, even if the length is unchanged. In other words, this method
* constrains the file offset to the closed interval {@code [0,newLength]}.
* *
* @param newLength The desired length of the file * @param newLength The desired length of the file
* @throws IOException If an I/O error occurs * @throws IOException If the argument is negative or
* if some other I/O error occurs
* @since 1.2 * @since 1.2
*/ */
public void setLength(long newLength) throws IOException { public void setLength(long newLength) throws IOException {