diff --git a/commons/audit/handler-csv/src/main/java/org/forgerock/audit/handlers/csv/CsvWriter.java b/commons/audit/handler-csv/src/main/java/org/forgerock/audit/handlers/csv/CsvWriter.java index 350b322f7f..40231ac71f 100644 --- a/commons/audit/handler-csv/src/main/java/org/forgerock/audit/handlers/csv/CsvWriter.java +++ b/commons/audit/handler-csv/src/main/java/org/forgerock/audit/handlers/csv/CsvWriter.java @@ -12,6 +12,7 @@ * information: "Portions copyright [year] [name of copyright owner]". * * Copyright 2015 ForgeRock AS. + * Portions Copyrighted 2026 3A Systems, LLC */ package org.forgerock.audit.handlers.csv; @@ -37,13 +38,13 @@ interface CsvWriter extends AutoCloseable { /** * Write a row into the CSV files. * @param values The keys of the {@link Map} have to match the column's header. - * @throws IOException + * @throws IOException if an I/O error occurs while writing the row. */ void writeEvent(Map values) throws IOException; /** * Flush the data into the CSV file. - * @throws IOException + * @throws IOException if an I/O error occurs while flushing. */ void flush() throws IOException; diff --git a/commons/audit/handler-csv/src/main/java/org/forgerock/audit/handlers/csv/HmacCalculator.java b/commons/audit/handler-csv/src/main/java/org/forgerock/audit/handlers/csv/HmacCalculator.java index ea93ab55a0..db7b1e38af 100644 --- a/commons/audit/handler-csv/src/main/java/org/forgerock/audit/handlers/csv/HmacCalculator.java +++ b/commons/audit/handler-csv/src/main/java/org/forgerock/audit/handlers/csv/HmacCalculator.java @@ -12,6 +12,7 @@ * information: "Portions copyright [year] [name of copyright owner]". * * Copyright 2015 ForgeRock AS. +* Portions Copyrighted 2026 3A Systems, LLC */ package org.forgerock.audit.handlers.csv; @@ -61,7 +62,7 @@ public void setCurrentKey(byte[] bytes) { * * @param data the data used to calculate the HMAC * @return the calculated HMAC as a base64 encoded String. - * @throws SignatureException + * @throws SignatureException if the HMAC cannot be generated. */ public String calculate(byte[] data) throws SignatureException { try { diff --git a/commons/audit/handler-csv/src/main/java/org/forgerock/audit/handlers/csv/SecureCsvWriter.java b/commons/audit/handler-csv/src/main/java/org/forgerock/audit/handlers/csv/SecureCsvWriter.java index c14ef3207d..41dc69a6b9 100644 --- a/commons/audit/handler-csv/src/main/java/org/forgerock/audit/handlers/csv/SecureCsvWriter.java +++ b/commons/audit/handler-csv/src/main/java/org/forgerock/audit/handlers/csv/SecureCsvWriter.java @@ -12,6 +12,7 @@ * information: "Portions copyright [year] [name of copyright owner]". * * Copyright 2015-2016 ForgeRock AS. + * Portions Copyrighted 2026 3A Systems, LLC */ package org.forgerock.audit.handlers.csv; @@ -308,7 +309,7 @@ public boolean forceRotation() throws IOException { /** * Write a row into the CSV files. * @param values The keys of the {@link Map} have to match the column's header. - * @throws IOException + * @throws IOException if an I/O error occurs while writing the event. */ @Override public void writeEvent(Map values) throws IOException { @@ -318,7 +319,7 @@ public void writeEvent(Map values) throws IOException { /** * Write a row into the CSV files. * @param values The keys of the {@link Map} have to match the column's header. - * @throws IOException + * @throws IOException if an I/O error occurs while writing the event. */ public void writeEvent(Writer writer, Map values) throws IOException { signatureLock.lock(); diff --git a/commons/audit/handler-csv/src/main/java/org/forgerock/audit/handlers/csv/StandardCsvWriter.java b/commons/audit/handler-csv/src/main/java/org/forgerock/audit/handlers/csv/StandardCsvWriter.java index 235fbd1deb..81dc3fc4b7 100644 --- a/commons/audit/handler-csv/src/main/java/org/forgerock/audit/handlers/csv/StandardCsvWriter.java +++ b/commons/audit/handler-csv/src/main/java/org/forgerock/audit/handlers/csv/StandardCsvWriter.java @@ -12,6 +12,7 @@ * information: "Portions copyright [year] [name of copyright owner]". * * Copyright 2015-2016 ForgeRock AS. + * Portions Copyrighted 2026 3A Systems, LLC */ package org.forgerock.audit.handlers.csv; @@ -123,7 +124,7 @@ public void writeHeader(String... headers) throws IOException { /** * Write a row into the CSV files. * @param values The keys of the {@link Map} have to match the column's header. - * @throws IOException + * @throws IOException if an I/O error occurs while writing the row. */ @Override public void writeEvent(Map values) throws IOException { @@ -132,7 +133,7 @@ public void writeEvent(Map values) throws IOException { /** * Flush the data into the CSV file. - * @throws IOException + * @throws IOException if an I/O error occurs while flushing. */ public void flush() throws IOException { csvWriter.flush(); diff --git a/commons/audit/handler-jms/src/main/java/org/forgerock/audit/handlers/jms/JmsResourceManager.java b/commons/audit/handler-jms/src/main/java/org/forgerock/audit/handlers/jms/JmsResourceManager.java index e48299e029..facca72d59 100644 --- a/commons/audit/handler-jms/src/main/java/org/forgerock/audit/handlers/jms/JmsResourceManager.java +++ b/commons/audit/handler-jms/src/main/java/org/forgerock/audit/handlers/jms/JmsResourceManager.java @@ -12,7 +12,7 @@ * information: "Portions copyright [year] [name of copyright owner]". * * Copyright 2016 ForgeRock AS. - * Portions copyright 2024 3A Systems LLC. + * Portions copyright 2024-2026 3A Systems LLC. */ package org.forgerock.audit.handlers.jms; @@ -67,7 +67,7 @@ class JmsResourceManager { * * @param configuration The Audit Configuration. * @param jmsContextManager The {@link JmsContextManager}. - * @throws InternalServerErrorException + * @throws InternalServerErrorException if the JMS resources cannot be initialized. */ public JmsResourceManager(JmsAuditEventHandlerConfiguration configuration, JmsContextManager jmsContextManager) throws ResourceException { @@ -87,7 +87,7 @@ public JmsResourceManager(JmsAuditEventHandlerConfiguration configuration, JmsCo /** * Opens the connection to the JMS services with the configured session mode. - * @throws JMSException + * @throws JMSException if there is trouble opening the connection. */ public void openConnection() throws JMSException { connection = connectionFactory.createConnection(); @@ -98,7 +98,7 @@ public void openConnection() throws JMSException { /** * Closes the connection to the JMS services. * - * @throws JMSException + * @throws JMSException if there is trouble closing the connection. */ public void closeConnection() throws JMSException { if (null != connection) { diff --git a/commons/json-schema/cli/src/main/java/org/forgerock/json/schema/Main.java b/commons/json-schema/cli/src/main/java/org/forgerock/json/schema/Main.java index 301056615f..ba79282921 100644 --- a/commons/json-schema/cli/src/main/java/org/forgerock/json/schema/Main.java +++ b/commons/json-schema/cli/src/main/java/org/forgerock/json/schema/Main.java @@ -12,6 +12,7 @@ * information: "Portions Copyrighted [year] [name of copyright owner]". * * Copyright 2011-2016 ForgeRock AS. + * Portions Copyrighted 2026 3A Systems, LLC */ package org.forgerock.json.schema; @@ -199,9 +200,9 @@ private void loadSchema(URI base, File schemaFile) throws IOException { * Files found; the List is sorted using File.compareTo(). * * @param aStartingDir is a valid directory, which can be read. - * @param filter - * @return - * @throws java.io.FileNotFoundException + * @param filter the filter used to select which files to include. + * @return the list of files found beneath the starting directory. + * @throws java.io.FileNotFoundException if the starting directory does not exist or cannot be read. */ private List getFileListingNoSort(File aStartingDir, FileFilter filter) throws FileNotFoundException { List result = new ArrayList<>(); @@ -222,8 +223,8 @@ private List getFileListingNoSort(File aStartingDir, FileFilter filter) th /** * Directory is valid if it exists, does not represent a file, and can be read. * - * @param aDirectory - * @throws java.io.FileNotFoundException + * @param aDirectory the directory to validate. + * @throws java.io.FileNotFoundException if the directory does not exist. */ private void validateDirectory(File aDirectory) throws FileNotFoundException { if (aDirectory == null) { diff --git a/commons/launcher/launcher/src/main/java/org/forgerock/commons/launcher/ConfigurationUtil.java b/commons/launcher/launcher/src/main/java/org/forgerock/commons/launcher/ConfigurationUtil.java index b67903c645..7689ea80d6 100644 --- a/commons/launcher/launcher/src/main/java/org/forgerock/commons/launcher/ConfigurationUtil.java +++ b/commons/launcher/launcher/src/main/java/org/forgerock/commons/launcher/ConfigurationUtil.java @@ -62,6 +62,7 @@ private ConfigurationUtil() { * which will match each entry. * * @param location + * the URL of the jar file to scan. * @param includes * to filter the results within a regular expression. * @return a list of files within the jar |file| @@ -153,6 +154,7 @@ public void connect() throws IOException {} * which will match each entry. * * @param location + * the URL of the zip file to scan. * @param includes * to filter the results within a regular expression. * @return a list of files within the zip |file| diff --git a/commons/launcher/launcher/src/main/javadoc/overview.html b/commons/launcher/launcher/src/main/javadoc/overview.html index 9c83c2e3e5..6673fdb57d 100644 --- a/commons/launcher/launcher/src/main/javadoc/overview.html +++ b/commons/launcher/launcher/src/main/javadoc/overview.html @@ -1,3 +1,4 @@ + @@ -13,7 +14,5 @@

ForgeRock OSGi Launcher

- -

diff --git a/commons/launcher/pom.xml b/commons/launcher/pom.xml index d3de358e02..11f3eb0f0f 100644 --- a/commons/launcher/pom.xml +++ b/commons/launcher/pom.xml @@ -22,7 +22,7 @@ ~ your own identifying information: ~ "Portions Copyrighted [year] [name of copyright owner]" - Portions Copyright 2017-2024 3A Systems, LLC. + Portions Copyright 2017-2026 3A Systems, LLC. --> 4.0.0 @@ -96,7 +96,7 @@ org.apache.maven.plugins maven-javadoc-plugin - 2.9 + ${javadocPluginVersion} diff --git a/commons/selfservice/core/src/main/java/org/forgerock/selfservice/core/crypto/FieldStorageSchemeImpl.java b/commons/selfservice/core/src/main/java/org/forgerock/selfservice/core/crypto/FieldStorageSchemeImpl.java index 79dd65e899..15b6792669 100644 --- a/commons/selfservice/core/src/main/java/org/forgerock/selfservice/core/crypto/FieldStorageSchemeImpl.java +++ b/commons/selfservice/core/src/main/java/org/forgerock/selfservice/core/crypto/FieldStorageSchemeImpl.java @@ -12,6 +12,7 @@ * information: "Portions copyright [year] [name of copyright owner]". * * Copyright 2015 ForgeRock AS. + * Portions Copyrighted 2026 3A Systems, LLC */ package org.forgerock.selfservice.core.crypto; @@ -66,7 +67,7 @@ class FieldStorageSchemeImpl implements FieldStorageScheme { * * @param digestSize the size of the digest in bytes. * @param algorithm the algorithm to use. - * @throws Exception + * @throws Exception if no provider supports the given digest algorithm. */ FieldStorageSchemeImpl(int digestSize, String algorithm) throws Exception { this.messageDigest = MessageDigest.getInstance(algorithm); diff --git a/i18n-framework/maven-plugin/src/main/java/org/forgerock/i18n/maven/AbstractGenerateMessagesMojo.java b/i18n-framework/maven-plugin/src/main/java/org/forgerock/i18n/maven/AbstractGenerateMessagesMojo.java index 1e3e97eed4..d79dcfd93b 100644 --- a/i18n-framework/maven-plugin/src/main/java/org/forgerock/i18n/maven/AbstractGenerateMessagesMojo.java +++ b/i18n-framework/maven-plugin/src/main/java/org/forgerock/i18n/maven/AbstractGenerateMessagesMojo.java @@ -12,6 +12,7 @@ * information: "Portions Copyrighted [year] [name of copyright owner]". * * Copyright 2011-2013 ForgeRock AS + * Portions Copyrighted 2026 3A Systems, LLC */ package org.forgerock.i18n.maven; @@ -341,7 +342,12 @@ String getComment() { final String[] sa = ws.split(EOL); for (final String s : sa) { - sb.append(indent(1)).append(" * ").append(s).append(EOL); + // Escape HTML metacharacters so that message text (which may contain + // '&', '<' or '>' - e.g. LDAP filters or GUI HTML fragments) yields + // valid Javadoc. The runtime message is loaded from the property + // bundle by key, so escaping this documentation comment is harmless. + final String escaped = s.replace("&", "&").replace("<", "<").replace(">", ">"); + sb.append(indent(1)).append(" * ").append(escaped).append(EOL); } sb.append(indent(1)).append(" */").append(EOL); return sb.toString(); diff --git a/maven-external-dependency-plugin/maven-external-dependency-plugin/pom.xml b/maven-external-dependency-plugin/maven-external-dependency-plugin/pom.xml index 909cda4739..f64703df63 100644 --- a/maven-external-dependency-plugin/maven-external-dependency-plugin/pom.xml +++ b/maven-external-dependency-plugin/maven-external-dependency-plugin/pom.xml @@ -16,7 +16,9 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> + +Portions Copyrighted 2026 3A Systems, LLC +--> 4.0.0 @@ -247,7 +249,7 @@ under the License. org.apache.maven.plugins maven-javadoc-plugin - 2.6.1 + ${javadocPluginVersion} ${basedir}/src/main/javadoc/stylesheet.css public diff --git a/maven-external-dependency-plugin/maven-external-dependency-plugin/src/main/java/com/savage7/maven/plugin/dependency/DeployExternalDependencyMojo.java b/maven-external-dependency-plugin/maven-external-dependency-plugin/src/main/java/com/savage7/maven/plugin/dependency/DeployExternalDependencyMojo.java index 079f392934..a0e5577855 100644 --- a/maven-external-dependency-plugin/maven-external-dependency-plugin/src/main/java/com/savage7/maven/plugin/dependency/DeployExternalDependencyMojo.java +++ b/maven-external-dependency-plugin/maven-external-dependency-plugin/src/main/java/com/savage7/maven/plugin/dependency/DeployExternalDependencyMojo.java @@ -259,8 +259,8 @@ else if (artifactItem.getGeneratePom() == true) * section * * @return deployment repository defined in distribution management - * @throws MojoExecutionException - * @throws MojoFailureException + * @throws MojoExecutionException if the repository is not defined in the POM's distribution management section + * @throws MojoFailureException if the deployment goal fails */ private ArtifactRepository getDeploymentRepository() throws MojoExecutionException, MojoFailureException @@ -282,7 +282,7 @@ private ArtifactRepository getDeploymentRepository() * Checks for offline mode; throws exception if offline, deploy goal cannot * proceed * - * @throws MojoFailureException + * @throws MojoFailureException if Maven is running in offline mode */ private void failIfOffline() throws MojoFailureException { diff --git a/persistit/core/src/main/java/com/persistit/Accumulator.java b/persistit/core/src/main/java/com/persistit/Accumulator.java index 63a53a2802..9af9934c9d 100644 --- a/persistit/core/src/main/java/com/persistit/Accumulator.java +++ b/persistit/core/src/main/java/com/persistit/Accumulator.java @@ -535,8 +535,8 @@ private Accumulator(final Tree tree, final int index, final long baseValue, fina * This method is called when computing a snapshot value and when * aggregating Delta instances. * - * @param a - * @param b + * @param a the first operand + * @param b the second operand * @return the result of the commutative operation on a and b */ abstract long applyValue(long a, long b); @@ -548,18 +548,18 @@ private Accumulator(final Tree tree, final int index, final long baseValue, fina * SeqAccumulator update(a, b) returns a + b (computed * atomically) whereas apply(a, b) return Math.max(a, b). * - * @param a - * @param b + * @param a the first operand + * @param b the second operand * @return the result of the commutative operation on a and b */ abstract long updateValue(long a, long b); /** - * @param value + * @param value the current value * @param updated * return One of the supplied parameters as the value to be held * in a Delta. - * + * */ abstract long selectValue(long value, long updated); @@ -665,8 +665,8 @@ public long getSnapshotValue() throws PersistitInterruptedException { } /** - * @param timestamp - * @param step + * @param timestamp the start timestamp bounding committed transactions to include + * @param step the step number bounding operations of the current transaction to include * @return The value computed by accumulating values contributed by (a) all * transactions having commit timestamps less than or equal to * timestamp, and (b) all operations performed by the @@ -686,7 +686,7 @@ long getSnapshotValue(final long timestamp, final int step) throws PersistitInte * recovery processing to apply Deltas from recovered committed * transactions. * - * @param value + * @param value the delta value to apply to the base value */ void updateBaseValue(final long value, final long commitTimestamp) { _baseValue = applyValue(_baseValue, value); diff --git a/persistit/core/src/main/java/com/persistit/AlertMonitor.java b/persistit/core/src/main/java/com/persistit/AlertMonitor.java index 4cfeb76b73..63ea41434a 100644 --- a/persistit/core/src/main/java/com/persistit/AlertMonitor.java +++ b/persistit/core/src/main/java/com/persistit/AlertMonitor.java @@ -749,7 +749,7 @@ public MBeanNotificationInfo[] getNotificationInfo() { * standard log message. If there have been multiple Events, emit a * recurring event message. * - * @param history + * @param history the event history to log */ private void log(final History history) { final Event event = history.getLastEvent(); @@ -765,7 +765,7 @@ private void log(final History history) { /** * Broadcast a JMX Notification. * - * @param history + * @param history the event history to broadcast */ private void sendNotification(final History history) { final Event event = history.getLastEvent(); @@ -793,7 +793,7 @@ private void sendNotification(final History history) { * were three argument elements. *

* - * @param event + * @param event the event to format * @return formatted event */ private String format(final Event event) { diff --git a/persistit/core/src/main/java/com/persistit/BackupTask.java b/persistit/core/src/main/java/com/persistit/BackupTask.java index 2c6e7ad3be..64e0fe1782 100644 --- a/persistit/core/src/main/java/com/persistit/BackupTask.java +++ b/persistit/core/src/main/java/com/persistit/BackupTask.java @@ -1,6 +1,7 @@ /** * Copyright 2011-2012 Akiban Technologies, Inc. - * + * Portions Copyrighted 2026 3A Systems, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -171,8 +172,9 @@ private void populateBackupFiles() throws Exception { * A convenience method for backing up relatively small amounts of data from * within Persistit. In production it is expected that the actual file * copies required for backup will be performed be third-party utilities. - * + * * @throws Exception + * if the backup operation fails */ private void doBackup() throws Exception { final ZipOutputStream zos = new ZipOutputStream(new BufferedOutputStream(new FileOutputStream(_toFile), @@ -221,8 +223,9 @@ private void doBackup() throws Exception { * A convenience method for unit tests to unzip a backup created by * {@link #doBackup()}. In production it is expected a backup produced by * {@link #doBackup()} will be restored via an external unzip utility. - * + * * @throws Exception + * if the restore operation fails */ public void doRestore(final String path) throws Exception { final File zipFile = new File(path); diff --git a/persistit/core/src/main/java/com/persistit/Buffer.java b/persistit/core/src/main/java/com/persistit/Buffer.java index 963dece395..6c375bd911 100644 --- a/persistit/core/src/main/java/com/persistit/Buffer.java +++ b/persistit/core/src/main/java/com/persistit/Buffer.java @@ -452,12 +452,12 @@ void clearEnqueuedForPruning() { * * Extract fields from the buffer. * - * @throws PersistitIOException - * @throws InvalidPageAddressException - * @throws InvalidPageStructureException - * @throws VolumeClosedException - * @throws InUseException - * @throws PersistitInterruptedException + * @throws PersistitIOException if an I/O error occurs + * @throws InvalidPageAddressException if the page address is invalid + * @throws InvalidPageStructureException if the page structure is invalid + * @throws VolumeClosedException if the volume is closed + * @throws InUseException if the resource is currently in use + * @throws PersistitInterruptedException if the thread is interrupted while waiting */ void load(final Volume vol, final long page) throws PersistitIOException, InvalidPageAddressException, InvalidPageStructureException, VolumeClosedException, InUseException, PersistitInterruptedException { @@ -614,7 +614,7 @@ void clearBytes(final int from, final int to) { * Clears all tailblock bytes that are no longer in use. This makes sure we * don't retain data that has been deleted or moved in this page. * - * @throws InvalidPageStructureException + * @throws InvalidPageStructureException if the page structure is invalid */ void clearSlack() throws InvalidPageStructureException { if (isGarbagePage()) { @@ -828,7 +828,7 @@ Buffer getNext() { * @return An encoded result (see above). Returns 0 if the supplied key * precedes the first key in the page. Returns Integer.MAX_VALUE if * it follows the last key in the page. - * @throws PersistitInterruptedException + * @throws PersistitInterruptedException if the thread is interrupted while waiting */ int findKey(final Key key) throws PersistitInterruptedException { final FastIndex fastIndex = getFastIndex(); @@ -1119,7 +1119,7 @@ boolean isPrimordialAntiValue(final int foundAt) { * Given a foundAt position, return a long value that encodes the offset and * size of the associated value field * - * @param foundAt + * @param foundAt the encoded position of the key within the page * @return (offset << 32) | size; */ long at(final int foundAt) { @@ -1227,9 +1227,9 @@ long getPointer(final int foundAt) throws PersistitException { * Internal implementation of getKey using a previously computed result from * the findKey() method. * - * @param key - * @param mode - * @param foundAt + * @param key the Key being sought and updated with the result + * @param mode the traversal direction + * @param foundAt the result previously computed by {@link #findKey} * @return foundAt value */ int traverse(final Key key, final Key.Direction mode, final int foundAt) { @@ -1248,8 +1248,8 @@ int traverse(final Key key, final Key.Direction mode, final int foundAt) { /** * Helper method to compute the actual bytes in the previous key. * - * @param key - * @param foundAt + * @param key the Key to populate with the previous key + * @param foundAt the result previously computed by {@link #findKey} * @return foundAt value */ int previousKey(final Key key, final int foundAt) { @@ -1321,8 +1321,8 @@ int previousKey(final Key key, final int foundAt) { /** * Helper method to compute the actual bytes in the successor key. * - * @param key - * @param foundAt + * @param key the Key to populate with the successor key + * @param foundAt the result previously computed by {@link #findKey} * @return foundAt value */ int nextKey(final Key key, final int foundAt) { @@ -1356,8 +1356,8 @@ int nextKey(final Key key, final int foundAt) { /** * Helper method for IntegrityCheck to find next long record key block * - * @param value - * @param foundAt + * @param value the Value to receive the long record data + * @param foundAt the position at which to begin searching * @return foundAt value */ int nextLongRecord(final Value value, final int foundAt) { @@ -1411,7 +1411,7 @@ int toKeyBlock(int foundAt) { * The key on under which the value will be stored * @param valueHelper * The value, converted to a byte array - * @throws PersistitInterruptedException + * @throws PersistitInterruptedException if the thread is interrupted while waiting */ int putValue(final Key key, final ValueHelper valueHelper) throws PersistitInterruptedException { final int p = findKey(key); @@ -1577,7 +1577,7 @@ int putValue(final Key key, final ValueHelper valueHelper, final int foundAt, fi * This method is for debugging only. It should be asserted after a key has * been inserted or removed. * - * @param p + * @param p the offset of the keyblock to check * @return when key is adjacent */ private boolean adjacentKeyCheck(int p) { @@ -1922,7 +1922,7 @@ private int wedgeTail(final int tail, int delta) { * @return offset of the inserted key block. If positive, this value denotes * a location in this Buffer. If negative, it denotes a location in * the right sibling Buffer. - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ final int split(final Buffer rightSibling, final Key key, final ValueHelper valueHelper, int foundAt, final Key indexKey, final Sequence sequence, final SplitPolicy policy) throws PersistitException { @@ -2961,11 +2961,11 @@ private void reduceEbc(final int p, final int newEbc, final byte[] indexKeyBytes /** * Move records from buffer2 to this buffer. The * - * @param buffer - * @param p1 - * @param p2 - * @param insertAt - * @param includesRightEdge + * @param buffer the source buffer from which records are moved + * @param p1 the offset of the first keyblock to move + * @param p2 the offset just past the last keyblock to move + * @param insertAt the offset in this buffer at which the records are inserted + * @param includesRightEdge whether the right edge keyblock is also moved */ void moveRecords(final Buffer buffer, final int p1, final int p2, int insertAt, final boolean includesRightEdge) { if (p2 - p1 + _keyBlockEnd > _alloc) { @@ -3195,7 +3195,7 @@ boolean isAfterRightEdge(final int foundAt) { * Determines whether supplied index points to the left of the first key in * the page. * - * @param foundAt + * @param foundAt the keyblock index */ boolean isBeforeLeftEdge(final int foundAt) { return (((foundAt & EXACT_MASK) == 0 && (foundAt & P_MASK) <= KEY_BLOCK_START) || (foundAt & P_MASK) < KEY_BLOCK_START); @@ -3598,10 +3598,10 @@ PersistitException verify(Key key, final VerifyVisitor visitor) { * pruning the page can be saved with the preceding checkpoint even though a * new checkpoint has been proposed. * - * @param tree + * @param tree the Tree to which this buffer belongs * @return true if this method changed the contents of the * buffer - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ boolean pruneMvvValues(final Tree tree, final boolean pruneLongMVVs, final List cleanupActions) throws PersistitException { @@ -3876,7 +3876,7 @@ public String toStringDetail() { } /** - * @param findPointer + * @param findPointer the page pointer to locate, or a negative value to show all records * @return a human-readable representation of a page; if it is an index page * and findPointer >= 0, then only show the records that surround * the one that points to findPointer. This provides a way to @@ -4234,7 +4234,7 @@ void enqueuePruningAction(final int treeHandle) { * A set of Volumes for which IV records have already been * written. This method adds a volume to this set whenever it * writes an IV record. - * @throws Exception + * @throws Exception if an error occurs while dumping the buffer */ void dump(final ByteBuffer bb, final boolean secure, final boolean verbose, final Set identifiedVolumes) throws Exception { diff --git a/persistit/core/src/main/java/com/persistit/BufferPool.java b/persistit/core/src/main/java/com/persistit/BufferPool.java index 8af3ee0c44..98d528e2b6 100644 --- a/persistit/core/src/main/java/com/persistit/BufferPool.java +++ b/persistit/core/src/main/java/com/persistit/BufferPool.java @@ -543,6 +543,7 @@ int getDirtyPageCount() { * @param volume * The volume * @throws PersistitInterruptedException + * if the thread was interrupted while waiting for I/O */ boolean invalidate(final Volume volume) throws PersistitException { final float ratio = (float) volume.getStorage().getNextAvailablePage() / (float) _bufferCount; @@ -891,12 +892,18 @@ Buffer get(final Volume vol, final long page, final boolean writer, final boolea * Buffer should be used only for display and diagnostic purposes. * * @param vol + * the Volume containing the page to copy * @param page + * the page address of the page to copy * @return Copy of the Buffer * @throws InvalidPageAddressException + * if the supplied page address is invalid * @throws InvalidPageStructureException + * if the page image is corrupt * @throws VolumeClosedException + * if the volume has been closed * @throws PersistitInterruptedException + * if the thread was interrupted while waiting for I/O */ public Buffer getBufferCopy(final Volume vol, final long page) throws InvalidPageAddressException, InvalidPageStructureException, VolumeClosedException, InUseException, PersistitIOException, @@ -952,6 +959,7 @@ public Buffer getBufferCopy(final int index) throws IllegalArgumentException { * @return Buffer An available buffer, or null if no buffer is * currently available. The buffer has a writer claim. * @throws PersistitException + * if a persistence error occurs while evicting a page * @throws IllegalStateException * if there is no available buffer. */ @@ -1327,6 +1335,7 @@ private boolean matches(final Buffer buffer) { * Used to sort buffers in ascending page address order by volume. * * @param buffer + * the BufferHolder to compare with * @return -1, 0 or 1 as this Buffer falls before, a, or * after the supplied Buffer in the desired page * address order. @@ -1397,7 +1406,9 @@ public String toString() { /** * @param i + * the index of the buffer within this pool * @param detail + * true to include detailed buffer state * @return toString value for buffer at index i. */ String toString(final int i, final boolean detail) { @@ -1420,6 +1431,7 @@ String toString(final int i, final boolean detail) { * @param secure * true to obscure data values in the dump * @throws Exception + * if an error occurs while writing the dump */ void dump(final DataOutputStream stream, final ByteBuffer bb, final boolean secure, final boolean verbose) throws Exception { diff --git a/persistit/core/src/main/java/com/persistit/CLI.java b/persistit/core/src/main/java/com/persistit/CLI.java index 51341e6c23..639af288d5 100644 --- a/persistit/core/src/main/java/com/persistit/CLI.java +++ b/persistit/core/src/main/java/com/persistit/CLI.java @@ -191,7 +191,7 @@ public class CLI { * annotation, and its arguments must be defined with @Arg annotations. This * method allows applications to extend the CLI. * - * @param clazz + * @param clazz the class whose @Cmd-annotated methods are registered as CLI commands */ public static void registerCommands(final Class clazz) { for (final Method method : clazz.getDeclaredMethods()) { @@ -248,8 +248,8 @@ public static void registerCommands(final Class clazz) { * * To execute the select command on a server on port 9999. * - * @param args - * @throws Exception + * @param args command-line arguments; the first element specifies the host and/or port of the CLI server, and the remaining elements form the CLI command to execute + * @throws Exception if an error occurs while connecting to or communicating with the CLI server */ public static void main(final String[] args) throws Exception { final StringBuilder sb = new StringBuilder(); @@ -296,10 +296,10 @@ public static void main(final String[] args) throws Exception { * commands and write any generated output to the supplied * PrintWriter. * - * @param persistit - * @param reader - * @param writer - * @throws Exception + * @param persistit the Persistit instance on which the commands operate + * @param reader the BufferedReader from which CLI command lines are read + * @param writer the PrintWriter to which generated output is written + * @throws Exception if an error occurs while reading, executing a command, or writing output */ public static void runScript(final Persistit persistit, final BufferedReader reader, final PrintWriter writer) throws Exception { @@ -324,7 +324,7 @@ private static long availableMemory() { * name=value parameters, all separate by spaces. Argument values containing * spaces can be quoted by a leading backslash. * - * @param commandLine + * @param commandLine the command line string to split into command and argument tokens * @return List of String values, one per command name or argument token. */ public static List pieces(final String commandLine) { @@ -699,13 +699,13 @@ void checkOpen() throws NotOpenException { * Open files on disk and attempt to make a read-only Persistit instance. * This method does not return a Task and cannot be executed in a live * - * @param datapath - * @param journalpath - * @param volumepath - * @param rmiport - * @param y + * @param datapath the directory path in which the data files are located + * @param journalpath the path to the journal files; if empty, the data path is used + * @param volumepath the path to the volume file(s); if empty, the data path is used + * @param rmiport the RMI management port on which to register the instance + * @param y true to recover committed transactions while opening * @return Result description - * @throws Exception + * @throws Exception if the read-only Persistit instance cannot be opened */ @Cmd("open") String open(@Arg("datapath|string|Data path") final String datapath, diff --git a/persistit/core/src/main/java/com/persistit/CheckpointManager.java b/persistit/core/src/main/java/com/persistit/CheckpointManager.java index 7d094e45eb..68a54e463e 100644 --- a/persistit/core/src/main/java/com/persistit/CheckpointManager.java +++ b/persistit/core/src/main/java/com/persistit/CheckpointManager.java @@ -12,6 +12,7 @@ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. + * Portions Copyrighted 2026 3A Systems, LLC */ package com.persistit; @@ -219,7 +220,7 @@ void pollCreateCheckpoint() throws PersistitException { * checkpoints. * * @return The newly created Checkpoint - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ synchronized Checkpoint createCheckpoint() throws PersistitException { /* diff --git a/persistit/core/src/main/java/com/persistit/ClassIndex.java b/persistit/core/src/main/java/com/persistit/ClassIndex.java index 2db6d0ca5e..37de4bb759 100644 --- a/persistit/core/src/main/java/com/persistit/ClassIndex.java +++ b/persistit/core/src/main/java/com/persistit/ClassIndex.java @@ -404,7 +404,7 @@ private void releaseExchange(final Exchange ex) { * For unit tests only. Next class ID handle will be at least as large as * this. * - * @param id + * @param id the minimum value for the next assigned class ID handle */ void setTestIdFloor(final int id) { _testIdFloor = id; @@ -413,7 +413,7 @@ void setTestIdFloor(final int id) { /** * For unit tests only. Clears all entries. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ void clearAllEntries() throws PersistitException { getExchange().removeAll(); diff --git a/persistit/core/src/main/java/com/persistit/Configuration.java b/persistit/core/src/main/java/com/persistit/Configuration.java index 2c3580f128..a9e830126a 100644 --- a/persistit/core/src/main/java/com/persistit/Configuration.java +++ b/persistit/core/src/main/java/com/persistit/Configuration.java @@ -438,6 +438,7 @@ public void setMaximumCount(final int maximumCount) { * Set the minimum and maximum buffer count. * * @param count + * the buffer count to set as both the minimum and maximum */ public void setCount(final int count) { setMinimumCount(count); @@ -611,8 +612,11 @@ public void parse(final String string) { * {@value com.persistit.Configuration#GIGA} as a multiplier. * * @param bufferSize + * the buffer (page) size to which this count applies * @param propertyName + * the name of the property being parsed * @param propertyValue + * the property value to parse as a buffer count * @throws IllegalArgumentException * if the propertyValue is not in the form of a valid * Integer @@ -642,8 +646,11 @@ public void parseBufferCount(final int bufferSize, final String propertyName, fi * 75% of the remainder up to 8Gb, but not less than 64Mb. * * @param bufferSize + * the buffer (page) size to which this configuration applies * @param propertyName + * the name of the property being parsed * @param propertyValue + * the property value to parse as memory constraints */ public void parseBufferMemory(final int bufferSize, final String propertyName, final String propertyValue) { checkBufferSize(bufferSize, propertyName); @@ -1183,7 +1190,10 @@ public static float parseFloatProperty(final String propName, final String str) * case-insensitive. * * @param propName + * Name of the property, used in formatting the Exception if the + * value is invalid. * @param str + * The string representation, either "true" or "false". * @return the boolean value */ public static boolean parseBooleanValue(final String propName, final String str) { @@ -1263,6 +1273,7 @@ public boolean getBooleanProperty(final String propName, final boolean dflt) { * {@link VolumeSpecification#VolumeSpecification(String)}. * @return a VolumeSpecification * @throws InvalidVolumeSpecificationException + * if the supplied string is not a valid volume specification * @see #getProperty(String) */ public VolumeSpecification volumeSpecification(final String vstring) throws InvalidVolumeSpecificationException { @@ -1313,6 +1324,8 @@ public String getBufferPoolConfiguration() { * supplied string. * * @param string + * the buffer pool configuration string, one specification per + * buffer size separated by ';' */ public void setBufferPoolConfiguration(final String string) { for (final BufferPoolConfiguration bpc : bufferPoolMap.values()) { diff --git a/persistit/core/src/main/java/com/persistit/DefaultObjectCoder.java b/persistit/core/src/main/java/com/persistit/DefaultObjectCoder.java index 437935b671..0d833d8899 100644 --- a/persistit/core/src/main/java/com/persistit/DefaultObjectCoder.java +++ b/persistit/core/src/main/java/com/persistit/DefaultObjectCoder.java @@ -189,8 +189,8 @@ private DefaultObjectCoder(final Persistit persistit, final Class clientClass, f * of stored instances * * @return the newly registered DefaultObjectCoder - * - * @throws IntrospectionException + * + * @throws IntrospectionException if the client class cannot be introspected */ public synchronized DefaultObjectCoder registerObjectCoderFromBean(final Persistit persistit, final Class clientClass, final String[] keyPropertyNames) throws IntrospectionException { @@ -504,8 +504,8 @@ public boolean isZeroByteFree() { * application to convey an application-specific context for the * operation. (See {@link CoderContext}.) The default value is * null. - * - * @throws ConversionException + * + * @throws ConversionException if the key segment cannot be converted into the target object */ @Override public void renderKeySegment(final Key key, final Object target, final Class clazz, final CoderContext context) diff --git a/persistit/core/src/main/java/com/persistit/DefaultValueCoder.java b/persistit/core/src/main/java/com/persistit/DefaultValueCoder.java index 2c5393fe8d..492208fb37 100644 --- a/persistit/core/src/main/java/com/persistit/DefaultValueCoder.java +++ b/persistit/core/src/main/java/com/persistit/DefaultValueCoder.java @@ -284,8 +284,8 @@ public Object run() { /** * Performs unprivileged initialization logic common to both constructors. * - * @param clientClass - * @param mustBeSerializable + * @param clientClass the client class to be encoded and decoded + * @param mustBeSerializable whether the client class is required to be serializable */ private void init(final Persistit persistit, final Class clientClass, final boolean mustBeSerializable) { _clazz = clientClass; @@ -1012,7 +1012,7 @@ Object newInstance() { * @param object * The object whose fields are to be serialized * - * @throws ConversionException + * @throws ConversionException if the value cannot be converted */ public void putDefaultFields(final Value value, final Object object) throws ConversionException { Accessor accessor = null; @@ -1054,7 +1054,7 @@ public void putDefaultFields(final Value value, final Object object) throws Conv * @return An Object having the same class as the suppled * clazz parameter. * - * @throws ConversionException + * @throws ConversionException if the value cannot be converted */ @Override public Object get(final Value value, final Class clazz, final CoderContext context) throws ConversionException { @@ -1110,7 +1110,7 @@ Object readResolve(Object instance) { * operation. (See {@link CoderContext}.) The default value is * null. * - * @throws ConversionException + * @throws ConversionException if the value cannot be converted */ @Override public void render(final Value value, final Object target, final Class clazz, final CoderContext context) @@ -1145,7 +1145,7 @@ public void render(final Value value, final Object target, final Class clazz, fi * @param target * The object whose fields will be set * - * @throws ConversionException + * @throws ConversionException if the value cannot be converted */ void renderDefaultFields(final Value value, final Object target) throws ConversionException { Accessor accessor = null; diff --git a/persistit/core/src/main/java/com/persistit/Exchange.java b/persistit/core/src/main/java/com/persistit/Exchange.java index 48e16251c4..38e9ecf46a 100644 --- a/persistit/core/src/main/java/com/persistit/Exchange.java +++ b/persistit/core/src/main/java/com/persistit/Exchange.java @@ -344,7 +344,7 @@ public void sawVersion(final long version, final int offset, final int valueLeng * true to create a new Tree if one by the specified * name does not already exist. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public Exchange(final Persistit persistit, final String volumeName, final String treeName, final boolean create) throws PersistitException { @@ -368,7 +368,7 @@ public Exchange(final Persistit persistit, final String volumeName, final String * @param create * true to create a new Tree if one by the specified * name does not already exist. - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public Exchange(final Persistit persistit, final Volume volume, final String treeName, final boolean create) throws PersistitException { @@ -674,7 +674,7 @@ public interface TraverseVisitor { * Key and Value may be read * @return true to continue traversing keys, or * false to stop - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean visit(final ReadOnlyExchange ex) throws PersistitException; } @@ -1127,11 +1127,11 @@ private int search(final Key key, final boolean writer) throws PersistitExceptio * determines whether information cached in the LevelCache is still valid; * if so the previous result is still valid. * - * @param buffer - * @param key - * @param lc + * @param buffer the Buffer to search + * @param key the Key to find + * @param lc the LevelCache providing cached lookup state * @return foundAt value - * @throws PersistitInterruptedException + * @throws PersistitInterruptedException if the thread is interrupted while waiting */ private int findKey(final Buffer buffer, final Key key, final LevelCache lc) throws PersistitInterruptedException { // @@ -1990,7 +1990,7 @@ private Buffer quicklyReclaimBuffer(final LevelCache lc, final boolean writer) t * Siblings). * @return true if there is a key to traverse to, else * false. - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean traverse(final Direction direction, final boolean deep) throws PersistitException { final boolean result = traverse(direction, deep, Integer.MAX_VALUE); @@ -2051,7 +2051,7 @@ public boolean traverse(final Direction direction, final boolean deep) throws Pe * @return true if there is a key to traverse to, else * false. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean traverse(final Direction direction, final boolean deep, final int minimumBytes) throws PersistitException { @@ -2428,7 +2428,7 @@ private boolean traverse(final Direction direction, final boolean deep, final in * @return true if additional keys remaining in the traversal * set, or false to indicate that keys are exhausted. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean traverse(final Direction direction, final boolean deep, final int minimumBytes, @@ -2477,7 +2477,7 @@ public boolean traverse(final Direction direction, final boolean deep, final int * * @return true if there is a key to traverse to, else null. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean traverse(final Direction direction, final KeyFilter keyFilter, final int minBytes) throws PersistitException { @@ -2530,7 +2530,7 @@ public boolean traverse(final Direction direction, final KeyFilter keyFilter, fi * traverse(Key.GT, false). * * @return true if there is a key to traverse to, else null. - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean next() throws PersistitException { return traverse(GT, false); @@ -2541,7 +2541,7 @@ public boolean next() throws PersistitException { * traverse(Key.LT, false). * * @return true if there is a key to traverse to, else null. - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean previous() throws PersistitException { return traverse(LT, false); @@ -2559,7 +2559,7 @@ public boolean previous() throws PersistitException { * Siblings). * * @return true if there is a key to traverse to, else null. - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean next(final boolean deep) throws PersistitException { return traverse(GT, deep); @@ -2578,7 +2578,7 @@ public boolean next(final boolean deep) throws PersistitException { * * @return true if there is a key to traverse to, else null. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean previous(final boolean deep) throws PersistitException { return traverse(LT, deep); @@ -2590,7 +2590,7 @@ public boolean previous(final boolean deep) throws PersistitException { * are included in the result is determined by the KeyFilter. * * @return true if there is a key to traverse to, else null. - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean next(final KeyFilter filter) throws PersistitException { return traverse(GT, filter, Integer.MAX_VALUE); @@ -2603,7 +2603,7 @@ public boolean next(final KeyFilter filter) throws PersistitException { * KeyFilter. * * @return true if there is a key to traverse to, else null. - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean previous(final KeyFilter filter) throws PersistitException { return traverse(LT, filter, Integer.MAX_VALUE); @@ -2617,7 +2617,7 @@ public boolean previous(final KeyFilter filter) throws PersistitException { * * @return true if the key has a successor * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean hasNext() throws PersistitException { return traverse(GT, false, -1); @@ -2630,7 +2630,7 @@ public boolean hasNext() throws PersistitException { * * @return true if the key has a successor * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean hasNext(final KeyFilter filter) throws PersistitException { if (filter == null) @@ -2656,7 +2656,7 @@ public boolean hasNext(final KeyFilter filter) throws PersistitException { * * @return true if the key has a successor * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean hasNext(final boolean deep) throws PersistitException { return traverse(GT, deep, -1); @@ -2669,7 +2669,7 @@ public boolean hasNext(final boolean deep) throws PersistitException { * changed. * * @return true if the key has a predecessor - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean hasPrevious() throws PersistitException { return traverse(LT, false, -1); @@ -2690,7 +2690,7 @@ public boolean hasPrevious() throws PersistitException { * * @return true if the key has a predecessor * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean hasPrevious(final boolean deep) throws PersistitException { return traverse(LT, deep, -1); @@ -2703,7 +2703,7 @@ public boolean hasPrevious(final boolean deep) throws PersistitException { * * @return true if the key has a successor * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean hasPrevious(final KeyFilter filter) throws PersistitException { if (filter == null) @@ -2722,7 +2722,7 @@ public boolean hasPrevious(final KeyFilter filter) throws PersistitException { * * @return true if the key has an associated value * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean isValueDefined() throws PersistitException { return traverse(EQ, true, -1); @@ -2734,7 +2734,7 @@ public boolean isValueDefined() throws PersistitException { * associated with the current key, then replace it. * * @return This Exchange to permit method call chaining - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public Exchange store() throws PersistitException { return store(_key, _value); @@ -2745,7 +2745,7 @@ public Exchange store() throws PersistitException { * timeout value of * {@value com.persistit.SharedResource#DEFAULT_MAX_WAIT_TIME} milliseconds. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public void lock() throws PersistitException { lock(_key, SharedResource.DEFAULT_MAX_WAIT_TIME); @@ -2758,7 +2758,7 @@ public void lock() throws PersistitException { * * @param key * The key to lock - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public void lock(final Key key) throws PersistitException { lock(key, SharedResource.DEFAULT_MAX_WAIT_TIME); @@ -2825,7 +2825,7 @@ public void lock(final Key key) throws PersistitException { * the source Key * @param timeout * timeout interval in milliseconds, zero for default timeout - * @throws PersistitException + * @throws PersistitException if a persistence error occurs * @throws RollbackException * in the specific case that another concurrent transaction has * also locked the same key @@ -2873,7 +2873,7 @@ public void lock(final Key lockKey, final long timeout) throws PersistitExceptio * need for external synchronization. * * @return This Exchange to permit method call chaining - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public Exchange fetchAndStore() throws PersistitException { assertCorrectThread(true); @@ -2899,7 +2899,7 @@ public Exchange fetchAndStore() throws PersistitException { * . * * @return This Exchange to permit method call chaining - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public Exchange fetch() throws PersistitException { return fetch(_value, Integer.MAX_VALUE); @@ -2929,7 +2929,7 @@ public Exchange fetch() throws PersistitException { * returned value. * * @return This Exchange to permit method call chaining - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public Exchange fetch(final int minimumBytes) throws PersistitException { return fetch(_value, minimumBytes); @@ -2948,7 +2948,7 @@ public Exchange fetch(final int minimumBytes) throws PersistitException { * fetched. * * @return This Exchange to permit method call chaining - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public Exchange fetch(final Value value) throws PersistitException { return fetch(value, Integer.MAX_VALUE); @@ -3035,7 +3035,7 @@ private boolean mvccFetch(final Value value, final int minimumBytes) throws Pers * * * @return This Exchange to permit method call chaining - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public Exchange fetch(final Value value, int minimumBytes) throws PersistitException { assertCorrectThread(true); @@ -3174,7 +3174,7 @@ void fetchFixupForLongRecords(final Value value, final int minimumBytes) throws * * @return true if the current Key has logical * children - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean hasChildren() throws PersistitException { _key.copyTo(_spareKey2); @@ -3193,7 +3193,7 @@ public boolean hasChildren() throws PersistitException { * is, the value of {@link Value#isDefined} becomes false. * * @return true if there was a key/value pair to remove - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean fetchAndRemove() throws PersistitException { assertCorrectThread(true); @@ -3212,7 +3212,7 @@ public boolean fetchAndRemove() throws PersistitException { * Exchange will no longer be usable. Attempts to perform * operations on it will result in an IllegalStateException. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public void removeTree() throws PersistitException { assertCorrectThread(true); @@ -3234,7 +3234,7 @@ public void removeTree() throws PersistitException { * Tree. * * @return true if there was a key/value pair to remove - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean remove() throws PersistitException { return removeInternal(EQ, false); @@ -3244,7 +3244,7 @@ public boolean remove() throws PersistitException { * Remove all keys in this Exchange's Tree. * * @return true if there were key/value pairs removed - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean removeAll() throws PersistitException { clear(); @@ -3273,7 +3273,7 @@ public boolean removeAll() throws PersistitException { * One of Key.EQ, Key.GT, Key.GTEQ * @return true if one or more records were actually removed, * else false. - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean remove(final Direction direction) throws PersistitException { return removeInternal(direction, false); @@ -3370,7 +3370,7 @@ public boolean removeKeyRange(final Key key1, final Key key2) throws PersistitEx * Control whether to copy the existing value for the first key * into _spareValue before deleting the record. * @return true if any records were removed. - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ private boolean removeKeyRangeInternal(final Key key1, final Key key2, final boolean fetchFirst) throws PersistitException { @@ -3462,7 +3462,7 @@ private boolean removeKeyRangeInternal(final Key key1, final Key key2, final boo * being identified and removes it only if it is a primordial * AntiValue. * @return true if any records were removed. - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ boolean raw_removeKeyRangeInternal(final Key key1, final Key key2, final boolean fetchFirst, final boolean removeOnlyAntiValue) throws PersistitException { @@ -3876,7 +3876,7 @@ boolean raw_removeKeyRangeInternal(final Key key1, final Key key2, final boolean * * @param lc * LevelCache set up by raw_removeKeyRangeInternal - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ private void rebalanceSplit(final LevelCache lc) throws PersistitException { // diff --git a/persistit/core/src/main/java/com/persistit/FastIndex.java b/persistit/core/src/main/java/com/persistit/FastIndex.java index 399d1225d1..c13f1aae83 100644 --- a/persistit/core/src/main/java/com/persistit/FastIndex.java +++ b/persistit/core/src/main/java/com/persistit/FastIndex.java @@ -514,11 +514,11 @@ synchronized void insertKeyBlock(final int foundAt, final int previousEbc, final * Fixes up the elements surrounding insertion of keyblock that causes the * successor ebc to get fixed up. * - * @param insertIndex - * @param runIndex - * @param runCount - * @param ebc - * @param successorEbc + * @param insertIndex the index at which the new keyblock is inserted + * @param runIndex the index of the first keyblock in the affected run + * @param runCount the number of keyblocks in the run + * @param ebc the elided byte count at the head of the run + * @param successorEbc the elided byte count of the successor keyblock */ private void fixupSuccessor(final int lastIndex, final int insertIndex, final int runIndex, final int runCount, final int ebc, final int successorEbc) { diff --git a/persistit/core/src/main/java/com/persistit/GetVersion.java b/persistit/core/src/main/java/com/persistit/GetVersion.java index 4049d4394e..bf29293626 100644 --- a/persistit/core/src/main/java/com/persistit/GetVersion.java +++ b/persistit/core/src/main/java/com/persistit/GetVersion.java @@ -1,6 +1,7 @@ /** * Copyright 2011-2012 Akiban Technologies, Inc. - * + * Portions Copyrighted 2026 3A Systems, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -36,8 +37,8 @@ public class GetVersion { /** * Write the build version string to {@link System#out} * - * @param a - * @throws Exception + * @param a the command-line arguments (ignored) + * @throws Exception if an error occurs while reading the version string */ public static void main(final String[] a) throws Exception { System.out.println(getVersionString()); diff --git a/persistit/core/src/main/java/com/persistit/IOMeter.java b/persistit/core/src/main/java/com/persistit/IOMeter.java index 6773ab7fdf..63a44752bd 100644 --- a/persistit/core/src/main/java/com/persistit/IOMeter.java +++ b/persistit/core/src/main/java/com/persistit/IOMeter.java @@ -408,7 +408,8 @@ public int op(final String opName) { * how frequently to schedule its own activities without interfering * severely with current operational load. * - * @return + * @return an estimate of the number of bytes read or written per second, or + * -1 if there was no recent activity */ synchronized long recentCharge() { final long now = System.nanoTime(); @@ -438,7 +439,7 @@ synchronized long recentCharge() { * * @param args * Specify one argument in the form file= - * @throws Exception + * @throws Exception if an error occurs while reading or dumping the log */ public static void main(final String[] args) throws Exception { final ArgParser ap = new ArgParser("com.persistit.IOMeter", args, new String[] { "file||log file name", diff --git a/persistit/core/src/main/java/com/persistit/IntegrityCheck.java b/persistit/core/src/main/java/com/persistit/IntegrityCheck.java index a61c1e1631..2857e3757c 100644 --- a/persistit/core/src/main/java/com/persistit/IntegrityCheck.java +++ b/persistit/core/src/main/java/com/persistit/IntegrityCheck.java @@ -391,7 +391,7 @@ public void setSuspendUpdates(final boolean suspendUpdates) { * Control output format. When CSV mode is enabled, the output is organized * as comma-separated-variable text that can be imported into a spreadsheet. * - * @param csvMode + * @param csvMode true to enable CSV output mode */ public void setCsvMode(final boolean csvMode) { _csv = csvMode; @@ -773,7 +773,7 @@ private void reset() { * @param volume * The {@link Volume} to check. * @return true if the volume is clean (has no Faults). - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean checkVolume(final Volume volume) throws PersistitException { reset(); @@ -819,7 +819,7 @@ public boolean checkVolume(final Volume volume) throws PersistitException { * @param tree * The Tree to check. * @return true if the volume is clean (has no Faults). - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean checkTree(final Tree tree) throws PersistitException { final String messageStart; @@ -887,9 +887,9 @@ public boolean checkTree(final Tree tree) throws PersistitException { * page is a data page, then we are at the bottom of the tree. Else we * recursively checkTree on each of the subordinate pages. * - * @param page - * @param level - * @throws PersistitException + * @param page the page address of the subtree root to check + * @param level the level of the page within the tree + * @throws PersistitException if a persistence error occurs */ private void checkTree(final Key parentKey, final long parent, final long page, final int level, final Tree tree) throws PersistitException { diff --git a/persistit/core/src/main/java/com/persistit/JournalManager.java b/persistit/core/src/main/java/com/persistit/JournalManager.java index 621bbbe6ec..5b3fcbe0fe 100644 --- a/persistit/core/src/main/java/com/persistit/JournalManager.java +++ b/persistit/core/src/main/java/com/persistit/JournalManager.java @@ -253,10 +253,10 @@ class JournalManager implements JournalManagerMXBean, VolumeHandleLookup { * suffix contains twelve digits.) *

* - * @param rman - * @param path - * @param maximumSize - * @throws PersistitException + * @param rman the RecoveryManager supplying recovered journal state, or null to start a new journal + * @param path the base journal file path (ignored when continuing a recovered journal) + * @param maximumSize the maximum size in bytes of each journal file (ignored when continuing a recovered journal) + * @throws PersistitException if a persistence error occurs */ public synchronized void init(final RecoveryManager rman, final String path, final long maximumSize) throws PersistitException { @@ -315,7 +315,7 @@ public void startJournal() throws PersistitException { /** * Copy dynamic variables into a {@link Management.JournalInfo} structure. * - * @param info + * @param info the JournalInfo structure to populate */ public synchronized void populateJournalInfo(final Management.JournalInfo info) { info.closed = _closed.get(); @@ -586,7 +586,7 @@ public int urgency() { * {@link #urgency()}. When that value is {@value #URGENT} then the delay is * {@value #URGENT_COMMIT_DELAY_MILLIS} milliseconds. * - * @throws PersistitInterruptedException + * @throws PersistitInterruptedException if the thread is interrupted while waiting */ public void throttle() throws PersistitInterruptedException { final long interval = _throttleSleepInterval; @@ -853,7 +853,7 @@ private long readPageBufferFromJournal(final PageNode pn, final ByteBuffer bb) t * journal address * @return pageAddress of the page at the specified location, or -1 if the * address does not reference a valid page - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ Buffer readPageBuffer(final long address) throws PersistitException { ByteBuffer bb = ByteBuffer.allocate(PA.OVERHEAD); @@ -910,7 +910,7 @@ private void advance(final int recordSize) { * {@link #prepareWriteBuffer(int)} - the write buffer needs to be ready to * receive the JH record. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ synchronized void writeJournalHeader() throws PersistitException { JH.putType(_writeBuffer); @@ -933,7 +933,7 @@ synchronized void writeJournalHeader() throws PersistitException { * {@link #prepareWriteBuffer(int)} - the write buffer needs to be ready to * receive the JE record. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ synchronized void writeJournalEnd() throws PersistitException { if (_writeBufferAddress != Long.MAX_VALUE) { @@ -1156,9 +1156,9 @@ void writePageToJournal(final Buffer buffer) throws PersistitException { /** * package-private for unit tests only. * - * @param volume - * @param handle - * @throws PersistitException + * @param volume the volume whose handle mapping is written + * @param handle the internal handle assigned to the volume + * @throws PersistitException if a persistence error occurs */ synchronized void writeVolumeHandleToJournal(final Volume volume, final int handle) throws PersistitException { prepareWriteBuffer(IV.MAX_LENGTH); @@ -1216,8 +1216,8 @@ synchronized void writeTreeHandleToJournal(final TreeDescriptor td, final int ha * Journal address of previous TX record written by this * transaction, or 0 if there is to previous record * - * @return - * @throws PersistitException + * @return the journal address at which the TX record was written + * @throws PersistitException if a persistence error occurs */ synchronized long writeTransactionToJournal(final ByteBuffer buffer, final long startTimestamp, final long commitTimestamp, final long backchainAddress) throws PersistitException { @@ -1374,7 +1374,7 @@ void crash() throws IOException { /** * Flushes the write buffer * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ synchronized long flush() throws PersistitException { _persistit.checkFatal(); @@ -1479,7 +1479,7 @@ public void force() throws PersistitException { * @param size * Size of record to be written * @return true if and only if a new journal file was started - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ private boolean prepareWriteBuffer(final int size) throws PersistitException { _persistit.checkFatal(); @@ -1664,7 +1664,7 @@ synchronized FileChannel getFileChannel(final long address) throws PersistitIOEx *

* Does nothing of the appendOnly is set. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ @Override public void copyBack() throws Exception { @@ -1685,7 +1685,7 @@ public void copyBack() throws Exception { * Remove transactions and PageNode entries when possible due to completion * of a new checkpoint. * - * @param checkpoint + * @param checkpoint the checkpoint that has just been written */ private void checkpointWritten(final Checkpoint checkpoint) { @@ -1843,7 +1843,7 @@ void pruneObsoleteTransactions(final boolean rollbackPruningEnabled) { * currently pausing, the pause time may be shortened to try to * complete the I/O when requested. In particular, a value of * zero indicates the I/O should start immediately. - * @throws PersistitInterruptedException + * @throws PersistitInterruptedException if the thread is interrupted while waiting */ void waitForDurability(final long flushedTimestamp, final long leadTime, final long stallTime) @@ -2281,7 +2281,7 @@ void start() { * General method used to wait for durability. {@See * JournalManager#waitForDurability(long, long, long)}. * - * @throws PersistitInterruptedException + * @throws PersistitInterruptedException if the thread is interrupted while waiting */ private void waitForDurability(final long flushedTimestamp, final long leadTime, final long stallTime) throws PersistitException { @@ -2984,7 +2984,7 @@ long getLastValidCheckpointBaseAddress() { /** * For use only by unit tests that test page maps, etc. * - * @param handleToVolumeMap + * @param handleToVolumeMap the handle-to-volume map entries to inject */ synchronized void unitTestInjectVolumes(final Map handleToVolumeMap) { _handleToVolumeMap.putAll(handleToVolumeMap); @@ -2993,7 +2993,7 @@ synchronized void unitTestInjectVolumes(final Map handleToVolum /** * For use only by unit tests that test page maps, etc. * - * @param pageMap + * @param pageMap the page map entries to inject */ void unitTestInjectPageMap(final Map pageMap) { _pageMap.putAll(pageMap); diff --git a/persistit/core/src/main/java/com/persistit/JournalTool.java b/persistit/core/src/main/java/com/persistit/JournalTool.java index 4db161a044..03d218e79d 100644 --- a/persistit/core/src/main/java/com/persistit/JournalTool.java +++ b/persistit/core/src/main/java/com/persistit/JournalTool.java @@ -1,6 +1,7 @@ /** * Copyright 2005-2012 Akiban Technologies, Inc. - * + * Portions Copyrighted 2026 3A Systems, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -404,9 +405,9 @@ public void scan() throws Exception { * @return The record type: one of the type values specified in * {@link com.persistit.JournalRecord}), 0 if the journal file has * fewer than 16 bytes remaining or -t where t is an invalid type. - * @throws CorruptJournalException - * @throws PersistitException - * @throws JournalNotClosedException + * @throws CorruptJournalException if the journal contains a corrupt record + * @throws PersistitException if a persistence error occurs + * @throws JournalNotClosedException if the journal was not closed cleanly */ private int scanOneRecord() throws Exception { diff --git a/persistit/core/src/main/java/com/persistit/Key.java b/persistit/core/src/main/java/com/persistit/Key.java index e5d718a8e5..01636af565 100644 --- a/persistit/core/src/main/java/com/persistit/Key.java +++ b/persistit/core/src/main/java/com/persistit/Key.java @@ -962,8 +962,8 @@ public void copyTo(final Key key) { /** * Construct a Key with a maximum length of * {@value #MAX_KEY_LENGTH}. - * - * @param persistit + * + * @param persistit the Persistit instance */ public Key(final Persistit persistit) { this(persistit, MAX_KEY_LENGTH); @@ -1079,8 +1079,8 @@ public int getDepth() { * The index is the next position in the backing byte array from which a * segment value will be decoded. Applications should usually use the * {@link #indexTo} method to set the index to a valid location. - * - * @param index + * + * @param index the position in the backing byte array from which the next segment value will be decoded * @return This Key, to permit method call chaining */ public Key setIndex(final int index) { @@ -1221,8 +1221,8 @@ public int compareKeyFragment(final Key key, final int fragmentStart, final int * positive integer if the next segment of this Key is larger * than the next segment of the supplied Key, a negative * integer if it is smaller, or zero if the segments are equal. - * - * @param key + * + * @param key the Key whose next segment is compared to this key's next segment * @return the comparison result */ public int compareKeySegment(final Key key) { @@ -1331,8 +1331,8 @@ public Key clear() { * {@value #MAX_KEY_LENGTH_UPPER_BOUND}. As a side-effect, this method also * calls the {@link #clear()} method. *

- * - * @param size + * + * @param size the size in bytes of the new backing byte array * @throws IllegalArgumentException * if the specified size is not valid. */ @@ -1818,8 +1818,8 @@ public Key append(final int v) { /** * Encodes an int into a supplied byte array. - * - * @param v + * + * @param v the int value to encode * @return size of appended segment */ private int appendIntInternal(final int v) { @@ -2166,8 +2166,8 @@ public Key append(final Object object, final CoderContext context) { * Append the next key segment of the supplied Key to this * Key. The next key segment is determined by the current index * of the key and can be set using the {@link #setIndex(int)} method. - * - * @param key + * + * @param key the Key whose next segment is appended to this key */ public Key appendKeySegment(final Key key) { final int save = _size; @@ -3690,9 +3690,9 @@ private int getTypeCode() { /** * Implementation of String decoding - * - * @param quoted - * @param sb + * + * @param quoted true to emit a quoted, displayable representation of the string + * @param sb the Appendable to which the decoded string is written */ private Appendable decodeString(final boolean quoted, final Appendable sb) { int index = _index; @@ -3919,8 +3919,8 @@ private int quoteNulls(final int index, int size, final boolean zeroByteFree) { * Converts a key segment in quoted form to raw form. In quoted form, the * bytes NUL and SOH (0 and 1) are represented by the two-byte sequence (1, * C) where C is 32 for NUL or 33 for SOH. - * - * @param index + * + * @param index the starting offset within the backing byte array of the segment to unquote * @return The unquoted length of the array. */ private int unquoteNulls(final int index, final boolean zeroByteFree) { diff --git a/persistit/core/src/main/java/com/persistit/KeyFilter.java b/persistit/core/src/main/java/com/persistit/KeyFilter.java index 0befb0cae2..ecd909e749 100644 --- a/persistit/core/src/main/java/com/persistit/KeyFilter.java +++ b/persistit/core/src/main/java/com/persistit/KeyFilter.java @@ -409,8 +409,8 @@ public KeyFilter(final Key key, final int minDepth, final int maxDepth) { * KeyFilter if and only if each of the first min(M, * N) segments of K is selected by the corresponding member of * the terms array. - * - * @param terms + * + * @param terms The Term array */ public KeyFilter(final Term[] terms) { this(terms, 0, Integer.MAX_VALUE); @@ -1507,11 +1507,13 @@ public boolean next(final Key key, final Key.Direction direction) { * Process the a Term in the KeyFilter. The first level terms * of the KeyFilter have already been satisfied. * - * @param key - * @param index - * @param level - * @param forward - * @param eq + * @param key the key being advanced to the next matching value + * @param index the byte offset within the key's encoded bytes at which the + * current term begins + * @param level the index of the term being processed + * @param forward true to find a successor key, + * false to find a predecessor + * @param eq whether an exact match at the current position is acceptable * @return whether there may be more matching keys */ private boolean next(final Key key, final int index, final int level, final boolean forward, final boolean eq) { diff --git a/persistit/core/src/main/java/com/persistit/KeyParser.java b/persistit/core/src/main/java/com/persistit/KeyParser.java index 3fc768a06d..4ba2d1f287 100644 --- a/persistit/core/src/main/java/com/persistit/KeyParser.java +++ b/persistit/core/src/main/java/com/persistit/KeyParser.java @@ -12,6 +12,7 @@ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. + * Portions Copyrighted 2026 3A Systems, LLC */ package com.persistit; @@ -218,7 +219,7 @@ public int getIndex() { * Attempt to parse a chunk of the source string as a key segment. If * successful, append the segment to the key. * - * @param key + * @param key the Key to which the parsed segment is appended * @return true a valid key segment was parsed */ private boolean parseKeySegment(final Key key) { diff --git a/persistit/core/src/main/java/com/persistit/LongRecordHelper.java b/persistit/core/src/main/java/com/persistit/LongRecordHelper.java index 3cd41d2242..1430d070ac 100644 --- a/persistit/core/src/main/java/com/persistit/LongRecordHelper.java +++ b/persistit/core/src/main/java/com/persistit/LongRecordHelper.java @@ -1,6 +1,7 @@ /** * Copyright 2012 Akiban Technologies, Inc. - * + * Portions Copyrighted 2026 3A Systems, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -57,9 +58,9 @@ class LongRecordHelper { * Value. This will replace the byte array in that value with the actual * long value. * - * @param value - * @param minimumBytesToFetch - * @throws PersistitException + * @param value the Value containing the LONG_RECORD pointer to decode + * @param minimumBytesToFetch the minimum number of bytes to fetch + * @throws PersistitException if a persistence error occurs */ void fetchLongRecord(final Value value, final int minimumBytesToFetch, final long timeout) throws PersistitException { @@ -155,7 +156,7 @@ void fetchLongRecord(final Value value, final int minimumBytesToFetch, final lon * indicates whether this operation is within the context of a * transaction. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ long storeLongRecord(final Value value, final boolean inTxn) throws PersistitException { value.changeLongRecordMode(true); diff --git a/persistit/core/src/main/java/com/persistit/Management.java b/persistit/core/src/main/java/com/persistit/Management.java index 3ad7f4f755..57ed036081 100644 --- a/persistit/core/src/main/java/com/persistit/Management.java +++ b/persistit/core/src/main/java/com/persistit/Management.java @@ -70,7 +70,7 @@ public interface Management extends Remote, ManagementMXBean { * * @param fast * true to copy pages at maximum speed. - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ public void setJournalCopyingFast(boolean fast) throws RemoteException; @@ -79,7 +79,7 @@ public interface Management extends Remote, ManagementMXBean { * * @return true if the attempt to close Persistit was * successful; otherwise false - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ public boolean close() throws RemoteException; @@ -172,7 +172,7 @@ public interface Management extends Remote, ManagementMXBean { * * @return Array of LogicalRecord objects * - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ public LogicalRecord[] getLogicalRecordArray(String volumeName, String treeName, String keyFilterString, KeyState fromKey, Key.Direction direction, int maxRecordCount, int maxValueBytes, boolean decodeStrings) @@ -183,7 +183,7 @@ public LogicalRecord[] getLogicalRecordArray(String volumeName, String treeName, * the Journal. * * @return the JournalInfo - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ public JournalInfo getJournalInfo() throws RemoteException; @@ -192,7 +192,7 @@ public LogicalRecord[] getLogicalRecordArray(String volumeName, String treeName, * the recovery process. * * @return the JournalInfo - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ public RecoveryInfo getRecoveryInfo() throws RemoteException; @@ -201,7 +201,7 @@ public LogicalRecord[] getLogicalRecordArray(String volumeName, String treeName, * and rollback information. * * @return the TransactionInfo - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ public TransactionInfo getTransactionInfo() throws RemoteException; @@ -247,7 +247,7 @@ public LogicalRecord[] getLogicalRecordArray(String volumeName, String treeName, * @return The traversed count, and a value of the key associated with the * last record traversed. * - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ public LogicalRecordCount getLogicalRecordCount(String volumeName, String treeName, String keyFilterString, @@ -361,7 +361,7 @@ public BufferInfo[] getBufferInfoArray(int bufferSize, int traversalType, String * having depth d. * @return a BufferInfo object reflecting the selected page, or * null if the specified tree does not exist. - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ public BufferInfo getBufferInfo(String volumeName, String treeName, KeyState key, int level) throws RemoteException; @@ -462,7 +462,7 @@ public int populateBufferInfoArray(BufferInfo[] results, int bufferSize, int tra * Fully qualified class name. * @return The Class, or null if an exception * occurred while attempting to acquire the Class. - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ public Class getRemoteClass(String className) throws RemoteException; @@ -472,8 +472,8 @@ public int populateBufferInfoArray(BufferInfo[] results, int bufferSize, int tra * is no unique volume corresponding with the supplied name, then this * method returns null. * - * @param volumeName - * + * @param volumeName The name (or unique partial name) of the volume + * * @return the VolumeInfo */ public VolumeInfo getVolumeInfo(String volumeName) throws RemoteException; @@ -514,12 +514,12 @@ public int populateBufferInfoArray(BufferInfo[] results, int bufferSize, int tra * character in the supplied String, or -1 if the string is a valid String * representation of a KeyFilter. * - * @param keyFilterString - * + * @param keyFilterString The String representation of a KeyFilter to validate + * * @return index of first invalid character in the supplied * keyFilterString, or -1 if the string is valid. * - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ public int parseKeyFilterString(String keyFilterString) throws RemoteException; @@ -548,7 +548,7 @@ public int populateBufferInfoArray(BufferInfo[] results, int bufferSize, int tra * used in decoding the value. May be null. * * @return Array of zero or more decoded objects - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ public Object[] decodeValueObjects(ValueState valueState, CoderContext context) throws RemoteException; @@ -565,7 +565,7 @@ public int populateBufferInfoArray(BufferInfo[] results, int bufferSize, int tra * * @return Array of decoded key segments * - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ public Object[] decodeKeyObjects(KeyState keyState, CoderContext context) throws RemoteException; @@ -590,7 +590,7 @@ public int populateBufferInfoArray(BufferInfo[] results, int bufferSize, int tra * Verbosity level, one of {@link Task#LOG_NORMAL} or * {@link Task#LOG_VERBOSE}. * @return Task identifier Unique ID for the running task - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ public long startTask(String description, String owner, String commandLine, long maximumTime, int verbosity) throws RemoteException; @@ -603,7 +603,7 @@ public long startTask(String description, String owner, String commandLine, long * @param description * description identifying what the task is doing * @return the taskId as a String, or other status information - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ public String launch(final Task task, final String description) throws RemoteException; @@ -625,7 +625,7 @@ public long startTask(String description, String owner, String commandLine, long * * @return Array of TaskStatus objects indicating status of * selected task(s). - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ public TaskStatus[] queryTaskStatus(long taskId, boolean details, boolean clearMessages) throws RemoteException; @@ -648,7 +648,7 @@ public long startTask(String description, String owner, String commandLine, long * status * @return Array of TaskStatus objects indicating status of * selected task(s). - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ public TaskStatus[] queryTaskStatus(long taskId, boolean details, boolean clearMessages, boolean clearTasks) throws RemoteException; @@ -662,7 +662,7 @@ public TaskStatus[] queryTaskStatus(long taskId, boolean details, boolean clearM * @param suspend * true to suspend the task, false to * allow it to resume. - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ public void setTaskSuspended(long taskId, boolean suspend) throws RemoteException; @@ -676,7 +676,7 @@ public TaskStatus[] queryTaskStatus(long taskId, boolean details, boolean clearM * * @param taskId * Task ID for a selected Task, or -1 for all Tasks. - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ public void stopTask(long taskId, boolean remove) throws RemoteException; @@ -687,7 +687,7 @@ public TaskStatus[] queryTaskStatus(long taskId, boolean details, boolean clearM * @param taskId * Task ID for a selected task, or -1 for all tasks. * - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ public void removeFinishedTasks(long taskId) throws RemoteException; diff --git a/persistit/core/src/main/java/com/persistit/ManagementImpl.java b/persistit/core/src/main/java/com/persistit/ManagementImpl.java index 3140c0243b..206c669476 100644 --- a/persistit/core/src/main/java/com/persistit/ManagementImpl.java +++ b/persistit/core/src/main/java/com/persistit/ManagementImpl.java @@ -218,7 +218,7 @@ public boolean isUpdateSuspended() { * enabled, Persistit will delay each Thread that attempts to perform an * update operation indefinitely. * - * @param suspended + * @param suspended true to suspend all update operations; otherwise false */ @Override public void setUpdateSuspended(final boolean suspended) { @@ -263,7 +263,7 @@ public void setAppendOnly(final boolean suspended) { * * @param fast * true to copy pages at maximum speed. - * @throws RemoteException + * @throws RemoteException if a remote error occurs */ @Override public void setJournalCopyingFast(final boolean fast) throws RemoteException { @@ -295,7 +295,7 @@ public void setDefaultCommitPolicy(final String policyName) { * * @return true if the attempt to close Persistit was * successful; otherwise false - * @throws RemoteException + * @throws RemoteException if a remote error occurs */ @Override public boolean close() throws RemoteException { @@ -311,7 +311,7 @@ public boolean close() throws RemoteException { * Attempts to flush and force all dirty data in Persistit by invoking * {@link Persistit#flush} and {@link Persistit#force}. * - * @throws RemoteException + * @throws RemoteException if a remote error occurs */ @Override public void flushAndForce() throws RemoteException { @@ -491,10 +491,10 @@ public LogicalRecordCount getLogicalRecordCount(final String volumeName, final S * causes the attempt to retrieve records to fail, then this method returns * an empty array. * - * @param volumeName - * - * @param pageAddress - * + * @param volumeName the name of the volume + * + * @param pageAddress the page address within the volume + * * @return the array */ @Override @@ -646,7 +646,7 @@ public BufferInfo getBufferInfo(final String volumeName, final long pageAddress) * having depth d. * @return a BufferInfo object reflecting the selected page, or * null if the specified tree does not exist. - * @throws RemoteException + * @throws RemoteException if a remote error occurs */ @Override public BufferInfo getBufferInfo(final String volumeName, final String treeName, final KeyState key, final int level) @@ -809,8 +809,8 @@ public VolumeInfo[] getVolumeInfoArray() { * is no unique volume corresponding with the supplied name, then this * method returns null. * - * @param volumeName - * + * @param volumeName the name of the volume + * * @return the VolumeInfo */ @Override @@ -911,7 +911,7 @@ public TreeInfo getTreeInfo(final String volumeName, final String treeName) thro * Fully qualified class name. * @return The Class, or null if an exception * occurred while attempting to acquire the Class. - * @throws RemoteException + * @throws RemoteException if a remote error occurs */ @Override public Class getRemoteClass(final String className) throws RemoteException { @@ -961,7 +961,7 @@ public int parseKeyFilterString(final String keyFilterString) throws RemoteExcep * * @return Array of zero or more Objects encoded * in the ValueState - * @throws RemoteException + * @throws RemoteException if a remote error occurs */ @Override public Object[] decodeValueObjects(final ValueState valueState, final CoderContext context) throws RemoteException { @@ -992,10 +992,12 @@ public Object[] decodeValueObjects(final ValueState valueState, final CoderConte * Representation of an encoded {@link Key}. * * @param context - * - * @return - * - * @throws RemoteException + * Object passed to any {@link ValueCoder} used in decoding the + * key segments. May be null + * + * @return Array of Objects, one per key segment + * + * @throws RemoteException if a remote error occurs */ @Override public Object[] decodeKeyObjects(final KeyState keyState, final CoderContext context) throws RemoteException { @@ -1031,7 +1033,7 @@ public Object[] decodeKeyObjects(final KeyState keyState, final CoderContext con * Verbosity level, one of {@link Task#LOG_NORMAL} or * {@link Task#LOG_NORMAL}. * @return Task identifier Unique ID for the running task - * @throws RemoteException + * @throws RemoteException if a remote error occurs */ @Override public synchronized long startTask(final String description, final String owner, final String commandLine, diff --git a/persistit/core/src/main/java/com/persistit/MediatedFileChannel.java b/persistit/core/src/main/java/com/persistit/MediatedFileChannel.java index 555184b83b..54892aa325 100644 --- a/persistit/core/src/main/java/com/persistit/MediatedFileChannel.java +++ b/persistit/core/src/main/java/com/persistit/MediatedFileChannel.java @@ -12,6 +12,7 @@ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. + * Portions Copyrighted 2026 3A Systems, LLC */ package com.persistit; @@ -136,7 +137,7 @@ private void handleClosedChannelException(final ClosedChannelException cce) thro * checks the status of the existing channel because multiple threads might * receive AsynchronousCloseException * - * @throws IOException + * @throws IOException if an I/O error occurs */ private synchronized void openChannel() throws IOException { if (isOpen() && (_channel == null || !_channel.isOpen())) { @@ -341,7 +342,7 @@ public long write(final ByteBuffer[] arg0, final int arg1, final int arg2) throw * provided as an argument must implement TestChannelInjector so that this * method can hook it up properly. * - * @param channel + * @param channel the replacement FileChannel to delegate to */ void injectChannelForTests(final FileChannel channel) { ((TestChannelInjector) channel).setChannel(_channel); diff --git a/persistit/core/src/main/java/com/persistit/Persistit.java b/persistit/core/src/main/java/com/persistit/Persistit.java index bbea6343b6..8c4c9841d5 100644 --- a/persistit/core/src/main/java/com/persistit/Persistit.java +++ b/persistit/core/src/main/java/com/persistit/Persistit.java @@ -349,7 +349,7 @@ public Persistit(final Properties properties) throws PersistitException { * control the creation of a functional Persistit within the * {@link #initialize()} method. The configuration may only be set once. * - * @param configuration + * @param configuration the Configuration to apply to this instance * @throws IllegalStateException * if the Configuration has already been set */ @@ -418,7 +418,7 @@ public void setProperties(final Properties properties) { * pending updates are written before the JVM exit. *

* - * @throws PersistitException + * @throws PersistitException if a persistence error prevents initialization */ public synchronized void initialize() throws PersistitException { if (isInitialized()) { @@ -493,7 +493,7 @@ public synchronized void initialize() throws PersistitException { * * @param propertiesFileName * The path to the properties file. - * @throws PersistitException + * @throws PersistitException if a persistence error prevents initialization */ @Deprecated public void initialize(final String propertiesFileName) throws PersistitException { @@ -531,7 +531,7 @@ public void initialize(final String propertiesFileName) throws PersistitExceptio * @param properties * The Properties instance from which to build the * configuration - * @throws PersistitException + * @throws PersistitException if a persistence error prevents initialization */ @Deprecated public void initialize(final Properties properties) throws PersistitException { @@ -567,7 +567,7 @@ public void initialize(final Properties properties) throws PersistitException { * @param configuration * The Configuration from which to initialize * Persistit - * @throws PersistitException + * @throws PersistitException if a persistence error prevents initialization */ @Deprecated public void initialize(final Configuration configuration) throws PersistitException { @@ -844,7 +844,7 @@ void removeVolume(final Volume volume) throws PersistitInterruptedException { * true to create a new Tree if one by the specified * name does not already exist. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs while acquiring the Exchange */ public Exchange getExchange(final Volume volume, final String treeName, final boolean create) throws PersistitException { @@ -906,7 +906,7 @@ public Exchange getExchange(final Volume volume, final String treeName, final bo * true to create a new Tree if one by the specified * name does not already exist. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs while acquiring the Exchange */ public Exchange getExchange(final String volumeName, final String treeName, final boolean create) throws PersistitException { @@ -936,7 +936,7 @@ public Exchange getExchange(final String volumeName, final String treeName, fina * The Exchange to release to the pool. If * null , this method returns silently. * - * @throws IllegalStateException + * @throws IllegalStateException if the Exchange is already in the pool */ public void releaseExchange(final Exchange exchange) { releaseExchange(exchange, false); @@ -968,7 +968,7 @@ public void releaseExchange(final Exchange exchange) { * true to clear all state information; * false to leave the state unchanged. * - * @throws IllegalStateException + * @throws IllegalStateException if the Exchange is already in the pool */ public void releaseExchange(final Exchange exchange, final boolean secure) { if (exchange == null) { @@ -1008,9 +1008,9 @@ public List getVolumes() { * has a Volume-only selector (no tree pattern was specified), then this * method adds the Volume's directory Tree to the list. * - * @param selector + * @param selector the TreeSelector that determines which Trees are selected * @return the List - * @throws PersistitException + * @throws PersistitException if a persistence error occurs while enumerating Trees */ public List getSelectedTrees(final TreeSelector selector) throws PersistitException { final List list = new ArrayList(); @@ -1045,7 +1045,7 @@ public List getSelectedTrees(final TreeSelector selector) throws Persistit * * @return The Volume * - * @throws PersistitException + * @throws PersistitException if the volume cannot be opened or created */ public Volume loadVolume(final String vstring) throws PersistitException { final VolumeSpecification volumeSpec = _configuration.volumeSpecification(vstring); @@ -1064,7 +1064,7 @@ public Volume loadVolume(final String vstring) throws PersistitException { * * @return The Volume * - * @throws PersistitException + * @throws PersistitException if the volume cannot be opened or created */ public Volume loadVolume(final VolumeSpecification volumeSpec) throws PersistitException { Volume volume = getVolume(volumeSpec.getName()); @@ -1089,7 +1089,7 @@ public Volume loadVolume(final VolumeSpecification volumeSpec) throws PersistitE * unspecified, the system temporary directory.. * * @return the temporary Volume. - * @throws PersistitException + * @throws PersistitException if the temporary volume cannot be created */ public Volume createTemporaryVolume() throws PersistitException { return createTemporaryVolume(temporaryVolumePageSize()); @@ -1109,7 +1109,7 @@ public Volume createTemporaryVolume() throws PersistitException { * 8192 or 16384, and the volume will be usable only if there are * buffers of the specified size in the {@link BufferPool}. * @return the temporary Volume. - * @throws PersistitException + * @throws PersistitException if the temporary volume cannot be created */ public Volume createTemporaryVolume(final int pageSize) throws PersistitException { if (!Volume.isValidPageSize(pageSize)) { @@ -1140,7 +1140,7 @@ private int temporaryVolumePageSize() { * the Volume to delete * @return true if the volume was previously loaded and has * been successfully deleted. - * @throws PersistitException + * @throws PersistitException if the volume cannot be closed or deleted */ public boolean deleteVolume(final String volumeName) throws PersistitException { @@ -1305,7 +1305,7 @@ public Volume getSystemVolume() throws VolumeNotFoundException { /** * @return reserved temporary volume for locks - * @throws PersistitException + * @throws PersistitException if the lock volume cannot be created */ public synchronized Volume getLockVolume() throws PersistitException { checkInitialized(); @@ -1413,7 +1413,7 @@ public Checkpoint getCurrentCheckpoint() { * closed or not yet initialized, do nothing and return null. * * @return the Checkpoint allocated by this process. - * @throws PersistitInterruptedException + * @throws PersistitInterruptedException if the thread is interrupted while waiting for the checkpoint to be written */ public Checkpoint checkpoint() throws PersistitException { if (_closed.get() || !_initialized.get()) { @@ -1443,7 +1443,7 @@ final long earliestDirtyTimestamp() { * condenses the total number of journals as much as possible given the * current activity in the system. * - * @throws Exception + * @throws Exception if an error occurs while copying pages back to their volumes */ public void copyBackPages() throws Exception { /* @@ -1531,7 +1531,7 @@ void cleanup() { * Reports status of the max longest-running transactions, in * order from oldest to youngest. * - * @param max + * @param max the maximum number of transactions to report * @return status of the max longest-running transactions, in * order from oldest to youngest, reported as a String with one line * per transaction. @@ -1566,7 +1566,7 @@ public String transactionReport(final int max) { * Close the Persistit Journal and all {@link Volume}s. This method is * equivalent to {@link #close(boolean) close(true)}. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs while closing */ public void close() throws PersistitException { close(true); @@ -1624,7 +1624,7 @@ public void close() throws PersistitException { * disk before shutdown completes; false to enable * fast (but incomplete) shutdown. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs while closing */ public void close(final boolean flush) throws PersistitException { if (_initialized.get() && !_closed.get()) { @@ -1865,7 +1865,7 @@ private void releaseAllResources() { * written. * * @return true if any file writes were performed, else false. - * @throws PersistitException + * @throws PersistitException if a persistence error occurs while flushing */ public boolean flush() throws PersistitException { if (_closed.get() || !_initialized.get()) { @@ -1973,7 +1973,7 @@ void checkFatal() throws FatalErrorException { * {@link #setUpdateSuspended} method controls whether update operations are * currently suspended. * - * @throws PersistitInterruptedException + * @throws PersistitInterruptedException if the thread is interrupted while waiting */ public void checkSuspended() throws PersistitInterruptedException { while (isUpdateSuspended()) { @@ -1998,7 +1998,7 @@ public SessionId getSessionId() { * extreme care to avoid having two threads with the same SessionId at any * time. * - * @param sessionId + * @param sessionId the SessionId to bind to the current thread */ public void setSessionId(final SessionId sessionId) { sessionId.assign(); @@ -2008,7 +2008,7 @@ public void setSessionId(final SessionId sessionId) { /** * Close the session resources associated with the current thread. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs while closing the session */ void closeSession() throws PersistitException { final SessionId sessionId = _sessionIdThreadLocal.get(); @@ -2153,7 +2153,7 @@ public Object getPersistitGuiContainer() { * instances of {@link com.persistit.encoding.ValueCoder} and * {@link com.persistit.encoding.KeyCoder}. * - * @param coderManager + * @param coderManager the CoderManager to install */ public void setCoderManager(final CoderManager coderManager) { _coderManager.set(coderManager); @@ -2284,7 +2284,7 @@ void pollAlertMonitors(final boolean force) { * Volumes and reports detailed results to * {@link java.lang.System#out}. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs during the integrity check */ public void checkAllVolumes() throws PersistitException { final IntegrityCheck icheck = new IntegrityCheck(this); @@ -2319,9 +2319,9 @@ static long availableHeap() { * If true, sets the shutdown suspend flag. Setting * this flag suspends the {@link #close} method to permit * continued use of the diagnostic GUI. - * @throws ClassNotFoundException - * @throws IllegalAccessException - * @throws InstantiationException + * @throws ClassNotFoundException if the diagnostic GUI class cannot be found + * @throws IllegalAccessException if the diagnostic GUI class cannot be accessed + * @throws InstantiationException if the diagnostic GUI class cannot be instantiated */ public void setupGUI(final boolean suspendShutdown) throws IllegalAccessException, InstantiationException, ClassNotFoundException, RemoteException { @@ -2574,8 +2574,8 @@ long unique() { * * * - * @param args - * @throws Exception + * @param args the command-line arguments + * @throws Exception if an error occurs while performing the requested operation */ public static void main(final String[] args) throws Exception { final ArgParser ap = new ArgParser("Persistit", args, ARG_TEMPLATE).strict(); diff --git a/persistit/core/src/main/java/com/persistit/PersistitMap.java b/persistit/core/src/main/java/com/persistit/PersistitMap.java index 038bc43654..07339b1c1e 100644 --- a/persistit/core/src/main/java/com/persistit/PersistitMap.java +++ b/persistit/core/src/main/java/com/persistit/PersistitMap.java @@ -192,12 +192,12 @@ public PersistitMap(final Exchange ex) { * Construct a PersistitMap over the range of keys from fromKey (inclusive) * to toKey (exclusive) * - * @param pm - * @param useFrom - * @param fromKey - * @param useTo - * @param toKey - * + * @param pm the base PersistitMap over which this submap is created + * @param useFrom true if fromKey bounds the start of the range + * @param fromKey the inclusive lower bound of the key range + * @param useTo true if toKey bounds the end of the range + * @param toKey the exclusive upper bound of the key range + * * @throws IllegalArgumentException * if fromKey is after toKey or if either fromKey or toKey is * outside the range of the supplied base PersistitMap diff --git a/persistit/core/src/main/java/com/persistit/RecoveryManager.java b/persistit/core/src/main/java/com/persistit/RecoveryManager.java index 57082c19d5..52c71e8e00 100644 --- a/persistit/core/src/main/java/com/persistit/RecoveryManager.java +++ b/persistit/core/src/main/java/com/persistit/RecoveryManager.java @@ -594,8 +594,8 @@ File addressToFile(final long address) { * checkpoint to branchMap. Updates in branchMap * are used only in recovering certain transactions (insertions with * LONG_RECORD values). - * - * @param pageMap + * + * @param pageMap the map that receives PageNodes for updates that occurred before the keystone checkpoint */ void collectRecoveredPages(final Map pageMap, final Map branchMap) { if (_lastValidCheckpoint != null) { @@ -917,9 +917,9 @@ private void read(final long address, final int size) throws PersistitIOExceptio * @return The record type: one of the type values specified in * {@link com.persistit.JournalRecord}), 0 if the journal file has * fewer than 16 bytes remaining or -t where t is an invalid type. - * @throws CorruptJournalException - * @throws PersistitIOException - * @throws JournalNotClosedException + * @throws CorruptJournalException if the journal is corrupt + * @throws PersistitIOException if an I/O error occurs + * @throws JournalNotClosedException if the journal was not cleanly closed */ private int scanOneRecord() throws PersistitIOException { @@ -993,10 +993,10 @@ private int scanOneRecord() throws PersistitIOException { * Process an IV (identify volume) record in the journal. Adds a handle -> * volume descriptor pair to the handle maps. * - * @param address - * @param timestamp - * @param recordSize - * @throws PersistitIOException + * @param address the journal address of the record + * @param timestamp the timestamp of the record + * @param recordSize the length of the record in bytes + * @throws PersistitIOException if an I/O error occurs */ void scanIdentifyVolume(final long address, final long timestamp, final int recordSize) throws PersistitIOException { if (recordSize > IV.MAX_LENGTH) { @@ -1023,10 +1023,10 @@ void scanIdentifyVolume(final long address, final long timestamp, final int reco * Processes an IT (identify tree) record in the journal. Adds a handle -> * TreeDescriptor entry in the handle maps. * - * @param address - * @param timestamp - * @param recordSize - * @throws PersistitIOException + * @param address the journal address of the record + * @param timestamp the timestamp of the record + * @param recordSize the length of the record in bytes + * @throws PersistitIOException if an I/O error occurs */ void scanIdentifyTree(final long address, final long timestamp, final int recordSize) throws PersistitIOException { if (recordSize > IT.MAX_LENGTH) { @@ -1059,10 +1059,10 @@ void scanIdentifyTree(final long address, final long timestamp, final int record /** * Process a PA (page) record in the journal. Adds an entry to the Page Map. * - * @param address - * @param timestamp - * @param recordSize - * @throws PersistitIOException + * @param address the journal address of the record + * @param timestamp the timestamp of the record + * @param recordSize the length of the record in bytes + * @throws PersistitIOException if an I/O error occurs */ void scanLoadPage(final long address, final long timestamp, final int recordSize) throws PersistitIOException { if (recordSize > Buffer.MAX_BUFFER_SIZE + PA.OVERHEAD) { @@ -1304,8 +1304,8 @@ void scanCheckpoint(final long address, final long timestamp, final int recordSi * records are read; these files are needed only to complete committed * transactions and to supply pages from the page map. * - * @param generation - * @throws PersistitIOException + * @param generation the journal file generation to validate + * @throws PersistitIOException if an I/O error occurs */ private void validateMemberFile(final long generation) throws PersistitIOException { final File file = JournalManager.generationToFile(_journalFilePath, generation); @@ -1434,8 +1434,8 @@ public void buildRecoveryPlan() throws PersistitIOException, PersistitInterrupte /** * Called during Phase 2 to record the FileAddress of a Transaction Update * record in the journal. - * - * @throws CorruptJournalException + * + * @throws CorruptJournalException if the journal is corrupt */ void scanOneTransaction(final long address, final long startTimestamp, final int recordSize) throws PersistitIOException { @@ -1567,7 +1567,7 @@ public void applyAllRecoveredTransactions(final TransactionPlayerListener commit * displaying error messages * @param timestamp * timestamp of the transaction - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ void convertToLongRecord(final Value value, final int treeHandle, final long from, final long timestamp) throws PersistitException { @@ -1736,9 +1736,9 @@ boolean analyze() throws Exception { /** * Read and display information about a journal. Read-only - does not change * any file. - * - * @param args - * @throws Exception + * + * @param args the command-line arguments + * @throws Exception if an error occurs */ public static void main(final String[] args) throws Exception { final String[] template = { diff --git a/persistit/core/src/main/java/com/persistit/SharedResource.java b/persistit/core/src/main/java/com/persistit/SharedResource.java index b235d7b891..3daa53f080 100644 --- a/persistit/core/src/main/java/com/persistit/SharedResource.java +++ b/persistit/core/src/main/java/com/persistit/SharedResource.java @@ -150,7 +150,7 @@ protected int tryAcquireShared(final int arg) { * * TODO - prove that caller already a reader claim * - * @return + * @return true if the claim was upgraded to exclusive */ private boolean tryUpgrade() { for (;;) { @@ -412,7 +412,7 @@ Persistit getPersistit() { * Sets bits in the state. This method does not change the bits used by the * synchronizer to maintain lock state. * - * @param resource + * @param resource the resource whose status bits are copied into this resource's state */ void setStatus(final SharedResource resource) { final int mask = resource.getStatus(); diff --git a/persistit/core/src/main/java/com/persistit/StreamSaver.java b/persistit/core/src/main/java/com/persistit/StreamSaver.java index 5d2b3a77fe..d086700b89 100644 --- a/persistit/core/src/main/java/com/persistit/StreamSaver.java +++ b/persistit/core/src/main/java/com/persistit/StreamSaver.java @@ -150,7 +150,7 @@ public StreamSaver(final Persistit persistit, final DataOutputStream dos) { * * @param file * The File to which data will be saved - * @throws FileNotFoundException + * @throws FileNotFoundException if the file cannot be opened */ public StreamSaver(final Persistit persistit, final File file) throws FileNotFoundException { this(persistit, new DataOutputStream(new BufferedOutputStream(new FileOutputStream(file), DEFAULT_BUFFER_SIZE))); @@ -174,7 +174,7 @@ static StreamSaver createTask(@Arg("file|string:|Save to file") final String fil * * @param pathName * The path name of the file to which data will be saved - * @throws FileNotFoundException + * @throws FileNotFoundException if the file cannot be opened */ public StreamSaver(final Persistit persistit, final String pathName) throws FileNotFoundException { this(persistit, new DataOutputStream(new BufferedOutputStream(new FileOutputStream(pathName), @@ -189,7 +189,7 @@ public StreamSaver(final Persistit persistit, final String pathName) throws File * The File to which data will be saved * @param bufferSize * The buffer size - * @throws FileNotFoundException + * @throws FileNotFoundException if the file cannot be opened */ public StreamSaver(final Persistit persistit, final File file, final int bufferSize) throws FileNotFoundException { this(persistit, new DataOutputStream(new BufferedOutputStream(new FileOutputStream(file), bufferSize))); @@ -203,7 +203,7 @@ public StreamSaver(final Persistit persistit, final File file, final int bufferS * The path name of the file to which data will be saved * @param bufferSize * The buffer size - * @throws FileNotFoundException + * @throws FileNotFoundException if the file cannot be opened */ public StreamSaver(final Persistit persistit, final String pathName, final int bufferSize) throws FileNotFoundException { @@ -240,7 +240,7 @@ public void setCycleCount(final int count) { * indicates that the save file represents all the records requested by the * save operation. * - * @throws IOException + * @throws IOException if an I/O error occurs */ public void close() throws IOException { writeTimestamp(); @@ -263,7 +263,7 @@ public void close() throws IOException { * * @param exchange * The Exchange - * @throws IOException + * @throws IOException if an I/O error occurs */ protected void writeData(final Exchange exchange) throws IOException { if (_lastVolume != exchange.getVolume()) { @@ -287,7 +287,7 @@ protected void writeData(final Exchange exchange) throws IOException { * The Key * @param value * The Value - * @throws IOException + * @throws IOException if an I/O error occurs */ protected void writeData(final Key key, final Value value) throws IOException { final int elisionCount = key.firstUniqueByteIndex(_lastKey); @@ -314,7 +314,7 @@ protected void writeData(final Key key, final Value value) throws IOException { * preceded by three FILL records to allow for easier inspection of the save * file. * - * @throws IOException + * @throws IOException if an I/O error occurs */ protected void writeRecordCount(final long dataRecordCount, final long otherRecordCount) throws IOException { _dos.writeChar(RECORD_TYPE_FILL); @@ -335,7 +335,7 @@ protected void writeRecordCount(final long dataRecordCount, final long otherReco * * @param exchange * The Exchange - * @throws IOException + * @throws IOException if an I/O error occurs */ protected void writeVolumeInfo(final Exchange exchange) throws IOException { writeVolumeInfo(exchange.getVolume()); @@ -348,8 +348,8 @@ protected void writeVolumeInfo(final Exchange exchange) throws IOException { * recreate a new, empty Tree having the same name as the * Tree being saved. * - * @param exchange - * @throws IOException + * @param exchange The Exchange + * @throws IOException if an I/O error occurs */ protected void writeTreeInfo(final Exchange exchange) throws IOException { writeTreeInfo(exchange.getTree()); @@ -364,7 +364,7 @@ protected void writeTreeInfo(final Exchange exchange) throws IOException { * * @param volume * The Volume - * @throws IOException + * @throws IOException if an I/O error occurs */ protected void writeVolumeInfo(final Volume volume) throws IOException { _dos.writeChar(RECORD_TYPE_VOLUME_ID); @@ -387,7 +387,7 @@ protected void writeVolumeInfo(final Volume volume) throws IOException { * * @param tree * The Tree - * @throws IOException + * @throws IOException if an I/O error occurs */ protected void writeTreeInfo(final Tree tree) throws IOException { _dos.writeChar(RECORD_TYPE_TREE_ID); @@ -399,7 +399,7 @@ protected void writeTreeInfo(final Tree tree) throws IOException { /** * Writes a TIMESTAMP record containing the current system time. * - * @throws IOException + * @throws IOException if an I/O error occurs */ protected void writeTimestamp() throws IOException { _dos.writeChar(RECORD_TYPE_TIMESTAMP); @@ -411,7 +411,7 @@ protected void writeTimestamp() throws IOException { * * @param comment * The comment string - * @throws IOException + * @throws IOException if an I/O error occurs */ protected void writeComment(final String comment) throws IOException { _dos.writeChar(RECORD_TYPE_COMMENT); @@ -424,7 +424,7 @@ protected void writeComment(final String comment) throws IOException { * * @param exception * The Exception - * @throws IOException + * @throws IOException if an I/O error occurs */ protected void writeException(final Exception exception) throws IOException { _dos.writeChar(RECORD_TYPE_EXCEPTION); @@ -441,8 +441,8 @@ protected void writeException(final Exception exception) throws IOException { * The Exchange * @param filter * The KeyFilter - * @throws PersistitException - * @throws IOException + * @throws PersistitException if a persistence error occurs + * @throws IOException if an I/O error occurs */ public void save(final Exchange exchange, final KeyFilter filter) throws PersistitException, IOException { postMessage("Saving Tree " + exchange.getTree().getName() + " in volume " + exchange.getVolume().getPath() @@ -474,8 +474,8 @@ public void save(final Exchange exchange, final KeyFilter filter) throws Persist * The volume name, or a substring that matches only one volume. * @param selectedTreeNames * An array names of the trees to be saved. - * @throws PersistitException - * @throws IOException + * @throws PersistitException if a persistence error occurs + * @throws IOException if an I/O error occurs */ public void saveTrees(final String volumeName, final String[] selectedTreeNames) throws PersistitException, IOException { @@ -491,8 +491,8 @@ public void saveTrees(final String volumeName, final String[] selectedTreeNames) * The Volume * @param selectedTreeNames * An array names of the trees to be saved. - * @throws PersistitException - * @throws IOException + * @throws PersistitException if a persistence error occurs + * @throws IOException if an I/O error occurs */ public void saveTrees(final Volume volume, final String[] selectedTreeNames) throws PersistitException, IOException { final String[] treeNames = volume.getTreeNames(); @@ -527,8 +527,8 @@ public void saveTrees(final Volume volume, final String[] selectedTreeNames) thr * @param treeSelector * The TreeSelectors to select volumes, trees, and * KeyFilters within trees. - * @throws PersistitException - * @throws IOException + * @throws PersistitException if a persistence error occurs + * @throws IOException if an I/O error occurs */ public void saveTrees(final TreeSelector treeSelector) throws PersistitException, IOException { final List trees = _persistit.getSelectedTrees(treeSelector); @@ -561,8 +561,8 @@ public void saveTrees(final TreeSelector treeSelector) throws PersistitException /** * Save all trees in all open volumes. * - * @throws PersistitException - * @throws IOException + * @throws PersistitException if a persistence error occurs + * @throws IOException if an I/O error occurs */ public void saveAll() throws PersistitException, IOException { diff --git a/persistit/core/src/main/java/com/persistit/Task.java b/persistit/core/src/main/java/com/persistit/Task.java index e5f39ff895..88d0ead8d9 100644 --- a/persistit/core/src/main/java/com/persistit/Task.java +++ b/persistit/core/src/main/java/com/persistit/Task.java @@ -1,6 +1,7 @@ /** * Copyright 2005-2012 Akiban Technologies, Inc. - * + * Portions Copyrighted 2026 3A Systems, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -179,8 +180,9 @@ protected Task(final Persistit persistit) { /** * Set the Persistit instance to be accessed by this Task. - * + * * @param persistit + * the Persistit instance to be accessed by this Task */ public void setPersistit(final Persistit persistit) { _persistit = persistit; @@ -188,8 +190,9 @@ public void setPersistit(final Persistit persistit) { /** * Called by a newly created Thread to perform the task. - * + * * @throws Exception + * if the task encounters an error while running */ protected abstract void runTask() throws Exception; @@ -299,6 +302,7 @@ protected long now() { * Level at which messages posted by the running task will be * retained in the message log. * @throws Exception + * if the task cannot be set up */ public void setup(final long taskId, final String description, final String owner, final long maxTime, final int verbosity) throws Exception { diff --git a/persistit/core/src/main/java/com/persistit/TimelyResource.java b/persistit/core/src/main/java/com/persistit/TimelyResource.java index fb8f68151f..9adf8e8697 100644 --- a/persistit/core/src/main/java/com/persistit/TimelyResource.java +++ b/persistit/core/src/main/java/com/persistit/TimelyResource.java @@ -163,8 +163,8 @@ public boolean isEmpty() throws TimeoutException, PersistitInterruptedException * * @return Whether this resource exists only within the context of the * current transaction. - * @throws TimeoutException - * @throws PersistitInterruptedException + * @throws TimeoutException if a timeout occurs while resolving commit status + * @throws PersistitInterruptedException if the thread is interrupted while waiting */ public boolean isTransactionPrivate(final boolean byStep) throws TimeoutException, PersistitInterruptedException { @@ -230,8 +230,8 @@ synchronized void setPrimordial() { * that implements PrunableVersion, invoke its * {@link PrunableVersion#prune()} method. * - * @throws TimeoutException - * @throws PersistitException + * @throws TimeoutException if a timeout occurs while resolving commit status + * @throws PersistitException if a persistence error occurs */ void prune() throws TimeoutException, PersistitException { final List entriesToPrune = new ArrayList(); @@ -314,10 +314,10 @@ void prune() throws TimeoutException, PersistitException { * information. This method checks for write-write dependencies throws a * RollbackException if there is a conflict. * - * @param entry - * @param txn - * @throws PersistitInterruptedException - * @throws RollbackException + * @param entry the Entry containing the version to add + * @param txn the transaction on whose behalf the version is added + * @throws PersistitInterruptedException if the thread is interrupted while waiting + * @throws RollbackException if a write-write conflict forces the transaction to roll back */ private void addVersion(final Entry entry, final Transaction txn) throws PersistitInterruptedException, RollbackException { @@ -382,8 +382,8 @@ private void addVersion(final Entry entry, final Transaction txn) throws Persist * @param version * versionHandle * @return Version for given version handle - * @throws TimeoutException - * @throws PersistitInterruptedException + * @throws TimeoutException if a timeout occurs while resolving commit status + * @throws PersistitInterruptedException if the thread is interrupted while waiting */ V getVersion(final long version) throws TimeoutException, PersistitInterruptedException { final Entry e = getEntry(version); diff --git a/persistit/core/src/main/java/com/persistit/Transaction.java b/persistit/core/src/main/java/com/persistit/Transaction.java index c5306defb2..ad7d653341 100644 --- a/persistit/core/src/main/java/com/persistit/Transaction.java +++ b/persistit/core/src/main/java/com/persistit/Transaction.java @@ -498,6 +498,7 @@ static CommitPolicy forName(final String policyName) { * only during recovery processing. * * @param id + * the transaction identifier to assign to this context */ private Transaction(final Persistit persistit, final SessionId sessionId, final long id) { _persistit = persistit; @@ -514,6 +515,8 @@ private static synchronized long nextId() { * transaction if it was abandoned due to thread death. * * @throws PersistitException + * if a persistence error occurs while closing the transaction + * context */ void close() throws PersistitException { if (_nestedDepth > 0 && !_commitCompleted && !_rollbackCompleted) { @@ -538,6 +541,8 @@ void close() throws PersistitException { * roll-back transition pending. * * @throws RollbackException + * if this transaction context has a roll-back transition + * pending */ public void checkPendingRollback() throws RollbackException { if (_rollbackPending) { @@ -930,11 +935,14 @@ public int getNestedTransactionDepth() { *

* * @param runnable - * + * the TransactionRunnable containing logic to + * access and update Persistit data + * * @return Count of passes needed to complete the transaction. Always 1 on * successful completion. * * @throws PersistitException + * if a persistence error occurs during the transaction */ public int run(final TransactionRunnable runnable) throws PersistitException { return run(runnable, 0, 0, _persistit.getDefaultTransactionCommitPolicy()); @@ -978,6 +986,7 @@ public int run(final TransactionRunnable runnable) throws PersistitException { * @return Count of attempts needed to complete the transaction * * @throws PersistitException + * if a persistence error occurs during the transaction * @throws RollbackException * If after retryCount+1 attempts the transaction * cannot be completed or committed due to concurrent updated @@ -1050,6 +1059,7 @@ public CommitPolicy getDefaultCommitPolicy() { * Set the current default policy * * @param policy + * the default CommitPolicy to set */ public void setDefaultCommitPolicy(final CommitPolicy policy) { _defaultCommitPolicy = policy; @@ -1119,9 +1129,13 @@ public int getRolledBackSinceLastCommitCount() { * Record a store operation. * * @param exchange + * the Exchange that performed the store operation * @param key + * the Key at which the value was stored * @param value + * the Value that was stored * @throws PersistitException + * if a persistence error occurs while recording the operation */ void store(final Exchange exchange, final Key key, final Value value) throws PersistitException { if (_nestedDepth > 0) { @@ -1134,9 +1148,13 @@ void store(final Exchange exchange, final Key key, final Value value) throws Per * Record a remove operation. * * @param exchange + * the Exchange that performed the remove operation * @param key1 + * the left edge Key of the removed range * @param key2 + * the right edge Key of the removed range * @throws PersistitException + * if a persistence error occurs while recording the operation */ void remove(final Exchange exchange, final Key key1, final Key key2) throws PersistitException { if (_nestedDepth > 0) { @@ -1149,7 +1167,9 @@ void remove(final Exchange exchange, final Key key1, final Key key2) throws Pers * Record a tree delete operation * * @param exchange + * the Exchange whose tree was removed * @throws PersistitException + * if a persistence error occurs while recording the operation */ void removeTree(final Exchange exchange) throws PersistitException { if (_nestedDepth > 0) { diff --git a/persistit/core/src/main/java/com/persistit/TransactionIndex.java b/persistit/core/src/main/java/com/persistit/TransactionIndex.java index 5a3809e80e..20c23b1df2 100644 --- a/persistit/core/src/main/java/com/persistit/TransactionIndex.java +++ b/persistit/core/src/main/java/com/persistit/TransactionIndex.java @@ -522,8 +522,8 @@ long commitStatus(final long versionHandle, final long ts, final int step) throw * this one and cause inconsistent results. * * @return the TransactionStatus. - * @throws InterruptedException - * @throws TimeoutException + * @throws InterruptedException if the thread is interrupted while waiting + * @throws TimeoutException if the transaction could not be registered within the timeout period */ TransactionStatus registerTransaction() throws TimeoutException, InterruptedException { return registerTransaction(false); @@ -536,8 +536,8 @@ TransactionStatus registerTransaction() throws TimeoutException, InterruptedExce * {@link CheckpointManager#createCheckpoint()}. * * @return the TransactionStatus. - * @throws InterruptedException - * @throws TimeoutException + * @throws InterruptedException if the thread is interrupted while waiting + * @throws TimeoutException if the transaction could not be registered within the timeout period */ TransactionStatus registerCheckpointTransaction() throws TimeoutException, InterruptedException { return registerTransaction(true); @@ -921,7 +921,7 @@ boolean isDeadlocked(final TransactionStatus source) { * Atomically decrement the MVV count for the aborted * TransactionStatus identified by the suppled version handle. * - * @param versionHandle + * @param versionHandle the version handle identifying the aborted transaction * @return The resulting count * @throws IllegalArgumentException * if the supplied versionHandle does not identify @@ -939,7 +939,7 @@ long decrementMvvCount(final long versionHandle) { /** * Compute hash index for a given timestamp. * - * @param ts + * @param ts the timestamp to hash * @return the hash table index */ private int hashIndex(final long ts) { @@ -951,8 +951,8 @@ private int hashIndex(final long ts) { * bucket. This method is called during recovery processing to register * transactions that were * - * @param ts - * @throws InterruptedException + * @param ts the start timestamp of the aborted transaction + * @throws InterruptedException if the thread is interrupted while waiting */ void injectAbortedTransaction(final long ts) throws InterruptedException { final TransactionStatus status; @@ -1042,8 +1042,8 @@ int resetMVVCounts(final long timestamp) { /** * Compute and return the snapshot value of an Accumulator - * - * @throws InterruptedException + * + * @throws InterruptedException if the thread is interrupted while waiting */ long getAccumulatorSnapshot(final Accumulator accumulator, final long timestamp, final int step, final long initialValue) throws InterruptedException { @@ -1085,7 +1085,7 @@ long getAccumulatorSnapshot(final Accumulator accumulator, final long timestamp, * checkpoint timestamp * @param accumulators * List of Accumulators that need to be check-pointed - * @throws InterruptedException + * @throws InterruptedException if the thread is interrupted while waiting */ void checkpointAccumulatorSnapshots(final long timestamp, final List accumulators) throws InterruptedException { @@ -1274,8 +1274,8 @@ public int getDroppedCount() { * Return the start timestamps of the oldest max transactions * currently running. * - * @param max - * @return + * @param max the maximum number of transactions to return + * @return an array of the oldest transaction start timestamps, or null if the cache could not be read consistently */ long[] oldestTransactions(final int max) { final long[] array = new long[Math.max(max, INITIAL_ACTIVE_TRANSACTIONS_SIZE)]; diff --git a/persistit/core/src/main/java/com/persistit/TransactionIndexBucket.java b/persistit/core/src/main/java/com/persistit/TransactionIndexBucket.java index c8e2e3fa85..0dd0b5bffe 100644 --- a/persistit/core/src/main/java/com/persistit/TransactionIndexBucket.java +++ b/persistit/core/src/main/java/com/persistit/TransactionIndexBucket.java @@ -12,6 +12,7 @@ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. + * Portions Copyrighted 2026 3A Systems, LLC */ package com.persistit; @@ -542,7 +543,7 @@ private void aggregate(final TransactionStatus status, final boolean committed) * @throws RetryException * if a TransactionStatus started but had not finished * committing. - * @throws InterruptedException + * @throws InterruptedException if the thread is interrupted while waiting */ long getAccumulatorSnapshot(final Accumulator accumulator, final long timestamp, final int step) throws RetryException, InterruptedException { diff --git a/persistit/core/src/main/java/com/persistit/TransactionPlayer.java b/persistit/core/src/main/java/com/persistit/TransactionPlayer.java index 4e62e7f684..754e96e612 100644 --- a/persistit/core/src/main/java/com/persistit/TransactionPlayer.java +++ b/persistit/core/src/main/java/com/persistit/TransactionPlayer.java @@ -12,6 +12,7 @@ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. + * Portions Copyrighted 2026 3A Systems, LLC */ package com.persistit; @@ -306,14 +307,14 @@ public static String addressToString(final long address, final long timestamp) { * new tree is determined by the * {@link TransactionPlayerListener#createTree(long)} method. * - * @param treeHandle - * @param from - * @param timestamp - * @param listener + * @param treeHandle the handle identifying the tree to which the operation applies + * @param from the journal address from which the operation is read + * @param timestamp the timestamp of the recovery operation + * @param listener the listener that decides whether a missing tree should be created * @return the Exchange on which a recovery operation should be * applied, or null if there is no backing * Tree. - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ private Exchange getExchange(final int treeHandle, final long from, final long timestamp, final TransactionPlayerListener listener) throws PersistitException { diff --git a/persistit/core/src/main/java/com/persistit/TransactionRunnable.java b/persistit/core/src/main/java/com/persistit/TransactionRunnable.java index 725d318ef6..4ed8df699a 100644 --- a/persistit/core/src/main/java/com/persistit/TransactionRunnable.java +++ b/persistit/core/src/main/java/com/persistit/TransactionRunnable.java @@ -1,6 +1,7 @@ /** * Copyright 2005-2012 Akiban Technologies, Inc. - * + * Portions Copyrighted 2026 3A Systems, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -48,8 +49,8 @@ public interface TransactionRunnable { * them. *

* - * @throws PersistitException - * @throws RollbackException + * @throws PersistitException if a persistence error occurs + * @throws RollbackException if the transaction must be rolled back */ public void runTransaction() throws PersistitException, RollbackException; } diff --git a/persistit/core/src/main/java/com/persistit/TransactionStatus.java b/persistit/core/src/main/java/com/persistit/TransactionStatus.java index da883cc563..c29c353cf7 100644 --- a/persistit/core/src/main/java/com/persistit/TransactionStatus.java +++ b/persistit/core/src/main/java/com/persistit/TransactionStatus.java @@ -135,7 +135,7 @@ class TransactionStatus { /** * Constructs a partial copy. Used only in diagnostic code. * - * @param status + * @param status the TransactionStatus to copy */ TransactionStatus(final TransactionStatus status) { this._bucket = status._bucket; @@ -219,7 +219,7 @@ boolean isNotified() { * that until we implement SSI this method is unnecessary, but is included * so that unit tests can test the interim state. * - * @param timestamp + * @param timestamp the commit timestamp */ void commit(final long timestamp) { if (timestamp < _ts || timestamp == UNCOMMITTED) { @@ -333,7 +333,7 @@ void setMvvCount(final int count) { * * @param timeout * in milliseconds - * @throws InterruptedException + * @throws InterruptedException if the thread is interrupted while waiting */ void briefLock(final long timeout) throws InterruptedException { boolean locked = false; @@ -362,9 +362,9 @@ void briefLock(final long timeout) throws InterruptedException { * wwDependency until the commit/abort status of the current transaction is * known. * - * @param timeout - * @return - * @throws InterruptedException + * @param timeout the maximum time to wait, in milliseconds + * @return true if the permit was acquired within the timeout + * @throws InterruptedException if the thread is interrupted while waiting */ boolean wwLock(final long timeout) throws InterruptedException { return _wwLock.tryAcquire(timeout, TimeUnit.MILLISECONDS); diff --git a/persistit/core/src/main/java/com/persistit/Tree.java b/persistit/core/src/main/java/com/persistit/Tree.java index f1e2ff83e8..c711d0d332 100644 --- a/persistit/core/src/main/java/com/persistit/Tree.java +++ b/persistit/core/src/main/java/com/persistit/Tree.java @@ -320,8 +320,8 @@ int load(final byte[] bytes, final int index, final int length) { /** * Initialize a Tree. * - * @param rootPageAddr - * @throws PersistitException + * @param rootPageAddr the root page address to assign to the tree + * @throws PersistitException if a persistence error occurs */ void setRootPageAddress(final long rootPageAddr) throws PersistitException { final TreeVersion version = version(); @@ -412,7 +412,7 @@ public int getHandle() { * Assign and set the tree handle. The tree must may not be a member of a * temporary volume. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ void loadHandle() throws PersistitException { assert !_volume.isTemporary() : "Handle allocation for temporary tree " + this; @@ -555,7 +555,7 @@ synchronized Accumulator getAccumulator(final Accumulator.Type type, final int i * Set the handle used to identify this Tree in the journal. May be invoked * only once. * - * @param handle + * @param handle the handle value to assign * @return the handle * @throws IllegalStateException * if the handle has already been set diff --git a/persistit/core/src/main/java/com/persistit/TreeBuilder.java b/persistit/core/src/main/java/com/persistit/TreeBuilder.java index 6be1c27dff..6a6a7a011e 100644 --- a/persistit/core/src/main/java/com/persistit/TreeBuilder.java +++ b/persistit/core/src/main/java/com/persistit/TreeBuilder.java @@ -178,9 +178,10 @@ public Map initialValue() { * added to the _allTrees list - in other words, sorting should leave * the list unchanged. * - * @param a - * @param b - * @return + * @param a the first tree to compare + * @param b the second tree to compare + * @return a negative integer, zero, or a positive integer as the first + * tree precedes, is equal to, or follows the second tree */ @Override public int compare(final Tree a, final Tree b) { @@ -346,7 +347,8 @@ public final String getName() { * Set the count of keys inserted or merged per call to * {@link #reportSorted(long)} or {@link #reportMerged(long)}. * - * @param multiple + * @param multiple the number of keys to insert or merge between successive + * report callbacks */ public final void setReportKeyCountMultiple(final long multiple) { _reportKeyCountMultiple = Util.rangeCheck(multiple, 1, Long.MAX_VALUE); @@ -472,7 +474,7 @@ public final List getSortFileDirectories() { * * @param exchange * The Exchange - * @throws Exception + * @throws Exception if an error occurs while storing the key-value pair */ public final void store(final Exchange exchange) throws Exception { store(exchange.getTree(), exchange.getKey(), exchange.getValue()); @@ -488,7 +490,7 @@ public final void store(final Exchange exchange) throws Exception { * the Key * @param value * the Value - * @throws Exception + * @throws Exception if an error occurs while storing the key-value pair */ public final void store(final Tree tree, final Key key, final Value value) throws Exception { final Map map = _sortExchangeMapThreadLocal.get(); @@ -547,8 +549,8 @@ private void insertNode(final Map sorted, final Node node) throws Ex /** * Merge the record previously stored in sort volumes into their destination * Trees. - * - * @throws Exception + * + * @throws Exception if an error occurs during the merge */ public synchronized void merge() throws Exception { finishSortVolume(); @@ -715,7 +717,7 @@ private void saveSortVolume(final Volume volume, final File file) throws Excepti * The temporary Volume that has been filled * @param file * the file to which the sorted key-value pairs will be written - * @throws Exception + * @throws Exception if the overriding implementation fails */ protected void beforeSortVolumeClosed(final Volume volume, final File file) throws Exception { @@ -733,7 +735,7 @@ protected void beforeSortVolumeClosed(final Volume volume, final File file) thro * The temporary Volume that has been filled * @param file * the file to which the sorted key-value pairs have been written - * @throws Exception + * @throws Exception if the overriding implementation fails */ protected void afterSortVolumeClose(final Volume volume, final File file) throws Exception { @@ -762,7 +764,7 @@ protected void afterSortVolumeClose(final Volume volume, final File file) throws * @throws DuplicateKeyException * if a key being inserted or merged matches a key already * exists - * @throws Exception + * @throws Exception if the overriding implementation fails */ protected boolean duplicateKeyDetected(final Tree tree, final Key key, final Value v1, final Value v2) throws Exception { @@ -780,7 +782,7 @@ protected boolean duplicateKeyDetected(final Tree tree, final Key key, final Val * @param exchange * represents the key-value pair proposed for merging * @return true to allow the record to be merged - * @throws Exception + * @throws Exception if the overriding implementation fails */ protected boolean beforeMergeKey(final Exchange exchange) throws Exception { return true; @@ -794,7 +796,7 @@ protected boolean beforeMergeKey(final Exchange exchange) throws Exception { * * @param exchange * represents the key-value pair that was merged. - * @throws Exception + * @throws Exception if the overriding implementation fails */ protected void afterMergeKey(final Exchange exchange) throws Exception { diff --git a/persistit/core/src/main/java/com/persistit/Value.java b/persistit/core/src/main/java/com/persistit/Value.java index 7e7cdb1729..32ce473f96 100644 --- a/persistit/core/src/main/java/com/persistit/Value.java +++ b/persistit/core/src/main/java/com/persistit/Value.java @@ -787,7 +787,7 @@ public boolean trim(final int newSize) { * This method is part of the Low-Level API. *

* - * @param length + * @param length the number of bytes to ensure can be appended * @return true if the backing byte array was replaced by a * larger array. */ @@ -822,7 +822,7 @@ public boolean ensureFit(final int length) { * Offset into the target at which the subarray should be copied * @param length * Number of bytes to copy - * @throws ArrayIndexOutOfBoundsException + * @throws ArrayIndexOutOfBoundsException if the specified range is outside the array bounds */ public void copyFromEncodedBytes(final byte[] dest, final int from, final int to, final int length) { System.arraycopy(_bytes, from, dest, to, length); @@ -5209,7 +5209,7 @@ static class ValueCache { * Look up the handle for an Object that has already been stored in this * Value. * - * @param object + * @param object the object whose handle is to be found * @return The handle, or -1 if the object has not been stored yet. */ int lookup(final Object object) { @@ -5224,7 +5224,7 @@ int lookup(final Object object) { /** * Get the object stored with the supplied handle value. * - * @param handle + * @param handle the handle of the object to retrieve * @return The object */ Object get(final int handle) { @@ -5241,8 +5241,8 @@ Object get(final int handle) { * Subsequent lookup and get operations will then be able to find this * object or fetch it by handle. * - * @param handle - * @param object + * @param handle the handle to associate with the object + * @param object the object to associate with the handle * @return previous handle, or -1 if none */ void store(final int handle, final Object object) { @@ -5389,7 +5389,7 @@ public String toString() { * the multi-value versions currently held in this Value object. * * @return the list of Versions - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ List unpackMvvVersions() throws PersistitException { final List versions = new ArrayList(); diff --git a/persistit/core/src/main/java/com/persistit/Version.java b/persistit/core/src/main/java/com/persistit/Version.java index 5b6e0a58dd..50d3e9ed5d 100644 --- a/persistit/core/src/main/java/com/persistit/Version.java +++ b/persistit/core/src/main/java/com/persistit/Version.java @@ -50,7 +50,7 @@ interface PrunableVersion extends Version { * Called after the last known Version managed by a * TimelyResource has been pruned. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ void vacate() throws PersistitException; @@ -61,7 +61,7 @@ interface PrunableVersion extends Version { * * @author peter * - * @param + * @param the type of Version created by this factory */ interface VersionCreator { V createVersion(final TimelyResource resource) throws PersistitException; diff --git a/persistit/core/src/main/java/com/persistit/Volume.java b/persistit/core/src/main/java/com/persistit/Volume.java index cec8fd74c6..d90deb2b3a 100644 --- a/persistit/core/src/main/java/com/persistit/Volume.java +++ b/persistit/core/src/main/java/com/persistit/Volume.java @@ -110,9 +110,9 @@ static Volume createLockVolume(final Persistit persistit, final int pageSize, fi /** * Construct a hollow Volume - used by JournalManager - * - * @param name - * @param id + * + * @param name the volume name + * @param id the volume id */ Volume(final String name, final long id) { _name = name; @@ -122,8 +122,8 @@ static Volume createLockVolume(final Persistit persistit, final int pageSize, fi /** * Construct a hollow Volume with its specification. - * - * @param specification + * + * @param specification the volume specification */ Volume(final VolumeSpecification specification) { this(specification.getName(), specification.getId()); @@ -190,8 +190,8 @@ void closing() { * Volume may no longer be used after this call. Waits up to * {@value com.persistit.SharedResource#DEFAULT_MAX_WAIT_TIME} milliseconds * for other threads to relinquish access to the volume. - * - * @throws PersistitException + * + * @throws PersistitException if a persistence error occurs */ public void close() throws PersistitException { close(SharedResource.DEFAULT_MAX_WAIT_TIME); @@ -205,7 +205,7 @@ public void close() throws PersistitException { * @param timeout * Maximum time in milliseconds to wait for other threads to * relinquish access to the volume. - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public void close(final long timeout) throws PersistitException { closing(); @@ -251,8 +251,8 @@ public void close(final long timeout) throws PersistitException { * delete and close the file. Instead, this method truncates the file, * rewrites the head page, and invalidates all buffers belonging to this * Volume in the {@link BufferPool}. - * - * @throws PersistitException + * + * @throws PersistitException if a persistence error occurs */ public void truncate() throws PersistitException { if (isReadOnly()) { @@ -292,7 +292,7 @@ public void truncate() throws PersistitException { * * @return true if the file existed and was successfully * deleted. - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public boolean delete() throws PersistitException { if (!isClosed()) { @@ -379,12 +379,12 @@ public int getPageSize() { * @param createIfNecessary * Determines whether this method will create a new tree if there * is no tree having the specified name. - * + * * @return The NewTree, or null if * createIfNecessary is false and there is no such tree * in this Volume. - * - * @throws PersistitException + * + * @throws PersistitException if a persistence error occurs */ public Tree getTree(final String name, final boolean createIfNecessary) throws PersistitException { checkClosing(); @@ -395,8 +395,8 @@ public Tree getTree(final String name, final boolean createIfNecessary) throws P * Returns an array of all currently defined Tree names. * * @return The array - * - * @throws PersistitException + * + * @throws PersistitException if a persistence error occurs */ public String[] getTreeNames() throws PersistitException { checkClosing(); @@ -455,8 +455,8 @@ public boolean isReadOnly() { /** * Open an existing Volume file or create a new one, depending on the * settings of the {@link VolumeSpecification}. - * - * @throws PersistitException + * + * @throws PersistitException if a persistence error occurs */ synchronized void open(final Persistit persistit) throws PersistitException { checkClosing(); @@ -567,7 +567,7 @@ public int getHandle() { * Set the handle used to identify this Tree in the journal. May be invoked * only once. * - * @param handle + * @param handle the handle value to assign * @return the handle * @throws IllegalStateException * if the handle has already been set diff --git a/persistit/core/src/main/java/com/persistit/VolumeHeader.java b/persistit/core/src/main/java/com/persistit/VolumeHeader.java index 0130a4a644..5b11eab806 100644 --- a/persistit/core/src/main/java/com/persistit/VolumeHeader.java +++ b/persistit/core/src/main/java/com/persistit/VolumeHeader.java @@ -176,7 +176,7 @@ static boolean changeLastExtensionTime(final byte[] bytes, final long value) { * +1 because the stored form of volumes created before 2.6.1 recorded * "highestUsedPage" rather than "nextAvailablePage" in this slot. * - * @param bytes + * @param bytes the volume header bytes * @return page address of the next available page */ static long getNextAvailablePage(final byte[] bytes) { @@ -187,7 +187,7 @@ static long getNextAvailablePage(final byte[] bytes) { * -1 because the stored form of volumes created before 2.6.1 recorded * "highestUsedPage" rather than "nextAvailablePage" in this slot. * - * @param bytes + * @param bytes the volume header bytes * @param value * next available page * @return whether the supplied value is different from the previously @@ -293,9 +293,9 @@ static boolean changeGlobalTimestamp(final byte[] bytes, final long value) { * * @return true if and only if there already exists a Volume * file. - * @throws InvalidVolumeSpecificationException - * @throws CorruptVolumeException - * @throws PersistitIOException + * @throws InvalidVolumeSpecificationException if the volume specification is invalid + * @throws CorruptVolumeException if the volume file is corrupt + * @throws PersistitIOException if an I/O error occurs */ public static boolean verifyVolumeHeader(final VolumeSpecification specification, final long systemTimestamp) throws CorruptVolumeException, InvalidVolumeSpecificationException, PersistitIOException { diff --git a/persistit/core/src/main/java/com/persistit/VolumeSpecification.java b/persistit/core/src/main/java/com/persistit/VolumeSpecification.java index 81097ea24c..a13cef9e3c 100644 --- a/persistit/core/src/main/java/com/persistit/VolumeSpecification.java +++ b/persistit/core/src/main/java/com/persistit/VolumeSpecification.java @@ -166,7 +166,7 @@ public VolumeSpecification(final String path, final String name, final int pageS * * @param specification * the specification String - * @throws InvalidVolumeSpecificationException + * @throws InvalidVolumeSpecificationException if the specification string is invalid */ public VolumeSpecification(final String specification) throws InvalidVolumeSpecificationException { diff --git a/persistit/core/src/main/java/com/persistit/VolumeStorage.java b/persistit/core/src/main/java/com/persistit/VolumeStorage.java index cd5fe44c6d..8a3f70bb6e 100644 --- a/persistit/core/src/main/java/com/persistit/VolumeStorage.java +++ b/persistit/core/src/main/java/com/persistit/VolumeStorage.java @@ -12,6 +12,7 @@ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. + * Portions Copyrighted 2026 3A Systems, LLC */ package com.persistit; @@ -40,8 +41,8 @@ abstract class VolumeStorage extends SharedResource { /** * Generate a random positive (non-zero) long value to be used as a * validation of a Volume's identity. - * - * @return + * + * @return a random positive (non-zero) long identity value */ protected static long generateId() { return (ID_GENERATOR.nextLong() & 0x0FFFFFFFFFFl) + 1; @@ -79,7 +80,7 @@ boolean isReadOnly() { /** * @return the channel used to read and write pages of this volume. - * @throws PersistitIOException + * @throws PersistitIOException if an I/O error occurs */ abstract FileChannel getChannel() throws PersistitIOException; @@ -87,20 +88,20 @@ boolean isReadOnly() { * Create a new Volume backing file according to the * {@link Volume}'s volume specification. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ abstract void create() throws PersistitException; /** * Open an existing Volume backing file. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ abstract void open() throws PersistitException; /** * @return true if a backing file exists on the specified path. - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ abstract boolean exists() throws PersistitException; @@ -109,14 +110,14 @@ boolean isReadOnly() { * * @return true if there was a file and it was successfully * deleted - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ abstract boolean delete() throws PersistitException; /** * Force all file system buffers to disk. * - * @throws PersistitIOException + * @throws PersistitIOException if an I/O error occurs */ abstract void force() throws PersistitIOException; @@ -124,14 +125,14 @@ boolean isReadOnly() { * Close the file resources held by this Volume. After this * method is called no further file I/O is possible. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ abstract void close() throws PersistitException; /** * Flush metadata to the volume backing store. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ abstract void flush() throws PersistitException; diff --git a/persistit/core/src/main/java/com/persistit/VolumeStorageT2.java b/persistit/core/src/main/java/com/persistit/VolumeStorageT2.java index f29945f51f..c3af912559 100644 --- a/persistit/core/src/main/java/com/persistit/VolumeStorageT2.java +++ b/persistit/core/src/main/java/com/persistit/VolumeStorageT2.java @@ -12,6 +12,7 @@ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. + * Portions Copyrighted 2026 3A Systems, LLC */ package com.persistit; @@ -111,7 +112,7 @@ synchronized FileChannel getChannel() throws PersistitIOException { * Create a new Volume backing file according to the * {@link Volume}'s volume specification. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ @Override void create() throws PersistitException { @@ -126,7 +127,7 @@ void create() throws PersistitException { /** * Open an existing Volume backing file. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ @Override void open() throws PersistitException { @@ -135,7 +136,7 @@ void open() throws PersistitException { /** * @return true if a backing file exists on the specified path. - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ @Override boolean exists() throws PersistitException { @@ -147,7 +148,7 @@ boolean exists() throws PersistitException { * * @return true if there was a file and it was successfully * deleted - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ @Override boolean delete() throws PersistitException { @@ -157,7 +158,7 @@ boolean delete() throws PersistitException { /** * Force all file system buffers to disk. * - * @throws PersistitIOException + * @throws PersistitIOException if an I/O error occurs */ @Override void force() throws PersistitIOException { @@ -168,7 +169,7 @@ void force() throws PersistitIOException { * Close the file resources held by this Volume. After this * method is called no further file I/O is possible. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ @Override void close() throws PersistitException { diff --git a/persistit/core/src/main/java/com/persistit/VolumeStorageV2.java b/persistit/core/src/main/java/com/persistit/VolumeStorageV2.java index 8b4fe32699..a8c0ebca87 100644 --- a/persistit/core/src/main/java/com/persistit/VolumeStorageV2.java +++ b/persistit/core/src/main/java/com/persistit/VolumeStorageV2.java @@ -92,8 +92,8 @@ class VolumeStorageV2 extends VolumeStorage { /** * Generate a random positive (non-zero) long value to be used as a * validation of a Volume's identity. - * - * @return + * + * @return a random positive (non-zero) long value identifying the volume */ VolumeStorageV2(final Persistit persistit, final Volume volume) { @@ -142,7 +142,7 @@ FileChannel getChannel() { * Create a new Volume backing file according to the * {@link Volume}'s volume specification. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ @Override synchronized void create() throws PersistitException { @@ -177,7 +177,7 @@ synchronized void create() throws PersistitException { /** * Open an existing Volume backing file. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ @Override synchronized void open() throws PersistitException { @@ -250,7 +250,7 @@ synchronized void open() throws PersistitException { /** * @return true if a backing file exists on the specified path. - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ @Override boolean exists() throws PersistitException { @@ -263,7 +263,7 @@ boolean exists() throws PersistitException { * * @return true if there was a file and it was successfully * deleted - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ @Override boolean delete() throws PersistitException { @@ -274,7 +274,7 @@ boolean delete() throws PersistitException { /** * Force all file system buffers to disk. * - * @throws PersistitIOException + * @throws PersistitIOException if an I/O error occurs */ @Override void force() throws PersistitIOException { @@ -289,7 +289,7 @@ void force() throws PersistitIOException { * Close the file resources held by this Volume. After this * method is called no further file I/O is possible. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ @Override void close() throws PersistitException { diff --git a/persistit/core/src/main/java/com/persistit/VolumeStructure.java b/persistit/core/src/main/java/com/persistit/VolumeStructure.java index 1699726c0d..77652facc4 100644 --- a/persistit/core/src/main/java/com/persistit/VolumeStructure.java +++ b/persistit/core/src/main/java/com/persistit/VolumeStructure.java @@ -140,7 +140,7 @@ Exchange accumulatorExchange() throws BufferSizeUnavailableException { * page and all the index and data pages pointed to by that root page. * * @return newly create NewTree object - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ private long createTreeRoot(final Tree tree) throws PersistitException { _persistit.checkSuspended(); @@ -181,7 +181,7 @@ private long createTreeRoot(final Tree tree) throws PersistitException { * createIfNecessary is false and there is no such tree * in this Volume. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public synchronized Tree getTree(final String name, final boolean createIfNecessary) throws PersistitException { if (DIRECTORY_TREE_NAME.equals(name)) { @@ -235,9 +235,9 @@ public synchronized Tree getTree(final String name, final boolean createIfNecess /** * Helper method used by pruning. Allows access to directory tree by name. * - * @param name - * @return - * @throws PersistitException + * @param name the tree name + * @return the Tree with the specified name, or null if none exists + * @throws PersistitException if a persistence error occurs */ Tree getTreeInternal(final String name) throws PersistitException { if (DIRECTORY_TREE_NAME.equals(name)) { @@ -345,8 +345,8 @@ void deallocateTree(final long treeRootPage, final int treeDepth) throws Persist /** * Called by Exchange to recreate a Tree after a volume has been truncated. * - * @param tree - * @throws PersistitException + * @param tree the Tree to recreate + * @throws PersistitException if a persistence error occurs */ void recreateTree(final Tree tree) throws PersistitException { Debug.$assert1.t(tree.getDepth() == -1); @@ -361,7 +361,7 @@ void recreateTree(final Tree tree) throws PersistitException { * Flush dirty {@link TreeStatistics} instances. Called periodically on the * PAGE_WRITER thread from {@link Persistit#cleanup()}. * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ void flushStatistics() throws PersistitException { final List trees = new ArrayList(); @@ -384,7 +384,7 @@ void flushStatistics() throws PersistitException { * * @return The array * - * @throws PersistitException + * @throws PersistitException if a persistence error occurs */ public String[] getTreeNames() throws PersistitException { final List list = new ArrayList(); diff --git a/persistit/core/src/main/java/com/persistit/encoding/CoderManager.java b/persistit/core/src/main/java/com/persistit/encoding/CoderManager.java index c896112202..c7d146c310 100644 --- a/persistit/core/src/main/java/com/persistit/encoding/CoderManager.java +++ b/persistit/core/src/main/java/com/persistit/encoding/CoderManager.java @@ -242,7 +242,7 @@ public interface CoderManager { * Return a ValueCoder for the supplied Class. If * there is none registered, implicitly create one and register it. * - * @param clazz + * @param clazz The Class * @return The ValueCoder */ public ValueCoder getValueCoder(Class clazz); diff --git a/persistit/core/src/main/java/com/persistit/encoding/CollectionValueCoder.java b/persistit/core/src/main/java/com/persistit/encoding/CollectionValueCoder.java index 97d1a6797f..b896fdc7ec 100644 --- a/persistit/core/src/main/java/com/persistit/encoding/CollectionValueCoder.java +++ b/persistit/core/src/main/java/com/persistit/encoding/CollectionValueCoder.java @@ -158,7 +158,7 @@ public void put(final Value value, final Object object, final CoderContext conte * null. * @return An Object having the same class as the suppled * clazz parameter. - * @throws ConversionException + * @throws ConversionException if the value cannot be converted */ @Override public Object get(final Value value, final Class clazz, final CoderContext context) throws ConversionException { @@ -202,7 +202,7 @@ public Object get(final Value value, final Class clazz, final CoderContext co * operation. (See {@link CoderContext}.) The default value is * null. * - * @throws ConversionException + * @throws ConversionException if the value cannot be converted */ @Override public void render(final Value value, final Object target, final Class clazz, final CoderContext context) @@ -274,7 +274,7 @@ public void render(final Value value, final Object target, final Class clazz, fi * operation. (See {@link CoderContext}.) The default value is * null. * - * @throws ConversionException + * @throws ConversionException if the value cannot be converted */ @Override public void display(final Value value, final StringBuilder target, final Class clazz, final CoderContext context) diff --git a/persistit/core/src/main/java/com/persistit/encoding/EnumValueCoder.java b/persistit/core/src/main/java/com/persistit/encoding/EnumValueCoder.java index cb1449a4e9..e3bd0d2bf0 100644 --- a/persistit/core/src/main/java/com/persistit/encoding/EnumValueCoder.java +++ b/persistit/core/src/main/java/com/persistit/encoding/EnumValueCoder.java @@ -1,6 +1,7 @@ /** * Copyright 2005-2012 Akiban Technologies, Inc. - * + * Portions Copyrighted 2026 3A Systems, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -81,7 +82,7 @@ public void put(final Value value, final Object object, final CoderContext conte * null. * @return An Object having the same class as the suppled * clazz parameter. - * @throws ConversionException + * @throws ConversionException if the value cannot be converted */ @Override public Object get(final Value value, Class clazz, final CoderContext context) throws ConversionException { diff --git a/persistit/core/src/main/java/com/persistit/encoding/HandleCache.java b/persistit/core/src/main/java/com/persistit/encoding/HandleCache.java index dd2599d93b..e656c9de0e 100644 --- a/persistit/core/src/main/java/com/persistit/encoding/HandleCache.java +++ b/persistit/core/src/main/java/com/persistit/encoding/HandleCache.java @@ -12,6 +12,7 @@ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. + * Portions Copyrighted 2026 3A Systems, LLC */ package com.persistit.encoding; @@ -31,7 +32,7 @@ public interface HandleCache { /** * Store a supplied handle. * - * @param handle + * @param handle the handle value to store * @throws IllegalStateException * if there already is a non-matching non-zero handle stored */ diff --git a/persistit/core/src/main/java/com/persistit/encoding/KeyCoder.java b/persistit/core/src/main/java/com/persistit/encoding/KeyCoder.java index 64598ee048..6607d42ab1 100644 --- a/persistit/core/src/main/java/com/persistit/encoding/KeyCoder.java +++ b/persistit/core/src/main/java/com/persistit/encoding/KeyCoder.java @@ -1,6 +1,7 @@ /** * Copyright 2005-2012 Akiban Technologies, Inc. - * + * Portions Copyrighted 2026 3A Systems, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -106,7 +107,7 @@ public interface KeyCoder { * application to convey an application-specific context for the * operation. (See {@link CoderContext}.) The default value is * null. - * @throws ConversionException + * @throws ConversionException if the value cannot be converted */ public Object decodeKeySegment(Key key, Class clazz, CoderContext context) throws ConversionException; @@ -130,7 +131,7 @@ public interface KeyCoder { * * @return whether this KeyCoder produces encodings guaranteed not to * contain zero bytes - * @throws ConversionException + * @throws ConversionException if the value cannot be converted */ public boolean isZeroByteFree() throws ConversionException; } diff --git a/persistit/core/src/main/java/com/persistit/encoding/KeyDisplayer.java b/persistit/core/src/main/java/com/persistit/encoding/KeyDisplayer.java index b8aa6c579c..795a0fe9e1 100644 --- a/persistit/core/src/main/java/com/persistit/encoding/KeyDisplayer.java +++ b/persistit/core/src/main/java/com/persistit/encoding/KeyDisplayer.java @@ -1,6 +1,7 @@ /** * Copyright 2005-2012 Akiban Technologies, Inc. - * + * Portions Copyrighted 2026 3A Systems, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -71,7 +72,7 @@ public interface KeyDisplayer extends KeyCoder { * operation. (See {@link CoderContext}.) The default value is * null. * - * @throws ConversionException + * @throws ConversionException if the value cannot be converted */ public void displayKeySegment(Key key, Appendable target, Class clazz, CoderContext context) throws ConversionException; diff --git a/persistit/core/src/main/java/com/persistit/encoding/KeyRenderer.java b/persistit/core/src/main/java/com/persistit/encoding/KeyRenderer.java index 7a1e6fdbf9..9975a9e5e5 100644 --- a/persistit/core/src/main/java/com/persistit/encoding/KeyRenderer.java +++ b/persistit/core/src/main/java/com/persistit/encoding/KeyRenderer.java @@ -12,6 +12,7 @@ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. + * Portions Copyrighted 2026 3A Systems, LLC */ package com.persistit.encoding; @@ -68,8 +69,8 @@ public interface KeyRenderer extends KeyCoder { * application to convey an application-specific context for the * operation. (See {@link CoderContext}.) The default value is * null. - * - * @throws ConversionException + * + * @throws ConversionException if the key segment cannot be converted into the target object */ public void renderKeySegment(Key key, Object target, Class clazz, CoderContext context) throws ConversionException; diff --git a/persistit/core/src/main/java/com/persistit/encoding/ObjectCache.java b/persistit/core/src/main/java/com/persistit/encoding/ObjectCache.java index b5444e9b9a..c2553a143e 100644 --- a/persistit/core/src/main/java/com/persistit/encoding/ObjectCache.java +++ b/persistit/core/src/main/java/com/persistit/encoding/ObjectCache.java @@ -234,8 +234,8 @@ public synchronized Object getWithNull(final Key key) { /** * Indicates whether there is a value associated with the key. - * - * @param key + * + * @param key the Key whose associated value is sought * @return true if the cache contains a representation of the * value associated with the key; otherwise false */ @@ -331,8 +331,8 @@ private void resize() { * modestly, so it may be appropriate to raise the default dead count * threshold. *

- * - * @param deadCountThreshold + * + * @param deadCountThreshold the number of dead references above which the cache is scanned and pruned */ private void processQueue(final int deadCountThreshold) { while (_queue.poll() != null) diff --git a/persistit/core/src/main/java/com/persistit/encoding/SerialValueCoder.java b/persistit/core/src/main/java/com/persistit/encoding/SerialValueCoder.java index 576b8e4ba0..eb5fcf62ce 100644 --- a/persistit/core/src/main/java/com/persistit/encoding/SerialValueCoder.java +++ b/persistit/core/src/main/java/com/persistit/encoding/SerialValueCoder.java @@ -12,6 +12,7 @@ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. + * Portions Copyrighted 2026 3A Systems, LLC */ package com.persistit.encoding; @@ -90,7 +91,7 @@ public SerialValueCoder(final Class clazz) { * @return An Object having the same class as the suppled * clazz parameter. * - * @throws ConversionException + * @throws ConversionException if the value cannot be converted */ @Override public Object get(final Value value, final Class clazz, final CoderContext context) { diff --git a/persistit/core/src/main/java/com/persistit/encoding/ValueCoder.java b/persistit/core/src/main/java/com/persistit/encoding/ValueCoder.java index e3b1028f3b..2024c4230f 100644 --- a/persistit/core/src/main/java/com/persistit/encoding/ValueCoder.java +++ b/persistit/core/src/main/java/com/persistit/encoding/ValueCoder.java @@ -172,7 +172,7 @@ public interface ValueCoder { * null. * @return An Object having the same class as the suppled * clazz parameter. - * @throws ConversionException + * @throws ConversionException if the value cannot be converted */ public Object get(Value value, Class clazz, CoderContext context) throws ConversionException; diff --git a/persistit/core/src/main/java/com/persistit/encoding/ValueDisplayer.java b/persistit/core/src/main/java/com/persistit/encoding/ValueDisplayer.java index 75960d9368..3db32b67e5 100644 --- a/persistit/core/src/main/java/com/persistit/encoding/ValueDisplayer.java +++ b/persistit/core/src/main/java/com/persistit/encoding/ValueDisplayer.java @@ -1,6 +1,7 @@ /** * Copyright 2005-2012 Akiban Technologies, Inc. - * + * Portions Copyrighted 2026 3A Systems, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -70,7 +71,7 @@ public interface ValueDisplayer extends ValueCoder { * operation. (See {@link CoderContext}.) The default value is * null. * - * @throws ConversionException + * @throws ConversionException if the value cannot be converted */ public void display(Value value, StringBuilder target, Class clazz, CoderContext context) throws ConversionException; diff --git a/persistit/core/src/main/java/com/persistit/encoding/ValueRenderer.java b/persistit/core/src/main/java/com/persistit/encoding/ValueRenderer.java index 056fe628c8..873a99709d 100644 --- a/persistit/core/src/main/java/com/persistit/encoding/ValueRenderer.java +++ b/persistit/core/src/main/java/com/persistit/encoding/ValueRenderer.java @@ -12,6 +12,7 @@ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. + * Portions Copyrighted 2026 3A Systems, LLC */ package com.persistit.encoding; @@ -79,7 +80,7 @@ public interface ValueRenderer extends ValueCoder { * operation. (See {@link CoderContext}.) The default value is * null. * - * @throws ConversionException + * @throws ConversionException if the value cannot be converted */ public void render(Value value, Object target, Class clazz, CoderContext context) throws ConversionException; } diff --git a/persistit/core/src/main/java/com/persistit/logging/DefaultPersistitLogger.java b/persistit/core/src/main/java/com/persistit/logging/DefaultPersistitLogger.java index e736af662e..ce58cb180c 100644 --- a/persistit/core/src/main/java/com/persistit/logging/DefaultPersistitLogger.java +++ b/persistit/core/src/main/java/com/persistit/logging/DefaultPersistitLogger.java @@ -1,6 +1,7 @@ /** * Copyright 2005-2012 Akiban Technologies, Inc. - * + * Portions Copyrighted 2026 3A Systems, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -118,7 +119,7 @@ public void open() throws Exception { /** * Closes the log file. * - * @throws InterruptedException + * @throws InterruptedException if the thread is interrupted while waiting */ @Override public void close() throws InterruptedException { diff --git a/persistit/core/src/main/java/com/persistit/logging/PersistitLogger.java b/persistit/core/src/main/java/com/persistit/logging/PersistitLogger.java index 783d61c6f7..dc799c2591 100644 --- a/persistit/core/src/main/java/com/persistit/logging/PersistitLogger.java +++ b/persistit/core/src/main/java/com/persistit/logging/PersistitLogger.java @@ -12,6 +12,7 @@ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. + * Portions Copyrighted 2026 3A Systems, LLC */ package com.persistit.logging; @@ -49,14 +50,14 @@ public interface PersistitLogger { /** * Called when Persistit starts using the log. * - * @throws Exception + * @throws Exception if the log cannot be opened */ void open() throws Exception; /** * Called when Persistit stops using the log. * - * @throws Exception + * @throws Exception if the log cannot be closed */ void close() throws Exception; diff --git a/persistit/core/src/main/java/com/persistit/mxbeans/CleanupManagerMXBean.java b/persistit/core/src/main/java/com/persistit/mxbeans/CleanupManagerMXBean.java index 120d958cfa..7f7b88b93a 100644 --- a/persistit/core/src/main/java/com/persistit/mxbeans/CleanupManagerMXBean.java +++ b/persistit/core/src/main/java/com/persistit/mxbeans/CleanupManagerMXBean.java @@ -12,6 +12,7 @@ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. + * Portions Copyrighted 2026 3A Systems, LLC */ package com.persistit.mxbeans; @@ -101,7 +102,8 @@ public interface CleanupManagerMXBean { * Set the minimum interval in milliseconds between attempts to enqueue a * page needing to be pruned. * - * @param delay + * @param delay the minimum interval in milliseconds between pruning enqueue + * attempts */ @Description("The minimum interval in milliseconds between attempts to enqueue a page needing to be pruned") public void setMinimumPruningDelay(long delay); diff --git a/persistit/core/src/main/java/com/persistit/mxbeans/IOMeterMXBean.java b/persistit/core/src/main/java/com/persistit/mxbeans/IOMeterMXBean.java index 755fc0c024..7da5ffd26f 100644 --- a/persistit/core/src/main/java/com/persistit/mxbeans/IOMeterMXBean.java +++ b/persistit/core/src/main/java/com/persistit/mxbeans/IOMeterMXBean.java @@ -96,8 +96,8 @@ public interface IOMeterMXBean { * fixed-length record being added to the file. The resulting log file can * become extremely large. * - * @param toFile - * @throws IOException + * @param toFile the path of the file into which I/O events should be logged, or null to disable logging + * @throws IOException if an I/O error occurs */ @Description("Path for diagnostic I/O log file - normally null") public void setLogFile(final String toFile) throws IOException; diff --git a/persistit/core/src/main/java/com/persistit/mxbeans/ManagementMXBean.java b/persistit/core/src/main/java/com/persistit/mxbeans/ManagementMXBean.java index 428a1acc7c..a4cf90b3a2 100644 --- a/persistit/core/src/main/java/com/persistit/mxbeans/ManagementMXBean.java +++ b/persistit/core/src/main/java/com/persistit/mxbeans/ManagementMXBean.java @@ -12,6 +12,7 @@ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. + * Portions Copyrighted 2026 3A Systems, LLC */ package com.persistit.mxbeans; @@ -79,7 +80,7 @@ public interface ManagementMXBean { * not registered. * * @return the port - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ int getRmiPort() throws RemoteException; @@ -88,7 +89,7 @@ public interface ManagementMXBean { * initialized * * @return total number of transactions committed - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ long getCommittedTransactionCount() throws RemoteException; @@ -97,7 +98,7 @@ public interface ManagementMXBean { * Persistit was initialized * * @return total number of transactions rolled back - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ long getRollbackCount() throws RemoteException; @@ -106,7 +107,7 @@ public interface ManagementMXBean { * or null if there are none. * * @return array of volumes - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ Management.VolumeInfo[] getVolumes() throws RemoteException; @@ -114,7 +115,7 @@ public interface ManagementMXBean { * @param max * Maximum number of transactions to report on. * @return Report on the max longest-running transactions. - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ String transactionReport(int max) throws RemoteException; @@ -165,7 +166,7 @@ public interface ManagementMXBean { * * @return true if Persistit will suspend any attempt to update * a Volume; otherwise false. - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ boolean isUpdateSuspended() throws RemoteException; @@ -174,8 +175,8 @@ public interface ManagementMXBean { * enabled, Persistit will delay each Thread that attempts to perform an * update operation indefinitely. * - * @param suspended - * @throws RemoteException + * @param suspended true to suspend all update operations; otherwise false + * @throws RemoteException if a remote communication error occurs */ void setUpdateSuspended(boolean suspended) throws RemoteException; @@ -183,7 +184,7 @@ public interface ManagementMXBean { * Flush and sync all dirty data in Persistit by invoking * {@link Persistit#flush} and {@link Persistit#force}. * - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ void flushAndForce() throws RemoteException; @@ -194,9 +195,9 @@ public interface ManagementMXBean { * {@link #launch(String)} method initiates the task in a new thread and * returns immediately. * - * @param commandLine + * @param commandLine the command line specifying the task to execute * @return The final status of the Task, as a String - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ String execute(final String commandLine) throws RemoteException; @@ -206,9 +207,9 @@ public interface ManagementMXBean { * starts the task in a new thread and returns immediately. In contrast, the * {@link #execute(String)} method completes the task before returning. * - * @param commandLine + * @param commandLine the command line specifying the task to start * @return The taskId, as a String - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ String launch(final String commandLine) throws RemoteException; @@ -218,7 +219,7 @@ public interface ManagementMXBean { * @param volumeName * name of the volume to lookup * @return information about the volume, or null if none found - * @throws RemoteException + * @throws RemoteException if a remote communication error occurs */ Management.VolumeInfo volumeByName(final String volumeName) throws RemoteException; } diff --git a/persistit/core/src/main/java/com/persistit/policy/JoinPolicy.java b/persistit/core/src/main/java/com/persistit/policy/JoinPolicy.java index 2c2f813841..6f9de1b843 100644 --- a/persistit/core/src/main/java/com/persistit/policy/JoinPolicy.java +++ b/persistit/core/src/main/java/com/persistit/policy/JoinPolicy.java @@ -125,8 +125,8 @@ public int rebalanceFit(final Buffer leftBuffer, final Buffer rightBuffer, final * Determines whether two pages will be permitted to be rejoined during a * delete operation. * - * @param buffer - * @param virtualSize + * @param buffer the Buffer that would receive the joined content + * @param virtualSize the proposed combined size in bytes of the joined pages * @return true if the buffer will accept content of the * specified size */ diff --git a/persistit/core/src/main/java/com/persistit/ref/AbstractReference.java b/persistit/core/src/main/java/com/persistit/ref/AbstractReference.java index ea6a29bf4c..00d77fd9dd 100644 --- a/persistit/core/src/main/java/com/persistit/ref/AbstractReference.java +++ b/persistit/core/src/main/java/com/persistit/ref/AbstractReference.java @@ -12,6 +12,7 @@ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. + * Portions Copyrighted 2026 3A Systems, LLC */ package com.persistit.ref; @@ -66,7 +67,7 @@ protected AbstractReference(final Object id, final Object referent) { * subsequent invocation of the get method will cause the * object to be looked up and instantiated. * - * @param id + * @param id the persistent identifier */ protected AbstractReference(final Object id) { _id = id; diff --git a/persistit/core/src/main/java/com/persistit/ref/AbstractWeakReference.java b/persistit/core/src/main/java/com/persistit/ref/AbstractWeakReference.java index 0d273b80f4..01bb4b8aba 100644 --- a/persistit/core/src/main/java/com/persistit/ref/AbstractWeakReference.java +++ b/persistit/core/src/main/java/com/persistit/ref/AbstractWeakReference.java @@ -81,7 +81,7 @@ protected AbstractWeakReference(final Object id, final Object referent) { * subsequent invocation of the get method will cause the * object to be looked up and instantiated. * - * @param id + * @param id the persistent identifier of the referent object */ protected AbstractWeakReference(final Object id) { _id = id; diff --git a/persistit/core/src/main/java/com/persistit/util/ArgParser.java b/persistit/core/src/main/java/com/persistit/util/ArgParser.java index e68aa7dfb8..418882d19f 100644 --- a/persistit/core/src/main/java/com/persistit/util/ArgParser.java +++ b/persistit/core/src/main/java/com/persistit/util/ArgParser.java @@ -231,7 +231,7 @@ public String getFlags() { * Return the boolean value of argument specified by its index in the * template * - * @param index + * @param index the index of the argument in the template * @return the boolean value for the specified template item */ public boolean booleanValue(final int index) { @@ -269,7 +269,7 @@ public int getIntValue(final String fieldName) { * Return the integer value of argument specified by its index in the * template * - * @param index + * @param index the index of the argument in the template * @return the int value for the specified template item */ public int intValue(final int index) { @@ -290,7 +290,7 @@ public long getLongValue(final String fieldName) { /** * Return the long value of argument specified by its index in the template * - * @param index + * @param index the index of the argument in the template * @return the long value for the specified template item */ @@ -302,7 +302,7 @@ public long longValue(final int index) { * Return the String value of argument specified by its index in the * template * - * @param index + * @param index the index of the argument in the template * @return the String value for the specified template item */ public String stringValue(final int index) { @@ -313,7 +313,7 @@ public String stringValue(final int index) { * Indicate whether the value returned for the specified field is the * default value. * - * @param fieldName + * @param fieldName the argument name of the field to test * @return true if the field contains its default value */ public boolean isSpecified(final String fieldName) { diff --git a/persistit/core/src/main/java/com/persistit/util/Debug.java b/persistit/core/src/main/java/com/persistit/util/Debug.java index 52a6e0d834..d2b5e70192 100644 --- a/persistit/core/src/main/java/com/persistit/util/Debug.java +++ b/persistit/core/src/main/java/com/persistit/util/Debug.java @@ -1,6 +1,7 @@ /** * Copyright 2005-2012 Akiban Technologies, Inc. - * + * Portions Copyrighted 2026 3A Systems, LLC + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -135,7 +136,7 @@ public static String callStack(final int from, final int to) { * Set the suspend flag so that callers to the suspend method either do or * do not suspend. * - * @param b + * @param b true to set the suspend flag, false to clear it */ synchronized static void setSuspended(final boolean b) { if (b) { diff --git a/persistit/core/src/main/java/com/persistit/util/ThreadSequencer.java b/persistit/core/src/main/java/com/persistit/util/ThreadSequencer.java index c91d2e9ec4..98f6985c48 100644 --- a/persistit/core/src/main/java/com/persistit/util/ThreadSequencer.java +++ b/persistit/core/src/main/java/com/persistit/util/ThreadSequencer.java @@ -321,7 +321,8 @@ interface Sequencer { * MAX_LOCATIONS possible locations in code where a join point can * occur. * - * @param location + * @param location the location at which the calling thread reaches a + * join point */ public void sequence(final int location); diff --git a/persistit/ui/src/main/java/com/persistit/ui/ManagementSlidingTableModel.java b/persistit/ui/src/main/java/com/persistit/ui/ManagementSlidingTableModel.java index 478a835bd1..c58e1a409a 100644 --- a/persistit/ui/src/main/java/com/persistit/ui/ManagementSlidingTableModel.java +++ b/persistit/ui/src/main/java/com/persistit/ui/ManagementSlidingTableModel.java @@ -107,7 +107,7 @@ class ManagementSlidingTableModel extends ManagementTableModel { * width is a percentage of the total table width, and * justification is L, C or R. * - * @param clazz + * @param clazz the management info class whose columns are displayed. */ public ManagementSlidingTableModel(final Class clazz, final String className, final AdminUI ui) diff --git a/persistit/ui/src/main/java/com/persistit/ui/ManagementTableModel.java b/persistit/ui/src/main/java/com/persistit/ui/ManagementTableModel.java index 82876ac073..605919b962 100644 --- a/persistit/ui/src/main/java/com/persistit/ui/ManagementTableModel.java +++ b/persistit/ui/src/main/java/com/persistit/ui/ManagementTableModel.java @@ -78,7 +78,7 @@ public class ManagementTableModel extends AbstractTableModel { * width is a percentage of the total table width, and * justification is L, C or R. * - * @param clazz + * @param clazz the management info class whose columns are displayed. */ public ManagementTableModel(final Class clazz, String className, final AdminUI ui) throws NoSuchMethodException { diff --git a/persistit/ui/src/main/java/com/persistit/ui/PersistitTableModel.java b/persistit/ui/src/main/java/com/persistit/ui/PersistitTableModel.java index cdf6b90c9a..516cb58e5c 100644 --- a/persistit/ui/src/main/java/com/persistit/ui/PersistitTableModel.java +++ b/persistit/ui/src/main/java/com/persistit/ui/PersistitTableModel.java @@ -1,5 +1,6 @@ /** * Copyright 2005-2012 Akiban Technologies, Inc. + * Portions Copyrighted 2026 3A Systems, LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -85,7 +86,7 @@ public class PersistitTableModel extends AbstractTableModel { /** * Establishes the supplied Exchange as the root of a display tree. * - * @param exchange + * @param exchange the Exchange to establish as the root of the display tree. */ public void setExchange(final Exchange exchange) { _exchange = exchange; @@ -196,7 +197,7 @@ public int getColumnCount() { /** * Sets up the TableColumnModel for a supplied JTable * - * @param table + * @param table the JTable whose column model is configured. */ public void setupColumns(final JTable table) { final TableColumnModel tcm = table.getColumnModel(); diff --git a/pom.xml b/pom.xml index 407f5bee06..8d1218d651 100644 --- a/pom.xml +++ b/pom.xml @@ -127,7 +127,7 @@ 3.0.1 - 3.10.1 + 3.12.0 @@ -1066,12 +1066,17 @@ warnings surfaced as CI annotations; keep the accessibility, html, reference and syntax checks that guard against real javadoc errors. --> all,-missing + + true false true ${javadocWindowTitle} ${javadocDocTitle}
${javadocDocTitle}]]>
-
${javadocDocTitle}]]>
+ protected ${javadocStylesheet} diff --git a/script/common/src/main/java/org/forgerock/script/ScriptRegistry.java b/script/common/src/main/java/org/forgerock/script/ScriptRegistry.java index eaea0f2732..049b7af23f 100644 --- a/script/common/src/main/java/org/forgerock/script/ScriptRegistry.java +++ b/script/common/src/main/java/org/forgerock/script/ScriptRegistry.java @@ -83,8 +83,12 @@ public interface ScriptRegistry extends SourceUnitObserver { * @throws NullPointerException * if script is null. * @throws org.forgerock.json.JsonValueException + * if the {@code script} JSON value is malformed or missing + * required attributes. * @throws IllegalArgumentException + * if the {@code script} value does not identify a valid script. * @throws ScriptException + * if the script cannot be compiled or evaluated. */ public ScriptEntry takeScript(JsonValue script) throws ScriptException; diff --git a/script/common/src/main/java/org/forgerock/script/engine/Utils.java b/script/common/src/main/java/org/forgerock/script/engine/Utils.java index 6901f6fd28..eb2d4ce1a3 100644 --- a/script/common/src/main/java/org/forgerock/script/engine/Utils.java +++ b/script/common/src/main/java/org/forgerock/script/engine/Utils.java @@ -211,10 +211,13 @@ private static Object deepCopy(Object source, final Stack> * Executes the given script with the appropriate context information. * * @param context + * the context information used to evaluate the script. * @param scriptPair * The script to execute - * @return + * @return the result of evaluating the script, or {@code null} if no script + * was provided. * @throws ResourceException + * if the script is inactive or its evaluation fails. */ public static Object evaluateScript(final Context context, final Pair scriptPair) throws ResourceException { diff --git a/script/common/src/main/java/org/forgerock/script/jsr223/ScriptExecutor.java b/script/common/src/main/java/org/forgerock/script/jsr223/ScriptExecutor.java index 23269f2bb3..3f7e9edd8e 100644 --- a/script/common/src/main/java/org/forgerock/script/jsr223/ScriptExecutor.java +++ b/script/common/src/main/java/org/forgerock/script/jsr223/ScriptExecutor.java @@ -20,6 +20,7 @@ * with the fields enclosed by brackets [] replaced by * your own identifying information: * "Portions Copyrighted [year] [name of copyright owner]" + * Portions Copyrighted 2026 3A Systems, LLC */ package org.forgerock.script.jsr223; @@ -141,7 +142,7 @@ public boolean isSourceModified() { /** * Subclasses may implement this to provide any special handling required * - * @return + * @return the post-processed result. */ protected abstract Object postProcess(Object result); diff --git a/script/common/src/main/java/org/forgerock/script/registry/ThreadClassLoaderManager.java b/script/common/src/main/java/org/forgerock/script/registry/ThreadClassLoaderManager.java index e58059b41e..4daf690bae 100644 --- a/script/common/src/main/java/org/forgerock/script/registry/ThreadClassLoaderManager.java +++ b/script/common/src/main/java/org/forgerock/script/registry/ThreadClassLoaderManager.java @@ -20,6 +20,7 @@ * with the fields enclosed by brackets [] replaced by * your own identifying information: * "Portions Copyrighted [year] [name of copyright owner]" + * Portions Copyrighted 2026 3A Systems, LLC */ package org.forgerock.script.registry; @@ -50,7 +51,7 @@ private ThreadClassLoaderManager() { /** * Returns the thread-local instance of the manager. * - * @return + * @return the thread-local instance of the manager. */ public static ThreadClassLoaderManager getInstance() { return instance.get(); diff --git a/script/common/src/main/java/org/forgerock/script/scope/Function.java b/script/common/src/main/java/org/forgerock/script/scope/Function.java index 0c96babd3c..eb4cb67a1a 100644 --- a/script/common/src/main/java/org/forgerock/script/scope/Function.java +++ b/script/common/src/main/java/org/forgerock/script/scope/Function.java @@ -40,12 +40,15 @@ public interface Function extends Serializable { * Computes a result, or throws an exception if unable to do so. * * @param scope + * the parameter providing the scope available to the function. * @param callback + * the callback function that may be invoked by this function. * @param arguments could be a single value or a List of values * @return computed result * @throws ResourceException * if unable to compute a result * @throws NoSuchMethodException + * if the requested method cannot be found. */ R call(Parameter scope, Function callback, Object... arguments) throws ResourceException, NoSuchMethodException; diff --git a/script/common/src/main/java/org/forgerock/script/source/ScriptSource.java b/script/common/src/main/java/org/forgerock/script/source/ScriptSource.java index 6b9c03d764..42b151f80b 100644 --- a/script/common/src/main/java/org/forgerock/script/source/ScriptSource.java +++ b/script/common/src/main/java/org/forgerock/script/source/ScriptSource.java @@ -20,6 +20,7 @@ * with the fields enclosed by brackets [] replaced by * your own identifying information: * "Portions Copyrighted [year] [name of copyright owner]" + * Portions Copyrighted 2026 3A Systems, LLC */ package org.forgerock.script.source; @@ -50,7 +51,7 @@ public interface ScriptSource extends SourceUnit { /** * - * @return + * @return the script names this source depends on. */ ScriptName[] getDependencies(); }